Skip to content

Commit b0506e3

Browse files
jmagakGitHub Actions
jmagak
and
GitHub Actions
authored
RHIDP-12595: Migrate RHDH UI features to New Frontend System (redhat-developer#2107)
* Migrate RHDH UI features to New Frontend System * Add RHDH UI features to New Frontend System * Add RHDH UI features to New Frontend System * Apply technical reviewers suggestions * Apply technical reviews suggestion * Apply Technical reviewers suggestions * Minimalism and CQA checks * Update New Front-end System naming * Update New Front-end System naming * Apply peer reviewers suuggestions * Update technical reviewers suggestions * Apply tech and peer suggestions * Apply peer suggestions --------- Co-authored-by: GitHub Actions <github-actions@github.com>
1 parent a8cd9be commit b0506e3

12 files changed

Lines changed: 739 additions & 0 deletions

‎assemblies/extend_installing-and-viewing-plugins-in-rhdh/assembly-customize-the-rhdh-interface-with-the-front-end-system.adoc‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
ifdef::context[:parent-context: {context}]
3+
4+
[id="customize-the-rhdh-interface-with-the-front-end-system_{context}"]
5+
= Customize the {product} interface with the front-end system
6+
7+
:previouscontext: {context}
8+
:context: customize-the-rhdh-interface-with-the-front-end-system
9+
10+
[role="_abstract"]
11+
Customize your {product} environment by using the extension-based front-end system to improve extensibility and performance. This system provides better customization options for themes, navigation, and plugin integration compared to the previous Scalprum-based approach.
12+
13+
// Customize the interface theme
14+
include::../modules/shared/proc-customize-the-platform-appearance-for-branding.adoc[leveloffset=+1]
15+
16+
// Configure the global header
17+
include::../modules/shared/proc-prepare-your-application-to-add-custom-navigation-and-toolbar-items.adoc[leveloffset=+1]
18+
19+
// Add custom navigation shortcuts, buttons, and links
20+
include::../modules/shared/proc-add-navigation-shortcuts-to-reduce-clicks-to-frequently-used-resources.adoc[leveloffset=+1]
21+
22+
// Add plugin-specific buttons to the toolbar for quick actions
23+
include::../modules/shared/proc-add-plugin-specific-buttons-to-the-toolbar-for-quick-actions.adoc[leveloffset=+1]
24+
25+
// Add plugin links to drop-down menus
26+
include::../modules/shared/proc-add-plugin-links-to-drop-down-menus.adoc[leveloffset=+1]
27+
28+
// Reorganize or remove header items to match your team's priorities
29+
include::../modules/shared/proc-reorganize-or-remove-header-items-to-match-your-team-s-priorities.adoc[leveloffset=+1]
30+
31+
// Configure the dynamic homepage
32+
include::../modules/shared/proc-control-what-you-see-first-on-the-homepage.adoc[leveloffset=+1]
33+
34+
// Enable the Lightspeed virtual assistant plugin
35+
include::../modules/shared/proc-get-instant-help-with-an-ai-powered-virtual-assistant.adoc[leveloffset=+1]
36+
37+
// Enable the quickstart plugin
38+
include::../modules/shared/proc-learn-platform-features-through-guided-tutorials.adoc[leveloffset=+1]
39+
40+
// Preserve custom integrations when migrating to the front-end system
41+
include::../modules/shared/proc-preserve-custom-integrations-when-migrating-to-the-front-end-system.adoc[leveloffset=+1]
42+
43+
:context: {previouscontext}
44+
:!previouscontext:
45+
46+
ifdef::parent-context[:context: {parent-context}]
47+
ifndef::parent-context[:!context:]

‎modules/shared/proc-add-navigation-shortcuts-to-reduce-clicks-to-frequently-used-resources.adoc‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="add-navigation-shortcuts-to-reduce-clicks-to-frequently-used-resources_{context}"]
4+
= Add navigation shortcuts to reduce clicks to frequently used resources
5+
6+
[role="_abstract"]
7+
Add custom toolbar buttons and drop-down menu items to the {product} global header to give you quick access to frequently used tools, documentation, and support resources.
8+
9+
You can add navigation shortcuts by using any of the following approaches:
10+
11+
* Configuration-driven items through `{my-app-config-file}` without code
12+
* Extension blueprints for plugin contributions (`GlobalHeaderComponentBlueprint` for toolbar items, `GlobalHeaderMenuItemBlueprint` for drop-down menu entries)
13+
* Fully custom React components
14+
15+
.Prerequisites
16+
17+
* You have installed the `@red-hat-developer-hub/backstage-plugin-global-header` package.
18+
* You have access to the `{my-app-config-file}` file.
19+
* You have integrated the global header plugin into your application features.
20+
21+
.Procedure
22+
23+
. To add navigation shortcuts, configure the `globalHeader` block in your `{my-app-config-file}` file with `components` for toolbar buttons and `menuItems` for dropdown entries:
24+
+
25+
[source,yaml]
26+
----
27+
globalHeader:
28+
components:
29+
- title: Visualizer Dashboard
30+
titleKey: visualizer.dashboard.title # Optional localization key for the title.
31+
icon: dashboard
32+
link: /visualizer/tree
33+
priority: 75 # Priority determines display order. Higher values appear first.
34+
menuItems:
35+
- target: help # Target specifies which drop-down menu (`help`, `profile`, or `app-launcher`) receives this item.
36+
title: Internal Wiki
37+
titleKey: wiki.internal.title
38+
icon: article
39+
link: https://wiki.internal.example.com
40+
sectionLabel: resources # Section groups related menu items together.
41+
priority: 80
42+
----
43+
44+
. Save the configuration file.
45+
. Restart your {product} instance to apply the changes.
46+
47+
.Verification
48+
49+
. Open your {product} instance in a web browser.
50+
. Verify that your custom toolbar button is displayed in the global header.
51+
. Click the target drop-down menu to confirm your menu item is displayed in the correct section.

