com.vaadin.navigator
Class Navigator

java.lang.Object
  com.vaadin.navigator.Navigator

All Implemented Interfaces:

java.io.Serializable

public class Navigator
extends java.lang.Object
implements java.io.Serializable

Navigator utility that allows switching of views in a part of an application. The view switching can be based e.g. on URI fragments containing the view name and parameters to the view. There are two types of parameters for views: an optional parameter string that is included in the fragment (may be bookmarkable). Views can be explicitly registered or dynamically generated and listening to view changes is possible. Note that Navigator is not a component itself but comes with Navigator.SimpleViewDisplay which is a component that displays the selected view as its contents.

Since:

7.0

Author:

Vaadin Ltd

See Also:

Serialized Form

Nested Class Summary

static class	Navigator.ClassBasedViewProvider View provider which maps a single view name to a class to instantiate for the view.
static class	Navigator.ComponentContainerViewDisplay View display that replaces the contents of a ComponentContainer with the active View.
static class	Navigator.EmptyView Empty view component.
static class	Navigator.SimpleViewDisplay View display that is a component itself and replaces its contents with the view.
static class	Navigator.StaticViewProvider View provider which supports mapping a single view name to a single pre-initialized view instance.
static class	Navigator.UriFragmentManager A NavigationStateManager using hashbang fragments in the Page location URI to track views and enable listening to view changes.

Constructor Summary

Navigator(ComponentContainer container)
Create a navigator that is tracking the active view using URI fragments of the current Page and replacing the contents of a ComponentContainer with the active view.

Navigator(NavigationStateManager stateManager, ViewDisplay display)
Create a navigator.

Navigator(Page page, ViewDisplay display)
Create a navigator that is tracking the active view using URI fragments.

Method Summary

void	addProvider(ViewProvider provider) Register a view provider (factory).
void	addView(java.lang.String viewName, java.lang.Class<? extends View> viewClass) Register for a view name a view class.
void	addView(java.lang.String viewName, View view) Register a static, pre-initialized view instance for a view name.
void	addViewChangeListener(ViewChangeListener listener) Listen to changes of the active view.
protected void	fireAfterViewChange(ViewChangeListener.ViewChangeEvent event) Fires an event after the current view has changed.
protected boolean	fireBeforeViewChange(ViewChangeListener.ViewChangeEvent event) Fires an event before an imminent view change.
ViewDisplay	getDisplay() Return the ViewDisplay used by the navigator.
protected NavigationStateManager	getStateManager() Returns the NavigationStateManager that is used to get, listen to and manipulate the navigation state used by this Navigator.
void	navigate() Navigates to the current navigation state.
void	navigateTo(java.lang.String navigationState) Navigate to a view and initialize the view with given parameters.
protected void	navigateTo(View view, java.lang.String viewName, java.lang.String parameters) Internal method activating a view, setting its parameters and calling listeners.
void	removeProvider(ViewProvider provider) Unregister a view provider (factory).
void	removeView(java.lang.String viewName) Remove view from navigator.
void	removeViewChangeListener(ViewChangeListener listener) Remove a view change listener.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Navigator

public Navigator(ComponentContainer container)

Create a navigator that is tracking the active view using URI fragments of the current Page and replacing the contents of a ComponentContainer with the active view. In case the container is not on the current page, use another Navigator(Page, ViewDisplay) with an explicitly created Navigator.ComponentContainerViewDisplay. All components of the container are removed each time before adding the active Navigator.EmptyView. Views must implement Component when using this constructor.

After all Navigator.EmptyViews and ViewProviders have been registered, the application should trigger navigation to the current fragment using e.g.

 navigator.navigateTo(Page.getCurrent().getFragment());
 

Parameters:

container - ComponentContainer whose contents should be replaced with the active view on view change

Navigator

public Navigator(Page page,
                 ViewDisplay display)

Create a navigator that is tracking the active view using URI fragments.

After all Navigator.EmptyViews and ViewProviders have been registered, the application should trigger navigation to the current fragment using e.g.

 navigator.navigateTo(Page.getCurrent().getFragment());
 

Parameters:

page - whose URI fragments are used

display - where to display the views

Navigator

public Navigator(NavigationStateManager stateManager,
                 ViewDisplay display)

