diff --git a/assemblies/assembly-customizing-the-appearance.adoc b/assemblies/assembly-customizing-the-appearance.adoc index a452248f7..b2b5524e8 100644 --- a/assemblies/assembly-customizing-the-appearance.adoc +++ b/assemblies/assembly-customizing-the-appearance.adoc @@ -25,8 +25,13 @@ include::modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc[ include::modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc[leveloffset=+1] -include::modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+1] +include::modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+1] +include::modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+2] + +include::modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc[leveloffset=+2] + +include::modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc[leveloffset=+2] include::modules/customizing-the-appearance/proc-customizing-entity-tab-titles.adoc[leveloffset=+1] diff --git a/modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc b/modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc new file mode 100644 index 000000000..2c8936032 --- /dev/null +++ b/modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc @@ -0,0 +1,9 @@ +[id='con-customize-rhdh-sidebar-menuitems_{context}'] += Customizing the sidebar menu items for your {product-short} instance + +The sidebar menu in {product} consists of two main parts that you can configure: + +Dynamic plugin menu items:: Your preferences and your active plugins define dynamically one part of the sidebar menu. +Main menu items:: The core navigation structure of sidebar is static. + +* *Dynamic plugin menu items*: These items are displayed beneath the main menu and can be customized based on the plugins installed. The main menu items section is dynamic and can change based on your preferences and installed plugins. \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc b/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc new file mode 100644 index 000000000..04cb849ef --- /dev/null +++ b/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc @@ -0,0 +1,63 @@ +[id='con-customize-rhdh-sidebar-menuitems_{context}'] += Configuring a dynamic plugin menu item for your {product-short} instance + +To configure a dynamic plugin menu item, complete the following step: + +.Procedure + +* In the `{my-app-config-file}` file, update the `menuItems` section of your __ plugin. For example: ++ +[source,yaml] +---- +dynamicPlugins: + frontend: + __: # <1> + menuItems: + : # <2> + icon: # home | group | category | extension | school | __ # <3> + title: __ # <4> + priority: 10 # <5> + parent: favorites # <6> +---- +<1> `__`: Enter the plugin name. This name is the same as the `scalprum.name` key in the `package.json` file. +<2> `__`: Enter a unique name in the main sidebar navigation for either a standalone menu item or a parent menu item. If this field specifies a plugin menu item, the name of the menu item must match the name using in the corresponding path in `dynamicRoutes`. For example, if `dynamicRoutes` defines `path: /my-plugin`, then `menu_item_name` must be defined as `my-plugin`. +<3> `icon`: (Optional) Enter the icon name. You can use any of the following icons: + * Default icons, such as `home`, `group`, `category`, `extension`, and `school`. To use default icons, set the icon as an (`" "`) empty string. + * A custom icon, where __ specifies the name of your custom icon + * An SVG icon, such as: `icon: ...` + * An HTML image, such as: `icon: https://img.icons8.com/ios-glyphs/20/FFFFFF/shop.png` +<4> `title`: (Optional) Enter the menu item title. Omit it when the title is already specified in the `dynamicRoutes` configuration under `menuItem.text`. To hide the title from the sidebar, set the title as an (`" "`) empty string. +// Update <4> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333. +<5> `priority`: (Optional) Sets the order in which menu items appear in the sidebar. The default priority is 0, which places the item at the bottom of the list. A higher priority value places the item higher in the sidebar. You can define this field for each section. +<6> `parent`: (Optional) Enter the parent menu item under which the current item is nested. If this field is used, the parent menu item must be defined elsewhere in the `menuItems` configuration of any enabled plugin. You can define this field for each section. + ++ +.Example `menuItems` configuration +[source,yaml,subs="+attributes"] +---- +dynamicPlugins: + frontend: + __: + dynamicRoutes: + - path: /my-plugin + module: CustomModule + importName: FooPluginPage + menuItem: + icon: fooIcon + text: Foo Plugin Page + menuItems: + my-plugin: # <1> + priority: 10 # <2> + parent: favorites # <3> + favorites: # <4> + icon: favorite # <5> + title: Favorites # <6> + priority: 100 # <7> +---- +<1> `my-plugin`: Matches the value of the `path` field in `dynamicRoutes`. +<2> `priority`: Controls order of plugins under the parent menu item. +<3> `parent`: Nests this plugin under the `favorites` parent menu item. +<4> `favorites`: Configuration for the parent menu item. +<5> `icon`: Displays the `favorite` icon from the {product-very-short} system icons. +<6> `title`: Displays the title name for the parent menu item. +<7> `priority`: Order of the `favourites` menu item in the sidebar. \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc index ce6f7ece1..98e6f36f0 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc @@ -1,21 +1,14 @@ [id='proc-customize-rhdh-sidebar-menuitems_{context}'] = Customizing the sidebar menu items for your {product-short} instance -The sidebar menu in {product} consists of two main parts that you can configure: - -Dynamic plugin menu items:: Your preferences and your active plugins define dynamically one part of the sidebar menu. -Main menu items:: The core navigation structure of sidebar is static. - -* *Dynamic plugin menu items*: These items are displayed beneath the main menu and can be customized based on the plugins installed. The main menu items section is dynamic and can change based on your preferences and installed plugins. +To customize the main menu items, complete the following steps: .Procedure +. Open the `{my-app-config-file}` file. -. Customize the main menu items using the following steps: -+ --- -.. Open the `{my-app-config-file}` file. -.. To customize the order and parent-child relationships for the main menu items, use the `dynamicPlugins.frontend.default.main-menu-items.menuItems` field. -.. For dynamic plugin menu items, use the `dynamicPlugins.frontend..menuItems` field. +. To customize the order and parent-child relationships for the main menu items, use the `dynamicPlugins.frontend.default.main-menu-items.menuItems` field. + +. For dynamic plugin menu items, use the `dynamicPlugins.frontend..menuItems` field. .Example `{my-app-config-file}` file [source,yaml] @@ -52,125 +45,4 @@ dynamicPlugins: icon: add to: create priority: 50 ----- - -.Procedure - -. To configure a dynamic plugin menu item, update the `menuItems` section of your __ plugin to your `{my-app-config-file}` file. For example: -+ -[source,yaml] ----- -dynamicPlugins: - frontend: - __: # <1> - menuItems: - : # <2> - icon: # home | group | category | extension | school | __ # <3> - title: __ # <4> - priority: 10 # <5> - parent: favorites # <6> ----- -<1> `__`: Enter the plugin name. This name is the same as the `scalprum.name` key in the `package.json` file. -<2> `__`: Enter a unique name in the main sidebar navigation for either a standalone menu item or a parent menu item. If this field specifies a plugin menu item, the name of the menu item must match the name using in the corresponding path in `dynamicRoutes`. For example, if `dynamicRoutes` defines `path: /my-plugin`, then `menu_item_name` must be defined as `my-plugin`. -<3> `icon`: (Optional) Enter the icon name. You can use any of the following icons: - * Default icons, such as `home`, `group`, `category`, `extension`, and `school`. To use default icons, set the icon as an (`" "`) empty string. - * A custom icon, where __ specifies the name of your custom icon - * An SVG icon, such as: `icon: ...` - * An HTML image, such as: `icon: https://img.icons8.com/ios-glyphs/20/FFFFFF/shop.png` -<4> `title`: (Optional) Enter the menu item title. Omit it when the title is already specified in the `dynamicRoutes` configuration under `menuItem.text`. To hide the title from the sidebar, set the title as an (`" "`) empty string. -// Update <4> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333. -<5> `priority`: (Optional) Sets the order in which menu items appear in the sidebar. The default priority is 0, which places the item at the bottom of the list. A higher priority value places the item higher in the sidebar. You can define this field for each section. -<6> `parent`: (Optional) Enter the parent menu item under which the current item is nested. If this field is used, the parent menu item must be defined elsewhere in the `menuItems` configuration of any enabled plugin. You can define this field for each section. - -+ -.Example `menuItems` configuration -[source,yaml,subs="+attributes"] ----- -dynamicPlugins: - frontend: - __: - dynamicRoutes: - - path: /my-plugin - module: CustomModule - importName: FooPluginPage - menuItem: - icon: fooIcon - text: Foo Plugin Page - menuItems: - my-plugin: # <1> - priority: 10 # <2> - parent: favorites # <3> - favorites: # <4> - icon: favorite # <5> - title: Favorites # <6> - priority: 100 # <7> ----- -<1> `my-plugin`: Matches the value of the `path` field in `dynamicRoutes`. -<2> `priority`: Controls order of plugins under the parent menu item. -<3> `parent`: Nests this plugin under the `favorites` parent menu item. -<4> `favorites`: Configuration for the parent menu item. -<5> `icon`: Displays the `favorite` icon from the {product-very-short} system icons. -<6> `title`: Displays the title name for the parent menu item. -<7> `priority`: Order of the `favourites` menu item in the sidebar. - - -. To modify a main menu item or add a custom menu item, add a section to the `default.main-menu-items` > `menuItems` section in your `{my-app-config-file}` file. Use the `default.` prefix to identify the key as a main menu item. -+ -[source,yaml] ----- -dynamicPlugins: - frontend: - default.main-menu-items: - menuItems: - default.__: # <1> - icon: # home | group | category | extension | school | __ # <2> - title: __ # <3> - priority: 10 # <4> - default.__: # <5> - parent: __ # <6> - icon: # home | group | category | extension | school | __ # <7> - title: __ # <8> - to: __ # <9> - priority: 100 # <10> ----- -<1> `default.__`: (Optional) Enter the menu group parent item name to configure static main menu items. If no `default.__` has a `parent` value set, this field is not needed. -<2> `icon`: Enter the menu icon. Required for parent menu items. -<3> `title`: Enter the menu group title. Required for parent menu items. -<4> `priority`: (Optional) Enter the order of this menu item within its menu level. -<5> `default.__`: Enter the menu item name for which you want to override the default value. Add the `default.` prefix to identify a main menu item. -<6> `parent`: (Optional) Enter the parent menu item for this item. Required if is specified as the child of any menu items. -<7> `icon`: (Optional) Enter the menu icon. To use the default icon, set the icon as an (`" "`) empty string. -<8> `title`: (Optional) Enter the menu group title. Only required for adding a new custom main menu item. To hide a default main menu item title from the sidebar, set the title as an (`" "`) empty string. -// Update <8> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333. -<9> `to`: (Optional) Enter the path that the menu item navigates to. If it is not set, it defaults to the home page. -<10> `priority`: (Optional) Enter the order of this menu item within its menu level. - -+ -.Example `mainItems` configuration -[source,yaml] ----- -default.main-menu-items: - menuItems: - default.catalog: - icon: category # <1> - title: My Catalog - priority: 5 - default.learning-path: - title: '' # <2> to hide the learning path from default sidebar - default.parentlist: # <3> - title: Overview - icon: bookmarks - default.home: - parent: default.parentlist # <4> - default.references: - title: References # <5> - icon: school # <6> - to: /references # <7> ----- -<1> `icon`: Specifies if you want to change the icon default menu item for the catalog. -<2> `title`: Specifies an empty string `" "` to hide the learning path from the default sidebar. -<3> `default.parentlist`: Introduces the parent menu item. -<4> `parent`: Nests home menu under the `default.parentlist` parent menu item. -<5> `title`: Specifies a name for `default.references` -<6> `icon`: Displays the `school` icon. -<7> `to`: Redirects `default.references` to the `/references` page. \ No newline at end of file +---- \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc b/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc new file mode 100644 index 000000000..20f43aab8 --- /dev/null +++ b/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc @@ -0,0 +1,66 @@ +[id='proc-modifying-or-adding-rhdh-custom-menuitem_{context}'] += Modifying or adding a custom menu items for your {product-short} instance + +To modify a main menu item or add a custom menu item, + +.Procedure +* In the `{my-app-config-file}` file, add a section to the `default.main-menu-items` > `menuItems` section. Use the `default.` prefix to identify the key as a main menu item. ++ +[source,yaml] +---- +dynamicPlugins: + frontend: + default.main-menu-items: + menuItems: + default.__: # <1> + icon: # home | group | category | extension | school | __ # <2> + title: __ # <3> + priority: 10 # <4> + default.__: # <5> + parent: __ # <6> + icon: # home | group | category | extension | school | __ # <7> + title: __ # <8> + to: __ # <9> + priority: 100 # <10> +---- +<1> `default.__`: (Optional) Enter the menu group parent item name to configure static main menu items. If no `default.__` has a `parent` value set, this field is not needed. +<2> `icon`: Enter the menu icon. Required for parent menu items. +<3> `title`: Enter the menu group title. Required for parent menu items. +<4> `priority`: (Optional) Enter the order of this menu item within its menu level. +<5> `default.__`: Enter the menu item name for which you want to override the default value. Add the `default.` prefix to identify a main menu item. +<6> `parent`: (Optional) Enter the parent menu item for this item. Required if is specified as the child of any menu items. +<7> `icon`: (Optional) Enter the menu icon. To use the default icon, set the icon as an (`" "`) empty string. +<8> `title`: (Optional) Enter the menu group title. Only required for adding a new custom main menu item. To hide a default main menu item title from the sidebar, set the title as an (`" "`) empty string. +// Update <8> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333. +<9> `to`: (Optional) Enter the path that the menu item navigates to. If it is not set, it defaults to the home page. +<10> `priority`: (Optional) Enter the order of this menu item within its menu level. + ++ +.Example `mainItems` configuration +[source,yaml] +---- +default.main-menu-items: + menuItems: + default.catalog: + icon: category # <1> + title: My Catalog + priority: 5 + default.learning-path: + title: '' # <2> to hide the learning path from default sidebar + default.parentlist: # <3> + title: Overview + icon: bookmarks + default.home: + parent: default.parentlist # <4> + default.references: + title: References # <5> + icon: school # <6> + to: /references # <7> +---- +<1> `icon`: Specifies if you want to change the icon default menu item for the catalog. +<2> `title`: Specifies an empty string `" "` to hide the learning path from the default sidebar. +<3> `default.parentlist`: Introduces the parent menu item. +<4> `parent`: Nests home menu under the `default.parentlist` parent menu item. +<5> `title`: Specifies a name for `default.references` +<6> `icon`: Displays the `school` icon. +<7> `to`: Redirects `default.references` to the `/references` page. \ No newline at end of file