‎modules/shared/proc-add-plugin-links-to-drop-down-menus.adoc‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="add-plugin-links-to-drop-down-menus_{context}"]
4+
= Add plugin links to drop-down menus
5+
6+
[role="_abstract"]
7+
Integrate the links and actions of your plugin into the {product} `help`, `profile`, or `app launcher` drop-down menus to help users discover your features.
8+
9+
By using `GlobalHeaderMenuItemBlueprint`, you can create custom menu item entries programmatically.
10+
11+
.Prerequisites
12+
13+
* You have configured the global header plugin in your application.
14+
* You have access to your plugin source code.
15+
16+
.Procedure
17+
18+
. To add a plugin link to a drop-down menu, create a menu item extension specifying the target drop-down menu:
19+
+
20+
[source,typescript]
21+
----
22+
import { GlobalHeaderMenuItemBlueprint } from '@red-hat-developer-hub/backstage-plugin-global-header/alpha';
23+
24+
const myMenuItem = GlobalHeaderMenuItemBlueprint.make({
25+
name: 'my-menu-item',
26+
params: {
27+
target: 'help', // Target drop-down menu: 'help', 'profile', or 'app-launcher'
28+
component: MyMenuItemComponent,
29+
priority: 50,
30+
},
31+
});
32+
----
33+
34+
. Optional: To add simple links without custom components, you can use data-driven configuration:
35+
+
36+
[source,typescript]
37+
----
38+
const supportLink = GlobalHeaderMenuItemBlueprint.make({
39+
name: 'support-link',
40+
params: {
41+
target: 'help',
42+
title: 'Support Portal',
43+
icon: 'support',
44+
link: 'https://support.example.com',
45+
sectionLabel: 'external-resources', // Section groups related items together within the drop-down menu
46+
priority: 60,
47+
},
48+
});
49+
----
50+
51+
. To activate the menu item, register the extension in your plugin's alpha exports:
52+
+
53+
[source,typescript]
54+
----
55+
export default createPlugin({
56+
id: 'my-plugin',
57+
extensions: [myMenuItem, supportLink],
58+
});
59+
----

