3.5.12. URL History and Navigation

Since7.0

CUBA URL History and Navigation feature provides browser history and navigation functionality which is essential for many web applications. This functionality consists of the following parts:

  • History – support for the browser Back button. The Forward button is not supported due to impossibility to reproduce all conditions of opening a screen.

  • Routes and Navigation – registration and handling of routes to the application screens.

  • Routing API – a set of methods that enables reflecting a current state of the screen in the URL.

A fragment is the last part of the URL after the "#" symbol. It is used as a route value.

For example, consider the following URL:

host:port/app/#main/42/orders/edit?id=17

In this URL, the fragment is main/42/orders/edit?id=17 and it consists of the following parts:

  • main – the route to the root screen (Main Window);

  • 42 – a state mark which is used by internals of the navigation mechanism;

  • orders/edit – the nested screen’s route;

  • ?id=17 – the parameters part.

All opened screens map their routes to the current URL. For example, when the user browser screen is open and currently active, the application URL looks as follows:

http://localhost:8080/app/#main/0/users

If a screen doesn’t have registered route, only a state mark is appended to the URL fragment. For example:

http://localhost:8080/app/#main/42

For editor screens, the edited entity id is added to address as a parameter if the screen has a registered route. For example:

http://localhost:8080/app/#main/1/users/edit?id=27zy3tj6f47p2e3m4w58vdca9y

Identifiers of the UUID type are encoded as Base32 Crockford Encoding, all other types are used as is.

When the user is not logged in but some screen route is requested, the redirect parameter is used. Suppose the app/#main/orders route is entered in the address. When the application is loaded and login screen is shown, the address will be changed to: app/#login?redirectTo=orders. After logging in, the screen corresponding to the orders route will be opened.

If the requested route does non exist, the application shows an empty screen with the "Not Found" caption.

The URL History and Navigation feature is enabled by default. The cuba.web.urlHandlingMode application property allows you to disable it using the NONE value, or to revert to the old mechanism of handling the browser Back button using the BACK_ONLY value.