URL History and Navigation

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

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

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

  • Routing API - a set of methods that enables reflecting the screen’s current state 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/#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 Screen).

  • 42 - the 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 opened and currently active, the application URL looks as follows:

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

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

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

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

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

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

The redirect parameter is used when the user is not logged in, but some screen route is requested. Suppose the #main/orders route is entered in the address. When the application is loaded, and the login screen is shown, the route will be changed to #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 jmix.ui.url-handling-mode application property allows you to disable it using the NONE value.