CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-vaadin--vaadin

Comprehensive Java web application development framework that enables server-side Java development with modern web UI components and automatic client-server communication.

Overview
Eval results
Files

routing.mddocs/

Routing and Navigation

Vaadin's routing system provides declarative, annotation-based navigation for single-page applications. It supports parameterized routes, nested layouts, navigation guards, and programmatic navigation.

Core Imports

// Route definition annotations
import com.vaadin.flow.router.Route;
import com.vaadin.flow.router.PageTitle;
import com.vaadin.flow.router.Menu;
import com.vaadin.flow.router.ParentLayout;
import com.vaadin.flow.router.ErrorRoute;

// Navigation components
import com.vaadin.flow.router.RouterLink;
import com.vaadin.flow.component.html.Anchor;

// Navigation parameters and events
import com.vaadin.flow.router.HasUrlParameter;
import com.vaadin.flow.router.OptionalParameter;
import com.vaadin.flow.router.WildcardParameter;
import com.vaadin.flow.router.BeforeEvent;
import com.vaadin.flow.router.BeforeEnterEvent;
import com.vaadin.flow.router.BeforeLeaveEvent;
import com.vaadin.flow.router.AfterNavigationEvent;

// Navigation lifecycle interfaces
import com.vaadin.flow.router.BeforeEnterObserver;
import com.vaadin.flow.router.BeforeLeaveObserver;
import com.vaadin.flow.router.AfterNavigationObserver;

// Navigation control and events
import com.vaadin.flow.router.NavigationTrigger;
import com.vaadin.flow.router.Location;
import com.vaadin.flow.router.LocationChangeEvent;
import com.vaadin.flow.router.ContinueNavigationAction;

// Route layouts
import com.vaadin.flow.router.RouterLayout;
import com.vaadin.flow.component.HasElement;

// Router and configuration
import com.vaadin.flow.router.Router;
import com.vaadin.flow.router.RouteConfiguration;
import com.vaadin.flow.router.RouteData;
import com.vaadin.flow.router.NavigationResult;

// Route parameters
import com.vaadin.flow.router.RouteParameters;
import com.vaadin.flow.router.QueryParameters;

// Error handling
import com.vaadin.flow.router.HasErrorParameter;
import com.vaadin.flow.router.ErrorParameter;
import com.vaadin.flow.router.RouteNotFoundError;
import com.vaadin.flow.router.InternalServerError;
import com.vaadin.flow.server.NotFoundException;

// Menu system
import com.vaadin.flow.router.MenuConfiguration;
import com.vaadin.flow.router.MenuEntry;

// Security integration
import com.vaadin.flow.server.auth.AnonymousAllowed;
import com.vaadin.flow.server.auth.PermitAll;
import com.vaadin.flow.server.auth.DenyAll;
import com.vaadin.flow.server.auth.RolesAllowed;

// Navigation highlight
import com.vaadin.flow.router.HighlightCondition;
import com.vaadin.flow.router.HighlightAction;

// Core components and UI
import com.vaadin.flow.component.Component;
import com.vaadin.flow.component.UI;
import com.vaadin.flow.component.HasText;
import com.vaadin.flow.component.HasEnabled;
import com.vaadin.flow.component.HtmlComponent;

// Standard Java types
import java.util.Optional;
import java.util.List;
import java.util.Set;
import java.util.Map;
import java.util.EventObject;

Route Definition

@Route Annotation

Primary annotation for defining navigation routes to views.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Route {
    String value() default "";
    Class<? extends RouterLayout> layout() default RouterLayout.class;
    boolean registerAtStartup() default true;
    boolean absolute() default false;
}

@PageTitle Annotation

Sets the browser page title for the route.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface PageTitle {
    String value();
}

@Menu Annotation

Integrates the route with Vaadin's menu system.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Menu {
    String title() default "";
    double order() default 0.0;
    String icon() default "";
}

Basic Navigation

RouterLink

Component for creating navigation links between views.

public class RouterLink extends Component implements HasText, HasEnabled {
    public RouterLink();
    public RouterLink(String text, Class<? extends Component> navigationTarget);
    public RouterLink(String text, Class<? extends Component> navigationTarget, Object parameter);

    // Navigation target
    public void setRoute(Class<? extends Component> route);
    public void setRoute(Class<? extends Component> route, Object parameter);
    public void setRoute(Class<? extends Component> route, List<Object> parameters);

    // Appearance
    public void setText(String text);
    public String getText();
    public void setTabIndex(int tabIndex);

    // Highlight
    public void setHighlightCondition(HighlightCondition<RouterLink> highlightCondition);
    public void setHighlightAction(HighlightAction<RouterLink> highlightAction);
}

Anchor

HTML anchor component for external links and downloads.

public class Anchor extends HtmlComponent implements HasText, HasEnabled {
    public Anchor();
    public Anchor(String href);
    public Anchor(String href, String text);

    public void setHref(String href);
    public String getHref();
    public void setTarget(String target);
    public String getTarget();
    public void setText(String text);
    public String getText();
}

Parameterized Routes

HasUrlParameter Interface

