[release-1.4] RHIDP-5433: Applied modularization changes for the Customizing title

modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc

@@ -1,80 +1,83 @@
 [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:
+The sidebar menu in {product} consists of two main parts that you can configure:
 
-* *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.
+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.
-
-.Procedure
-
-. Customize the main menu items using the following steps:
-+
---
-.. Open the `app-config-rhdh.yaml` 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.
-
-.Example `app-config-rhdh.yaml` file
+.Default static menu item configuration
 [source,yaml]
 ----
 dynamicPlugins:
   frontend:
-    <package_name>: # same as `scalprum.name` key in plugin's `package.json`
-      menuItems: # optional, allows you to configure plugin menu items in the main sidebar navigation
-        <menu_item_name>: # unique name in the plugin menu items list <1>
-          icon: home | group | category | extension | school | _<your_icon>_  # <2>
-          title: My Plugin Page # optional, same as `menuItem.text` in `dynamicRoutes` <3>
-          priority: 10 # optional, defines the order of menu items in the sidebar <4>
-          parent: favorites # optional, defines parent-child relationships for nested menu items <5>
+    default.main-menu-items:
+        menuItems:
+          default.home:
+            title: Home
+            icon: home
+            priority: 100
+          default.my-group: 
+            title: My Group
+            icon: group
+            priority: 90
+          default.catalog:
+            title: Catalog
+            icon: category
+            to: catalog
+            priority: 80
+          default.apis:
+            title: APIs
+            icon: extension
+            to: api-docs
+            priority: 70
+          default.learning-path:
+            title: Learning Paths
+            icon: school,
+            to: learning-paths
+            priority: 60
+          default.create:
+            title: Create
+            icon: add
+            to: create
+            priority: 50
 ----
 
-You can modify the fields in the previous example to configure the desired order and parent-child relationships of the sidebar menu items.
-
-<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`.
-+
-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`.
+.Procedure
 
-<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: 
+. 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:
 +
-.Home Icon in the internal library
-[source, yaml]
+[source,yaml]
 ----
 dynamicPlugins:
   frontend:
-    <package_name>:
+    _<plugin_name>_: # <1>
       menuItems:
-        <menu_item_name>: 
-          icon: home
+        <menu_item_name>: # <2>
+          icon: # home | group | category | extension | school | _<my_icon>_ # <3>
+          title: _<plugin_page_title>_ # <4>
+          priority: 10 # <5>
+          parent: favorites # <6>
 ----
-+
-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:
-+
-.Example SVG icon
-[source,html]
-----
-icon: <svg width="20px" height="20px" viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg" fill="#ffffff">...</svg>
-----
-+
-.Example image icon
-[source,html]
-----
-icon: https://img.icons8.com/ios-glyphs/20/FFFFFF/shop.png
-----
-
-<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`.
-
-<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.
-
-<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.
+<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]
+[source,yaml,subs="+attributes"]
 ----
 dynamicPlugins:
   frontend:
-    <package_name>:
+    _<package_name>_:
       dynamicRoutes:
         - path: /my-plugin
           module: CustomModule
@@ -83,47 +86,80 @@ dynamicPlugins:
             icon: fooIcon
             text: Foo Plugin Page
       menuItems:
-        my-plugin: # matches `path` in `dynamicRoutes`
-          priority: 10 # controls order of plugins under the parent menu item
-          parent: favorites # nests this plugin under the `favorites` parent menu item
-        favorites: # configuration for the parent menu item
-          icon: favorite # icon from RHDH system icons
-          title: Favorites # title for the parent menu item
-          priority: 100 # controls the order of this top-level menu item
+        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 ensure that a menu item is identified as a main menu item, you must add the `default.` prefix to its key. For example:
-+
---
-.Example configuration of main menu items in sidebar navigation
+
+. 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: # key for configuring static main menu items
-      menuItems: 
-        default.<menu_item_name>: # key of the menu item configuration. `default.` prefix is required for a main menu item key <1>
-          parent: my_menu_group # optional, specifies the parent menu item for this item
-          priority: 10 # optional, specifies the order of this menu item within its menu level
-        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>
-          icon: my_menu_group_icon # required for parent menu items, defines the icon for the menu group
-          title: my_menu_group_title # required for parent menu items, defines the icon for the menu group
-          priority: 100 # optional, specifies the order of the parent menu item in the sidebar
+    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.
 
-
-<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.
-
-[NOTE]
-====
-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. 
-====
---
-
-
-
-
-
-
-
++
+.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.

modules/customizing-the-home-page/proc-defining-the-layout-of-the-product-home-page.adoc

@@ -5,15 +5,17 @@
 [id="defining-the-layout-of-the-product-home-page_{context}"]
 = Defining the layout of the {product} Home 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.
+
 .Prerequisites
 * Include the following optimal parameters in each of your breakpoints:
 ** width (w)
 ** height (h)
 ** position (x and y)
 
 .Procedure
-* Configure your {product-short} `app-config.yaml` configuration file by choosing one of the following options:
-** Use the full space on smaller windows and half of the space on larger windows as follows:
+. 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.
+* Use the full space on smaller windows and half of the space on larger windows as shown in the following example:
 
 [source,yaml]
 ----
@@ -36,7 +38,7 @@ dynamicPlugins:
               debugContent: a placeholder
 ----
 
-** Show the cards side by side by defining the `x` parameter as follows:
+* Show the cards side by side by defining the `x` parameter as shown in the following example:
 
 [source,yaml]
 ----
@@ -73,7 +75,7 @@ dynamicPlugins:
 ----
 However, you can see a second card below this card by default.
 
-* Show the cards in three columns by defining the `x` parameter as follows:
+* Show the cards in three columns by defining the `x` parameter as shown in the following example:
 
 [source,yaml]
 ----

modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc

@@ -6,15 +6,15 @@
 [id="using-a-dedicated-service-to-provide-data-to-the-quick-access-card_{context}"]
 = Using a dedicated service to provide data to the Quick access card
 
-When using a dedicated service, you can do the following:
+When using a dedicated service, you can do the following tasks:
 
 * Use the same service to provide the data to all configurable {product-short} pages or use a different service for each page.
 * 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.
 * Deploy the `red-hat-developer-hub-customization-provider` service and the {product-short} Helm chart on the same cluster.
 
 .Prerequisites
 
-* You have installed the {product} using Helm Chart.
+* You have installed the {product} using Helm chart.
 For more information, see xref:{installing-on-ocp-book-url}#assembly-install-rhdh-ocp-helm[{installing-on-ocp-book-title} with the Helm chart].
 
 .Procedure
@@ -28,12 +28,12 @@ To use a separate service to provide the Home page data, complete the following
 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.
 --
 
-. On the *General* tab, enter *red-hat-developer-hub-customization-provider* in the *Name* field and click *Create*.
-. On the *Advanced Options* tab, copy the value from the *Target Port*.
+. On the *General* tab, enter `red-hat-developer-hub-customization-provider` in the *Name* field and click *Create*.
+. On the *Advanced Options* tab, copy the value from *Target Port*.
 +
 [NOTE]
 ====
-The *Target Port* automatically generates a Kubernetes or {ocp-short} service to communicate with.
+*Target Port* automatically generates a Kubernetes or {ocp-short} service to communicate with.
 ====
 +
 . Add the following code to the `app-config-rhdh.yaml` file:
@@ -45,12 +45,12 @@ proxy:
     # Other Proxies
     # customize developer hub instance
     '/developer-hub':
-      target: ${HOMEPAGE_DATA_URL}
+      target: ${HOMEPAGE_DATA_URL} <1>
       changeOrigin: true
       # Change to "false" in case of using self-hosted cluster with a self-signed certificate
       secure: true
 ----
-where `HOMEPAGE_DATA_URL` is defined as `pass:c[http://<SERVICE_NAME>:8080]`, for example, `pass:c[http://rhdh-customization-provider:8080]`.
+<1> `pass:c[http://<SERVICE_NAME>:8080]`, for example, `pass:c[http://rhdh-customization-provider:8080]`.
 +
 [NOTE]
 ====
@@ -62,11 +62,11 @@ The `red-hat-developer-hub-customization-provider` service contains the 8080 por
 . Delete the {product-short} pod to ensure that the new configurations are loaded correctly.
 
 .Verification
-* To view the service, navigate to the *Administrator* perspective in the {ocp-short} web console and click *Networking* > *Service*.
+* To view the service, go to the *Administrator* perspective in the {ocp-short} web console and click *Networking* > *Service*.
 +
 [NOTE]
 ====
-You can also view the *Service Resources* in the Topology view.
+You can also view *Service Resources* in the Topology view.
 ====
 
 * 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.
 If the request call fails or is not configured, the {product-short} instance falls back to the default local data.
 ====
 
-* 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:
+* 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:
 
 [source,yaml]
 ----