Managing URI Fragments

The exact syntax of the fragment identifier part is defined in RFC 3986 (Internet standard STD 66) that defines the URI syntax. A fragment may only contain the regular URI path characters (see the standard) and additionally the slash and the question mark.

Vaadin offers two ways to enable the use of URI fragments: the high-level Navigator utility described in “Navigating in an Application” and the low-level API described here.

You can set the current fragment identifier with the setUriFragment() method in the Page object.

Java

Setting the URI fragment causes an UriFragmentChangeEvent, which is processed in the same server request. As with UI rendering, the URI fragment is changed in the browser after the currently processed server request returns the response.

Prefixing the fragment identifier with an exclamation mark enables the web crawler support described in .

The current URI fragment can be acquired with the getUriFragment() method from the current Page object. The fragment is known when the init() method of the UI is called.

See the on-line example.

To enable reusing the same code when the URI fragment is changed, as described next, it is usually best to build the relevant part of the UI in a separate method. In the above example, we called an enter() method, in a way that is similar to handling view changes with Navigator.

After the UI has been initialized, changes in the URI fragment can be handled with a UriFragmentChangeListener. The listeners are called when the URI fragment changes, but not when the UI is initialized, where the current fragment is available from the page object as described earlier.

For example, we could define the listener as follows in the init() method of a UI class:

Java

See the .

Application State Management with URI Fragment Utility shows an application that allows specifying the menu selection with a URI fragment and correspondingly sets the fragment when the user selects a menu item.

Application State Management with URI Fragment Utility

Stateful AJAX applications can not normally be crawled by a search engine, as they run in a single page and a crawler can not navigate the states even if URI fragments are enabled. The Google search engine and crawler where the fragment identifiers are prefixed with exclamation mark, such as #!myfragment. The servlet needs to have a separate searchable content page accessible with the same URL, but with a _escaped_fragment_ parameter. For example, for /myapp/myui#!myfragment it would be /myapp/myui?_escaped_fragment_=myfragment.

You can provide the crawl content by overriding the service() method in a custom servlet class. For regular requests, you should call the super implementation in the VaadinServlet class.

Java

See the on-line example.

The crawlable content does not need to be human readable. It can provide an index of links to other application states, as we did in the example above. The links should use the “ #!” notation, but can not be relative to avoid having the _escaped_fragment_ parameter.

You need to use the custom servlet class in the web.xml deployment descriptor instead of the normal VaadinServlet class, as described in .