Skip to content

Commit bbf271f

Browse files
GitHub Actionsjmagak
GitHub Actions
authored and
jmagak
committed
Add frontend plugn wiring section
Add frontend plugn wiring section
1 parent 8be4076 commit bbf271f

16 files changed

+773
-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_{context}"]
2+
= Front-end plugin wiring
3+
:context: assembly-front-end-plugin-wiring
4+
5+
You can configure front-end plugins to do the following:
6+
7+
* Extend the internal library of available icons
8+
* Declare a new full page by defining a new route
9+
* Extend to an existing page using router bindings
10+
* Use mount points within the application
11+
* Provide additional utility APIs or replace existing ones
12+
13+
// Extending the internal icon catalog
14+
include::../modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc[leveloffset=+1]
15+
16+
// Defining dynamic routes for new plugin pages
17+
include::../modules/dynamic-plugins/proc-defining-dynamic-routes.adoc[leveloffset=+1]
18+
19+
// Customizing menu items in the sidebar navigation
20+
include::../modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc[leveloffset=+1]
21+
22+
// Bind to existing plugins
23+
include::../modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc[leveloffset=+1]
24+
25+
// Using mount points
26+
include::../modules/dynamic-plugins/proc-using-mount-points.adoc[leveloffset=+1]
27+
28+
include::../modules/dynamic-plugins/proc-customizing-entity-page.adoc[leveloffset=+2]
29+
30+
include::../modules/dynamic-plugins/proc-adding-application-header.adoc[leveloffset=+2]
31+
32+
include::../modules/dynamic-plugins/proc-adding-application-listeners.adoc[leveloffset=+2]
33+
34+
include::../modules/dynamic-plugins/proc-adding-application-providers.adoc[leveloffset=+2]
35+
36+
// Customizing and extending entity tabs
37+
include::../modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.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/proc-adding-application-header.adoc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
[id="proc-adding-application-header.adoc-catalog"]
2+
3+
= Adding application header
4+
5+
You can customize global headers by specifying configurations in the `app-config.yaml` file as shown in the following example:
6+
7+
[source,yaml]
8+
----
9+
# app-config.yaml
10+
dynamicPlugins:
11+
frontend:
12+
<package_name>: # e.g., preinstalled plugin `red-hat-developer-hub.backstage-plugin-global-header`
13+
mountPoints:
14+
- mountPoint: application/header # <1>
15+
importName: <header_component> # <2>
16+
config:
17+
position: above-main-content # <3>
18+
----
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:
22+
* `above-main-content`: Positions the header above the main content area.
23+
* `above-sidebar`: Positions the header above the sidebar.
24+
+
25+
[NOTE]
26+
====
27+
To configure multiple global headers at different positions, add entries to the `mountPoints` field.
28+
====

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

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

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

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
[id="proc-adding-application-providers"]
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+
<package_name>: # plugin_package_name same as `scalprum.name` key in plugin's `package.json`
13+
dynamicRoutes:
14+
- path: /<route>
15+
importName: Component # Component you want 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+
====

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[id="proc-adding-custom-authentication-provider-settings"]
2+
3+
= Adding custom authentication provider settings
4+
5+
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.
6+
7+
You can use the `providerSettings` configuration to add entries for an authentication provider from a dynamic plugin, as shown in the following example:
8+
9+
[source,yaml]
10+
----
11+
dynamicPlugins:
12+
frontend:
13+
<package_name>:
14+
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>
18+
----
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.

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
[id="proc-binding-to-existing-plugins"]
2+
3+
= Binding to existing plugins
4+
5+
You can bind to existing plugins and their routes, and declare new targets sourced from dynamic plugins as shown in the following `routeBindings` configuration:
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+
<package_name>: # same as `scalprum.name` key in plugin's `package.json`
17+
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`
22+
bindings:
23+
- bindTarget: "barPlugin.externalRoutes" # Required. One of the supported or imported bind targets
24+
bindMap: # <1>
25+
headerLink: "fooPlugin.routes.root"
26+
----
27+
<1> A required map of route bindings and is similar to `bind` function options
28+
29+
To configure `routeBindings`, complete the following steps:
30+
31+
. Define new targets using `routeBindings.targets`. Set the required `importName` to a `BackstagePlugin<{}>` implementation.
32+
33+
. Declare route bindings using the *routeBindings.bindings* field by setting `bindTarget` to the name of the target to bind to. This can be a dynamic or static target, such as:
34+
+
35+
** `catalogPlugin.externalRoutes`
36+
37+
** `catalogImportPlugin.externalRoutes`
38+
39+
** `techdocsPlugin.externalRoutes`
40+
41+
** `scaffolderPlugin.externalRoutes`
42+
+
43+
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: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
[id="proc-customizing-and-extending-entity-tabs"]
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+
<package_name>: # same as `scalprum.name` key in plugin's `package.json`
17+
entityTabs:
18+
# Adding 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 #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
32+
- path: "/"
33+
title: "Changed Overview"
34+
mountPoint: "entity.page.overview"
35+
priority: -6 # <4>
36+
----
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.
41+
42+
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:
43+
44+
.Input parameters
45+
[cols="20%,20%,30%,30%", frame="all", options="header"]
46+
|===
47+
|Route
48+
|Title
49+
|Mount Point
50+
|Entity Kind
51+
52+
|`/`
53+
|Overview
54+
|`entity.page.overview`
55+
|Any
56+
57+
|`/topology`
58+
|Topology
59+
|`entity.page.topology`
60+
|Any
61+
62+
|`/issues`
63+
|Issues
64+
|`entity.page.issues`
65+
|Any
66+
67+
|`/pr`
68+
|CPull/Merge Requests
69+
|`entity.page.pull-requests`
70+
|Any
71+
72+
|`/ci`
73+
|CI
74+
|`entity.page.ci``
75+
|VAny
76+
77+
|`/cd`
78+
|CD
79+
|`entity.page.cd`
80+
|Any
81+
82+
|`/kubernetes`
83+
|Kubernetes
84+
|`entity.page.kubernetes`
85+
|Any
86+
87+
|`/image-registry`
88+
|Image Registry
89+
|`entity.page.image-registry`
90+
|Any
91+
92+
|`/monitoring`
93+
|Monitoring
94+
|`entity.page.monitoring`
95+
|Any
96+
97+
|`/lighthouse`
98+
|Lighthouse
99+
|`entity.page.lighthouse`
100+
|Any
101+
102+
|`/api`
103+
|Api
104+
|`entity.page.api`
105+
|kind: Service or kind: Component
106+
107+
|`/dependencies`
108+
|Dependencies
109+
|`entity.page.dependencies`
110+
|kind: Component
111+
112+
|`/docs`
113+
|Docs
114+
|`entity.page.docs`
115+
|Any
116+
117+
|`/definition`
118+
|Definition
119+
|`entity.page.definition`
120+
|kind: API
121+
122+
|`/system`
123+
|Diagram
124+
|`entity.page.diagram`
125+
|kind: System
126+
|===
127+
128+
[NOTE]
129+
====
130+
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.
131+
====

0 commit comments

Comments
 (0)