Getting started with Dynamic Menu

This guide explains the minimal steps to integrate Dynamic Menu in a new application.

Prepare the Application

A new application created on start.vaadin.com can be used as a starting point for this tutorial. Open the site, select an empty project, choose Spring Boot as the framework, and download the generated archive. Extract it, import it into your IDE of choice, and verify the application starts correctly by running the main class.

Add the AppJars Repository

AppJars artifacts are published to the public AppJars Maven repository. Add it to your pom.xml so that Maven can resolve the AppJars dependencies:

<repositories>
    <repository>
        <id>appjars</id>
        <name>AppJars Public Repository</name>
        <url>https://maven.appjars.com</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Add the Dependencies

Given that it is a monolithic application, the following dependencies representing the three layers of the appjar must be added:

<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-dynamic-menu-flow</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-dynamic-menu-data-impl</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-dynamic-menu-business-impl</artifactId>
</dependency>

After adding them, build the application to confirm that the dependencies are resolved correctly.

Implement the Authority Utils

Dynamic Menu needs to know what roles and authorities exist in the application in order to restrict menu items by role. Provide this information by implementing the DynamicMenuAuthorityUtils interface and registering it as a Spring component:

@Primary
@Component
public class AppDynamicMenuAuthorityUtils implements DynamicMenuAuthorityUtils {

    @Override
    public Set<String> getAvailableAuthorities() {
        return Set.of("ROLE_USER", "ROLE_ADMIN");
    }

    @Override
    public String getAnonymousAuthority() {
        return "ROLE_ANONYMOUS";
    }
}

The import for DynamicMenuAuthorityUtils is com.appjars.dynamicmenu.utils.DynamicMenuAuthorityUtils.

• getAvailableAuthorities: Returns the full set of roles or authorities defined in the application. These are presented in the menu item editor when configuring visibility restrictions.
• getAnonymousAuthority: Returns the authority assigned to unauthenticated users.

The @Primary annotation is required. Dynamic Menu ships a default implementation that returns a placeholder set of roles, so without @Primary the application has two candidate beans and startup fails with an ambiguity error.

Configure the Router Layout

Inject the RouteConfigurer provided by Dynamic Menu and configure the router layout in a @PostConstruct method so that the appjar views share the same layout as the rest of the application:

@Autowired
@Qualifier("DynamicMenuRouteConfigurer")
RouteConfigurer routeConfigurer;

@PostConstruct
public void configure() {
    routeConfigurer.setViewsRouterLayout(MainLayout.class);
}

The import for RouteConfigurer is com.appjars.dynamicmenu.flow.view.util.RouteConfigurer.

Add the View to the Navigation

Add the Dynamic Menu view to the application's navigation menu. Insert the following snippet at the end of the method createNavigation() in MainLayout, before returning nav:

if (accessChecker.hasAccess(ListMenuItemsView.class)) {
    nav.addItem(new SideNavItem("Menu Items", ListMenuItemsView.class, LineAwesomeIcon.LIST_SOLID.create()));
}

The import for the view class is:

• com.appjars.dynamicmenu.flow.view.ListMenuItemsView

Configure Application Properties

Add the following properties to application.properties:

spring.jpa.hibernate.ddl-auto=update
spring.jpa.generate-ddl=true
spring.aop.proxy-target-class=false
vaadin.i18n.provider=com.appjars.utils.i18n.AppjarsI18nProvider

The spring.aop.proxy-target-class=false property is required for the appjar to function correctly.

Finally, add com.flowingcode and com.appjars to the list of whitelisted packages in application.properties:

vaadin.allowed-packages = com.vaadin,org.vaadin,dev.hilla,com.example.application,com.flowingcode,com.appjars

Testing the Application

Start the application by running the main Spring Boot class. After it starts, log in and navigate to Menu Items in the navigation menu.

Create a new menu item by clicking the New Menu Item button. Assign it a label, an optional icon, and an internal route pointing to an existing view in the application. Optionally restrict its visibility to specific roles using the permissions field. Once saved, the menu item will be available for use in the application's dynamic navigation.