Interface for views that accept URL parameters.

public interface HasUrlParameter<T> {
    void setParameter(BeforeEvent event, T parameter);
    void setParameter(BeforeEvent event, @OptionalParameter T parameter);
    void setParameter(BeforeEvent event, @WildcardParameter String parameter);
}

Route Parameters

Support for various parameter types in URLs.

// Optional parameter annotation
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface OptionalParameter {
}

// Wildcard parameter annotation
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface WildcardParameter {
}

Navigation Lifecycle

Navigation Event Interfaces

Interfaces for handling navigation lifecycle events.

public interface BeforeEnterObserver {
    void beforeEnter(BeforeEnterEvent event);
}

public interface BeforeLeaveObserver {
    void beforeLeave(BeforeLeaveEvent event);
}

public interface AfterNavigationObserver {
    void afterNavigation(AfterNavigationEvent event);
}

Navigation Events

Event classes providing navigation context and control.

public class BeforeEnterEvent extends EventObject {
    public Location getLocation();
    public NavigationTrigger getTrigger();
    public UI getUI();

    // Navigation control
    public void forwardTo(String route);
    public void forwardTo(Class<? extends Component> routeTarget);
    public void rerouteTo(String route);
    public void rerouteTo(Class<? extends Component> routeTarget);

    // Parameter access
    public RouteParameters getRouteParameters();
    public QueryParameters getQueryParameters();

    // Error handling
    public boolean hasErrorParameter();
    public ErrorParameter<?> getErrorParameter();
}

public class BeforeLeaveEvent extends EventObject {
    public Location getLocation();
    public NavigationTrigger getTrigger();
    public UI getUI();

    // Navigation control
    public void postpone();
    public ContinueNavigationAction getContinueNavigationAction();
}

public class AfterNavigationEvent extends EventObject {
    public Location getLocation();
    public LocationChangeEvent getLocationChangeEvent();
    public List<Component> getActiveChain();
}

Navigation Trigger

Enum indicating how navigation was triggered.

public enum NavigationTrigger {
    USER,           // User-initiated navigation
    PROGRAMMATIC,   // Programmatic navigation
    ROUTER_LINK,    // RouterLink click
    HISTORY,        // Browser history navigation
    REFRESH         // Page refresh
}

Route Layouts

RouterLayout Interface

Interface for components that serve as layout containers for routed content.

public interface RouterLayout extends Component {
    void showRouterLayoutContent(HasElement content);

    // Optional lifecycle methods
    default void afterNavigation(AfterNavigationEvent event) {}
    default void beforeEnter(BeforeEnterEvent event) {}
    default void beforeLeave(BeforeLeaveEvent event) {}
}

ParentLayout Annotation

Specifies parent layouts for nested layout structures.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface ParentLayout {
    Class<? extends RouterLayout> value();
}

Programmatic Navigation

UI Navigation Methods

Methods for programmatic navigation within the current UI.

public class UI extends Component {
    // Navigation
    public void navigate(String location);
    public void navigate(Class<? extends Component> navigationTarget);
    public void navigate(Class<? extends Component> navigationTarget, Object parameter);
    public void navigate(Class<? extends Component> navigationTarget, RouteParameters parameters);

    // Current location
    public Location getInternals().getActiveViewLocation();
    public Router getRouter();
}

Router Class

Core routing functionality and configuration.

public class Router {
    public Optional<NavigationResult> navigate(UI ui, Location location, NavigationTrigger trigger);
    public void reconfigure(RouteConfiguration configuration);
    public RouteConfiguration getConfiguration();

    // Route resolution
    public Optional<String> getUrl(Class<? extends Component> navigationTarget);
    public Optional<String> getUrl(Class<? extends Component> navigationTarget, RouteParameters parameters);
}

Route Configuration

RouteConfiguration

Configuration and registration of routes.

public class RouteConfiguration {
    public static RouteConfiguration forSessionScope();
    public static RouteConfiguration forApplicationScope();

    // Route registration
    public void setRoute(String path, Class<? extends Component> navigationTarget);
    public void setRoute(String path, Class<? extends Component> navigationTarget,
                        Class<? extends RouterLayout> parentLayout);
    public void removeRoute(String path);
    public void removeRoute(Class<? extends Component> navigationTarget);

    // Route information
    public List<RouteData> getAvailableRoutes();
    public Optional<Class<? extends Component>> getRoute(String path);
    public Optional<String> getTemplate(Class<? extends Component> navigationTarget);

    // Parent chain
    public List<Class<? extends RouterLayout>> getParentLayouts(Class<? extends Component> navigationTarget);
}

RouteData

Information about registered routes.

public class RouteData {
    public String getUrl();
    public List<Class<?>> getParameterTypes();
    public Class<? extends Component> getNavigationTarget();
    public List<Class<? extends RouterLayout>> getParentLayouts();
    public String getTemplate();
}

Route Parameters and Query Parameters

RouteParameters

Container for route path parameters.

public class RouteParameters {
    public static RouteParameters empty();
    public static RouteParameters of(String name, String value);
    public static RouteParameters of(String name1, String value1, String name2, String value2);

