Skip to content

RHIDP-6525: Modularizing Customizing #1056

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

RHIDP-6525: Modularizing Customizing #1056

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion assemblies/assembly-customizing-the-appearance.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand Down
9 changes: 9 additions & 0 deletions modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
63 changes: 63 additions & 0 deletions modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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_name>_ plugin. For example:
+
[source,yaml]
----
dynamicPlugins:
frontend:
_<plugin_name>_: # <1>
menuItems:
<menu_item_name>: # <2>
icon: # home | group | category | extension | school | _<my_icon>_ # <3>
title: _<plugin_page_title>_ # <4>
priority: 10 # <5>
parent: favorites # <6>
----
<1> `_<plugin_name>_`: Enter the plugin name. This name is the same as the `scalprum.name` key in the `package.json` file.
<2> `_<menu_item_name>_`: 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 _<my_icon>_ specifies the name of your custom icon
* An SVG icon, such as: `icon: <svg width="20px" height="20px" viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg" fill="#ffffff">...</svg>`
* 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:
_<package_name>_:
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.
140 changes: 6 additions & 134 deletions modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.<package_name>.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.<package_name>.menuItems` field.

.Example `{my-app-config-file}` file
[source,yaml]
Expand Down Expand Up @@ -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_name>_ plugin to your `{my-app-config-file}` file. For example:
+
[source,yaml]
----
dynamicPlugins:
frontend:
_<plugin_name>_: # <1>
menuItems:
<menu_item_name>: # <2>
icon: # home | group | category | extension | school | _<my_icon>_ # <3>
title: _<plugin_page_title>_ # <4>
priority: 10 # <5>
parent: favorites # <6>
----
<1> `_<plugin_name>_`: Enter the plugin name. This name is the same as the `scalprum.name` key in the `package.json` file.
<2> `_<menu_item_name>_`: 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 _<my_icon>_ specifies the name of your custom icon
* An SVG icon, such as: `icon: <svg width="20px" height="20px" viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg" fill="#ffffff">...</svg>`
* 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:
_<package_name>_:
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._<menu_group_parent_item_name>_: # <1>
icon: # home | group | category | extension | school | _<my_icon>_ # <2>
title: _<menu_group_parent_title>_ # <3>
priority: 10 # <4>
default._<menu_item_name>_: # <5>
parent: _<menu_group_parent_item_name>_ # <6>
icon: # home | group | category | extension | school | _<my_icon>_ # <7>
title: _<my_menu_title>_ # <8>
to: _<path_to_the_menu_target_page>_ # <9>
priority: 100 # <10>
----
<1> `default._<menu_group_parent_item_name>_`: (Optional) Enter the menu group parent item name to configure static main menu items. If no `default._<menu_item_name>_` 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._<menu_item_name>_`: 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 <menu_item_name> 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.
----
66 changes: 66 additions & 0 deletions ...s/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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._<menu_group_parent_item_name>_: # <1>
icon: # home | group | category | extension | school | _<my_icon>_ # <2>
title: _<menu_group_parent_title>_ # <3>
priority: 10 # <4>
default._<menu_item_name>_: # <5>
parent: _<menu_group_parent_item_name>_ # <6>
icon: # home | group | category | extension | school | _<my_icon>_ # <7>
title: _<my_menu_title>_ # <8>
to: _<path_to_the_menu_target_page>_ # <9>
priority: 100 # <10>
----
<1> `default._<menu_group_parent_item_name>_`: (Optional) Enter the menu group parent item name to configure static main menu items. If no `default._<menu_item_name>_` 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._<menu_item_name>_`: 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 <menu_item_name> 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.
Loading