Skip to content

Commit ab7c72e

Browse files
openshift-cherrypick-robotGitHub Actions
openshift-cherrypick-robot
and
GitHub Actions
authored
[release-1.7] RHIDP-5152: Add Frontend Plugn Wiring Section (#1308)
* Add frontend plugn wiring section Add frontend plugn wiring section * Add frontend plugn wiring section * Add frontend plugn wiring section * Add frontend plugn wiring section * Add frontend plugn wiring section * Add frontend plugn wiring section --------- Co-authored-by: GitHub Actions <[email protected]>
1 parent cfd77f2 commit ab7c72e

18 files changed

+816
-0
lines changed

‎assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
[id="assembly-front-end-plugin-wiring.adoc_{context}"]
2+
= Front-end plugin wiring
3+
:context: assembly-front-end-plugin-wiring
4+
5+
You can configure front-end plugins to customize icons, integrate components at mount points, and provide or replace utility APIs.
6+
7+
// Extending the internal icon catalog
8+
include::../modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc[leveloffset=+1]
9+
10+
// Defining dynamic routes for new plugin pages
11+
include::../modules/dynamic-plugins/proc-defining-dynamic-routes-for-new-plugin-pages.adoc[leveloffset=+1]
12+
13+
// Customizing menu items in the sidebar navigation
14+
include::../modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc[leveloffset=+1]
15+
16+
// Bind to existing plugins
17+
include::../modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc[leveloffset=+1]
18+
19+
// Using mount points
20+
include::../modules/dynamic-plugins/proc-using-mount-points.adoc[leveloffset=+1]
21+
22+
include::../modules/dynamic-plugins/proc-customizing-entity-page.adoc[leveloffset=+2]
23+
24+
include::../modules/dynamic-plugins/proc-adding-application-header.adoc[leveloffset=+2]
25+
26+
include::../modules/dynamic-plugins/proc-adding-application-listeners.adoc[leveloffset=+2]
27+
28+
include::../modules/dynamic-plugins/proc-adding-application-providers.adoc[leveloffset=+2]
29+
30+
// Customizing and extending entity tabs
31+
include::../modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc[leveloffset=+1]
32+
33+
// SignIn page
34+
include::../modules/dynamic-plugins/con-using-custom-signinpage-component.adoc[leveloffset=+1]
35+
36+
// custom scaffolder extension
37+
include::../modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc[leveloffset=+1]
38+
39+
// Provide additional Utility APIs
40+
include::../modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc[leveloffset=+1]
41+
42+
// Adding custom authentication provider settings
43+
include::../modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc[leveloffset=+1]
44+
45+
// Provide custom techdocs addons
46+
include::../modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc[leveloffset=+1]
47+
48+
// Customizing theme
49+
include::../modules/dynamic-plugins/proc-customizing-theme.adoc[leveloffset=+1]

‎modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
[id="con-providing-custom-scaffolder-field-extensions.adoc_{context}"]
2+
= Providing custom Scaffolder field extensions
3+
4+
The Scaffolder component in {product} ({product-very-short}) enables users to create software components using templates through a guided wizard. You can extend the functionality of the Scaffolder by providing custom form fields as dynamic plugins using the `scaffolderFieldExtensions` configuration.
5+
6+
Custom field extensions allow you to add specialized form fields that capture domain-specific data during the scaffolding process, such as environment selectors, input validations, or repository checks.
7+
8+
When you configure custom scaffolder field extensions:
9+
10+
* The dynamic plugin exposes the field extension component using `createScaffolderFieldExtension`.
11+
* Each field extension requires a unique `importName` for registration.
12+
* You register multiple field extensions by listing each in the configuration.
13+
14+
[source,yaml]
15+
----
16+
dynamicPlugins:
17+
frontend:
18+
my-plugin: # The plugin package name
19+
scaffolderFieldExtensions:
20+
- importName: MyNewFieldExtension # References the exported scaffolder field extension component from your plugin
21+
----
22+
23+
[NOTE]
24+
====
25+
The `module` field is optional and specifies which set of assets to access within the plugin. By default, the system uses the `PluginRoot` module, consistent with the `scalprum.exposedModules` key in the `package.json` file of your package.
26+
====

‎modules/dynamic-plugins/con-using-custom-signinpage-component.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
[id="con-using-custom-signinpage-component.adoc_{context}"]
2+
= Using a custom SignInPage component
3+
4+
In {product} ({product-very-short}), the `SignInPage` component manages the authentication flow of the application. This component connects one or more authentication providers to the sign-in process. By default, {product-short} uses a static `SignInPage` that supports all built-in authentication providers.
5+
6+
When you configure a custom `SignInPage`:
7+
8+
* The system loads the specified `importName` component from your dynamic plugin.
9+
* The component returns a configured `SignInPage` that connects the desired authentication provider factories.
10+
* Only one `signInPage` is specified for the application at a time.
11+
12+
[source,yaml]
13+
----
14+
dynamicPlugins:
15+
frontend:
16+
my-plugin: # The plugin package name
17+
signInPage:
18+
importName: CustomSignInPage
19+
----
20+
21+
[NOTE]
22+
====
23+
The `package_name` specified under `dynamicPlugins.frontend` must match the `scalprum.name` value in the `package.json` file of your plugin to ensure the dynamic plugin loads correctly at runtime.
24+
25+
The `module` field is optional and allows specifying which set of assets must be accessed within the dynamic plugin. By default, the system uses the `PluginRoot` module.
26+
====

‎modules/dynamic-plugins/proc-adding-application-header.adoc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
[id="proc-adding-application-header.adoc_{context}"]
2+
= Adding application header
3+
4+
You can customize global headers by specifying configurations in the `app-config.yaml` file as shown in the following example:
5+
6+
[source,yaml]
7+
----
8+
# app-config.yaml
9+
dynamicPlugins:
10+
frontend:
11+
my-plugin: # The plugin package name
12+
mountPoints:
13+
- mountPoint: application/header # Adds the header as a global header
14+
importName: <header_component> # Specifies the component exported by the global header plugin
15+
config:
16+
position: above-main-content # Supported values: (`above-main-content`| above-sidebar`)
17+
----
18+
19+
[NOTE]
20+
====
21+
To configure multiple global headers at different positions, add entries to the `mountPoints` field.
22+
====

‎modules/dynamic-plugins/proc-adding-application-listeners.adoc‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
[id="proc-adding-application-listeners.adoc_{context}"]
2+
= Adding application listeners
3+
4+
You can add application listeners using the `application/listener` mount point as shown in the following example:
5+
6+
[source,yaml]
7+
----
8+
# app-config.yaml
9+
dynamicPlugins:
10+
frontend:
11+
my-plugin: # The plugin package name
12+
mountPoints:
13+
- mountPoint: application/listener
14+
importName: <exported listener component>
15+
----
16+
17+
[NOTE]
18+
====
19+
You can configure multiple application listeners by adding entries to the `mountPoints` field.
20+
====

‎modules/dynamic-plugins/proc-adding-application-providers.adoc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
[id="proc-adding-application-providers.adoc_{context}"]
2+
3+
= Adding application providers
4+
5+
You can add application providers using the `application/provider` mount point. You can use a mount point to configure a context provider as shown in the following example:
6+
7+
[source,yaml]
8+
----
9+
# app-config.yaml
10+
dynamicPlugins:
11+
frontend:
12+
my-plugin: # The plugin package name
13+
dynamicRoutes:
14+
- path: /<route>
15+
importName: Component # The component to load on the route
16+
mountPoints:
17+
- mountPoint: application/provider
18+
importName: <exported provider component>
19+
----
20+
21+
[NOTE]
22+
====
23+
. You can configure multiple application providers by adding entries to the `mountPoints` field.
24+
. The `package_name` key under `dynamicPlugins.frontend` **must match** the `scalprum.name` value in the `package.json` file of your plugin. This ensures your dynamic plugin loads correctly at runtime.
25+
====

‎modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
[id="proc-adding-custom-authentication-provider-settings.adoc_{context}"]
2+
= Adding custom authentication provider settings
3+
4+
You can install new authentication providers from a dynamic plugin that either adds additional configuration support for an existing provider or adds a new authentication provider. These providers are listed in the user settings section under the *Authentication Providers* tab.
5+
6+
You can use the `providerSettings` configuration to add entries for an authentication provider from a dynamic plugin, as shown in the following example:
7+
8+
[source,yaml]
9+
----
10+
dynamicPlugins:
11+
frontend:
12+
my-plugin: # The plugin package name
13+
providerSettings:
14+
# The title for the authentication provider shown above the user's profile image if available
15+
- title: My Custom Auth Provider
16+
# The description of the authentication provider
17+
description: Sign in using My Custom Auth Provider
18+
# The ID of the authentication provider as provided to the `createApiRef` API call.
19+
provider: core.auth.my-custom-auth-provider
20+
----
21+
22+
[NOTE]
23+
====
24+
`provider` looks up the corresponding API factory for the authentication provider to connect the provider's Sign In/Sign Out button.
25+
====

‎modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
[id="proc-binding-to-existing-plugins.adoc_{context}"]
2+
= Binding to existing plugins
3+
4+
You can bind to existing plugins and their routes, and declare new targets sourced from dynamic plugins as shown in the following `routeBindings` configuration:
5+
6+
[source,yaml]
7+
----
8+
# dynamic-plugins-config.yaml
9+
plugins:
10+
- plugin: <plugin_path_or_url>
11+
disabled: false
12+
pluginConfig:
13+
dynamicPlugins:
14+
frontend:
15+
my-plugin: # The plugin package name
16+
routeBindings:
17+
targets: # A new bind target
18+
# (Optional): Defaults to importName. Explicit name of the plugin that exposes the bind target.
19+
- name: barPlugin
20+
# (Required): Explicit import name that reference a BackstagePlugin<{}> implementation.
21+
importName: barPlugin
22+
# # (Optional): Same as key in `scalprum.exposedModules` key in the `package.json` file of the plugin.
23+
module: CustomModule
24+
bindings:
25+
- bindTarget: "barPlugin.externalRoutes" # (Required): One of the supported or imported bind targets
26+
bindMap: # A required map of route bindings similar to `bind` function options
27+
headerLink: "fooPlugin.routes.root"
28+
----
29+
30+
To configure `routeBindings`, complete the following steps:
31+
32+
. Define new targets using `routeBindings.targets`. Set the required `importName` to a `BackstagePlugin<{}>` implementation.
33+
34+
. Declare route bindings using the *routeBindings.bindings* field by setting `bindTarget` to the name of the target to bind to. This is a dynamic or static target, such as:
35+
+
36+
** `catalogPlugin.externalRoutes`
37+
38+
** `catalogImportPlugin.externalRoutes`
39+
40+
** `techdocsPlugin.externalRoutes`
41+
42+
** `scaffolderPlugin.externalRoutes`
43+
+
44+
You can extend existing pages with additional content using mount points, which are predefined identifiers available throughout the application.

‎modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
[id="proc-customizing-and-extending-entity-tabs.adoc_{context}"]
2+
3+
= Customizing and extending entity tabs
4+
5+
You can customize and extend the set of tabs using the `entityTabs` configuration as follows:
6+
7+
[source,yaml]
8+
----
9+
# dynamic-plugins-config.yaml
10+
plugins:
11+
- plugin: <plugin_path_or_url>
12+
disabled: false
13+
pluginConfig:
14+
dynamicPlugins:
15+
frontend:
16+
my-plugin: # The plugin package name
17+
entityTabs:
18+
# Specify a new tab
19+
- path: /new-path
20+
title: My New Tab
21+
mountPoint: entity.page.my-new-tab
22+
# Change an existing tab's title or mount point
23+
- path: /
24+
title: General
25+
mountPoint: entity.page.overview
26+
# Specify the sub-path route in the catalog where this tab is available
27+
- path: "/pr"
28+
title: "Changed Pull/Merge Requests" # Specify the title you want to display
29+
priority: 1
30+
# The base mount point name available on the tab. This name expands to create two mount points per tab, with` /context` and with `/cards`
31+
mountPoint: "entity.page.pull-requests"
32+
- path: "/"
33+
title: "Changed Overview"
34+
mountPoint: "entity.page.overview"
35+
# Specify the order of tabs. The tabs with higher priority values appear first
36+
priority: -6
37+
----
38+
39+
You can configure dynamic front-end plugins to target the mount points exposed by the entityTabs configuration. The following are the default catalog entity routes in the default order:
40+
41+
.Input parameters
42+
[cols="20%,20%,30%,30%", frame="all", options="header"]
43+
|===
44+
|Route
45+
|Title
46+
|Mount Point
47+
|Entity Kind
48+
49+
|`/`
50+
|Overview
51+
|`entity.page.overview`
52+
|Any
53+
54+
|`/topology`
55+
|Topology
56+
|`entity.page.topology`
57+
|Any
58+
59+
|`/issues`
60+
|Issues
61+
|`entity.page.issues`
62+
|Any
63+
64+
|`/pr`
65+
|CPull/Merge Requests
66+
|`entity.page.pull-requests`
67+
|Any
68+
69+
|`/ci`
70+
|CI
71+
|`entity.page.ci``
72+
|VAny
73+
74+
|`/cd`
75+
|CD
76+
|`entity.page.cd`
77+
|Any
78+
79+
|`/kubernetes`
80+
|Kubernetes
81+
|`entity.page.kubernetes`
82+
|Any
83+
84+
|`/image-registry`
85+
|Image Registry
86+
|`entity.page.image-registry`
87+
|Any
88+
89+
|`/monitoring`
90+
|Monitoring
91+
|`entity.page.monitoring`
92+
|Any
93+
94+
|`/lighthouse`
95+
|Lighthouse
96+
|`entity.page.lighthouse`
97+
|Any
98+
99+
|`/api`
100+
|Api
101+
|`entity.page.api`
102+
|kind: Service or kind: Component
103+
104+
|`/dependencies`
105+
|Dependencies
106+
|`entity.page.dependencies`
107+
|kind: Component
108+
109+
|`/docs`
110+
|Docs
111+
|`entity.page.docs`
112+
|Any
113+
114+
|`/definition`
115+
|Definition
116+
|`entity.page.definition`
117+
|kind: API
118+
119+
|`/system`
120+
|Diagram
121+
|`entity.page.diagram`
122+
|kind: System
123+
|===
124+
125+
[NOTE]
126+
====
127+
Mount points within Catalog such as _`entity.page.*`_ are rendered as tabs and become visible only if at least one plugin contributes to them, or if they can render static content.
128+
====

0 commit comments

Comments
 (0)