diff options
Diffstat (limited to 'documentation/advanced/advanced-navigator.asciidoc')
| -rw-r--r-- | documentation/advanced/advanced-navigator.asciidoc | 68 |
1 files changed, 29 insertions, 39 deletions
diff --git a/documentation/advanced/advanced-navigator.asciidoc b/documentation/advanced/advanced-navigator.asciidoc index 7ef5b1ac36..00fedd635e 100644 --- a/documentation/advanced/advanced-navigator.asciidoc +++ b/documentation/advanced/advanced-navigator.asciidoc @@ -10,9 +10,9 @@ layout: page Plain Vaadin applications do not have normal web page navigation as they usually run on a single page, as all Ajax applications do. Quite commonly, however, applications have different views between which the user should be able to -navigate. The [classname]#Navigator# in Vaadin can be used for most cases of -navigation. Views managed by the navigator automatically get a distinct URI -fragment, which can be used to be able to bookmark the views and their states +navigate. Also users often need to have direct links to specific views. The [classname]#Navigator# in Vaadin can be used for most cases of +navigation. Views managed by the navigator automatically get a distinct URI, +which can be used to be able to bookmark the views and their states and to go back and forward in the browser history. [[advanced.navigator.navigating]] @@ -61,17 +61,9 @@ public class NavigatorUI extends UI { } ---- -The [classname]#Navigator# automatically sets the URI fragment of the -application URL. It also registers a [interfacename]#URIFragmentChangedListener# -in the page +The [classname]#Navigator# automatically parses the URI to identify and show the [interfacename]#View#. The browser navigation back and forward are also handled by it. -ifdef::web[] -(see <<dummy/../../../framework/advanced/advanced-urifu#advanced.urifu,"Managing -URI -Fragments">>) -endif::web[] - to show the view identified by the URI fragment if entered or navigated to in -the browser. This also enables browser navigation history in the application. +Starting from [literal]#++8.2.0.alpha2++# there is also PushState based navigation. This new way for the Navigator to manage URLs is described here as well. It is still under development so changes are expected. To enable this feature, add the [classname]#PushStateNavigation# annotation to your UI. [[advanced.navigator.navigating.viewprovider]] === View Providers @@ -95,7 +87,7 @@ You can handle view changes also by implementing a [interfacename]#ViewChangeListener# and adding it to a [classname]#Navigator#. When a view change occurs, a listener receives a [classname]#ViewChangeEvent# object, which has references to the old and the activated view, the name of the -activated view, as well as the fragment parameters. +activated view, as well as the parameters (the part of of URI after the viewname). @@ -104,7 +96,7 @@ activated view, as well as the fragment parameters. Views can be any objects that implement the [interfacename]#View# interface. When the [methodname]#navigateTo()# is called for the navigator, or the -application is opened with the URI fragment associated with the view, the +application is opened with the URI associated with the view, the navigator switches to the view and calls its [methodname]#enter()# method. To continue with the example, consider the following simple start view that just @@ -143,21 +135,23 @@ latter method is that the view is attached to the view container as well as to the UI at that time, which is not the case in the constructor. -[[advanced.navigator.urifragment]] -== Handling URI Fragment Path +[[advanced.navigator.pathparam]] +== Handling Path Parameters -URI fragment part of a URL is the part after a hash [literal]#++#++# character. -Is used for within-UI URLs, because it is the only part of the URL that can be -changed with JavaScript from within a page without reloading the page. The URLs -with URI fragments can be used for hyperlinking and bookmarking, as well as -browser history, just like any other URLs. In addition, an exclamation mark -[literal]#++#!++# after the hash marks that the page is a stateful AJAX page, -which can be crawled by search engines. Crawling requires that the application -also responds to special URLs to get the searchable content. URI fragments are -managed by [classname]#Page#, which provides a low-level API. +By default the URLs managed through the [classname]#Navigator# have a URI fragment +that contains the identifier of the [interfacename]#View#. The URI fragment is +separated from the rest of the URL by a [literal]#++#++# character. -URI fragments can be used with [classname]#Navigator# in two ways: for -navigating to a view and to a state within a view. The URI fragment accepted by +If the [classname]#PushStateNavigation# annotation is present on the [classname]#UI# +the HTML5 History API is used. When using the PushState, the identifier is separated +from the root path by a [literal]#++/++# like a real URL. + +In addition to the View identifier, URI can contain additional parameters to be +passed to views. The parameters are the part of the URI after the longest matching view identifier, separated by [literal]#++/++#. These parameters together with the identifier +form the __navigation state__. + +The navigation state can be used with [classname]#Navigator# in two ways: for +navigating to a view and to a state within a view. The navigation state accepted by [methodname]#navigateTo()# can have the view name at the root, followed by fragment parameters after a slash (" [literal]#++/++#"). These parameters are passed to the [methodname]#enter()# method in the [interfacename]#View#. @@ -202,7 +196,7 @@ public class MainView extends VerticalLayout implements View { navigator.navigateTo(MAINVIEW + "/" + menuitem); } } - + VerticalLayout menuContent; Panel equalPanel; Button logout; @@ -224,19 +218,19 @@ public class MainView extends VerticalLayout implements View { new ButtonListener("sheep"))); // Allow going back to the start - logout.addClickListener(event -> // Java 8 + logout.addClickListener(event -> navigator.navigateTo("")); - } - + } + @DesignRoot class AnimalViewer extends VerticalLayout { Label watching; Embedded pic; Label back; - + public AnimalViewer(String animal) { Design.read(this); - + watching.setValue("You are currently watching a " + animal); pic.setSource(new ThemeResource( @@ -274,12 +268,8 @@ The animal sub-view would have the following declarative design: ---- The main view is shown in <<figure.advanced.navigator.mainview>>. At this point, -the URL would be [literal]#++http://localhost:8080/myapp#!main/reindeer++#. +the URL would be [literal]#++http://localhost:8080/myapp/main/reindeer++#. [[figure.advanced.navigator.mainview]] .Navigator Main View image::img/navigator-mainview.png[] - - - - |