‎modules/shared/proc-add-plugin-specific-buttons-to-the-toolbar-for-quick-actions.adoc‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="add-plugin-specific-buttons-to-the-toolbar-for-quick-actions_{context}"]
4+
= Add plugin-specific buttons to the toolbar for quick actions
5+
6+
[role="_abstract"]
7+
Add custom buttons or interactive widgets to the global header toolbar that trigger your plugin's functionality directly. Use `GlobalHeaderComponentBlueprint` to create these toolbar components programmatically.
8+
9+
.Prerequisites
10+
11+
* You have set up the global header plugin in your application.
12+
* You have access to your plugin source code.
13+
14+
.Procedure
15+
16+
. To add a plugin button to the toolbar, create a custom toolbar component extension in your plugin code:
17+
+
18+
[source,typescript]
19+
----
20+
import { GlobalHeaderComponentBlueprint } from '@red-hat-developer-hub/backstage-plugin-global-header/alpha';
21+
22+
const myToolbarButton = GlobalHeaderComponentBlueprint.make({
23+
name: 'my-toolbar-item',
24+
params: {
25+
component: MyCustomComponent, // React component to render in the toolbar.
26+
priority: 100, // Higher priority values display first in the toolbar.
27+
},
28+
});
29+
----
30+
31+
. To create icon buttons without custom components, you can provide data-driven configuration instead of a component:
32+
+
33+
[source,typescript]
34+
----
35+
const dashboardButton = GlobalHeaderComponentBlueprint.make({
36+
name: 'dashboard-button',
37+
params: {
38+
icon: 'dashboard',
39+
title: 'Dashboard',
40+
link: '/dashboard',
41+
priority: 75, // Higher priority values display first in the toolbar.
42+
},
43+
});
44+
----
45+
46+
. To activate the toolbar button, register the extension in your plugin's alpha exports:
47+
+
48+
[source,typescript]
49+
----
50+
export default createPlugin({
51+
id: 'my-plugin',
52+
extensions: [myToolbarButton],
53+
});
54+
----

‎modules/shared/proc-control-what-you-see-first-on-the-homepage.adoc‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="control-what-you-see-first-on-the-homepage_{context}"]
4+
= Control what you see first on the homepage
5+
6+
[role="_abstract"]
7+
Configure the dynamic homepage plugin to choose which templates and widgets appear when you log in. You can use customizable layouts to drag and resize cards, or fixed layouts with predefined positions.
8+
9+
Available widgets include:
10+
11+
* Onboarding sections
12+
* Entity catalogs
13+
* Software templates
14+
* Quick access cards
15+
* Search bars
16+
* Recently visited items
17+
* Top visited resources
18+
19+
.Prerequisites
20+
21+
* You have installed the `@red-hat-developer-hub/backstage-plugin-dynamic-home-page` package.
22+
* You have access to the `packages/app/src/App.tsx` file.
23+
* You have access to the `{my-app-config-file}` file.
24+
25+
.Procedure
26+
27+
. To enable the dynamic homepage, import and register the homepage modules in your `packages/app/src/App.tsx` file:
28+
+
29+
[source,typescript]
30+
----
31+
import { createApp } from '@backstage/frontend-defaults';
32+
import {
33+
homePageDevModule,
34+
homepageTranslationsModule,
35+
} from '@red-hat-developer-hub/backstage-plugin-dynamic-home-page/alpha';
36+
37+
export default createApp({
38+
features: [
39+
homePageDevModule, // Enables the dynamic homepage plugin
40+
homepageTranslationsModule, // Adds internationalization support
41+
// Additional features
42+
],
43+
});
44+
----
45+
46+
. To set the homepage route and visit tracking, configure them in your `{my-app-config-file}` file:
47+
+
48+
[source,yaml]
49+
----
50+
app:
51+
extensions:
52+
- page:home:
53+
config:
54+
path: / # Set to / to make the homepage your landing page
55+
- api:home/visits: true # Enables visit tracking for recently visited and top visited widgets
56+
- app-root-element:home/visit-listener: true # Activates the visit listener to record page visits
57+
----
58+
59+
. Choose a layout mode by setting the `customizable` option. Set to `true` for a customizable grid where you can drag and resize cards, or set to `false` for a read-only grid with fixed card positions:
60+
+
61+
[source,yaml]
62+
----
63+
app:
64+
extensions:
65+
- home-page-layout:home/dynamic-homepage-layout:
66+
config:
67+
customizable: true # Set to false to prevent you from moving or resizing cards
68+
----
69+
70+
. To control widget display order and sizing, configure widget sections with priority values and responsive breakpoints. Priority values determine display order in read-only layouts, with higher values appearing first.
71+
+
72+
[source,yaml]
73+
----
74+
app:
75+
extensions:
76+
- home-page-layout:home/dynamic-homepage-layout:
77+
config:
78+
customizable: false
79+
widgetLayout:
80+
RhdhTemplateSection: # Software templates widget section
81+
priority: 300 # Priority applies only to read-only layouts. Higher values display first.
82+
breakpoints: # Card dimensions (width w and height h in grid units) across device sizes
83+
xl: { w: 12, h: 5 }
84+
lg: { w: 12, h: 5 }
85+
md: { w: 12, h: 5 }
86+
sm: { w: 12, h: 5 }
87+
xs: { w: 12, h: 7.5 }
88+
xxs: { w: 12, h: 13.5 }
89+
RhdhEntitySection: # Entity catalog widget section showing registered components
90+
priority: 200
91+
breakpoints:
92+
xl: { w: 12, h: 7 }
93+
lg: { w: 12, h: 7 }
94+
md: { w: 12, h: 7 }
95+
sm: { w: 12, h: 7 }
96+
xs: { w: 12, h: 9 }
97+
xxs: { w: 12, h: 15 }
98+
RhdhOnboardingSection: # Onboarding widget section with getting started guides
99+
priority: 100
100+
breakpoints:
101+
xl: { w: 12, h: 6 }
102+
lg: { w: 12, h: 6 }
103+
md: { w: 12, h: 6 }
104+
sm: { w: 12, h: 6 }
105+
xs: { w: 12, h: 8 }
106+
xxs: { w: 12, h: 12 }
107+
----
108+
109+
. Save the configuration file.
110+
. Restart your {product} instance to apply the homepage layout changes.
111+
112+
.Verification
113+
114+
. Open your {product} instance in a web browser.
115+
. Verify that the homepage displays at the configured path.
116+
. Check that widget cards appear in the expected order and size.
117+
. If `customizable: true`, confirm that you can drag and resize cards.
118+
. Verify that visit tracking works by navigating to different pages and checking the recently visited widget.

