Typed URL Parameters for Navigation Targets

A navigation target that supports typed parameters passed through the URL should:

  • Implement the HasUrlParameter interface, and

  • Define the parameter type using generics.

HasUrlParameter defines the setParameter method that is called by the Router, based on values extracted from the URL. This method will always be invoked before a navigation target is activated.

Example: Defining a navigation target that takes a string parameter and produces a greeting string from it, which the target then sets as its own text content on navigation:

@Route(value = "greet")
public class GreetingComponent extends Div
        implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event,
                             String parameter) {
        setText(String.format("Hello, %s!", parameter));
    }
}
  • On startup, the navigation target is automatically configured for every greet/<anything> path, except where a separate navigation target with the exact @Route is configured to match greet/<some specific path>.

Note
An exact navigation target always takes precedence when resolving the URL.
Note
The URL defined in the @Route annotation must not include the parameter template placeholder. It is automatically added internally to the URL template.

Optional URL Parameters

URL parameters can be annotated as optional using @OptionalParameter.

Example: Defining the route to match both greet and greet/<anything>:

@Route("greet")
public class OptionalGreeting extends Div
        implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event,
            @OptionalParameter String parameter) {
        if (parameter == null) {
            setText("Welcome anonymous.");
        } else {
            setText(String.format("Welcome %s.",
                  parameter));
        }
    }
}
Note
A more specific route always takes precedence over a parameterised route.

Wildcard URL Parameters

Where more parameters are needed, the URL parameter can also be annotated with @WildcardParameter.

Example: Defining the route to match greet and anything after it, for instance greet/one/five/three:

@Route("greet")
public class WildcardGreeting extends Div
        implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event,
            @WildcardParameter String parameter) {
        if (parameter.isEmpty()) {
            setText("Welcome anonymous.");
        } else {
            setText(String.format(
                  "Handling parameter %s.",
                  parameter));
        }
    }
}
Note
The wildcard parameter will never be null.
Note
More specific routes always take precedence over wildcard routes.

Query Parameters

It is possible to get any query parameters contained in a URL, for example ?name1=value1&name2=value2.

Use the getQueryParameters() method of the Location class to access query parameters. You can obtain the Location class through the BeforeEvent parameter of the setParameter method.

Note
A Location object represents a relative URL made up of path segments and query parameters, without the hostname, for example new Location ("book/search?keyword=Vaadin").
@Override
public void setParameter(BeforeEvent event,
        @OptionalParameter String parameter) {

    Location location = event.getLocation();
    QueryParameters queryParameters = location
            .getQueryParameters();

    Map<String, List<String>> parametersMap =
            queryParameters.getParameters();
}
Note
getQueryParameters() supports multiple values associated with the same key, for example https://example.com/?genre=fiction&restrictions=16+&genre=classic will result in the corresponding map {"genre" : ["fiction", "classic"], "restrictions": ["16+"]}}.