You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
= Customizing the sidebar menu items for your {product-short} instance
3
3
4
-
The sidebar menu in {product} consists of two main parts:
4
+
The sidebar menu in {product} consists of two main parts that you can configure:
5
5
6
-
* *Main menu items*: These items are the static menu items that form the core navigation structure of sidebar. These menu items remain consistent and are predefined.
6
+
Dynamic plugin menu items:: Your preferences and your active plugins define dynamically one part of the sidebar menu.
7
+
Main menu items:: The core navigation structure of sidebar is static.
7
8
8
-
* *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.
9
-
10
-
.Procedure
11
-
12
-
. Customize the main menu items using the following steps:
13
-
+
14
-
--
15
-
.. Open the `app-config-rhdh.yaml` file.
16
-
.. To customize the order and parent-child relationships for the main menu items, use the `dynamicPlugins.frontend.default.main-menu-items.menuItems` field.
17
-
.. For dynamic plugin menu items, use the `dynamicPlugins.frontend.<package_name>.menuItems` field.
18
-
19
-
.Example `app-config-rhdh.yaml` file
9
+
.Default static menu item configuration
20
10
[source,yaml]
21
11
----
22
12
dynamicPlugins:
23
13
frontend:
24
-
<package_name>: # same as `scalprum.name` key in plugin's `package.json`
25
-
menuItems: # optional, allows you to configure plugin menu items in the main sidebar navigation
26
-
<menu_item_name>: # unique name in the plugin menu items list <1>
27
-
icon: home | group | category | extension | school | _<your_icon>_ # <2>
28
-
title: My Plugin Page # optional, same as `menuItem.text` in `dynamicRoutes` <3>
29
-
priority: 10 # optional, defines the order of menu items in the sidebar <4>
30
-
parent: favorites # optional, defines parent-child relationships for nested menu items <5>
14
+
default.main-menu-items:
15
+
menuItems:
16
+
default.home:
17
+
title: Home
18
+
icon: home
19
+
priority: 100
20
+
default.my-group:
21
+
title: My Group
22
+
icon: group
23
+
priority: 90
24
+
default.catalog:
25
+
title: Catalog
26
+
icon: category
27
+
to: catalog
28
+
priority: 80
29
+
default.apis:
30
+
title: APIs
31
+
icon: extension
32
+
to: api-docs
33
+
priority: 70
34
+
default.learning-path:
35
+
title: Learning Paths
36
+
icon: school,
37
+
to: learning-paths
38
+
priority: 60
39
+
default.create:
40
+
title: Create
41
+
icon: add
42
+
to: create
43
+
priority: 50
31
44
----
32
45
33
-
You can modify the fields in the previous example to configure the desired order and parent-child relationships of the sidebar menu items.
34
-
35
-
<1> This attribute represents a unique name in the main sidebar navigation. It can denote either a standalone menu item or a parent menu item. If this attribute represents a plugin menu item, the name of the attribute must match with the corresponding path in `dynamicRoutes`. For example, if `dynamicRoutes` defines `path: /my-plugin`, then `menu_item_name` must be defined as `my-plugin`.
36
-
+
37
-
For more complex, multi-segment paths such as `path: /metrics/users/info`, the `menu_item_name` must use dot notation to represent the full path, for example, `metrics.users.info`. Trailing and leading slashes in paths are ignored. For example, `path: /docs` results in `menu_item_name: docs`, and `path: /metrics/users` results in `menu_item_name: metrics.users`.
46
+
.Procedure
38
47
39
-
<2> This optional attribute specifies the icon for the menu item. You can use default icons or extend the icon set with dynamic plugins. {product-short} also provides additional icons in its internal library, such as:
48
+
. 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:
40
49
+
41
-
.Home Icon in the internal library
42
-
[source, yaml]
50
+
[source,yaml]
43
51
----
44
52
dynamicPlugins:
45
53
frontend:
46
-
<package_name>:
54
+
_<plugin_name>_: # <1>
47
55
menuItems:
48
-
<menu_item_name>:
49
-
icon: home
56
+
<menu_item_name>: # <2>
57
+
icon: # home | group | category | extension | school | _<my_icon>_ # <3>
58
+
title: _<plugin_page_title>_ # <4>
59
+
priority: 10 # <5>
60
+
parent: favorites # <6>
50
61
----
51
-
+
52
-
Similarly, the internal library includes icons for `group`, `category`, `extension`, and `school`. If the icon is already defined in the `dynamicRoutes` configuration under `menuItem.icon`, it can be removed from the in the `menuItems` configuration. Also, both SVG and HTML image icons are supported. For example:
<3> This optional attribute specifies the title of the menu item. It can be removed if the title is already specified in the `dynamicRoutes` configuration under `menuItem.text`.
67
-
68
-
<4> This optional attribute 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 attribute for each section.
69
-
70
-
<5> This optional attribute specifies the parent menu item under which the current item is nested. If this attribute is used, the parent menu item must be defined elsewhere in the `menuItems` configuration of any enabled plugin. You can define this attribute for each section.
62
+
<1> `_<plugin_name>_`: Enter the plugin name. This name is the same as the `scalprum.name` key in the `package.json` file.
63
+
<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`.
64
+
<3> `icon`: (Optional) Enter the icon name. You can use any of the following icons:
65
+
* Default icons, such as `home`, `group`, `category`, `extension`, and `school`. To use default icons, set the icon as an (`" "`) empty string.
66
+
* A custom icon, where _<my_icon>_ specifies the name of your custom icon
67
+
* 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>`
68
+
* An HTML image, such as: `icon: https://img.icons8.com/ios-glyphs/20/FFFFFF/shop.png`
69
+
<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.
70
+
// Update <4> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333.
71
+
<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.
72
+
<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.
71
73
74
+
+
72
75
.Example `menuItems` configuration
73
-
[source,yaml]
76
+
[source,yaml,subs="+attributes"]
74
77
----
75
78
dynamicPlugins:
76
79
frontend:
77
-
<package_name>:
80
+
_<package_name>_:
78
81
dynamicRoutes:
79
82
- path: /my-plugin
80
83
module: CustomModule
@@ -83,47 +86,80 @@ dynamicPlugins:
83
86
icon: fooIcon
84
87
text: Foo Plugin Page
85
88
menuItems:
86
-
my-plugin: # matches `path` in `dynamicRoutes`
87
-
priority: 10 # controls order of plugins under the parent menu item
88
-
parent: favorites # nests this plugin under the `favorites` parent menu item
89
-
favorites: # configuration for the parent menu item
90
-
icon: favorite # icon from RHDH system icons
91
-
title: Favorites # title for the parent menu item
92
-
priority: 100 # controls the order of this top-level menu item
89
+
my-plugin: # <1>
90
+
priority: 10 # <2>
91
+
parent: favorites # <3>
92
+
favorites: # <4>
93
+
icon: favorite # <5>
94
+
title: Favorites # <6>
95
+
priority: 100 # <7>
93
96
----
94
-
--
97
+
<1> `my-plugin`: Matches the value of the `path` field in `dynamicRoutes`.
98
+
<2> `priority`: Controls order of plugins under the parent menu item.
99
+
<3> `parent`: Nests this plugin under the `favorites` parent menu item.
100
+
<4> `favorites`: Configuration for the parent menu item.
101
+
<5> `icon`: Displays the `favorite` icon from the {product-very-short} system icons.
102
+
<6> `title`: Displays the title name for the parent menu item.
103
+
<7> `priority`: Order of the `favourites` menu item in the sidebar.
95
104
96
-
. To ensure that a menu item is identified as a main menu item, you must add the `default.` prefix to its key. For example:
97
-
+
98
-
--
99
-
.Example configuration of main menu items in sidebar navigation
105
+
106
+
. 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.
107
+
+
100
108
[source,yaml]
101
109
----
102
110
dynamicPlugins:
103
111
frontend:
104
-
default.main-menu-items: # key for configuring static main menu items
105
-
menuItems:
106
-
default.<menu_item_name>: # key of the menu item configuration. `default.` prefix is required for a main menu item key <1>
107
-
parent: my_menu_group # optional, specifies the parent menu item for this item
108
-
priority: 10 # optional, specifies the order of this menu item within its menu level
109
-
default.<menu_group_parent_item_name>: # must be configured if it is specified as the parent of any menu items. `default.` prefix is required for a main group parent item key <1>
110
-
icon: my_menu_group_icon # required for parent menu items, defines the icon for the menu group
111
-
title: my_menu_group_title # required for parent menu items, defines the icon for the menu group
112
-
priority: 100 # optional, specifies the order of the parent menu item in the sidebar
112
+
default.main-menu-items:
113
+
menuItems:
114
+
default._<menu_group_parent_item_name>_: # <1>
115
+
icon: # home | group | category | extension | school | _<my_icon>_ # <2>
116
+
title: _<menu_group_parent_title>_ # <3>
117
+
priority: 10 # <4>
118
+
default._<menu_item_name>_: # <5>
119
+
parent: _<menu_group_parent_item_name>_ # <6>
120
+
icon: # home | group | category | extension | school | _<my_icon>_ # <7>
121
+
title: _<my_menu_title>_ # <8>
122
+
to: _<path_to_the_menu_target_page>_ # <9>
123
+
priority: 100 # <10>
113
124
----
125
+
<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.
126
+
<2> `icon`: Enter the menu icon. Required for parent menu items.
127
+
<3> `title`: Enter the menu group title. Required for parent menu items.
128
+
<4> `priority`: (Optional) Enter the order of this menu item within its menu level.
129
+
<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.
130
+
<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.
131
+
<7> `icon`: (Optional) Enter the menu icon. To use the default icon, set the icon as an (`" "`) empty string.
132
+
<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.
133
+
// Update <8> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333.
134
+
<9> `to`: (Optional) Enter the path that the menu item navigates to. If it is not set, it defaults to the home page.
135
+
<10> `priority`: (Optional) Enter the order of this menu item within its menu level.
114
136
115
-
116
-
<1> The `default.` prefix identifies an item as a main menu item. You can add the `default.` prefix to both individual menu items or parent menu group configuration, such as `default.<menu_group_parent_item_name>` in the previous example.
117
-
118
-
[NOTE]
119
-
====
120
-
The default priority of main menu items determines their order in the sidebar. You can customize the order of the static main menu items by adjusting their priority values. Ensure that the priority and title of each item is clear to facilitate easy reordering.
121
-
====
122
-
--
123
-
124
-
125
-
126
-
127
-
128
-
129
-
137
+
+
138
+
.Example `mainItems` configuration
139
+
[source,yaml]
140
+
----
141
+
default.main-menu-items:
142
+
menuItems:
143
+
default.catalog:
144
+
icon: category # <1>
145
+
title: My Catalog
146
+
priority: 5
147
+
default.learning-path:
148
+
title: '' # <2> to hide the learning path from default sidebar
149
+
default.parentlist: # <3>
150
+
title: Overview
151
+
icon: bookmarks
152
+
default.home:
153
+
parent: default.parentlist # <4>
154
+
default.references:
155
+
title: References # <5>
156
+
icon: school # <6>
157
+
to: /references # <7>
158
+
----
159
+
<1> `icon`: Specifies if you want to change the icon default menu item for the catalog.
160
+
<2> `title`: Specifies an empty string `" "` to hide the learning path from the default sidebar.
161
+
<3> `default.parentlist`: Introduces the parent menu item.
162
+
<4> `parent`: Nests home menu under the `default.parentlist` parent menu item.
163
+
<5> `title`: Specifies a name for `default.references`
164
+
<6> `icon`: Displays the `school` icon.
165
+
<7> `to`: Redirects `default.references` to the `/references` page.
The Home page uses a 12-column grid to position your cards. You can use the optimal parameters to define the layout of your {product-short} Home page.
9
+
8
10
.Prerequisites
9
11
* Include the following optimal parameters in each of your breakpoints:
10
12
** width (w)
11
13
** height (h)
12
14
** position (x and y)
13
15
14
16
.Procedure
15
-
* Configure your {product-short} `app-config.yaml` configuration file by choosing one of the following options:
16
-
** Use the full space on smaller windows and half of the space on larger windows as follows:
17
+
. Configure the layout of the cards on the home page by entering one of the following configurations in your {product-short} `{my-app-config-file}` file.
18
+
* Use the full space on smaller windows and half of the space on larger windows as shown in the following example:
17
19
18
20
[source,yaml]
19
21
----
@@ -36,7 +38,7 @@ dynamicPlugins:
36
38
debugContent: a placeholder
37
39
----
38
40
39
-
** Show the cards side by side by defining the `x` parameter as follows:
41
+
* Show the cards side by side by defining the `x` parameter as shown in the following example:
40
42
41
43
[source,yaml]
42
44
----
@@ -73,7 +75,7 @@ dynamicPlugins:
73
75
----
74
76
However, you can see a second card below this card by default.
75
77
76
-
* Show the cards in three columns by defining the `x` parameter as follows:
78
+
* Show the cards in three columns by defining the `x` parameter as shown in the following example:
Copy file name to clipboardexpand all lines: modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc
= Using a dedicated service to provide data to the Quick access card
8
8
9
-
When using a dedicated service, you can do the following:
9
+
When using a dedicated service, you can do the following tasks:
10
10
11
11
* Use the same service to provide the data to all configurable {product-short} pages or use a different service for each page.
12
12
* Use the https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[`red-hat-developer-hub-customization-provider`] as an example service, which provides data for both the Home and Tech Radar pages. The `red-hat-developer-hub-customization-provider` service provides the same data as default {product-short} data. You can fork the `red-hat-developer-hub-customization-provider` service repository from GitHub and modify it with your own data, if required.
13
13
* Deploy the `red-hat-developer-hub-customization-provider` service and the {product-short} Helm chart on the same cluster.
14
14
15
15
.Prerequisites
16
16
17
-
* You have installed the {product} using Helm Chart.
17
+
* You have installed the {product} using Helm chart.
18
18
For more information, see xref:{installing-on-ocp-book-url}#assembly-install-rhdh-ocp-helm[{installing-on-ocp-book-title} with the Helm chart].
19
19
20
20
.Procedure
@@ -28,12 +28,12 @@ To use a separate service to provide the Home page data, complete the following
28
28
To use the `red-hat-developer-hub-customization-provider` service, add the URL for the https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[red-hat-developer-hub-customization-provider] repository or your fork of the repository containing your customizations.
29
29
--
30
30
31
-
. On the *General* tab, enter *red-hat-developer-hub-customization-provider* in the *Name* field and click *Create*.
32
-
. On the *Advanced Options* tab, copy the value from the *Target Port*.
31
+
. On the *General* tab, enter `red-hat-developer-hub-customization-provider` in the *Name* field and click *Create*.
32
+
. On the *Advanced Options* tab, copy the value from *Target Port*.
33
33
+
34
34
[NOTE]
35
35
====
36
-
The *Target Port* automatically generates a Kubernetes or {ocp-short} service to communicate with.
36
+
*Target Port* automatically generates a Kubernetes or {ocp-short} service to communicate with.
37
37
====
38
38
+
39
39
. Add the following code to the `app-config-rhdh.yaml` file:
@@ -45,12 +45,12 @@ proxy:
45
45
# Other Proxies
46
46
# customize developer hub instance
47
47
'/developer-hub':
48
-
target: ${HOMEPAGE_DATA_URL}
48
+
target: ${HOMEPAGE_DATA_URL} <1>
49
49
changeOrigin: true
50
50
# Change to "false" in case of using self-hosted cluster with a self-signed certificate
51
51
secure: true
52
52
----
53
-
where `HOMEPAGE_DATA_URL` is defined as `pass:c[http://<SERVICE_NAME>:8080]`, for example, `pass:c[http://rhdh-customization-provider:8080]`.
53
+
<1> `pass:c[http://<SERVICE_NAME>:8080]`, for example, `pass:c[http://rhdh-customization-provider:8080]`.
54
54
+
55
55
[NOTE]
56
56
====
@@ -62,11 +62,11 @@ The `red-hat-developer-hub-customization-provider` service contains the 8080 por
62
62
. Delete the {product-short} pod to ensure that the new configurations are loaded correctly.
63
63
64
64
.Verification
65
-
* To view the service, navigate to the *Administrator* perspective in the {ocp-short} web console and click *Networking* > *Service*.
65
+
* To view the service, go to the *Administrator* perspective in the {ocp-short} web console and click *Networking* > *Service*.
66
66
+
67
67
[NOTE]
68
68
====
69
-
You can also view the *Service Resources* in the Topology view.
69
+
You can also view *Service Resources* in the Topology view.
70
70
====
71
71
72
72
* Ensure that the provided API URL for the Home page returns the data in JSON format as shown in the following example:
@@ -109,7 +109,7 @@ You can also view the *Service Resources* in the Topology view.
109
109
If the request call fails or is not configured, the {product-short} instance falls back to the default local data.
110
110
====
111
111
112
-
* If the images or icons do not load, then allowlist them by adding your image or icon host URLs to the content security policy’s (csp) `img-src` in your custom ConfigMap as follows:
112
+
* If the images or icons do not load, then allowlist them by adding your image or icon host URLs to the content security policy (csp) `img-src` in your custom ConfigMap as shown in the following example:
0 commit comments