‎modules/shared/proc-customize-the-platform-appearance-for-branding.adoc‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="customize-the-platform-appearance-for-branding_{context}"]
4+
= Customize the platform appearance for branding
5+
6+
[role="_abstract"]
7+
Apply custom color schemes, logos, and visual elements to the {product} interface so the platform reflects your organization's brand identity.
8+
9+
.Prerequisites
10+
11+
* You have installed the `@backstage/frontend-defaults` package.
12+
* You have access to the `packages/app/src/App.tsx` file.
13+
* You have access to the `{my-app-config-file}` file.
14+
15+
.Procedure
16+
17+
. To enable the custom theme, import the `rhdhThemeModule` from the theme plugin alpha module in your `packages/app/src/App.tsx` file:
18+
+
19+
[source,typescript]
20+
----
21+
import { createApp } from '@backstage/frontend-defaults';
22+
import { rhdhThemeModule } from '@red-hat-developer-hub/backstage-plugin-theme/alpha';
23+
24+
export default createApp({
25+
features: [
26+
rhdhThemeModule,
27+
// Additional features
28+
],
29+
});
30+
----
31+
+
32+
[NOTE]
33+
====
34+
For advanced customization beyond color schemes and branding, you can create a custom theme module that extends the base theme configuration. For a complete example of creating a custom theme module by overriding theme plugin extensions, see the link:https://github.com/redhat-developer/rhdh-plugins/blob/main/workspaces/theme/packages/app/src/App.tsx[theme plugin example] in the rhdh-plugins repository.
35+
====
36+
37+
. To set the application title and branding, configure extension settings in your `{my-app-config-file}` file:
38+
+
39+
[source,yaml]
40+
----
41+
app:
42+
title: My Company Catalog
43+
baseUrl: http://localhost:3000
44+
45+
organization:
46+
name: My Company
47+
----
48+
49+
. Save the configuration file and restart your {product} instance to apply the theme changes.
50+
51+
.Verification
52+
53+
. Open your {product} instance in a web browser.
54+
. Verify that the interface displays your custom theme.
55+
. Check that theme colors match your brand identity specifications.

0 commit comments

Comments
 (0)