Skip to content

Commit cee74ae

Browse files
GitHub Actionsjmagak
GitHub Actions
authored and
jmagak
committed
Add frontend plugn wiring section
1 parent df9b3b1 commit cee74ae

13 files changed

+144
-116
lines changed

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

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,17 @@ You can customize global headers by specifying configurations in the `app-config
99
# app-config.yaml
1010
dynamicPlugins:
1111
frontend:
12-
<package_name>: # e.g., preinstalled plugin `red-hat-developer-hub.backstage-plugin-global-header`
12+
my-plugin: # <1>
1313
mountPoints:
14-
- mountPoint: application/header # <1>
15-
importName: <header_component> # <2>
14+
- mountPoint: application/header # <2>
15+
importName: <header_component> # <3>
1616
config:
17-
position: above-main-content # <3>
17+
position: above-main-content # <4>
1818
----
19-
<1> Specify where to add the header. To specify it as a global header, use `application/header`.
20-
<2> Specify the component exported by the global header plugin (for example, `GlobalHeader` for `red-hat-developer-hub.backstage-plugin-global-header).
21-
<3> Specify the header's position. The supported values include:
19+
<1> Specify the plugin package name.
20+
<2> Specify where to add the header. To specify it as a global header, use `application/header`.
21+
<3> Specify the component exported by the global header plugin (for example, `GlobalHeader` for `red-hat-developer-hub.backstage-plugin-global-header).
22+
<4> Specify the header's position. The supported values include:
2223
* `above-main-content`: Positions the header above the main content area.
2324
* `above-sidebar`: Positions the header above the sidebar.
2425
+

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ You can add application listeners using the `application/listener` mount point a
99
# app-config.yaml
1010
dynamicPlugins:
1111
frontend:
12-
<package_name>: # <1>
12+
my-plugin: # <1>
1313
mountPoints:
1414
- mountPoint: application/listener
1515
importName: <exported listener component>

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

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,19 @@ You can add application providers using the `application/provider` mount point.
99
# app-config.yaml
1010
dynamicPlugins:
1111
frontend:
12-
<package_name>: # plugin_package_name same as `scalprum.name` key in plugin's `package.json`
12+
my-plugin: # <1>
1313
dynamicRoutes:
1414
- path: /<route>
15-
importName: Component # Component you want to load on the route
15+
importName: Component # <2>
1616
mountPoints:
1717
- mountPoint: application/provider
1818
importName: <exported provider component>
1919
----
20+
<1> Specify the plugin package name.
21+
<2> Specify the component you want to load on the route.
2022

2123
[NOTE]
2224
====
23-
You can configure multiple application providers by adding entries to the `mountPoints` field.
25+
. You can configure multiple application providers by adding entries to the `mountPoints` field.
26+
. The `package_name` key under `dynamicPlugins.frontend` **must match** the `scalprum.name` value in your plugin's `package.json`. This ensures your dynamic plugin loads correctly during runtime.
2427
====

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

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,13 @@ You can use the `providerSettings` configuration to add entries for an authentic
1010
----
1111
dynamicPlugins:
1212
frontend:
13-
<package_name>:
13+
my-plugin: # <1>
1414
providerSettings:
15-
- title: My Custom Auth Provider # <1>
16-
description: Sign in using My Custom Auth Provider # <2>
17-
provider: core.auth.my-custom-auth-provider # <3>
15+
- title: My Custom Auth Provider # <2>
16+
description: Sign in using My Custom Auth Provider # <3>
17+
provider: core.auth.my-custom-auth-provider # <4>
1818
----
19-
<1> Specify the title for the authentication provider shown above the user's profile image if available.
20-
<2> Specify the description of the authentication provider.
21-
<3> Specify the ID of the authentication provider as provided to the `createApiRef` API call. This value is used to look up the corresponding API factory for the authentication provider to connect the provider's Sign In/Sign Out button.
19+
<1> Specify the plugin package name.
20+
<2> Specify the title for the authentication provider shown above the user's profile image if available.
21+
<3> Specify the description of the authentication provider.
22+
<4> Specify the ID of the authentication provider as provided to the `createApiRef` API call. This value is used to look up the corresponding API factory for the authentication provider to connect the provider's Sign In/Sign Out button.

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

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,24 @@ plugins:
1313
pluginConfig:
1414
dynamicPlugins:
1515
frontend:
16-
<package_name>: # same as `scalprum.name` key in plugin's `package.json`
16+
my-plugin: # <1>
1717
routeBindings:
18-
targets: # Declare a new bind target
19-
- name: barPlugin # Optional, defaults to importName. Explicit name of the plugin that exposes the bind target
20-
importName: barPlugin # Required. Explicit import name that reference a BackstagePlugin<{}> implementation.
21-
module: CustomModule # Optional, same as key in `scalprum.exposedModules` key in plugin's `package.json`
18+
targets: # <2>
19+
- name: barPlugin # <3>
20+
importName: barPlugin # <4>
21+
module: CustomModule # <5>
2222
bindings:
23-
- bindTarget: "barPlugin.externalRoutes" # Required. One of the supported or imported bind targets
24-
bindMap: # <1>
23+
- bindTarget: "barPlugin.externalRoutes" # <6>
24+
bindMap: # <7>
2525
headerLink: "fooPlugin.routes.root"
2626
----
27-
<1> A required map of route bindings and is similar to `bind` function options
27+
<1> Specify the plugin package name.
28+
<2> Declare a new bind target
29+
<3> (Optional): defaults to importName. Explicit name of the plugin that exposes the bind target.
30+
<4> Required. Explicit import name that reference a BackstagePlugin<{}> implementation.
31+
<5> (Optional): Same as key in `scalprum.exposedModules` key in plugin's `package.json`
32+
<6> (Required): One of the supported or imported bind targets
33+
<7> A required map of route bindings and is similar to `bind` function options
2834

2935
To configure `routeBindings`, complete the following steps:
3036

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

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,31 +13,32 @@ plugins:
1313
pluginConfig:
1414
dynamicPlugins:
1515
frontend:
16-
<package_name>: # same as `scalprum.name` key in plugin's `package.json`
16+
my-plugin: # <1>
1717
entityTabs:
18-
# Adding a new tab
18+
# <2>
1919
- path: /new-path
2020
title: My New Tab
2121
mountPoint: entity.page.my-new-tab
22-
# Change an existing tab's title or mount point
22+
# <3>
2323
- path: /
2424
title: General
25-
mountPoint: entity.page.overview #this can be customized too
26-
# Prioritizing tabs (higher priority appears first)
27-
- path: "/pr" # <1>
28-
title: "Changed Pull/Merge Requests" # <2>
29-
priority: 1 # Added priority field
30-
mountPoint: "entity.page.pull-requests" # <3>
31-
# Negative priority hides default tabs
25+
mountPoint: entity.page.overview
26+
- path: "/pr" # <4>
27+
title: "Changed Pull/Merge Requests" # <5>
28+
priority: 1
29+
mountPoint: "entity.page.pull-requests" # <6>
3230
- path: "/"
3331
title: "Changed Overview"
3432
mountPoint: "entity.page.overview"
35-
priority: -6 # <4>
33+
priority: -6 # <7>
3634
----
37-
<1> Specify the sub-path route in the catalog where this tab is available.
38-
<2> Specify the title you want to display.
39-
<3> The base mount point name that is available on the tab. This name is expanded to create two mount points per tab, one appended with` /context` and the second appended with `/cards`.
40-
<4> Specify the order of tabs. The tabs with higher priority values appear first.
35+
<1> Specify the plugin package name.
36+
<2> Specify a new tab
37+
<3> Change an existing tab's title or mount point
38+
<4> Specify the sub-path route in the catalog where this tab is available.
39+
<5> Specify the title you want to display.
40+
<6> The base mount point name that is available on the tab. This name is expanded to create two mount points per tab, one appended with` /context` and the second appended with `/cards`.
41+
<7> Specify the order of tabs. The tabs with higher priority values appear first.
4142

4243
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:
4344

‎modules/dynamic-plugins/proc-customizing-entity-page.adoc

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -119,24 +119,27 @@ plugins:
119119
pluginConfig:
120120
dynamicPlugins:
121121
frontend:
122-
<package_name>: # same as `scalprum.name` key in plugin's `package.json`
123-
mountPoints: # optional, uses existing mount points
122+
my-plugin: # <1>
123+
mountPoints: # <2>
124124
- mountPoint: <mountPointName>/[cards|context]
125-
module: CustomModule # optional, same as key in `scalprum.exposedModules` key in plugin's `package.json`
126-
importName: FooPluginPage # actual component name that should be rendered
127-
config: # optional, allows you to pass additional configuration to the component
128-
layout: {} # <1>
129-
if: # <2>
125+
module: CustomModule
126+
importName: FooPluginPage
127+
config: # <3>
128+
layout: {} # <4>
129+
if: # <5>
130130
allOf|anyOf|oneOf:
131-
- isMyPluginAvailable # an imported function from the same `module` within the plugin returns boolean
132-
- isKind: component # Check if the entity is of a specific kind
133-
- isType: service # Check if the entity is of a specific type
134-
- hasAnnotation: annotationKey # Check if the entity has a specific annotation key
135-
props: {} # <3>
131+
- isMyPluginAvailable
132+
- isKind: component
133+
- isType: service
134+
- hasAnnotation: annotationKey
135+
props: {} # <6>
136136
----
137-
<1> Used only in `/cards` type which renders visible content. You can pass MUI sx properties to the component, which is useful when controlling the layout of the component. `entity.page.*` mount points are rendered as CSS grid, hence with the SX property you can control the grid layout and exact positioning of the rendered component.
138-
<2> Used only in `/cards` type which renders visible content. `if` is passed to `<EntitySwitch.Case if={<here>}`.
139-
<3> Useful when you are passing additional data to the component.
137+
<1> Specify the plugin package name.
138+
<2> (Optional): Uses existing mount points
139+
<3> (Optional): Allows you to pass additional configuration to the component.
140+
<4> Used only in `/cards` type which renders visible content. You can pass MUI sx properties to the component, which is useful when controlling the layout of the component. `entity.page.*` mount points are rendered as CSS grid, hence with the SX property you can control the grid layout and exact positioning of the rendered component.
141+
<5> Used only in `/cards` type which renders visible content. `if` is passed to `<EntitySwitch.Case if={<here>}`.
142+
<6> Useful when you are passing additional data to the component.
140143

141144
The available conditions include:
142145

‎modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -13,28 +13,29 @@ plugins:
1313
pluginConfig:
1414
dynamicPlugins:
1515
frontend:
16-
<package_name>: # same as `scalprum.name` key in plugin's `package.json`
17-
menuItems: # optional, allows you to configure plugin menu items in the main sidebar navigation
18-
<menu_item_name>: # <1>
19-
icon: fooIcon # <2>
20-
title: Foo Plugin Page # <3>
21-
priority: 10 # <4>
22-
parent: favorites # <5>
23-
enabled: false # <6>
16+
my-plugin: # <1>
17+
menuItems:
18+
<menu_item_name>: # <2>
19+
icon: fooIcon # <3>
20+
title: Foo Plugin Page # <4>
21+
priority: 10 # <5>
22+
parent: favorites # <6>
23+
enabled: false # <7>
2424
----
25-
<1> Specify the unique name in the main sidebar navigation (for example, either a standalone menu item or a parent menu item).
25+
<1> Specify the plugin package name.
26+
<2> Specify the unique name in the main sidebar navigation (for example, either a standalone menu item or a parent menu item).
2627
* Handling Complex Paths:
2728
** For simple paths like `path: /my-plugin`, the `menu_item_name` should be `my-plugin`.
2829
** For complex paths like `/metrics/users/info`, the `menu_item_name` should represent the full path in dot notation (for example `metrics.users.info`).
2930
** Ignore trailing and leading slashes in paths as follows:
3031
+
3132
*** For `path: /docs`, the `menu_item_name` is `docs`.
3233
*** For `path: /metrics/users`, the `menu_item_name` is `metrics.users`.
33-
<2> Optional: Defines the icon for the menu item, which refers to a Backstage system icon.
34-
<3> Optional: Specify the display title of the menu item.
35-
<4> Optional: Defines the order in which menu items appear. The default priority is `0`.
36-
<5> Optional: Defines the parent menu item to nest the current item under.
37-
<6> Optional: Allows you to remove a `menuItem` from the sidebar when it is set to `false`.
34+
<3> Optional: Defines the icon for the menu item, which refers to a Backstage system icon.
35+
<4> Optional: Specify the display title of the menu item.
36+
<5> Optional: Defines the order in which menu items appear. The default priority is `0`.
37+
<6> Optional: Defines the parent menu item to nest the current item under.
38+
<7> Optional: Allows you to remove a `menuItem` from the sidebar when it is set to `false`.
3839

3940
[NOTE]
4041
====

‎modules/dynamic-plugins/proc-customizing-theme.adoc

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -23,21 +23,22 @@ You can declare the theme using the `themes` configuration as shown in the follo
2323
----
2424
dynamicPlugins:
2525
frontend:
26-
<package_name>: # same as `scalprum.name` key in a plugins `package.json`
26+
my-plugin: # <1>
2727
themes:
28-
- id: light # Using 'light' overrides the app-provided light theme <1>
28+
- id: light # <2>
2929
title: Light
3030
variant: light
3131
icon: someIconReference
3232
importName: lightThemeProvider
33-
- id: dark # Using 'dark' overrides the app-provided dark theme <1>
34-
title: Dark # <2>
35-
variant: dark # <3>
36-
icon: someIconReference # <4>
37-
importName: darkThemeProvider # <5>
33+
- id: dark # <3>
34+
title: Dark # <4>
35+
variant: dark # <5>
36+
icon: someIconReference # <6>
37+
importName: darkThemeProvider # <7>
3838
----
39-
<1> Specify the theme, either `light` or `dark` to replace the default theme.
40-
<2> Specify the theme name displayed to the user on the *Settings* page.
41-
<3> Whether the theme is `light` or `dark`, can only be one of these values.
42-
<4> A string reference to a system or app icon
43-
<5> Specify the name of the exported theme provider function, the function signature should match `({ children }: { children: ReactNode }): React.JSX.Element`
39+
<1> Specify the plugin package name.
40+
<2> Specify the theme, either `light` or `dark` to replace the default theme. Using 'light' overrides the app-provided light theme
41+
<3> Specify the theme name displayed to the user on the *Settings* page. Using 'dark' overrides the app-provided dark theme
42+
<4> Whether the theme is `light` or `dark`, can only be one of these values.
43+
<5> A string reference to a system or app icon
44+
<6> Specify the name of the exported theme provider function, the function signature should match `({ children }: { children: ReactNode }): React.JSX.Element`

‎modules/dynamic-plugins/proc-defining-dynamic-routes.adoc

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -15,27 +15,28 @@ plugins:
1515
pluginConfig:
1616
dynamicPlugins:
1717
frontend:
18-
<package_name>: # same as `scalprum.name` key in plugin's `package.json`
19-
dynamicRoutes: # exposes full routes
20-
- path: /my-plugin # <1>
21-
module: CustomModule # <2>
22-
importName: FooPluginPage # <3>
23-
menuItem: # <4>
24-
icon: fooIcon # Backstage system icon
25-
text: Foo Plugin Page # menu item text
26-
enabled: false # optional, allows you to remove the menu item when set to false
27-
config: # <5>
28-
props: ... # optional, React props to pass to the component
18+
my-plugin: # <1>
19+
dynamicRoutes:
20+
- path: /my-plugin # <2>
21+
module: CustomModule # <3>
22+
importName: FooPluginPage # <4>
23+
menuItem: # <5>
24+
icon: fooIcon
25+
text: Foo Plugin Page
26+
enabled: false
27+
config: # <6>
28+
props: ...
2929
----
30-
<1> Specify the unique path in the application. The path cannot override existing routes except the `/` home route. You can replace the main home page using the dynamic plugins mechanism.
31-
<2> Optional: Specify the set of assets you want to access within the plugin. By default, the system uses the `PluginRoot` module if none is specified.
32-
<3> Optional: Specify the actual component name as a standalone page. If not specified, the system uses the `default` export.
33-
<4> `menuItem` - Allows you to extend the main sidebar navigation and point to a new route. The `menuItem` accepts the following properties:
30+
<1> Specify the plugin package name.
31+
<2> Specify the unique path in the application. The path cannot override existing routes except the `/` home route. You can replace the main home page using the dynamic plugins mechanism.
32+
<3> Optional: Specify the set of assets you want to access within the plugin. By default, the system uses the `PluginRoot` module if none is specified.
33+
<4> Optional: Specify the actual component name as a standalone page. If not specified, the system uses the `default` export.
34+
<5> `menuItem` - Allows you to extend the main sidebar navigation and point to a new route. The `menuItem` accepts the following properties:
3435
* `text`: The label shown to the user
3536
* `icon`: The Backstage system icon name.
3637
* `enabled`: Optional: Allows the user to remove a menuItem from the sidebar when it is set to false.
3738
* `importName`: Specifies the optional name of an exported `SidebarItem` component.
38-
<5> Optional: Passes `props` to a custom sidebar item
39+
<6> Optional: Passes `props` to a custom sidebar item
3940
+
4041
To configure a custom `SidebarItem` to enhance experiences such as notification badges, ensure the component accepts the following properties:
4142

0 commit comments

Comments
 (0)