Skip to content

Commit a6f04ec

Browse files
jmagakGitHub Actions
jmagak
and
GitHub Actions
authored
RHIDP-5490: Configure global header in RHDH (redhat-developer#954)
* Update the configure global header Update the configure global header Update the configure global header Update the configure global header Update the configure global header Update the configure global header * Update the configure global header * Update the configure global header * Update the configure global header * Update the configure global header * Update the configure global header * Update the configure global header * Update the configure global header * Update the configure global header * Apply technical review suggestions * Apply technical review suggestions * Apply review suggestions * Apply review suggestions * Apply peer suggestions * Apply technical reviews * Apply technical review * Apply technical reviews * Apply technical reviews * Apply peer reviews * Apply technical reviews --------- Co-authored-by: GitHub Actions <[email protected]>
1 parent 348fa6a commit a6f04ec

File tree

4 files changed

+262
-0
lines changed

4 files changed

+262
-0
lines changed

‎assemblies/assembly-configuring-the-global-header.adoc

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:context: configuring-the-global-header-in-rhdh
3+
[id="{context}"]
4+
= Configuring the global header in {product}
5+
6+
As an administrator, you can configure the {product} global header to create a consistent and flexible navigation bar across your {product-short} instance.
7+
By default, the {product-short} global header includes the following components:
8+
9+
* *Create* button provides quick access to a variety of templates, enabling users to efficiently set up services, backend and front-end plugins within {product-short}
10+
* *Support* button that can link an internal or external support page
11+
* *Notifications* button displays alerts and updates from plugins and external services
12+
* *Search* input field allows users to find services, components, documentation, and other resources within {product-short}
13+
* *Plugin extension capabilities* provide a preinstalled and enabled catalog of available plugins in {product-short}
14+
* *User profile* drop-down menu provides access to profile settings, appearance customization, {product-short} metadata, and a logout button
15+
16+
include::modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc[leveloffset=+1]
17+
18+
19+
include::modules/configuring-the-global-header/proc-mount-points.adoc[leveloffset=+1]

‎modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc

+167
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
[id="customizing-your-product-global-header_{context}"]
2+
= Customizing your {product} global header
3+
4+
You can use the `red-hat-developer-hub.backstage-plugin-global-header` dynamic plugin to extend the global header with additional buttons and customize the order and position of icons and features. Additionally, you can create and integrate your custom dynamic header plugins using the mount points provided by this new header feature, allowing you to further tailor to suit your needs.
5+
For more information on enabling dynamic plugins, see link:{installing-and-viewing-dynamic-plugins-url}[{installing-and-viewing-dynamic-plugins-title}].
6+
7+
.Default global header configuration
8+
9+
[source,yaml,subs="+attributes,+quotes"]
10+
----
11+
- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header
12+
disabled: false
13+
pluginConfig:
14+
app:
15+
sidebar:
16+
search: false <1>
17+
settings: false <2>
18+
dynamicPlugins:
19+
frontend:
20+
default.main-menu-items: <3>
21+
menuItems:
22+
default.create:
23+
title: ''
24+
red-hat-developer-hub.backstage-plugin-global-header: # the default enabled dynamic header plugin
25+
mountPoints:
26+
- mountPoint: application/header
27+
importName: GlobalHeader
28+
config:
29+
position: above-main-content <4>
30+
- mountPoint: global.header/component
31+
importName: SearchComponent
32+
config:
33+
priority: 100
34+
- mountPoint: global.header/component
35+
importName: Spacer
36+
config:
37+
priority: 99
38+
props:
39+
growFactor: 0
40+
- mountPoint: global.header/component
41+
importName: HeaderIconButton
42+
config:
43+
priority: 90
44+
props:
45+
title: Create...
46+
icon: add
47+
to: create
48+
- mountPoint: global.header/component
49+
importName: SupportButton
50+
config:
51+
priority: 80
52+
- mountPoint: global.header/component
53+
importName: NotificationButton
54+
config:
55+
priority: 70
56+
- mountPoint: global.header/component
57+
importName: Divider
58+
config:
59+
priority: 50
60+
- mountPoint: global.header/component
61+
importName: ProfileDropdown
62+
config:
63+
priority: 10
64+
- mountPoint: global.header/profile
65+
importName: MenuItemLink
66+
config:
67+
priority: 100
68+
props:
69+
title: Settings
70+
link: /settings
71+
icon: manageAccounts
72+
- mountPoint: global.header/profile
73+
importName: LogoutButton
74+
config:
75+
priority: 10
76+
----
77+
<1> *search*: Hides the *Search* modal in the sidebar menu. Change it to `true` to display the *Search* modal in the sidebar.
78+
<2> *settings*: Hides the *Settings* button in the sidebar menu. Change it to `true` to display the *Settings* button in the sidebar.
79+
<3> `default.main-menu-items`: Hides the *Create* button from the sidebar menu. Remove this field to display the *Create* button in the sidebar.
80+
<4> *position*: Defines the position of the header. Options: `above-main-content` or `above-sidebar`.
81+
82+
To extend the functionality of the default global header, include any the following attributes in your global header entry:
83+
84+
`mountPoint`::
85+
Specifies the location of the header. Use `application/header` to specify it as a global header. You can configure several global headers at different positions by adding entries to the `mountPoints` field.
86+
87+
`importName`::
88+
Specifies the component exported by the global header plugin.
89+
+
90+
The `red-hat-developer-hub.backstage-plugin-global-header` package (enabled by default) offers the following header components as possible mount point values:
91+
92+
- **`SearchComponent`**: Adds a search bar (enabled by default).
93+
- **`Spacer`**: Adds spacing in the header to position buttons at the end. Useful when you disable `SearchComponent`.
94+
- **`HeaderIconButton`**: Adds an icon button. By default, the *Create* icon button remains enabled.
95+
- **`SupportButton`**: Adds a *Support* icon button, allowing users to configure a link to an internal or external page. Enabled by default but requires additional configuration to display.
96+
- **`NotificationButton`**: Adds a *Notifications* icon button to display unread notifications in real time and navigate to the *Notifications* page. Enabled by default (requires the notifications plugin).
97+
- **`Divider`**: Adds a vertical divider. By default, a divider appears between the profile dropdown and other header components.
98+
- **`ProfileDropdown`**: Adds a profile dropdown showing the logged-in user's name. By default, it contains two menu items.
99+
- **`MenuItemLink`**: Adds a link item in a dropdown menu. By default, the profile dropdown includes a link to the *Settings* page.
100+
- **`LogoutButton`**: Adds a logout button in the profile dropdown (enabled by default).
101+
- **`CreateDropdown`**: Adds a *Create* dropdown button (disabled by default). The menu items are configurable.
102+
- **`SoftwareTemplatesSection`**: Adds a list of software template links to the *Create* dropdown menu (disabled by default). You must enable `CreateDropdown`.
103+
- **`RegisterAComponentSection`**: Adds a link to the *Register a Component* page in the *Create* dropdown menu (disabled by default). You must enable `CreateDropdown`.
104+
105+
`config.position`::
106+
Specifies the position of the header. Supported values are `above-main-content` and `above-sidebar`.
107+
108+
.Prerequisites
109+
* You must configure the support URL in the `{my-app-config-file}` file to display the *Support* button in the header.
110+
* You must install the notifications plugin to display the *Notifications* button in the header.
111+
112+
.Procedure
113+
114+
. Copy the default configuration and modify the field values to suit your needs. You can adjust the `priority` value of each header component to control its position. Additionally, you can enable or disable components by adding or removing them from the configuration. To ensure that the remaining header buttons align with the end of the header before the profile dropdown button, set `config.props.growFactor` to `1` in the `Spacer` mount point to enable the `Spacer` component. For example:
115+
+
116+
[source,yaml]
117+
----
118+
- mountPoint: global.header/component
119+
importName: Spacer
120+
config:
121+
priority: 100
122+
props:
123+
growFactor: 1
124+
----
125+
126+
. To use your custom header, you must install it as a dynamic plugin by adding your plugin configuration to your `app-config-dynamic.yaml` file. For example:
127+
+
128+
[source,yaml,subs="+attributes,+quotes"]
129+
----
130+
- package: _<npm_or_oci_package-reference>_
131+
disabled: false
132+
pluginConfig:
133+
dynamicPlugins:
134+
frontend:
135+
<package_name>:
136+
mountPoints:
137+
- mountPoint: application/header
138+
importName: _<application_header_name>_
139+
config:
140+
position: above-main-content
141+
- mountPoint: global.header/component
142+
importName: _<header_component_name>_
143+
config:
144+
priority: 100
145+
- mountPoint: global.header/component
146+
importName: _<header_component_name>_
147+
config:
148+
priority: 90
149+
----
150+
+
151+
where:
152+
153+
<npm_or_oci_package-reference>:: Specifies the package name.
154+
<application_header_name>:: Specifies the name of the application header. For example: `MyHeader`
155+
<header_component_name>:: Specifies the name of the header component. For example: `MyHeaderComponent`
156+
+
157+
[NOTE]
158+
====
159+
`importName` is an optional name referencing the value returned by the scaffolder field extension API.
160+
====
161+
. Optional: To disable the global header, set the value of the `disabled` field to `true` in your `dynamic-plugins.yaml` file. For example:
162+
+
163+
[source,yaml,subs="+attributes,+quotes"]
164+
----
165+
- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header
166+
disabled: true
167+
----

‎modules/configuring-the-global-header/proc-mount-points.adoc

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
[id="mount-points-for-dynamic-plugin-intergration_{context}"]
2+
= Mount points for dynamic plugin integration
3+
4+
You can customize the application header in {product-short} using mount points for dynamic plugins. These mount points give flexibility in configuring the position of the header, its components and dropdown menus. You can create a customized experience with the following enhancements:
5+
6+
application/header::
7+
Controls the header position. Use `config.position` to set placement as either `above-main-content` or `above-sidebar`.
8+
9+
global.header/component::
10+
Configures header components. Use `config.priority` to set the order of components, and pass properties (including CSS styles) via `config.props`.
11+
+
12+
.Example adding a *Self-service* button
13+
[source,yaml,subs="attributes,quotes"]
14+
----
15+
- mountPoint: global.header/component
16+
importName: HeaderIconButton
17+
config:
18+
priority: 80
19+
props:
20+
title: *Self-service*
21+
icon: add
22+
to: create
23+
----
24+
+
25+
.Example adding a spacer element
26+
[source,yaml]
27+
----
28+
- mountPoint: global.header/component
29+
importName: Spacer
30+
config:
31+
priority: 99
32+
props:
33+
growFactor: 0
34+
----
35+
+
36+
.Example adding a divider element
37+
[source,yaml]
38+
----
39+
mountPoints:
40+
- mountPoint: global.header/component
41+
importName: Divider
42+
config:
43+
priority: 150
44+
----
45+
46+
global.header/profile::
47+
Configures the profile dropdown list when the `ProfileDropdown` component is enabled.
48+
+
49+
.Example adding a settings link to the profile dropdown
50+
[source,yaml]
51+
----
52+
- mountPoint: global.header/profile
53+
importName: MenuItemLink
54+
config:
55+
priority: 100
56+
props:
57+
title: Settings
58+
link: /settings
59+
icon: manageAccounts
60+
----
61+
62+
global.header/create::
63+
Configures the create dropdown list when the `CreateDropdown` component is enabled.
64+
+
65+
.Example adding a section for registering a component
66+
[source,yaml]
67+
----
68+
- mountPoint: global.header/create
69+
importName: RegisterAComponentSection
70+
config:
71+
props:
72+
growFactor: 0
73+
----

‎titles/customizing/master.adoc

+3
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ include::assemblies/assembly-configuring-templates.adoc[leveloffset=+1]
2323
include::modules/customizing-the-learning-paths/proc-customize-rhdh-learning-paths.adoc[leveloffset=+1]
2424

2525

26+
include::assemblies/assembly-configuring-the-global-header.adoc[leveloffset=+1]
27+
28+
2629
include::assemblies/assembly-configuring-a-floating-action-button.adoc[leveloffset=+1]
2730

2831

0 commit comments

Comments
 (0)