Skip to end of metadata
Go to start of metadata

Starting in version 2.1, Errai offers a system for creating applications that have multiple bookmarkable pages. This navigation system has the following features:

  • Declarative, statically-analyzable configuration of pages and links
    • Compile time referential safety (i.e. “no broken links”)
    • Generates a storyboard of the application’s navigation flow at compile time
  • Decentralized configuration
    • Create a new page by creating a new annotated class. No need to edit a second file.
    • Make navigational changes in the natural place in the code.
  • Integrates cleanly with Errai UI templates, but also works well with other view technologies.
  • Builds on Errai IoC & CDI

Getting Started

Compile-time dependency

To use Errai UI Navigation, you must include it on the compile-time classpath. If you are using Maven for your build, add these dependencies:

If you are not using Maven for dependency management, add errai-navigation-version.jar to the compile-time classpath of a project that's already set up for Errai UI templating.

GWT Module Descriptor

Once you have Errai UI Navigation on your classpath, ensure your application inherits the GWT module as well. Add this line to your application's *.gwt.xml file:

How it Works

Errai Navigation has three main parts: the @Page annotation marks any widget as a page; the TransitionTo<P> interface is an injectable type that provides a link to another page; and the Navigation singleton offers control over the navigation system as a whole.

The Navigation singleton owns a GWT Panel called the navigation panel. This panel always contains a widget corresponding to the the fragment ID (the part after the # symbol) in the browser's location bar. Whenever the fragment ID changes for any reason (for example, because the user pressed the back button, navigated to a bookmarked URL, or simply typed a fragment ID by hand), the widget in the navigation panel is replaced by the widget associated with that fragment ID. Likewise, when the application asks the navigation system to follow a link, the fragment ID in the browser's location bar is updated to reflect the new current page.

Declaring a Page

To declare a page, annotate any subclass of Widget with the @Page annotation:

By default, the name of a page is the simple name of the class that declares it. In the above example, the ItemListPage will fill the navigation panel whenever the browser's location bar ends with #ItemListPage. If you prefer a different page name, use the @Page annotation's path attribute:

Navigation and Errai UI
Any widget can be a page. This includes Errai UI @Templated classes! Simply annotate any Errai UI templated class with @Page, and it will become a page that can be navigated to.

The Starting Page

Each application must have exactly one starting page. This requirement is enforced at compile time. The starting page is displayed when there is no fragment ID present in the browser's location bar.

Use the startingPage attribute to declare the starting page, like this:

Pages are looked up as CDI beans, so you can inject other CDI beans into fields or a constructor. Pages can also have @PostConstruct and @PreDestroy CDI methods.

Page Lifecycle

There are four annotations related to page lifecycle events: @PageShowing, @PageShown, @PageHiding, and @PageHidden. These annotations designate methods so a page widget can be notified when it is displayed or hidden:

Page Lifecycle:

  1. The fragment identifier in the URL changes
  2. The @PageHiding method on the current (about-to-be-navigated-away-from) page is invoked
  3. The current page is removed from the browser's DOM
  4. The @PageHidden method on the just-removed page is invoked
  5. The navigation system looks up the corresponding @Page bean in the client-side bean manager (we'll call this bean "the new page")
  6. The navigation system writes to all @PageState fields in the new page bean (more on this in the next section)
  7. The @PageShowing method of the new page is invoked
  8. The new page widget is added to the DOM (as a direct child of the navigation content panel)
  9. The @PageShown method of the new page is invoked.

The @PageShowing and @PageShown methods are permitted one optional parameter of type HistoryToken---more on this in the next section.

The lifespan of a Page instance is governed by CDI scope: Dependent and implict-scoped page beans are instantiated each time the user navigates to them, whereas Singleton and ApplicationScoped beans are created only once over the lifetime of the application. If a particular page is slow to appear because its UI takes a lot of effort to build, try marking it as a singleton.

Page State Parameters

A page widget will often represent a view on on instance of a class of things. For example, there might be an ItemPage that displays a particular item available at a store. In cases like this, it's important that the bookmarkable navigation URL includes not only the name of the page but also an identifier for the particular item being displayed.

This is where page state parameters come in. Consider the following page widget:

This page would be reachable at a URL like;itemId=4. Before the page was displayed, the Errai UI Navigation framework would write the int value 4 into the itemId field.

There are three ways to pass state information to a page: by passing a Multimap to TransitionTo.go(); by passing a Multimap to Navigation.goTo(), or by including the state information in the fragment identifier of a hyperlink as illustrated in the previous paragraph (use the HistoryToken class to construct such a fragment ID properly.)

A page widget can have any number of @PageState fields. The fields can be of any primitive or boxed primitive type (except char or Character), String, or a Collection, List, or Set of the allowable scalar types. Nested collections are not supported.

@PageState fields can be private, protected, default access, or public. They are always updated by direct field access; never via a setter method. The updates occur just before the @PageShowing method is invoked.

In addition to receiving page state information via direct writes to @PageState fields, you can also receive the whole Multimap in the @PageShowing and @PageShown methods through a parameter of type HistoryToken. Whether or not a lifecycle method has such a parameter, the @PageState fields will still be written as usual.

Page state values are represented in the URL much like HTML form parameters: as key=value pairs separated by the ampersand (&) character. Multi-valued page state fields are represented by repeated occurrences of the same key. If a key corresponding to a @PageState field is absent from the state information passed to the page, the framework writes a default value: null for scalar Object fields, the JVM default (0 or false) for primitives, and an empty collection for collection-valued fields. To construct and parse state tokens programmatically, use the HistoryToken class.

Declaring a Link with TransitionAnchor

The easiest way to declare a link between pages is to inject an instance of TransitionAnchor<P>, where P is the class of the target page.

Here is an example declaring an anchor link from the templated welcome page to the item list page. The first code sample would go in while the second would go in the WelcomePage.html, the associated html template.

You can inject any number of links into a page. The only restriction is that the target of the link must be a Widget type that is annotated with @Page. When the user clicks the link Errai will transition to the item list page.

Declaring a Manual Link

Sometimes it is necessary to manually transition between pages (such as in response to an event being fired). To declare a manual link from one page to another, inject an instance of TransitionTo<P>, where P is the class of the target page.

This code declares a manual transition from the welcome page to the item list page:

You do not need to implement the TransitionTo interface yourself; the framework creates the appropriate instance for you.

As with TransitionAnchor, the only restriction is that the target of the link must be a Widget type that is annotated with @Page.

Following a Manual Link

To follow a manual link, simply call the go() method on an injected TransitionTo object. For example:

Installing the Navigation Panel into the User Interface

Beginning in version 2.4, Errai will automatically attach the Navigation Panel to the Root Panel, but it is possible to override this behaviour by simply adding the Navigation Panel to another component manually. The best time to do this is during application startup, for example in the @PostConstruct method of your @EntryPoint class. By using the default behaviour you can allow Errai Navigation to control the full contents of the page, or you can opt to keep some parts of the page (headers, footers, and sidebars, for example) away from Errai Navigation by choosing an alternate location for the Navigation Panel.

The following example reserves space for header and footer content that is not affected by the navigation system:

This last example demonstrates a simple approach to defining the page structure with an Errai UI template. The final product is identical to the above example, but in this case the overall page structure is declared in an HTML template rather than being defined programmatically in procedural logic:

Overriding the default Nagivating Panel type

By default Errai uses {{com.​google.​gwt.​user.​client.​ui.SimplePanel}} as a container for navigation panel. Sometimes this is not sufficient and users would prefer using another implementation. For example a that manages child size state.

To provide your own implementation of the navigation panel you must implement org.jboss.errai.ui.nav.client.local.NavigatingContainer. For example:

Then in your GWT module descriptor you need to override the default navigation panel (org.jboss.errai.ui.nav.client.local.NavigatingContainer) by adding:

Viewing the Generated Navigation Graph

Because the pages and links in an Errai Navigation application are declared structurally, the framework gets a complete picture of the app's navigation structure at compile time. This knowledge is saved out during compilation (and at page reload when in Dev Mode) to the file .errai/navgraph.gv. You can view the navigation graph using any tool that understands the GraphViz (also known as DOT) file format.

One popular open source tool that can display GraphViz/DOT files is GraphViz. Free downloads are available for all major operating systems.

When rendered, a navigation graph looks like this:

In the rendered graph, the pages are nodes (text surrounded by an ellipse). The starting page is drawn with a heavier stroke. The links are drawn as arrows from one page to another. The labels on these arrows come from the Java field names the TransitionTo objects were injected into.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.