    public Optional<String> get(String name);
    public String getOrDefault(String name, String defaultValue);
    public Set<String> getParameterNames();
    public Map<String, String> getParameters();

    public RouteParameters and(String name, String value);
    public RouteParameters and(RouteParameters other);
}

QueryParameters

Container for URL query parameters.

public class QueryParameters {
    public static QueryParameters empty();
    public static QueryParameters simple(Map<String, String> parameters);
    public static QueryParameters full(Map<String, List<String>> parameters);

    public Optional<String> getSingleParameter(String name);
    public List<String> getParameters(String name);
    public Set<String> getParameterNames();
    public Map<String, List<String>> getParameters();

    public String getQueryString();
}

Location

Represents a navigation location with path and query parameters.

public class Location {
    public Location(String path);
    public Location(String path, QueryParameters queryParameters);

    public String getPath();
    public List<String> getSegments();
    public String getPathWithQueryParameters();
    public QueryParameters getQueryParameters();

    public Location toggleTrailingSlash();
    public Location appendSegment(String segment);
    public Location appendPath(String path);
}

Error Handling

Error Routes

Special routes for handling navigation errors.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface ErrorRoute {
    Class<? extends RouterLayout> layout() default RouterLayout.class;
}

HasErrorParameter Interface

Interface for error handling views.

public interface HasErrorParameter<T extends Exception> {
    int setErrorParameter(BeforeEnterEvent event, ErrorParameter<T> parameter);
}

public class ErrorParameter<T extends Exception> {
    public T getException();
    public String getCustomMessage();
    public boolean hasCustomMessage();
    public Class<T> getCaughtExceptionType();
}

Standard Error Views

Built-in error handling components.

public class RouteNotFoundError extends Component implements HasErrorParameter<NotFoundException> {
    public int setErrorParameter(BeforeEnterEvent event, ErrorParameter<NotFoundException> parameter);
}

public class InternalServerError extends Component implements HasErrorParameter<Exception> {
    public int setErrorParameter(BeforeEnterEvent event, ErrorParameter<Exception> parameter);
}

Menu Integration

Menu Configuration

Programmatic menu configuration and management.

public class MenuConfiguration {
    public static MenuConfiguration getMenuConfiguration(UI ui);

    // Menu items
    public void addMenuItem(MenuEntry menuEntry);
    public void removeMenuItem(String path);
    public List<MenuEntry> getMenuEntries();

    // Menu structure
    public void setMenuOrder(List<String> menuOrder);
    public List<String> getMenuOrder();
}

public class MenuEntry {
    public MenuEntry(String path, String title);
    public MenuEntry(String path, String title, double order);
    public MenuEntry(String path, String title, String icon);

    public String getPath();
    public String getTitle();
    public double getOrder();
    public String getIcon();
    public Class<? extends Component> getMenuClass();
}

Navigation Guards

Route Access Control

Integration with security frameworks for route protection.

// Spring Security integration
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface AnonymousAllowed {
}

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface PermitAll {
}

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface DenyAll {
}

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RolesAllowed {
    String[] value();
}

Usage Examples

Basic Route Definition

@Route("users")
@PageTitle("User Management")
@Menu(title = "Users", order = 1.0, icon = "vaadin:users")
public class UserView extends VerticalLayout {
    public UserView() {
        add(new H1("User Management"));
        // View content
    }
}

Parameterized Route

@Route("user/:userID")
@PageTitle("User Details")
public class UserDetailsView extends VerticalLayout implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event, String userID) {
        User user = userService.findById(userID);
        if (user == null) {
            event.rerouteTo(NotFoundView.class);
            return;
        }
        showUserDetails(user);
    }
}

Navigation Guards

@Route("admin")
@RolesAllowed("ADMIN")
public class AdminView extends VerticalLayout implements BeforeEnterObserver {

    @Override
    public void beforeEnter(BeforeEnterEvent event) {
        if (!hasAdminAccess()) {
            event.rerouteTo(AccessDeniedView.class);
        }
    }
}

Nested Layouts

@Route(value = "main", layout = MainLayout.class)
public class MainView extends VerticalLayout {
    // View implementation
}

@ParentLayout(AppLayout.class)
public class MainLayout extends VerticalLayout implements RouterLayout {
    @Override
    public void showRouterLayoutContent(HasElement content) {
        getElement().appendChild(content.getElement());
    }
}

Programmatic Navigation

public void navigateToUser(String userId) {
    UI.getCurrent().navigate("user/" + userId);

    // Or with type safety
    UI.getCurrent().navigate(UserDetailsView.class, userId);

    // With route parameters
    RouteParameters params = new RouteParameters("userID", userId);
    UI.getCurrent().navigate(UserDetailsView.class, params);
}

The routing system provides comprehensive navigation capabilities for building complex single-page applications with proper URL management, browser history support, and deep linking.

Install with Tessl CLI

npx tessl i tessl/maven-com-vaadin--vaadin

docs

components.md

data-binding.md

data-components.md

index.md

layouts.md

routing.md

security.md

server-communication.md

theming.md

tile.json