From d0bf25a8621d8066b414889ae8ac416fd996e937 Mon Sep 17 00:00:00 2001 From: Tomi Virtanen Date: Mon, 7 Oct 2024 16:56:13 +0300 Subject: [PATCH 1/2] docs: document MenuConfiguration Renamed menu-registry to menu-configuration. Updated content to match with new simpler public API of MenuConfiguration. MenuRegistry was changed to internal API and only new public API is documented. RelatedTo: vaadin/flow#20063 --- .../flow/advanced/menu-configuration.adoc | 48 +++++++++ articles/flow/advanced/menu-registry.adoc | 102 ------------------ articles/flow/integrations/hilla.adoc | 2 +- 3 files changed, 49 insertions(+), 103 deletions(-) create mode 100644 articles/flow/advanced/menu-configuration.adoc delete mode 100644 articles/flow/advanced/menu-registry.adoc diff --git a/articles/flow/advanced/menu-configuration.adoc b/articles/flow/advanced/menu-configuration.adoc new file mode 100644 index 0000000000..d4fb212f5a --- /dev/null +++ b/articles/flow/advanced/menu-configuration.adoc @@ -0,0 +1,48 @@ +--- +title: Menu Configuration +description: Collecting menu annotated routes for menu generation. +order: 115 +--- + + += Menu Configuration + +To generate a custom menu there's the [classname]`MenuConfiguration` for collecting defined server and client routes. Client routes are collected from the FileSystem routes definition. Server routes are collected for routes annotated with [annotationname]`@Menu`. + +The collected menu items are filtered by access control from the [classname]`UI` ([classname]`NavigationAccessControl` and [classname]`ViewAccessChecker`). If the application has login and route defined `Roles`, the returned list is filtered for only available routes. + + +== Creating Routes Menu + +For a Flow application, any route annotated with [annotationname]`@Menu` is eligible for automatic collection. + +To get the available menu routes, call the static method `MenuConfiguration.getMenuEntries()`. This returns a [classname]`List`. It would make creating a simple menu using [classname]`Anchor` look like this: + +[source,java] +---- +List menuEntries = MenuConfiguration.getMenuEntries(); +menuEntries.forEach(entry -> layout.add(new Anchor(entry.path(), entry.title()))); +---- + +== Data Returned for Menu Entries + +The [classname]`MenuEntry` for the route contains information on the route. Using this data, it's possible to populate a menu, automatically. + +The data contained is as follows: + +`path`:: +Route path that should be used for navigation. + +`title`:: +Title set in the [annotationname]`@Menu` annotation or the [annotationname]`@PageTitle` if defined; else the class simple name. For the client, title is populated from the FS router data. + +`order`:: +Order number for the menu entry if defined. + +`icon`:: +Icon to use in the menu. The value can be entered inside a `` element's `icon` attribute. This accepts icon group and a name like `vaadin:file`. Or the value can be given in `` element's `src` attribute, which takes the path to the icon (e.g., `line-awesome/svg/lock-open-solid.svg`). + +`menuClass`:: +Source class of the [annotationname]`@Menu` annotation. Always null for client routes. + +[discussion-id]`647922A8-D542-4FA7-AAF6-44D40FC6A33B` diff --git a/articles/flow/advanced/menu-registry.adoc b/articles/flow/advanced/menu-registry.adoc deleted file mode 100644 index 2d6b90e300..0000000000 --- a/articles/flow/advanced/menu-registry.adoc +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Menu Registry -description: Collecting menu annotated routes for menu generation. -order: 115 ---- - - -= Menu Registry - -To generate a custom menu there's the [classname]`MenuRegistry` for collecting defined server and client routes. Client routes are collected from the FileSystem routes definition. Server routes are collected for routes annotated with [annotationname]`@Menu`. - -The collected menu items are filtered by access control from the [classname]`UI` ([classname]`NavigationAccessControl` and [classname]`ViewAccessChecker`). If the application has login and route defined `Roles`, the returned list is filtered for only available routes. - - -== Creating Routes Menu - -For a Flow application, any route annotated with [annotationname]`@Menu` is eligible for automatic collection. - -To get the available menu routes, call the static method `MenuRegistry.collectMenuItems()`. This returns a [classname]`Map`. The key in the returned map is the route path that should be used for navigation. It would make creating a simple menu using [classname]`Anchor` look like this: - -[source,java] ----- -Map menuItems = MenuRegistry.collectMenuItems(); -menuItems.forEach((path, info) -> layout.add(new Anchor(path, info.menu().title()))); ----- - - -=== Only Server Routes for Hybrids - -For a hybrid application in which only server menu items are wanted, there's the static method [methodname]`collectAndAddServerMenuItems`. It takes in the [classname]`RouteConfiguration` to use, and a [classname]`Map` into which to populate the routes. - -This could be called as follows: - -[source,java] ----- -Map menuRoutes = new HashMap<>(); -MenuRegistry.collectAndAddServerMenuItems(RouteConfiguration.forApplicationScope(), menuRoutes); ----- - - -== Creating Client Routes Menu on Server - -For client routes, the same static method `MenuRegistry.collectMenuItems()` can also be used to get server routes. - - -=== Only Client Routes for Hybrids - -To collect only the client routes, [classname]`MenuRegistry` has the method [methodname]`getClientRoutes(boolean filterClientViews, AbstractConfiguration configuration)`. The `boolean filterClientViews` is used to define whether the accessible client routes should be removed from the result. The required configuration can be gotten from the [classname]`VaadinService` method, [methodname]`getDeploymentConfiguration()`. - -For a full list, there's also the shorthand method [methodname]`getClientRoutes()` in [classname]`FrontendUtils`. For creating a client menu, see <>. - - -== Data Returned for Menu Items - -The [classname]`AvailableViewInfo` for the route contains information on the route. Using this data, it's possible to populate a menu, automatically. - -The data contained is as follows: - -`title`:: -The [annotationname]`@PageTitle` if defined; else the class simple name. For the client, title is populated from the FS router data. - -`rolesAllowed`:: -Array of roles that are allowed for the item. - -`loginRequired`:: -Whether menu route requires a login to be viewed. - -`route`:: -Route for the view. -On the server this should match the array key. For client routes, though, this may be missing parent path parts, if any. - -`lazy`:: -Not in use. Later marks the route as lazy loaded from a different bundle. - -`register`:: -Whether route should be registered automatically into a menu. - -`menu`:: -[classname]`MenuData` on the [annotationname]`@Menu`. See below for menu definitions. - -`children`:: -Hierarchy information on routes below the given view. For client routes only. - -`routeParameters`:: -Defines any route parameters and their [classname]`RouteParamType` - - -Data in [classname]`MenuData`: - -`title`:: -Title set in the annotation or the same as [classname]`AvailableViewInfo.title`. - -`order`:: -Order number for the menu item if defined. - -`exclude`:: -Whether item should be excluded for the automatic menu. - -`icon`:: -Icon to use in the menu. The value can be entered inside a `` element's `icon` attribute. This accepts icon group and a name like `vaadin:file`. Or the value can be given in `` element's `src` attribute, which takes the path to the icon (e.g., `line-awesome/svg/lock-open-solid.svg`). - -[discussion-id]`647922A8-D542-4FA7-AAF6-44D40FC6A33B` diff --git a/articles/flow/integrations/hilla.adoc b/articles/flow/integrations/hilla.adoc index 2d2e5d8bbf..0dec05f033 100644 --- a/articles/flow/integrations/hilla.adoc +++ b/articles/flow/integrations/hilla.adoc @@ -238,7 +238,7 @@ public class MainView extends Div implements RouterLayout { For more information on `RouterLayout`, see <<../routing/layout.adoc#,Router Layouts & Nested Router Targets>>. -Information on dynamic menu item generation, see <<../advanced/menu-registry#,Menu Registry>>. +Information on dynamic menu item generation, see <<../advanced/menu-configuration#,Menu Configuration>>. [NOTE] If the application is using access protection add [annotationname]`@AnonymousAllowed` on the `MainView` so that the request is not denied. From 728c65b07c7d789b3ac1c8cd289655559decf42a Mon Sep 17 00:00:00 2001 From: Tomi Virtanen Date: Tue, 8 Oct 2024 16:34:13 +0300 Subject: [PATCH 2/2] Updated by review comments --- articles/flow/advanced/menu-configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/flow/advanced/menu-configuration.adoc b/articles/flow/advanced/menu-configuration.adoc index d4fb212f5a..b9e28ee756 100644 --- a/articles/flow/advanced/menu-configuration.adoc +++ b/articles/flow/advanced/menu-configuration.adoc @@ -16,7 +16,7 @@ The collected menu items are filtered by access control from the [classname]`UI` For a Flow application, any route annotated with [annotationname]`@Menu` is eligible for automatic collection. -To get the available menu routes, call the static method `MenuConfiguration.getMenuEntries()`. This returns a [classname]`List`. It would make creating a simple menu using [classname]`Anchor` look like this: +To get the available menu routes, call the static method `MenuConfiguration.getMenuEntries()`. This returns a [classname]`List` sorted primarily by order, then by path alphabetically and locale-sensitively. It would make creating a simple menu using [classname]`Anchor` look like this: [source,java] ----