v1 08. Router

Router

The router is the main component inside a Nalu application. It is used to navigate inside the application, generate a url, get the start parameter and cache a controller.

The instance of the router is injected into:

• every controller
• every filter
• every handler.

The router can be used to:

• route inside the navigation
• to generate a route
• provides url parameters from the start url
• manages the caching

Routing

To navigate inside a Nalu application you can use the route-method. The route-method accepts a route and a number of parameters (0 - n). For a successful navigation, the route must be valid. This means, there must be at least one controller, that accepts the route.

A route without parameters can be called like this:

  this.router.route("myShell/myRoute01/myRoute02");

In case the route has parameters, add them as to the method:

  this.router.route("myShell/myRoute01/myRoute02", parameter01, parameter02);

In this case Nalu will add the parameters at the end of the route. The resulting route will look like this:

   myShell/myRoute01/myRoute02/parameter01/parameter02

To set a parameter inside the route, use a '*' inside the route:

  this.router.route("myShell/myRoute01/*/myRoute02", parameter01, parameter02);

This will create the following route:

   myShell/myRoute01/parameter01/myRoute02/parameter02

Using this method:

  this.router.route("myShell/myRoute01/" + parameter01 + "/myRoute02/" + parameter02);

will create a similar result.

Attention:

If you are using useColonForParametersInUrl = true inside the Application annotation, you need to add a ':' before every parameter:

  this.router.route("myShell/myRoute01/:" + parameter01 + "/myRoute02/:" + parameter02);

In case the routing is used in this way:

  this.router.route("myShell/myRoute01/*/myRoute02", parameter01, parameter02);

there is no need to add ':' before parameters, because Nalu will do that for you.

Generating a Route

In case there is a need for a route inside a link, you can use the generate-method of the router. The method accepts a route and a list of parameters (0 - n) and will return the route. Calling the method with the following code:

  this.router.route("myShell/myRoute01/*/myRoute02", parameter01, parameter02);

will return a String that looks like that:

   myShell/myRoute01/parameter01/myRoute02/parameter02

Providing Start Parameters (since 1.1.0)

In case the application is called with parameters, Nalu provides a method inside the router to retrieve this parameter. Calling getStartQueryParameters() without parameters will return a Map<String, String> containing all start parameters.

For example, if the application is called with this url:

http://localhost:8080/myApp/index.html?param1=value01&param2=value02

and you want to access the param2, you can use this code:

  String value = this.router.getStartQueryParameters().get("param1");

to get the value of param1.

Caching

Nalu offers a caching feature. With this feature controllers and/or composites (since v1.3.2-SNAPSHOT) can be cached. This means, once Nalu has routed to a controller and this controller is cached, the instance of this controller (and of course the view) is cached and will be reused in case Nalu routes to this controller again.

To cache a controller, use: this.router.storeInCache(this); inside a controller. To remove the controller from the cache, so that it will be created again, use: this.router.removeFromCache(this);.

You can also cache composites.

Since 1.3.2 there is also a possibility to cache a composite as a singleton, so different sites can share a composite with the same state. You can configure this with the attribute scope in the annotation @Composites of the controllers which contain the composites:

  @Composites({ @Composite(
       name = "myComposite",
       compositeController = MyComposite.class,
       selector = "my-composite",
       scope = Scope.GLOBAL) })

  public class MyCompositeContainerController

There are two kind of scopes:

• Scope.GLOBAL to cache the composite as a singleton (share between components / sites)
• Scope.LOCAL to cache the composite only for this component / site (default)

RouterStateEvent (since 1.3.1)

Nalu will fire a RouterStateEvent in case a routing occurs. The RouterStateEvent provides two informations:

1. state of routing [START_ROUTING | ROUTING_ABORTED | ROUTING_DONE];
2. the current route