Create a navigator. When a custom navigation state manager is not needed, use the constructor Navigator(Page, ViewDisplay) which uses a URI fragment based state manager. Note that navigation to the initial view must be performed explicitly by the application after creating a Navigator using this constructor.

Parameters:

stateManager - NavigationStateManager keeping track of the active view and enabling bookmarking and direct navigation

display - used to display the views handled by this navigator

Method Detail

navigate

public void navigate()

Navigates to the current navigation state. This method should be called when all required Navigator.EmptyViews, ViewProviders, and ViewChangeListeners have been added to the navigator.

navigateTo

public void navigateTo(java.lang.String navigationState)

Navigate to a view and initialize the view with given parameters. The view string consists of a view name optionally followed by a slash and a parameters part that is passed as-is to the view. ViewProviders are used to find and create the correct type of view. If multiple providers return a matching view, the view with the longest name is selected. This way, e.g. hierarchies of subviews can be registered like "admin/", "admin/users", "admin/settings" and the longest match is used. If the view being deactivated indicates it wants a confirmation for the navigation operation, the user is asked for the confirmation. Registered ViewChangeListeners are called upon successful view change.

Parameters:

navigationState - view name and parameters

navigateTo

protected void navigateTo(View view,
                          java.lang.String viewName,
                          java.lang.String parameters)

Internal method activating a view, setting its parameters and calling listeners. This method also verifies that the user is allowed to perform the navigation operation.

Parameters:

view - view to activate

viewName - (optional) name of the view or null not to change the navigation state

parameters - parameters passed in the navigation state to the view

fireBeforeViewChange

protected boolean fireBeforeViewChange(ViewChangeListener.ViewChangeEvent event)

Fires an event before an imminent view change.

Listeners are called in registration order. If any listener returns false, the rest of the listeners are not called and the view change is blocked.

The view change listeners may also e.g. open a warning or question dialog and save the parameters to re-initiate the navigation operation upon user action.

Parameters:

event - view change event (not null, view change not yet performed)

Returns:

true if the view change should be allowed, false to silently block the navigation operation

getStateManager

protected NavigationStateManager getStateManager()

Returns the NavigationStateManager that is used to get, listen to and manipulate the navigation state used by this Navigator.

Returns:

NavigationStateManager in use

getDisplay

public ViewDisplay getDisplay()

Return the ViewDisplay used by the navigator. Unless another display is specified, a Navigator.SimpleViewDisplay (which is a Component) is used by default.

Returns:

current ViewDisplay

fireAfterViewChange

protected void fireAfterViewChange(ViewChangeListener.ViewChangeEvent event)

Fires an event after the current view has changed.

Listeners are called in registration order.

Parameters:

event - view change event (not null)

addView

public void addView(java.lang.String viewName,
                    View view)

Register a static, pre-initialized view instance for a view name. Registering another view with a name that is already registered overwrites the old registration of the same type.

Parameters:

viewName - String that identifies a view (not null nor empty string)

view - Navigator.EmptyView instance (not null)

addView

public void addView(java.lang.String viewName,
                    java.lang.Class<? extends View> viewClass)

Register for a view name a view class. Registering another view with a name that is already registered overwrites the old registration of the same type. A new view instance is created every time a view is requested.

Parameters:

viewName - String that identifies a view (not null nor empty string)

viewClass - Navigator.EmptyView class to instantiate when a view is requested (not null)

removeView

public void removeView(java.lang.String viewName)

Remove view from navigator. This method only applies to views registered using addView(String, View) or addView(String, Class).

Parameters:

viewName - name of the view to remove

addProvider

public void addProvider(ViewProvider provider)

Register a view provider (factory). Providers are called in order of registration until one that can handle the requested view name is found.

Parameters:

provider - provider to register

removeProvider

public void removeProvider(ViewProvider provider)

Unregister a view provider (factory).

Parameters:

provider - provider to unregister

addViewChangeListener

public void addViewChangeListener(ViewChangeListener listener)

Listen to changes of the active view. The listener will get notified after the view has changed.

Parameters:

listener - Listener to invoke during a view change.

removeViewChangeListener

public void removeViewChangeListener(ViewChangeListener listener)

Remove a view change listener.

Parameters:

listener - Listener to remove.