From e3964214aad4ab853f203fec3a1d164e10628daf Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 7 Jul 2025 11:27:53 +0300 Subject: [PATCH 1/6] Add frontend plugn wiring section Add frontend plugn wiring section --- .../assembly-front-end-plugin-wiring.adoc | 49 +++++ .../proc-adding-application-header.adoc | 28 +++ .../proc-adding-application-listeners.adoc | 22 +++ .../proc-adding-application-providers.adoc | 24 +++ ...stom-authentication-provider-settings.adoc | 21 ++ .../proc-binding-to-existing-plugins.adoc | 43 ++++ ...customizing-and-extending-entity-tabs.adoc | 131 ++++++++++++ .../proc-customizing-entity-page.adoc | 186 ++++++++++++++++++ .../proc-customizing-sidebar-menu-items.adoc | 42 ++++ .../proc-customizing-theme.adoc | 43 ++++ .../proc-defining-dynamic-routes.adoc | 68 +++++++ .../proc-extending-internal-icon-catalog.adoc | 27 +++ .../proc-provide-additional-utility-apis.adoc | 58 ++++++ .../proc-provide-custom-techdocs-addons.adoc | 23 +++ .../proc-using-mount-points.adoc | 5 + titles/plugins-rhdh-install/master.adoc | 3 + 16 files changed, 773 insertions(+) create mode 100644 assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc create mode 100644 modules/dynamic-plugins/proc-adding-application-header.adoc create mode 100644 modules/dynamic-plugins/proc-adding-application-listeners.adoc create mode 100644 modules/dynamic-plugins/proc-adding-application-providers.adoc create mode 100644 modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc create mode 100644 modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc create mode 100644 modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc create mode 100644 modules/dynamic-plugins/proc-customizing-entity-page.adoc create mode 100644 modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc create mode 100644 modules/dynamic-plugins/proc-customizing-theme.adoc create mode 100644 modules/dynamic-plugins/proc-defining-dynamic-routes.adoc create mode 100644 modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc create mode 100644 modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc create mode 100644 modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc create mode 100644 modules/dynamic-plugins/proc-using-mount-points.adoc diff --git a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc new file mode 100644 index 0000000000..11bc4d108d --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc @@ -0,0 +1,49 @@ +[id="assembly-front-end-plugin-wiring_{context}"] += Front-end plugin wiring +:context: assembly-front-end-plugin-wiring + +You can configure front-end plugins to do the following: + +* Extend the internal library of available icons +* Declare a new full page by defining a new route +* Extend to an existing page using router bindings +* Use mount points within the application +* Provide additional utility APIs or replace existing ones + +// Extending the internal icon catalog +include::../modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc[leveloffset=+1] + +// Defining dynamic routes for new plugin pages +include::../modules/dynamic-plugins/proc-defining-dynamic-routes.adoc[leveloffset=+1] + +// Customizing menu items in the sidebar navigation +include::../modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc[leveloffset=+1] + +// Bind to existing plugins +include::../modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc[leveloffset=+1] + +// Using mount points +include::../modules/dynamic-plugins/proc-using-mount-points.adoc[leveloffset=+1] + +include::../modules/dynamic-plugins/proc-customizing-entity-page.adoc[leveloffset=+2] + +include::../modules/dynamic-plugins/proc-adding-application-header.adoc[leveloffset=+2] + +include::../modules/dynamic-plugins/proc-adding-application-listeners.adoc[leveloffset=+2] + +include::../modules/dynamic-plugins/proc-adding-application-providers.adoc[leveloffset=+2] + +// Customizing and extending entity tabs +include::../modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc[leveloffset=+1] + +// Provide additional Utility APIs +include::../modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc[leveloffset=+1] + +// Adding custom authentication provider settings +include::../modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc[leveloffset=+1] + +// Provide custom techdocs addons +include::../modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc[leveloffset=+1] + +// Customizing theme +include::../modules/dynamic-plugins/proc-customizing-theme.adoc[leveloffset=+1] diff --git a/modules/dynamic-plugins/proc-adding-application-header.adoc b/modules/dynamic-plugins/proc-adding-application-header.adoc new file mode 100644 index 0000000000..dedb3dcb1a --- /dev/null +++ b/modules/dynamic-plugins/proc-adding-application-header.adoc @@ -0,0 +1,28 @@ +[id="proc-adding-application-header.adoc-catalog"] + += Adding application header + +You can customize global headers by specifying configurations in the `app-config.yaml` file as shown in the following example: + +[source,yaml] +---- +# app-config.yaml +dynamicPlugins: + frontend: + : # e.g., preinstalled plugin `red-hat-developer-hub.backstage-plugin-global-header` + mountPoints: + - mountPoint: application/header # <1> + importName: # <2> + config: + position: above-main-content # <3> +---- +<1> Specify where to add the header. To specify it as a global header, use `application/header`. +<2> Specify the component exported by the global header plugin (for example, `GlobalHeader` for `red-hat-developer-hub.backstage-plugin-global-header). +<3> Specify the header's position. The supported values include: +* `above-main-content`: Positions the header above the main content area. +* `above-sidebar`: Positions the header above the sidebar. ++ +[NOTE] +==== +To configure multiple global headers at different positions, add entries to the `mountPoints` field. +==== diff --git a/modules/dynamic-plugins/proc-adding-application-listeners.adoc b/modules/dynamic-plugins/proc-adding-application-listeners.adoc new file mode 100644 index 0000000000..4b20f2c3c9 --- /dev/null +++ b/modules/dynamic-plugins/proc-adding-application-listeners.adoc @@ -0,0 +1,22 @@ +[id="proc-adding-application-listeners"] + += Adding application listeners + +You can add application listeners using the `application/listener` mount point as shown in the following example: + +[source,yaml] +---- +# app-config.yaml +dynamicPlugins: + frontend: + : # <1> + mountPoints: + - mountPoint: application/listener + importName: +---- +<1> Specify the plugin package name. + +[NOTE] +==== +You can configure multiple application listeners by adding entries to the `mountPoints` field. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-adding-application-providers.adoc b/modules/dynamic-plugins/proc-adding-application-providers.adoc new file mode 100644 index 0000000000..4c8a2dd988 --- /dev/null +++ b/modules/dynamic-plugins/proc-adding-application-providers.adoc @@ -0,0 +1,24 @@ +[id="proc-adding-application-providers"] + += Adding application providers + +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: + +[source,yaml] +---- +# app-config.yaml +dynamicPlugins: + frontend: + : # plugin_package_name same as `scalprum.name` key in plugin's `package.json` + dynamicRoutes: + - path: / + importName: Component # Component you want to load on the route + mountPoints: + - mountPoint: application/provider + importName: +---- + +[NOTE] +==== +You can configure multiple application providers by adding entries to the `mountPoints` field. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc b/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc new file mode 100644 index 0000000000..78192caa62 --- /dev/null +++ b/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc @@ -0,0 +1,21 @@ +[id="proc-adding-custom-authentication-provider-settings"] + += Adding custom authentication provider settings + +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. + +You can use the `providerSettings` configuration to add entries for an authentication provider from a dynamic plugin, as shown in the following example: + +[source,yaml] +---- +dynamicPlugins: + frontend: + : + providerSettings: + - title: My Custom Auth Provider # <1> + description: Sign in using My Custom Auth Provider # <2> + provider: core.auth.my-custom-auth-provider # <3> +---- +<1> Specify the title for the authentication provider shown above the user's profile image if available. +<2> Specify the description of the authentication provider. +<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. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc b/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc new file mode 100644 index 0000000000..4b15e650c4 --- /dev/null +++ b/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc @@ -0,0 +1,43 @@ +[id="proc-binding-to-existing-plugins"] + += Binding to existing plugins + +You can bind to existing plugins and their routes, and declare new targets sourced from dynamic plugins as shown in the following `routeBindings` configuration: + +[source,yaml] +---- +# dynamic-plugins-config.yaml +plugins: + - plugin: + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + : # same as `scalprum.name` key in plugin's `package.json` + routeBindings: + targets: # Declare a new bind target + - name: barPlugin # Optional, defaults to importName. Explicit name of the plugin that exposes the bind target + importName: barPlugin # Required. Explicit import name that reference a BackstagePlugin<{}> implementation. + module: CustomModule # Optional, same as key in `scalprum.exposedModules` key in plugin's `package.json` + bindings: + - bindTarget: "barPlugin.externalRoutes" # Required. One of the supported or imported bind targets + bindMap: # <1> + headerLink: "fooPlugin.routes.root" +---- +<1> A required map of route bindings and is similar to `bind` function options + +To configure `routeBindings`, complete the following steps: + +. Define new targets using `routeBindings.targets`. Set the required `importName` to a `BackstagePlugin<{}>` implementation. + +. 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: ++ +** `catalogPlugin.externalRoutes` + +** `catalogImportPlugin.externalRoutes` + +** `techdocsPlugin.externalRoutes` + +** `scaffolderPlugin.externalRoutes` ++ +You can extend existing pages with additional content using mount points, which are predefined identifiers available throughout the application. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc b/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc new file mode 100644 index 0000000000..5e87371a2c --- /dev/null +++ b/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc @@ -0,0 +1,131 @@ +[id="proc-customizing-and-extending-entity-tabs"] + += Customizing and extending entity tabs + +You can customize and extend the set of tabs using the `entityTabs` configuration as follows: + +[source,yaml] +---- +# dynamic-plugins-config.yaml +plugins: + - plugin: + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + : # same as `scalprum.name` key in plugin's `package.json` + entityTabs: + # Adding a new tab + - path: /new-path + title: My New Tab + mountPoint: entity.page.my-new-tab + # Change an existing tab's title or mount point + - path: / + title: General + mountPoint: entity.page.overview #this can be customized too + # Prioritizing tabs (higher priority appears first) + - path: "/pr" # <1> + title: "Changed Pull/Merge Requests" # <2> + priority: 1 # Added priority field + mountPoint: "entity.page.pull-requests" # <3> + # Negative priority hides default tabs + - path: "/" + title: "Changed Overview" + mountPoint: "entity.page.overview" + priority: -6 # <4> +---- +<1> Specify the sub-path route in the catalog where this tab is available. +<2> Specify the title you want to display. +<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`. +<4> Specify the order of tabs. The tabs with higher priority values appear first. + +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: + +.Input parameters +[cols="20%,20%,30%,30%", frame="all", options="header"] +|=== +|Route +|Title +|Mount Point +|Entity Kind + +|`/` +|Overview +|`entity.page.overview` +|Any + +|`/topology` +|Topology +|`entity.page.topology` +|Any + +|`/issues` +|Issues +|`entity.page.issues` +|Any + +|`/pr` +|CPull/Merge Requests +|`entity.page.pull-requests` +|Any + +|`/ci` +|CI +|`entity.page.ci`` +|VAny + +|`/cd` +|CD +|`entity.page.cd` +|Any + +|`/kubernetes` +|Kubernetes +|`entity.page.kubernetes` +|Any + +|`/image-registry` +|Image Registry +|`entity.page.image-registry` +|Any + +|`/monitoring` +|Monitoring +|`entity.page.monitoring` +|Any + +|`/lighthouse` +|Lighthouse +|`entity.page.lighthouse` +|Any + +|`/api` +|Api +|`entity.page.api` +|kind: Service or kind: Component + +|`/dependencies` +|Dependencies +|`entity.page.dependencies` +|kind: Component + +|`/docs` +|Docs +|`entity.page.docs` +|Any + +|`/definition` +|Definition +|`entity.page.definition` +|kind: API + +|`/system` +|Diagram +|`entity.page.diagram` +|kind: System +|=== + +[NOTE] +==== +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. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-customizing-entity-page.adoc b/modules/dynamic-plugins/proc-customizing-entity-page.adoc new file mode 100644 index 0000000000..f7b28b55dc --- /dev/null +++ b/modules/dynamic-plugins/proc-customizing-entity-page.adoc @@ -0,0 +1,186 @@ +[id="proc-customizing-entity-page"] + += Customizing entity page + +You can extend catalog components and additional views. + +The available mount points include the following: + +.Input parameters +[cols="25%,25%,50%", frame="all", options="header"] +|=== +|Mount point +|Description +|Visible even when no plugins are enabled + +|`admin.page.plugins` +|Administration plugins page +|NO + +|`admin.page.rbac` +|Administration RBAC page +|NO + +|`entity.context.menu` +|Catalog entity context menu +|YES for all entities + +|`entity.page.overview` +|Catalog entity overview page +|YES for all entities + +|`entity.page.topology` +|Catalog entity *Topology* tab +|NO + +|`entity.page.issues` +|Catalog entity *Issues* tab +|NO + +|`entity.page.pull-requests` +|Catalog entity *Pull Requests* tab +|NO + +|`entity.page.ci` +|Catalog entity *CI* tab +|NO + +|`entity.page.cd` +|Catalog entity *CD* tab +|NO + +|`entity.page.kubernetes` +|Catalog entity *Kubernetes* tab +|NO + +|`entity.page.image-registry` +|Catalog entity *Image Registry* tab +|NO + +|`entity.page.monitoring` +|Catalog entity *Monitoring* tab +|NO + +|`entity.page.lighthouse` +|Catalog entity *Lighthouse* tab +|NO + +|`entity.page.api` +|Catalog entity *API* tab +|YES for entity of `kind: Component` and `spec.type: 'service'` + +|`entity.page.dependencies` +|Catalog entity *Dependencies* tab +|YES for entity of `kind: Component` + +|`entity.page.docs` +|Catalog entity *Documentation* tab +|YES for entity that satisfies `isTechDocsAvailable` + +|`entity.page.definition` +|Catalog entity *Definitions* tab +|YES for entity of `kind: Api` + +|`entity.page.diagram` +|Catalog entity *Diagram* tab +|YES for entity of `kind: System` + +|`search.page.types` +|Search result type +|YES, default catalog search type is available + +|`search.page.filters` +|Search filters +|YES, default catalog kind and lifecycle filters are visible + +|`search.page.results` +|Search results content +|YES, default catalog search is present +|=== + +[NOTE] +==== +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. +==== + +Each `entity.page.` mount point contains the following variations: + +* `/context` type that serves to create React contexts +* `/cards` type for regular React components + +The following is an example of the overall configuration structure of a mount point: + +[source,yaml] +---- +# dynamic-plugins-config.yaml +plugins: + - plugin: + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + : # same as `scalprum.name` key in plugin's `package.json` + mountPoints: # optional, uses existing mount points + - mountPoint: /[cards|context] + module: CustomModule # optional, same as key in `scalprum.exposedModules` key in plugin's `package.json` + importName: FooPluginPage # actual component name that should be rendered + config: # optional, allows you to pass additional configuration to the component + layout: {} # <1> + if: # <2> + allOf|anyOf|oneOf: + - isMyPluginAvailable # an imported function from the same `module` within the plugin returns boolean + - isKind: component # Check if the entity is of a specific kind + - isType: service # Check if the entity is of a specific type + - hasAnnotation: annotationKey # Check if the entity has a specific annotation key + props: {} # <3> +---- +<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. +<2> Used only in `/cards` type which renders visible content. `if` is passed to `}`. +<3> Useful when you are passing additional data to the component. + +The available conditions include: + +* `allOf`: All conditions must be met +* `anyOf`: At least one condition must be met +* `oneOf`: Only one condition must be met + +Conditions can be: + +* `isKind`: Accepts a string or a list of string with entity kinds. For example `isKind: component` renders the component only for entity of `kind: Component`. +* `isType`: Accepts a string or a list of string with entity types. For example `isType: service` renders the component only for entities of `spec.type: 'service'`. +* `hasAnnotation`: Accepts a string or a list of string with annotation keys. For example `hasAnnotation: my-annotation` renders the component only for entities that have defined `metadata.annotations['my-annotation']`. +* Condition imported from the plugin's `module`: Must be function name exported from the same `module` within the plugin. For example `isMyPluginAvailable` renders the component only if `isMyPluginAvailable` function returns `true`. The function must have the following signature: `(e: Entity) => boolean` + +The entity page also supports adding more items to the context menu at the top right of the page. The exported component should be a form of dialog wrapper component that accepts an `open` boolean property and an `onClose` event handler property as shown in the following example: + +[source,yaml] +---- +export type SimpleDialogProps = { + open: boolean; + onClose: () => void; +}; +---- + +You can configure the context menu entry using the props configuration entry for the mount point. The `title` and `icon` properties sets the menu item's text and icon. You can use any system icon or icon added through a dynamic plugin. The following is an example configuration: + +[source,yaml] +---- +# dynamic-plugins-config.yaml +plugins: + - plugin: + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + my-dynamic-plugin-package: + appIcons: + - name: dialogIcon + importName: DialogIcon + mountPoints: + - mountPoint: entity.context.menu + importName: SimpleDialog + config: + props: + title: Open Simple Dialog + icon: dialogIcon +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc b/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc new file mode 100644 index 0000000000..912f7b0f59 --- /dev/null +++ b/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc @@ -0,0 +1,42 @@ +[id="proc-customizing-sidebar-menu-items"] + += Customizing menu items in the sidebar navigation + +Customize the order and parent-child relationships of plugin menu items in the main sidebar navigation using the menu items configuration as shown in the following example: + +[source,yaml] +---- +# dynamic-plugins-config.yaml +plugins: + - plugin: + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + : # same as `scalprum.name` key in plugin's `package.json` + menuItems: # optional, allows you to configure plugin menu items in the main sidebar navigation + : # <1> + icon: fooIcon # <2> + title: Foo Plugin Page # <3> + priority: 10 # <4> + parent: favorites # <5> + enabled: false # <6> +---- +<1> Specify the unique name in the main sidebar navigation (for example, either a standalone menu item or a parent menu item). +* Handling Complex Paths: +** For simple paths like `path: /my-plugin`, the `menu_item_name` should be `my-plugin`. +** For complex paths like `/metrics/users/info`, the `menu_item_name` should represent the full path in dot notation (for example `metrics.users.info`). +** Ignore trailing and leading slashes in paths as follows: ++ +*** For `path: /docs`, the `menu_item_name` is `docs`. +*** For `path: /metrics/users`, the `menu_item_name` is `metrics.users`. +<2> Optional: Defines the icon for the menu item, which refers to a Backstage system icon. +<3> Optional: Specify the display title of the menu item. +<4> Optional: Defines the order in which menu items appear. The default priority is `0`. +<5> Optional: Defines the parent menu item to nest the current item under. +<6> Optional: Allows you to remove a `menuItem` from the sidebar when it is set to `false`. + +[NOTE] +==== +{product} supports up to 3 levels of nested menu items. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-customizing-theme.adoc b/modules/dynamic-plugins/proc-customizing-theme.adoc new file mode 100644 index 0000000000..f779b37bdb --- /dev/null +++ b/modules/dynamic-plugins/proc-customizing-theme.adoc @@ -0,0 +1,43 @@ +[id="proc-customizing-theme"] + += Customizing {product} theme + +You can customize {product-short} themes from a dynamic plugin with various configurations. The dynamic plugin exports a theme provider function with a signature of `({ children }: { children: ReactNode }): React.JSX.Element` as shown in the following example: + +[source,yaml] +---- +import { lightTheme } from './lightTheme'; +import { darkTheme } from './darkTheme'; +import { UnifiedThemeProvider } from '@backstage/theme'; +export const lightThemeProvider = ({ children }: { children: ReactNode }) => ( + +); +export const darkThemeProvider = ({ children }: { children: ReactNode }) => ( + +); +---- + +You can declare the theme using the `themes` configuration as shown in the following example: + +[source,yaml] +---- +dynamicPlugins: + frontend: + : # same as `scalprum.name` key in a plugins `package.json` + themes: + - id: light # Using 'light' overrides the app-provided light theme <1> + title: Light + variant: light + icon: someIconReference + importName: lightThemeProvider + - id: dark # Using 'dark' overrides the app-provided dark theme <1> + title: Dark # <2> + variant: dark # <3> + icon: someIconReference # <4> + importName: darkThemeProvider # <5> +---- +<1> Specify the theme, either `light` or `dark` to replace the default theme. +<2> Specify the theme name displayed to the user on the *Settings* page. +<3> Whether the theme is `light` or `dark`, can only be one of these values. +<4> A string reference to a system or app icon +<5> Specify the name of the exported theme provider function, the function signature should match `({ children }: { children: ReactNode }): React.JSX.Element` \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-defining-dynamic-routes.adoc b/modules/dynamic-plugins/proc-defining-dynamic-routes.adoc new file mode 100644 index 0000000000..859ede9e0d --- /dev/null +++ b/modules/dynamic-plugins/proc-defining-dynamic-routes.adoc @@ -0,0 +1,68 @@ +[id="proc-defining-dynamic-routes"] + += Defining dynamic routes for new plugin pages + +.Procedure +. Define each route by specifying a unique `path` and, if needed, an `importName` if it is different from the `default` export. +. Expose additional routes in a dynamic plugin by configuring `dynamicRoutes` as shown in the following example: + +[source,yaml] +---- +# dynamic-plugins-config.yaml +plugins: + - plugin: + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + : # same as `scalprum.name` key in plugin's `package.json` + dynamicRoutes: # exposes full routes + - path: /my-plugin # <1> + module: CustomModule # <2> + importName: FooPluginPage # <3> + menuItem: # <4> + icon: fooIcon # Backstage system icon + text: Foo Plugin Page # menu item text + enabled: false # optional, allows you to remove the menu item when set to false + config: # <5> + props: ... # optional, React props to pass to the component +---- +<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. +<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. +<3> Optional: Specify the actual component name as a standalone page. If not specified, the system uses the `default` export. +<4> `menuItem` - Allows you to extend the main sidebar navigation and point to a new route. The `menuItem` accepts the following properties: +* `text`: The label shown to the user +* `icon`: The Backstage system icon name. +* `enabled`: Optional: Allows the user to remove a menuItem from the sidebar when it is set to false. +* `importName`: Specifies the optional name of an exported `SidebarItem` component. +<5> Optional: Passes `props` to a custom sidebar item ++ +To configure a custom `SidebarItem` to enhance experiences such as notification badges, ensure the component accepts the following properties: + +[source,yaml] +---- +export type MySidebarItemProps = { + to: string; // supplied by the sidebar during rendering, this will be the path configured for the dynamicRoute +}; +---- + +.Example specifying a custom `SidebarItem` component: +[source,yaml] +---- +# dynamic-plugins-config.yaml +plugins: + - plugin: + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + my-dynamic-plugin-package-name: + dynamicRoutes: + - importName: CustomPage + menuItem: + config: + props: + text: Click Me! + importName: SimpleSidebarItem + path: /custom_page +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc b/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc new file mode 100644 index 0000000000..c2f07c3281 --- /dev/null +++ b/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc @@ -0,0 +1,27 @@ +[id="proc-extending-internal-icon-catalog"] + += Extending internal icon catalog + +You can use the internal catalog to fetch icons for configured routes with sidebar navigation menu entry. + +.Procedure +Add a custom icon to the internal icon catalog for use in a plugin's menu item by using the `appIcons` configuration as shown in the following example: + +[source,yaml] +---- +# dynamic-plugins-config.yaml +plugins: + - plugin: + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + : # same as `scalprum.name` key in plugin's `package.json` + appIcons: + - name: fooIcon # <1> + module: CustomModule # <2> + importName: FooIcon # <3> +---- +<1> Specify a name for the icon catalog +<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. +<3> Optional: Specify the actual component name to be rendered as a standalone page. If not specified, the system uses the `default` export. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc b/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc new file mode 100644 index 0000000000..e9d510ff1c --- /dev/null +++ b/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc @@ -0,0 +1,58 @@ +[id="proc-provide-additional-utility-apis"] + += Provide additional utility APIs + +If a dynamic plugin exports the plugin object returned by `createPlugin`, it is supplied to the `createApp` API. All API factories exported by the plugin are automatically registered and available in the front-end application. + +You can add an entry to the `dynamicPlugins.frontend` configuration when a dynamic plugin contains only API factories as shown in the following example: + +[source,yaml] +---- +# app-config.yaml +dynamicPlugins: + frontend: + my-dynamic-plugin-package-with-api-factories: {} +---- + +However, when the dynamic plugin is not exporting the plugin object, explicitly configure each API factory that should be registered with the `createApp` API using the `apiFactories` configuration as shown in the following example: + +[source,yaml] +---- +# app-config.yaml +dynamicPlugins: + frontend: + : # same as `scalprum.name` key in plugin's `package.json` + apiFactories: + - importName: BarApi # <1> + module: CustomModule # <2> +---- +<1> Optional: Specify the import name that references a `AnyApiFactory<{}>` implementation. Defaults to `default` export. +<2> Optional: An argument which allows you to specify which set of assets you want to access within the plugin. If not provided, the default module named PluginRoot is used. + +The API factories initialized by the {product-short} application shell can be overridden by an API factory provided by a dynamic plugin by specifying the same API ref ID. A dynamic plugin can export `AnyApiFactory<{}>` to cater for some specific use case as shown in the following example: + +[source,yaml] +---- +export const customScmAuthApiFactory = createApiFactory({ + api: scmAuthApiRef, + deps: { githubAuthApi: githubAuthApiRef }, + factory: ({ githubAuthApi }) => + ScmAuth.merge( + ScmAuth.forGithub(githubAuthApi, { host: "github.someinstance.com" }), + ScmAuth.forGithub(githubAuthApi, { + host: "github.someotherinstance.com", + }), + ), +}); +---- + +The corresponding configuration which overrides the default `ScmAuth` API factory that {product-short} defaults to is as shown in the following example: + +[source,yaml] +---- +dynamicPlugins: + frontend: + : + apiFactories: + - importName: customScmAuthApiFactory +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc b/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc new file mode 100644 index 0000000000..753670b6f0 --- /dev/null +++ b/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc @@ -0,0 +1,23 @@ +[id="proc-provide-custom-techdocs-addons"] + += Provide custom TechDocs addons + +If a plugin provides multiple addons, each `techdocsAddon` entry specifies a unique `importName` corresponding to the addon. +Front-end plugins contribute to TechDocs component, as a result, exposing the TechDocs addon component using the `techdocsAddons` configuration as shown in the following example: + +[source,yaml] +---- +dynamicPlugins: + frontend: + : # same as `scalprum.name` key in plugin's `package.json` + techdocsAddons: + - importName: ExampleAddon # <1> + config: + props: ... # optional, React props to pass to the addon +---- +<1> Specify the name of an exported Addon component + +[NOTE] +==== +`module`is an optional argument which allows you to specify the set of assets you want to access within the plugin. By default, `PluginRoot` module is used. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-using-mount-points.adoc b/modules/dynamic-plugins/proc-using-mount-points.adoc new file mode 100644 index 0000000000..effb998b10 --- /dev/null +++ b/modules/dynamic-plugins/proc-using-mount-points.adoc @@ -0,0 +1,5 @@ +[id="proc-using-mount-points"] + += Using mount points + +Mount points are defined identifiers available across {product}. You can use these points to extend existing pages with additional content. \ No newline at end of file diff --git a/titles/plugins-rhdh-install/master.adoc b/titles/plugins-rhdh-install/master.adoc index 91aa94aadd..37e8558398 100644 --- a/titles/plugins-rhdh-install/master.adoc +++ b/titles/plugins-rhdh-install/master.adoc @@ -22,3 +22,6 @@ include::modules/dynamic-plugins/proc-enable-plugins-rhdh-container-image.adoc[l // Extensions (marketplace) plugins include::assemblies/dynamic-plugins/assembly-extensions-plugins.adoc[leveloffset=+1] + +// frontend plugin wiring +include::assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc[leveloffset=+1] From c97fb7ac5949ee6d1b34d211297f391a6a0b8911 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 9 Jul 2025 14:00:52 +0300 Subject: [PATCH 2/6] Add frontend plugn wiring section --- .../proc-adding-application-header.adoc | 15 +++++---- .../proc-adding-application-listeners.adoc | 2 +- .../proc-adding-application-providers.adoc | 9 +++-- ...stom-authentication-provider-settings.adoc | 15 +++++---- .../proc-binding-to-existing-plugins.adoc | 22 ++++++++----- ...customizing-and-extending-entity-tabs.adoc | 31 ++++++++--------- .../proc-customizing-entity-page.adoc | 33 ++++++++++--------- .../proc-customizing-sidebar-menu-items.adoc | 29 ++++++++-------- .../proc-customizing-theme.adoc | 25 +++++++------- .../proc-defining-dynamic-routes.adoc | 33 ++++++++++--------- .../proc-extending-internal-icon-catalog.adoc | 20 +++++++---- .../proc-provide-additional-utility-apis.adoc | 16 +++++---- .../proc-provide-custom-techdocs-addons.adoc | 10 +++--- 13 files changed, 144 insertions(+), 116 deletions(-) diff --git a/modules/dynamic-plugins/proc-adding-application-header.adoc b/modules/dynamic-plugins/proc-adding-application-header.adoc index dedb3dcb1a..bac211d991 100644 --- a/modules/dynamic-plugins/proc-adding-application-header.adoc +++ b/modules/dynamic-plugins/proc-adding-application-header.adoc @@ -9,16 +9,17 @@ You can customize global headers by specifying configurations in the `app-config # app-config.yaml dynamicPlugins: frontend: - : # e.g., preinstalled plugin `red-hat-developer-hub.backstage-plugin-global-header` + my-plugin: # <1> mountPoints: - - mountPoint: application/header # <1> - importName: # <2> + - mountPoint: application/header # <2> + importName: # <3> config: - position: above-main-content # <3> + position: above-main-content # <4> ---- -<1> Specify where to add the header. To specify it as a global header, use `application/header`. -<2> Specify the component exported by the global header plugin (for example, `GlobalHeader` for `red-hat-developer-hub.backstage-plugin-global-header). -<3> Specify the header's position. The supported values include: +<1> Specify the plugin package name. +<2> Specify where to add the header. To specify it as a global header, use `application/header`. +<3> Specify the component exported by the global header plugin (for example, `GlobalHeader` for `red-hat-developer-hub.backstage-plugin-global-header). +<4> Specify the header's position. The supported values include: * `above-main-content`: Positions the header above the main content area. * `above-sidebar`: Positions the header above the sidebar. + diff --git a/modules/dynamic-plugins/proc-adding-application-listeners.adoc b/modules/dynamic-plugins/proc-adding-application-listeners.adoc index 4b20f2c3c9..6b11dc5790 100644 --- a/modules/dynamic-plugins/proc-adding-application-listeners.adoc +++ b/modules/dynamic-plugins/proc-adding-application-listeners.adoc @@ -9,7 +9,7 @@ You can add application listeners using the `application/listener` mount point a # app-config.yaml dynamicPlugins: frontend: - : # <1> + my-plugin: # <1> mountPoints: - mountPoint: application/listener importName: diff --git a/modules/dynamic-plugins/proc-adding-application-providers.adoc b/modules/dynamic-plugins/proc-adding-application-providers.adoc index 4c8a2dd988..a95e6746a7 100644 --- a/modules/dynamic-plugins/proc-adding-application-providers.adoc +++ b/modules/dynamic-plugins/proc-adding-application-providers.adoc @@ -9,16 +9,19 @@ You can add application providers using the `application/provider` mount point. # app-config.yaml dynamicPlugins: frontend: - : # plugin_package_name same as `scalprum.name` key in plugin's `package.json` + my-plugin: # <1> dynamicRoutes: - path: / - importName: Component # Component you want to load on the route + importName: Component # <2> mountPoints: - mountPoint: application/provider importName: ---- +<1> Specify the plugin package name. +<2> Specify the component you want to load on the route. [NOTE] ==== -You can configure multiple application providers by adding entries to the `mountPoints` field. +. You can configure multiple application providers by adding entries to the `mountPoints` field. +. 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. ==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc b/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc index 78192caa62..d464250839 100644 --- a/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc +++ b/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc @@ -10,12 +10,13 @@ You can use the `providerSettings` configuration to add entries for an authentic ---- dynamicPlugins: frontend: - : + my-plugin: # <1> providerSettings: - - title: My Custom Auth Provider # <1> - description: Sign in using My Custom Auth Provider # <2> - provider: core.auth.my-custom-auth-provider # <3> + - title: My Custom Auth Provider # <2> + description: Sign in using My Custom Auth Provider # <3> + provider: core.auth.my-custom-auth-provider # <4> ---- -<1> Specify the title for the authentication provider shown above the user's profile image if available. -<2> Specify the description of the authentication provider. -<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. \ No newline at end of file +<1> Specify the plugin package name. +<2> Specify the title for the authentication provider shown above the user's profile image if available. +<3> Specify the description of the authentication provider. +<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. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc b/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc index 4b15e650c4..16198088b5 100644 --- a/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc +++ b/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc @@ -13,18 +13,24 @@ plugins: pluginConfig: dynamicPlugins: frontend: - : # same as `scalprum.name` key in plugin's `package.json` + my-plugin: # <1> routeBindings: - targets: # Declare a new bind target - - name: barPlugin # Optional, defaults to importName. Explicit name of the plugin that exposes the bind target - importName: barPlugin # Required. Explicit import name that reference a BackstagePlugin<{}> implementation. - module: CustomModule # Optional, same as key in `scalprum.exposedModules` key in plugin's `package.json` + targets: # <2> + - name: barPlugin # <3> + importName: barPlugin # <4> + module: CustomModule # <5> bindings: - - bindTarget: "barPlugin.externalRoutes" # Required. One of the supported or imported bind targets - bindMap: # <1> + - bindTarget: "barPlugin.externalRoutes" # <6> + bindMap: # <7> headerLink: "fooPlugin.routes.root" ---- -<1> A required map of route bindings and is similar to `bind` function options +<1> Specify the plugin package name. +<2> Declare a new bind target +<3> (Optional): defaults to importName. Explicit name of the plugin that exposes the bind target. +<4> Required. Explicit import name that reference a BackstagePlugin<{}> implementation. +<5> (Optional): Same as key in `scalprum.exposedModules` key in plugin's `package.json` +<6> (Required): One of the supported or imported bind targets +<7> A required map of route bindings and is similar to `bind` function options To configure `routeBindings`, complete the following steps: diff --git a/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc b/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc index 5e87371a2c..a14e97126d 100644 --- a/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc +++ b/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc @@ -13,31 +13,32 @@ plugins: pluginConfig: dynamicPlugins: frontend: - : # same as `scalprum.name` key in plugin's `package.json` + my-plugin: # <1> entityTabs: - # Adding a new tab + # <2> - path: /new-path title: My New Tab mountPoint: entity.page.my-new-tab - # Change an existing tab's title or mount point + # <3> - path: / title: General - mountPoint: entity.page.overview #this can be customized too - # Prioritizing tabs (higher priority appears first) - - path: "/pr" # <1> - title: "Changed Pull/Merge Requests" # <2> - priority: 1 # Added priority field - mountPoint: "entity.page.pull-requests" # <3> - # Negative priority hides default tabs + mountPoint: entity.page.overview + - path: "/pr" # <4> + title: "Changed Pull/Merge Requests" # <5> + priority: 1 + mountPoint: "entity.page.pull-requests" # <6> - path: "/" title: "Changed Overview" mountPoint: "entity.page.overview" - priority: -6 # <4> + priority: -6 # <7> ---- -<1> Specify the sub-path route in the catalog where this tab is available. -<2> Specify the title you want to display. -<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`. -<4> Specify the order of tabs. The tabs with higher priority values appear first. +<1> Specify the plugin package name. +<2> Specify a new tab +<3> Change an existing tab's title or mount point +<4> Specify the sub-path route in the catalog where this tab is available. +<5> Specify the title you want to display. +<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`. +<7> Specify the order of tabs. The tabs with higher priority values appear first. 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: diff --git a/modules/dynamic-plugins/proc-customizing-entity-page.adoc b/modules/dynamic-plugins/proc-customizing-entity-page.adoc index f7b28b55dc..2144863214 100644 --- a/modules/dynamic-plugins/proc-customizing-entity-page.adoc +++ b/modules/dynamic-plugins/proc-customizing-entity-page.adoc @@ -119,24 +119,27 @@ plugins: pluginConfig: dynamicPlugins: frontend: - : # same as `scalprum.name` key in plugin's `package.json` - mountPoints: # optional, uses existing mount points + my-plugin: # <1> + mountPoints: # <2> - mountPoint: /[cards|context] - module: CustomModule # optional, same as key in `scalprum.exposedModules` key in plugin's `package.json` - importName: FooPluginPage # actual component name that should be rendered - config: # optional, allows you to pass additional configuration to the component - layout: {} # <1> - if: # <2> + module: CustomModule + importName: FooPluginPage + config: # <3> + layout: {} # <4> + if: # <5> allOf|anyOf|oneOf: - - isMyPluginAvailable # an imported function from the same `module` within the plugin returns boolean - - isKind: component # Check if the entity is of a specific kind - - isType: service # Check if the entity is of a specific type - - hasAnnotation: annotationKey # Check if the entity has a specific annotation key - props: {} # <3> + - isMyPluginAvailable + - isKind: component + - isType: service + - hasAnnotation: annotationKey + props: {} # <6> ---- -<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. -<2> Used only in `/cards` type which renders visible content. `if` is passed to `}`. -<3> Useful when you are passing additional data to the component. +<1> Specify the plugin package name. +<2> (Optional): Uses existing mount points +<3> (Optional): Allows you to pass additional configuration to the component. +<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. +<5> Used only in `/cards` type which renders visible content. `if` is passed to `}`. +<6> Useful when you are passing additional data to the component. The available conditions include: diff --git a/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc b/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc index 912f7b0f59..8026d50141 100644 --- a/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc +++ b/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc @@ -13,16 +13,17 @@ plugins: pluginConfig: dynamicPlugins: frontend: - : # same as `scalprum.name` key in plugin's `package.json` - menuItems: # optional, allows you to configure plugin menu items in the main sidebar navigation - : # <1> - icon: fooIcon # <2> - title: Foo Plugin Page # <3> - priority: 10 # <4> - parent: favorites # <5> - enabled: false # <6> + my-plugin: # <1> + menuItems: + : # <2> + icon: fooIcon # <3> + title: Foo Plugin Page # <4> + priority: 10 # <5> + parent: favorites # <6> + enabled: false # <7> ---- -<1> Specify the unique name in the main sidebar navigation (for example, either a standalone menu item or a parent menu item). +<1> Specify the plugin package name. +<2> Specify the unique name in the main sidebar navigation (for example, either a standalone menu item or a parent menu item). * Handling Complex Paths: ** For simple paths like `path: /my-plugin`, the `menu_item_name` should be `my-plugin`. ** For complex paths like `/metrics/users/info`, the `menu_item_name` should represent the full path in dot notation (for example `metrics.users.info`). @@ -30,11 +31,11 @@ plugins: + *** For `path: /docs`, the `menu_item_name` is `docs`. *** For `path: /metrics/users`, the `menu_item_name` is `metrics.users`. -<2> Optional: Defines the icon for the menu item, which refers to a Backstage system icon. -<3> Optional: Specify the display title of the menu item. -<4> Optional: Defines the order in which menu items appear. The default priority is `0`. -<5> Optional: Defines the parent menu item to nest the current item under. -<6> Optional: Allows you to remove a `menuItem` from the sidebar when it is set to `false`. +<3> Optional: Defines the icon for the menu item, which refers to a Backstage system icon. +<4> Optional: Specify the display title of the menu item. +<5> Optional: Defines the order in which menu items appear. The default priority is `0`. +<6> Optional: Defines the parent menu item to nest the current item under. +<7> Optional: Allows you to remove a `menuItem` from the sidebar when it is set to `false`. [NOTE] ==== diff --git a/modules/dynamic-plugins/proc-customizing-theme.adoc b/modules/dynamic-plugins/proc-customizing-theme.adoc index f779b37bdb..a5794ec94f 100644 --- a/modules/dynamic-plugins/proc-customizing-theme.adoc +++ b/modules/dynamic-plugins/proc-customizing-theme.adoc @@ -23,21 +23,22 @@ You can declare the theme using the `themes` configuration as shown in the follo ---- dynamicPlugins: frontend: - : # same as `scalprum.name` key in a plugins `package.json` + my-plugin: # <1> themes: - - id: light # Using 'light' overrides the app-provided light theme <1> + - id: light # <2> title: Light variant: light icon: someIconReference importName: lightThemeProvider - - id: dark # Using 'dark' overrides the app-provided dark theme <1> - title: Dark # <2> - variant: dark # <3> - icon: someIconReference # <4> - importName: darkThemeProvider # <5> + - id: dark # <3> + title: Dark # <4> + variant: dark # <5> + icon: someIconReference # <6> + importName: darkThemeProvider # <7> ---- -<1> Specify the theme, either `light` or `dark` to replace the default theme. -<2> Specify the theme name displayed to the user on the *Settings* page. -<3> Whether the theme is `light` or `dark`, can only be one of these values. -<4> A string reference to a system or app icon -<5> Specify the name of the exported theme provider function, the function signature should match `({ children }: { children: ReactNode }): React.JSX.Element` \ No newline at end of file +<1> Specify the plugin package name. +<2> Specify the theme, either `light` or `dark` to replace the default theme. Using 'light' overrides the app-provided light theme +<3> Specify the theme name displayed to the user on the *Settings* page. Using 'dark' overrides the app-provided dark theme +<4> Whether the theme is `light` or `dark`, can only be one of these values. +<5> A string reference to a system or app icon +<6> Specify the name of the exported theme provider function, the function signature should match `({ children }: { children: ReactNode }): React.JSX.Element` \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-defining-dynamic-routes.adoc b/modules/dynamic-plugins/proc-defining-dynamic-routes.adoc index 859ede9e0d..ead7744757 100644 --- a/modules/dynamic-plugins/proc-defining-dynamic-routes.adoc +++ b/modules/dynamic-plugins/proc-defining-dynamic-routes.adoc @@ -15,27 +15,28 @@ plugins: pluginConfig: dynamicPlugins: frontend: - : # same as `scalprum.name` key in plugin's `package.json` - dynamicRoutes: # exposes full routes - - path: /my-plugin # <1> - module: CustomModule # <2> - importName: FooPluginPage # <3> - menuItem: # <4> - icon: fooIcon # Backstage system icon - text: Foo Plugin Page # menu item text - enabled: false # optional, allows you to remove the menu item when set to false - config: # <5> - props: ... # optional, React props to pass to the component + my-plugin: # <1> + dynamicRoutes: + - path: /my-plugin # <2> + module: CustomModule # <3> + importName: FooPluginPage # <4> + menuItem: # <5> + icon: fooIcon + text: Foo Plugin Page + enabled: false + config: # <6> + props: ... ---- -<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. -<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. -<3> Optional: Specify the actual component name as a standalone page. If not specified, the system uses the `default` export. -<4> `menuItem` - Allows you to extend the main sidebar navigation and point to a new route. The `menuItem` accepts the following properties: +<1> Specify the plugin package name. +<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. +<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. +<4> Optional: Specify the actual component name as a standalone page. If not specified, the system uses the `default` export. +<5> `menuItem` - Allows you to extend the main sidebar navigation and point to a new route. The `menuItem` accepts the following properties: * `text`: The label shown to the user * `icon`: The Backstage system icon name. * `enabled`: Optional: Allows the user to remove a menuItem from the sidebar when it is set to false. * `importName`: Specifies the optional name of an exported `SidebarItem` component. -<5> Optional: Passes `props` to a custom sidebar item +<6> Optional: Passes `props` to a custom sidebar item + To configure a custom `SidebarItem` to enhance experiences such as notification badges, ensure the component accepts the following properties: diff --git a/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc b/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc index c2f07c3281..c9deda2baa 100644 --- a/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc +++ b/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc @@ -16,12 +16,18 @@ plugins: pluginConfig: dynamicPlugins: frontend: - : # same as `scalprum.name` key in plugin's `package.json` + my-plugin: # <1> appIcons: - - name: fooIcon # <1> - module: CustomModule # <2> - importName: FooIcon # <3> + - name: fooIcon # <2> + module: CustomModule # <3> + importName: FooIcon # <4> ---- -<1> Specify a name for the icon catalog -<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. -<3> Optional: Specify the actual component name to be rendered as a standalone page. If not specified, the system uses the `default` export. \ No newline at end of file +<1> Specify the plugin package name. +<2> Specify a name for the icon catalog +<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. +<4> Optional: Specify the actual component name to be rendered as a standalone page. If not specified, the system uses the `default` export. + +[NOTE] +==== +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. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc b/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc index e9d510ff1c..7bf8fd38f0 100644 --- a/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc +++ b/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc @@ -21,13 +21,14 @@ However, when the dynamic plugin is not exporting the plugin object, explicitly # app-config.yaml dynamicPlugins: frontend: - : # same as `scalprum.name` key in plugin's `package.json` + my-plugin: # <1> apiFactories: - - importName: BarApi # <1> - module: CustomModule # <2> + - importName: BarApi # <2> + module: CustomModule # <3> ---- -<1> Optional: Specify the import name that references a `AnyApiFactory<{}>` implementation. Defaults to `default` export. -<2> Optional: An argument which allows you to specify which set of assets you want to access within the plugin. If not provided, the default module named PluginRoot is used. +<1> Specify the plugin package name. +<2> Optional: Specify the import name that references a `AnyApiFactory<{}>` implementation. Defaults to `default` export. +<3> Optional: An argument which allows you to specify which set of assets you want to access within the plugin. If not provided, the default module named PluginRoot is used. The API factories initialized by the {product-short} application shell can be overridden by an API factory provided by a dynamic plugin by specifying the same API ref ID. A dynamic plugin can export `AnyApiFactory<{}>` to cater for some specific use case as shown in the following example: @@ -52,7 +53,8 @@ The corresponding configuration which overrides the default `ScmAuth` API factor ---- dynamicPlugins: frontend: - : + my-plugin: # <1> apiFactories: - importName: customScmAuthApiFactory ----- \ No newline at end of file +---- +<1> Specify the plugin package name. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc b/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc index 753670b6f0..1283f6337e 100644 --- a/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc +++ b/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc @@ -9,13 +9,15 @@ Front-end plugins contribute to TechDocs component, as a result, exposing the Te ---- dynamicPlugins: frontend: - : # same as `scalprum.name` key in plugin's `package.json` + my-plugin: # <1> techdocsAddons: - - importName: ExampleAddon # <1> + - importName: ExampleAddon # <2> config: - props: ... # optional, React props to pass to the addon + props: ... # <3> ---- -<1> Specify the name of an exported Addon component +<1> Specify the plugin package name. +<2> Specify the name of an exported Addon component +<3> (Optional): React props to pass to the addon [NOTE] ==== From d867b3ffc583bfa42125586ffdcdbcbac6570ba0 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 9 Jul 2025 15:07:36 +0300 Subject: [PATCH 3/6] Add frontend plugn wiring section --- .../assembly-front-end-plugin-wiring.adoc | 6 ++++ ...ng-custom-scaffolder-field-extensions.adoc | 29 +++++++++++++++++++ ...con-using-custom-signinpage-component.adoc | 27 +++++++++++++++++ 3 files changed, 62 insertions(+) create mode 100644 modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc create mode 100644 modules/dynamic-plugins/con-using-custom-signinpage-component.adoc diff --git a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc index 11bc4d108d..44199db822 100644 --- a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc +++ b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc @@ -36,6 +36,12 @@ include::../modules/dynamic-plugins/proc-adding-application-providers.adoc[level // Customizing and extending entity tabs include::../modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc[leveloffset=+1] +// SignIn page +include::../modules/dynamic-plugins/con-using-custom-signinpage-component.adoc[leveloffset=+1] + +// custom scaffolder extension +include::../modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc[leveloffset=+1] + // Provide additional Utility APIs include::../modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc[leveloffset=+1] diff --git a/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc b/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc new file mode 100644 index 0000000000..2ac5fe8f98 --- /dev/null +++ b/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc @@ -0,0 +1,29 @@ +[id="con-providing-custom-scaffolder-field-extensions"] + += Providing custom Scaffolder field extensions + +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. + +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. + +When you configure custom scaffolder field extensions: + +* The dynamic plugin exposes the field extension component using `createScaffolderFieldExtension`. +* Each field extension requires a unique `importName` for registration. +* Multiple field extensions can be registered by listing each in the configuration. + +[source,yaml] +---- +dynamicPlugins: + frontend: + my-plugin: # <1> + scaffolderFieldExtensions: + - importName: MyNewFieldExtension # <2> +---- +<1> Specify the plugin package name. +<2> The `importName` references the exported scaffolder field extension component from your plugin. + +[NOTE] +==== +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 your plugin's `package.json`. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc b/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc new file mode 100644 index 0000000000..5f8c871fdc --- /dev/null +++ b/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc @@ -0,0 +1,27 @@ +[id="con-using-custom-signinpage-component"] += Using a custom SignInPage component + +In {product} ({product-very-short}), the `SignInPage` component manages the application's authentication flow. The `SignInPage` 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. + +When you configure a custom `SignInPage`: + +* The system loads the specified `importName` component from your dynamic plugin. +* The component returns a configured `SignInPage` that connects the desired authentication provider factories. +* Only one `signInPage` can be specified for the application at a time. + +[source,yaml] +---- +dynamicPlugins: + frontend: + my-plugin: # <1> + signInPage: + importName: CustomSignInPage +---- +<1> Specify the plugin package name. + +[NOTE] +==== +The `package_name` under `dynamicPlugins.frontend` must match the `scalprum.name` value in your plugin's `package.json` to ensure the dynamic plugin loads correctly during runtime. + +The `module` field is optional and allows specifying which set of assets should be accessed within the dynamic plugin. By default, the system uses the `PluginRoot` module. +==== \ No newline at end of file From 6b75c9b1a07680ddfd6a51c5fb9fa29a31702064 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 13 Aug 2025 16:56:34 +0200 Subject: [PATCH 4/6] Add frontend plugn wiring section --- .../assembly-front-end-plugin-wiring.adoc | 12 ++--- ...ng-custom-scaffolder-field-extensions.adoc | 11 ++--- ...con-using-custom-signinpage-component.adoc | 9 ++-- .../proc-adding-application-header.adoc | 19 +++----- .../proc-adding-application-listeners.adoc | 6 +-- .../proc-adding-application-providers.adoc | 8 ++-- ...stom-authentication-provider-settings.adoc | 23 +++++----- .../proc-binding-to-existing-plugins.adoc | 29 +++++------- ...customizing-and-extending-entity-tabs.adoc | 26 +++++------ .../proc-customizing-entity-page.adoc | 26 +++++------ .../proc-customizing-sidebar-menu-items.adoc | 45 ++++++++++--------- .../proc-customizing-theme.adoc | 30 ++++++------- ...-dynamic-routes-for-new-plugin-pages.adoc} | 30 +++++++------ .../proc-extending-internal-icon-catalog.adoc | 18 ++++---- .../proc-provide-additional-utility-apis.adoc | 21 ++++----- .../proc-provide-custom-techdocs-addons.adoc | 21 +++------ .../proc-using-mount-points.adoc | 3 +- 17 files changed, 145 insertions(+), 192 deletions(-) rename modules/dynamic-plugins/{proc-defining-dynamic-routes.adoc => proc-defining-dynamic-routes-for-new-plugin-pages.adoc} (64%) diff --git a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc index 44199db822..f03d12f156 100644 --- a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc +++ b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc @@ -1,20 +1,14 @@ -[id="assembly-front-end-plugin-wiring_{context}"] +[id="assembly-front-end-plugin-wiring.adoc_{context}"] = Front-end plugin wiring :context: assembly-front-end-plugin-wiring -You can configure front-end plugins to do the following: - -* Extend the internal library of available icons -* Declare a new full page by defining a new route -* Extend to an existing page using router bindings -* Use mount points within the application -* Provide additional utility APIs or replace existing ones +You can configure front-end plugins to customize icons, integrate components at mount points, and provide or replace utility APIs. // Extending the internal icon catalog include::../modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc[leveloffset=+1] // Defining dynamic routes for new plugin pages -include::../modules/dynamic-plugins/proc-defining-dynamic-routes.adoc[leveloffset=+1] +include::../modules/dynamic-plugins/proc-defining-dynamic-routes-for-new-plugin-pages.adoc[leveloffset=+1] // Customizing menu items in the sidebar navigation include::../modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc[leveloffset=+1] diff --git a/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc b/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc index 2ac5fe8f98..cbccc55cd4 100644 --- a/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc +++ b/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc @@ -1,5 +1,4 @@ -[id="con-providing-custom-scaffolder-field-extensions"] - +[id="con-providing-custom-scaffolder-field-extensions.adoc_{context}"] = Providing custom Scaffolder field extensions 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. @@ -10,18 +9,16 @@ When you configure custom scaffolder field extensions: * The dynamic plugin exposes the field extension component using `createScaffolderFieldExtension`. * Each field extension requires a unique `importName` for registration. -* Multiple field extensions can be registered by listing each in the configuration. +* You register multiple field extensions by listing each in the configuration. [source,yaml] ---- dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name scaffolderFieldExtensions: - - importName: MyNewFieldExtension # <2> + - importName: MyNewFieldExtension # References the exported scaffolder field extension component from your plugin ---- -<1> Specify the plugin package name. -<2> The `importName` references the exported scaffolder field extension component from your plugin. [NOTE] ==== diff --git a/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc b/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc index 5f8c871fdc..d145f63b19 100644 --- a/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc +++ b/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc @@ -1,23 +1,22 @@ -[id="con-using-custom-signinpage-component"] +[id="con-using-custom-signinpage-component.adoc_{context}"] = Using a custom SignInPage component -In {product} ({product-very-short}), the `SignInPage` component manages the application's authentication flow. The `SignInPage` 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. +In {product} ({product-very-short}), the `SignInPage` component manages the application's authentication flow. 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. When you configure a custom `SignInPage`: * The system loads the specified `importName` component from your dynamic plugin. * The component returns a configured `SignInPage` that connects the desired authentication provider factories. -* Only one `signInPage` can be specified for the application at a time. +* Only one `signInPage` is specified for the application at a time. [source,yaml] ---- dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name signInPage: importName: CustomSignInPage ---- -<1> Specify the plugin package name. [NOTE] ==== diff --git a/modules/dynamic-plugins/proc-adding-application-header.adoc b/modules/dynamic-plugins/proc-adding-application-header.adoc index bac211d991..bb0f415b3a 100644 --- a/modules/dynamic-plugins/proc-adding-application-header.adoc +++ b/modules/dynamic-plugins/proc-adding-application-header.adoc @@ -1,5 +1,4 @@ -[id="proc-adding-application-header.adoc-catalog"] - +[id="proc-adding-application-header.adoc_{context}"] = Adding application header You can customize global headers by specifying configurations in the `app-config.yaml` file as shown in the following example: @@ -9,20 +8,14 @@ You can customize global headers by specifying configurations in the `app-config # app-config.yaml dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name mountPoints: - - mountPoint: application/header # <2> - importName: # <3> + - mountPoint: application/header # Adds the header as a global header + importName: # Specifies the component exported by the global header plugin config: - position: above-main-content # <4> + position: above-main-content # Supported values: (`above-main-content`| above-sidebar`) ---- -<1> Specify the plugin package name. -<2> Specify where to add the header. To specify it as a global header, use `application/header`. -<3> Specify the component exported by the global header plugin (for example, `GlobalHeader` for `red-hat-developer-hub.backstage-plugin-global-header). -<4> Specify the header's position. The supported values include: -* `above-main-content`: Positions the header above the main content area. -* `above-sidebar`: Positions the header above the sidebar. -+ + [NOTE] ==== To configure multiple global headers at different positions, add entries to the `mountPoints` field. diff --git a/modules/dynamic-plugins/proc-adding-application-listeners.adoc b/modules/dynamic-plugins/proc-adding-application-listeners.adoc index 6b11dc5790..7da94d5eac 100644 --- a/modules/dynamic-plugins/proc-adding-application-listeners.adoc +++ b/modules/dynamic-plugins/proc-adding-application-listeners.adoc @@ -1,5 +1,4 @@ -[id="proc-adding-application-listeners"] - +[id="proc-adding-application-listeners.adoc_{context}"] = Adding application listeners You can add application listeners using the `application/listener` mount point as shown in the following example: @@ -9,12 +8,11 @@ You can add application listeners using the `application/listener` mount point a # app-config.yaml dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name mountPoints: - mountPoint: application/listener importName: ---- -<1> Specify the plugin package name. [NOTE] ==== diff --git a/modules/dynamic-plugins/proc-adding-application-providers.adoc b/modules/dynamic-plugins/proc-adding-application-providers.adoc index a95e6746a7..e0671cd58b 100644 --- a/modules/dynamic-plugins/proc-adding-application-providers.adoc +++ b/modules/dynamic-plugins/proc-adding-application-providers.adoc @@ -1,4 +1,4 @@ -[id="proc-adding-application-providers"] +[id="proc-adding-application-providers.adoc_{context}"] = Adding application providers @@ -9,16 +9,14 @@ You can add application providers using the `application/provider` mount point. # app-config.yaml dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name dynamicRoutes: - path: / - importName: Component # <2> + importName: Component # The component to load on the route mountPoints: - mountPoint: application/provider importName: ---- -<1> Specify the plugin package name. -<2> Specify the component you want to load on the route. [NOTE] ==== diff --git a/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc b/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc index d464250839..c433af58a9 100644 --- a/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc +++ b/modules/dynamic-plugins/proc-adding-custom-authentication-provider-settings.adoc @@ -1,5 +1,4 @@ -[id="proc-adding-custom-authentication-provider-settings"] - +[id="proc-adding-custom-authentication-provider-settings.adoc_{context}"] = Adding custom authentication provider settings 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. @@ -10,13 +9,17 @@ You can use the `providerSettings` configuration to add entries for an authentic ---- dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name providerSettings: - - title: My Custom Auth Provider # <2> - description: Sign in using My Custom Auth Provider # <3> - provider: core.auth.my-custom-auth-provider # <4> + # The title for the authentication provider shown above the user's profile image if available + - title: My Custom Auth Provider + # The description of the authentication provider + description: Sign in using My Custom Auth Provider + # The ID of the authentication provider as provided to the `createApiRef` API call. + provider: core.auth.my-custom-auth-provider ---- -<1> Specify the plugin package name. -<2> Specify the title for the authentication provider shown above the user's profile image if available. -<3> Specify the description of the authentication provider. -<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. \ No newline at end of file + +[NOTE] +==== +`provider` looks up the corresponding API factory for the authentication provider to connect the provider's Sign In/Sign Out button. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc b/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc index 16198088b5..df8bda6dea 100644 --- a/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc +++ b/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc @@ -1,5 +1,4 @@ -[id="proc-binding-to-existing-plugins"] - +[id="proc-binding-to-existing-plugins.adoc_{context}"] = Binding to existing plugins You can bind to existing plugins and their routes, and declare new targets sourced from dynamic plugins as shown in the following `routeBindings` configuration: @@ -13,30 +12,26 @@ plugins: pluginConfig: dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name routeBindings: - targets: # <2> - - name: barPlugin # <3> - importName: barPlugin # <4> - module: CustomModule # <5> + targets: # A new bind target + # (Optional): Defaults to importName. Explicit name of the plugin that exposes the bind target. + - name: barPlugin + # (Required): Explicit import name that reference a BackstagePlugin<{}> implementation. + importName: barPlugin + # (Optional): Same as key in `scalprum.exposedModules` key in plugin's `package.json` + module: CustomModule bindings: - - bindTarget: "barPlugin.externalRoutes" # <6> - bindMap: # <7> + - bindTarget: "barPlugin.externalRoutes" # (Required): One of the supported or imported bind targets + bindMap: # A required map of route bindings similar to `bind` function options headerLink: "fooPlugin.routes.root" ---- -<1> Specify the plugin package name. -<2> Declare a new bind target -<3> (Optional): defaults to importName. Explicit name of the plugin that exposes the bind target. -<4> Required. Explicit import name that reference a BackstagePlugin<{}> implementation. -<5> (Optional): Same as key in `scalprum.exposedModules` key in plugin's `package.json` -<6> (Required): One of the supported or imported bind targets -<7> A required map of route bindings and is similar to `bind` function options To configure `routeBindings`, complete the following steps: . Define new targets using `routeBindings.targets`. Set the required `importName` to a `BackstagePlugin<{}>` implementation. -. 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: +. 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: + ** `catalogPlugin.externalRoutes` diff --git a/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc b/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc index a14e97126d..541fee45ba 100644 --- a/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc +++ b/modules/dynamic-plugins/proc-customizing-and-extending-entity-tabs.adoc @@ -1,4 +1,4 @@ -[id="proc-customizing-and-extending-entity-tabs"] +[id="proc-customizing-and-extending-entity-tabs.adoc_{context}"] = Customizing and extending entity tabs @@ -13,32 +13,28 @@ plugins: pluginConfig: dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name entityTabs: - # <2> + # Specify a new tab - path: /new-path title: My New Tab mountPoint: entity.page.my-new-tab - # <3> + # Change an existing tab's title or mount point - path: / title: General mountPoint: entity.page.overview - - path: "/pr" # <4> - title: "Changed Pull/Merge Requests" # <5> + # Specify the sub-path route in the catalog where this tab is available + - path: "/pr" + title: "Changed Pull/Merge Requests" # Specify the title you want to display priority: 1 - mountPoint: "entity.page.pull-requests" # <6> + # The base mount point name available on the tab. This name expands to create two mount points per tab, with` /context` and with `/cards` + mountPoint: "entity.page.pull-requests" - path: "/" title: "Changed Overview" mountPoint: "entity.page.overview" - priority: -6 # <7> + # Specify the order of tabs. The tabs with higher priority values appear first + priority: -6 ---- -<1> Specify the plugin package name. -<2> Specify a new tab -<3> Change an existing tab's title or mount point -<4> Specify the sub-path route in the catalog where this tab is available. -<5> Specify the title you want to display. -<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`. -<7> Specify the order of tabs. The tabs with higher priority values appear first. 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: diff --git a/modules/dynamic-plugins/proc-customizing-entity-page.adoc b/modules/dynamic-plugins/proc-customizing-entity-page.adoc index 2144863214..c49069b678 100644 --- a/modules/dynamic-plugins/proc-customizing-entity-page.adoc +++ b/modules/dynamic-plugins/proc-customizing-entity-page.adoc @@ -1,5 +1,4 @@ -[id="proc-customizing-entity-page"] - +[id="proc-customizing-entity-page.adoc_{context}"] = Customizing entity page You can extend catalog components and additional views. @@ -119,27 +118,22 @@ plugins: pluginConfig: dynamicPlugins: frontend: - my-plugin: # <1> - mountPoints: # <2> + my-plugin: # The plugin package name + mountPoints: # (Optional): Uses existing mount points - mountPoint: /[cards|context] module: CustomModule importName: FooPluginPage - config: # <3> - layout: {} # <4> - if: # <5> + config: # (Optional): Allows you to pass additional configuration to the component + layout: {} # Used only in `/cards` type which renders visible content + # Use only in `/cards` type which renders visible content. `if` is passed to `}`. + if: allOf|anyOf|oneOf: - isMyPluginAvailable - isKind: component - isType: service - hasAnnotation: annotationKey - props: {} # <6> + props: {} # Useful when you are passing additional data to the component ---- -<1> Specify the plugin package name. -<2> (Optional): Uses existing mount points -<3> (Optional): Allows you to pass additional configuration to the component. -<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. -<5> Used only in `/cards` type which renders visible content. `if` is passed to `}`. -<6> Useful when you are passing additional data to the component. The available conditions include: @@ -147,14 +141,14 @@ The available conditions include: * `anyOf`: At least one condition must be met * `oneOf`: Only one condition must be met -Conditions can be: +Conditions are: * `isKind`: Accepts a string or a list of string with entity kinds. For example `isKind: component` renders the component only for entity of `kind: Component`. * `isType`: Accepts a string or a list of string with entity types. For example `isType: service` renders the component only for entities of `spec.type: 'service'`. * `hasAnnotation`: Accepts a string or a list of string with annotation keys. For example `hasAnnotation: my-annotation` renders the component only for entities that have defined `metadata.annotations['my-annotation']`. * Condition imported from the plugin's `module`: Must be function name exported from the same `module` within the plugin. For example `isMyPluginAvailable` renders the component only if `isMyPluginAvailable` function returns `true`. The function must have the following signature: `(e: Entity) => boolean` -The entity page also supports adding more items to the context menu at the top right of the page. The exported component should be a form of dialog wrapper component that accepts an `open` boolean property and an `onClose` event handler property as shown in the following example: +The entity page supports adding more items to the context menu at the top right of the page. The exported component is a form of dialog wrapper component that accepts an `open` boolean property and an `onClose` event handler property as shown in the following example: [source,yaml] ---- diff --git a/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc b/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc index 8026d50141..1a608e274f 100644 --- a/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc +++ b/modules/dynamic-plugins/proc-customizing-sidebar-menu-items.adoc @@ -1,8 +1,8 @@ -[id="proc-customizing-sidebar-menu-items"] +[id="proc-customizing-sidebar-menu-items.adoc_{context}"] = Customizing menu items in the sidebar navigation -Customize the order and parent-child relationships of plugin menu items in the main sidebar navigation using the menu items configuration as shown in the following example: +You can customize the order and parent-child relationships of plugin menu items in the main sidebar navigation using the menu items configuration as shown in the following example: [source,yaml] ---- @@ -13,29 +13,30 @@ plugins: pluginConfig: dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name menuItems: - : # <2> - icon: fooIcon # <3> - title: Foo Plugin Page # <4> - priority: 10 # <5> - parent: favorites # <6> - enabled: false # <7> + # The unique name in the main sidebar navigation (for example, either a standalone menu item or a parent menu item) + : + # (Optional): The icon for the menu item, which refers to a Backstage system icon + icon: fooIcon + # (Optional): The display title of the menu item + title: Foo Plugin Page + # (Optional): The order in which menu items appear. The default priority is `0`. + priority: 10 + # (Optional): Defines the parent menu item to nest the current item under + parent: favorites + # (Optional): Allows you to remove a `menuItem` from the sidebar when it is set to `false` + enabled: false ---- -<1> Specify the plugin package name. -<2> Specify the unique name in the main sidebar navigation (for example, either a standalone menu item or a parent menu item). -* Handling Complex Paths: -** For simple paths like `path: /my-plugin`, the `menu_item_name` should be `my-plugin`. -** For complex paths like `/metrics/users/info`, the `menu_item_name` should represent the full path in dot notation (for example `metrics.users.info`). -** Ignore trailing and leading slashes in paths as follows: + +Handling Complex Paths: + +* For simple paths like `path: /my-plugin`, the `menu_item_name` should be `my-plugin`. +* For complex paths like `/metrics/users/info`, the `menu_item_name` should represent the full path in dot notation (for example `metrics.users.info`). +* Ignore trailing and leading slashes in paths as follows: + -*** For `path: /docs`, the `menu_item_name` is `docs`. -*** For `path: /metrics/users`, the `menu_item_name` is `metrics.users`. -<3> Optional: Defines the icon for the menu item, which refers to a Backstage system icon. -<4> Optional: Specify the display title of the menu item. -<5> Optional: Defines the order in which menu items appear. The default priority is `0`. -<6> Optional: Defines the parent menu item to nest the current item under. -<7> Optional: Allows you to remove a `menuItem` from the sidebar when it is set to `false`. +** For `path: /docs`, the `menu_item_name` is `docs`. +** For `path: /metrics/users`, the `menu_item_name` is `metrics.users`. [NOTE] ==== diff --git a/modules/dynamic-plugins/proc-customizing-theme.adoc b/modules/dynamic-plugins/proc-customizing-theme.adoc index a5794ec94f..f132391681 100644 --- a/modules/dynamic-plugins/proc-customizing-theme.adoc +++ b/modules/dynamic-plugins/proc-customizing-theme.adoc @@ -1,8 +1,7 @@ -[id="proc-customizing-theme"] - +[id="proc-customizing-theme.adoc_{context}"] = Customizing {product} theme -You can customize {product-short} themes from a dynamic plugin with various configurations. The dynamic plugin exports a theme provider function with a signature of `({ children }: { children: ReactNode }): React.JSX.Element` as shown in the following example: +You can customize {product-short} themes from a dynamic plugin with various configurations as shown in the following example: [source,yaml] ---- @@ -17,28 +16,27 @@ export const darkThemeProvider = ({ children }: { children: ReactNode }) => ( ); ---- +For more information about creating a custom theme, see link:{customizing-book-url}#proc-loading-custom-theme-using-dynamic-plugin-_customizing-appearance[creating a custom theme]. + You can declare the theme using the `themes` configuration as shown in the following example: [source,yaml] ---- dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name themes: - - id: light # <2> + # are `light` or `dark`. Using 'light' overrides the app-provided light theme + - id: light title: Light variant: light icon: someIconReference importName: lightThemeProvider - - id: dark # <3> - title: Dark # <4> - variant: dark # <5> - icon: someIconReference # <6> - importName: darkThemeProvider # <7> + # The theme name displayed to the user on the *Settings* page. Using 'dark' overrides the app-provided dark theme + - id: dark + title: Dark + variant: dark + icon: someIconReference # A string reference to a system or app icon + # The name of the exported theme provider function, the function signature should match `({ children }: { children: ReactNode }): React.JSX.Element` + importName: darkThemeProvider ---- -<1> Specify the plugin package name. -<2> Specify the theme, either `light` or `dark` to replace the default theme. Using 'light' overrides the app-provided light theme -<3> Specify the theme name displayed to the user on the *Settings* page. Using 'dark' overrides the app-provided dark theme -<4> Whether the theme is `light` or `dark`, can only be one of these values. -<5> A string reference to a system or app icon -<6> Specify the name of the exported theme provider function, the function signature should match `({ children }: { children: ReactNode }): React.JSX.Element` \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-defining-dynamic-routes.adoc b/modules/dynamic-plugins/proc-defining-dynamic-routes-for-new-plugin-pages.adoc similarity index 64% rename from modules/dynamic-plugins/proc-defining-dynamic-routes.adoc rename to modules/dynamic-plugins/proc-defining-dynamic-routes-for-new-plugin-pages.adoc index ead7744757..28e6143e6c 100644 --- a/modules/dynamic-plugins/proc-defining-dynamic-routes.adoc +++ b/modules/dynamic-plugins/proc-defining-dynamic-routes-for-new-plugin-pages.adoc @@ -1,12 +1,13 @@ -[id="proc-defining-dynamic-routes"] +[id="proc-defining-dynamic-routes-for-new-plugin-pages.adoc_{context}"] = Defining dynamic routes for new plugin pages .Procedure . Define each route by specifying a unique `path` and, if needed, an `importName` if it is different from the `default` export. . Expose additional routes in a dynamic plugin by configuring `dynamicRoutes` as shown in the following example: - ++ [source,yaml] ++ ---- # dynamic-plugins-config.yaml plugins: @@ -15,28 +16,29 @@ plugins: pluginConfig: dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name dynamicRoutes: - - path: /my-plugin # <2> - module: CustomModule # <3> - importName: FooPluginPage # <4> - menuItem: # <5> + # The unique path in the application. The path cannot override existing routes except the `/` home route. + - path: /my-plugin + # (Optional): The set of assets to access within the plugin. If not specified, the system uses the `PluginRoot` module. + module: CustomModule + # (Optional): The component name as a standalone page. If not specified, the system uses the `default` export. + importName: FooPluginPage + # Allows you to extend the main sidebar navigation and point to a new route. + menuItem: icon: fooIcon text: Foo Plugin Page enabled: false - config: # <6> + config: # (Optional): Passes `props` to a custom sidebar item props: ... ---- -<1> Specify the plugin package name. -<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. -<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. -<4> Optional: Specify the actual component name as a standalone page. If not specified, the system uses the `default` export. -<5> `menuItem` - Allows you to extend the main sidebar navigation and point to a new route. The `menuItem` accepts the following properties: ++ +The `menuItem` accepts the following properties: + * `text`: The label shown to the user * `icon`: The Backstage system icon name. * `enabled`: Optional: Allows the user to remove a menuItem from the sidebar when it is set to false. * `importName`: Specifies the optional name of an exported `SidebarItem` component. -<6> Optional: Passes `props` to a custom sidebar item + To configure a custom `SidebarItem` to enhance experiences such as notification badges, ensure the component accepts the following properties: diff --git a/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc b/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc index c9deda2baa..cb4fe94301 100644 --- a/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc +++ b/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc @@ -1,11 +1,11 @@ -[id="proc-extending-internal-icon-catalog"] +[id="proc-extending-internal-icon-catalog.adoc_{context}"] = Extending internal icon catalog You can use the internal catalog to fetch icons for configured routes with sidebar navigation menu entry. .Procedure -Add a custom icon to the internal icon catalog for use in a plugin's menu item by using the `appIcons` configuration as shown in the following example: +* Add a custom icon to the internal icon catalog for use in a plugin's menu item by using the `appIcons` configuration as shown in the following example: [source,yaml] ---- @@ -16,16 +16,14 @@ plugins: pluginConfig: dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name appIcons: - - name: fooIcon # <2> - module: CustomModule # <3> - importName: FooIcon # <4> + - name: fooIcon # The icon catalog name + # (Optional): The set of assets to access within the plugin. If not specified, the system uses the `PluginRoot` module. + module: CustomModule + # (Optional): The actual component name to be rendered as a standalone page. If not specified, the system uses the `default` export. + importName: FooIcon ---- -<1> Specify the plugin package name. -<2> Specify a name for the icon catalog -<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. -<4> Optional: Specify the actual component name to be rendered as a standalone page. If not specified, the system uses the `default` export. [NOTE] ==== diff --git a/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc b/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc index 7bf8fd38f0..1e933c0054 100644 --- a/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc +++ b/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc @@ -1,5 +1,4 @@ -[id="proc-provide-additional-utility-apis"] - +[id="proc-provide-additional-utility-apis.adoc_{context}"] = Provide additional utility APIs If a dynamic plugin exports the plugin object returned by `createPlugin`, it is supplied to the `createApp` API. All API factories exported by the plugin are automatically registered and available in the front-end application. @@ -21,16 +20,15 @@ However, when the dynamic plugin is not exporting the plugin object, explicitly # app-config.yaml dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name apiFactories: - - importName: BarApi # <2> - module: CustomModule # <3> + # (Optional): Specify the import name that references a `AnyApiFactory<{}>` implementation. (Defaults to `default` export) + - importName: BarApi + # (Optional): An argument which specifies the assets you want to access within the plugin. If not provided, the default module named `PluginRoot` is used + module: CustomModule ---- -<1> Specify the plugin package name. -<2> Optional: Specify the import name that references a `AnyApiFactory<{}>` implementation. Defaults to `default` export. -<3> Optional: An argument which allows you to specify which set of assets you want to access within the plugin. If not provided, the default module named PluginRoot is used. -The API factories initialized by the {product-short} application shell can be overridden by an API factory provided by a dynamic plugin by specifying the same API ref ID. A dynamic plugin can export `AnyApiFactory<{}>` to cater for some specific use case as shown in the following example: +The API factories initialized by the {product-short} application shell are overridden by an API factory provided by a dynamic plugin by specifying the same API ref ID. A dynamic plugin can export `AnyApiFactory<{}>` to cater for some specific use case as shown in the following example: [source,yaml] ---- @@ -53,8 +51,7 @@ The corresponding configuration which overrides the default `ScmAuth` API factor ---- dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name apiFactories: - importName: customScmAuthApiFactory ----- -<1> Specify the plugin package name. \ No newline at end of file +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc b/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc index 1283f6337e..b0383208e3 100644 --- a/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc +++ b/modules/dynamic-plugins/proc-provide-custom-techdocs-addons.adoc @@ -1,25 +1,16 @@ -[id="proc-provide-custom-techdocs-addons"] - +[id="proc-provide-custom-techdocs-addons.adoc_{context}"] = Provide custom TechDocs addons If a plugin provides multiple addons, each `techdocsAddon` entry specifies a unique `importName` corresponding to the addon. -Front-end plugins contribute to TechDocs component, as a result, exposing the TechDocs addon component using the `techdocsAddons` configuration as shown in the following example: +Front-end plugins exposes the TechDocs addon component using the `techdocsAddons` configuration as shown in the following example: [source,yaml] ---- dynamicPlugins: frontend: - my-plugin: # <1> + my-plugin: # The plugin package name techdocsAddons: - - importName: ExampleAddon # <2> + - importName: ExampleAddon # The exported Addon component config: - props: ... # <3> ----- -<1> Specify the plugin package name. -<2> Specify the name of an exported Addon component -<3> (Optional): React props to pass to the addon - -[NOTE] -==== -`module`is an optional argument which allows you to specify the set of assets you want to access within the plugin. By default, `PluginRoot` module is used. -==== \ No newline at end of file + props: ... # (Optional): React props to pass to the addon +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-using-mount-points.adoc b/modules/dynamic-plugins/proc-using-mount-points.adoc index effb998b10..c1cf6b4665 100644 --- a/modules/dynamic-plugins/proc-using-mount-points.adoc +++ b/modules/dynamic-plugins/proc-using-mount-points.adoc @@ -1,5 +1,4 @@ -[id="proc-using-mount-points"] - +[id="proc-using-mount-points.adoc_{context}"] = Using mount points Mount points are defined identifiers available across {product}. You can use these points to extend existing pages with additional content. \ No newline at end of file From e00ea8d97e9db2924f61fc4bdbf03d447415e39d Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 18 Aug 2025 12:53:58 +0200 Subject: [PATCH 5/6] Add frontend plugn wiring section --- .../con-providing-custom-scaffolder-field-extensions.adoc | 2 +- .../con-using-custom-signinpage-component.adoc | 6 +++--- .../dynamic-plugins/proc-adding-application-providers.adoc | 2 +- .../dynamic-plugins/proc-binding-to-existing-plugins.adoc | 2 +- modules/dynamic-plugins/proc-customizing-entity-page.adoc | 4 ++-- .../proc-defining-dynamic-routes-for-new-plugin-pages.adoc | 2 +- .../proc-extending-internal-icon-catalog.adoc | 2 +- .../proc-provide-additional-utility-apis.adoc | 2 +- 8 files changed, 11 insertions(+), 11 deletions(-) diff --git a/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc b/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc index cbccc55cd4..18d2a52d51 100644 --- a/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc +++ b/modules/dynamic-plugins/con-providing-custom-scaffolder-field-extensions.adoc @@ -22,5 +22,5 @@ dynamicPlugins: [NOTE] ==== -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 your plugin's `package.json`. +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. ==== \ No newline at end of file diff --git a/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc b/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc index d145f63b19..1fc8b8db48 100644 --- a/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc +++ b/modules/dynamic-plugins/con-using-custom-signinpage-component.adoc @@ -1,7 +1,7 @@ [id="con-using-custom-signinpage-component.adoc_{context}"] = Using a custom SignInPage component -In {product} ({product-very-short}), the `SignInPage` component manages the application's authentication flow. 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. +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. When you configure a custom `SignInPage`: @@ -20,7 +20,7 @@ dynamicPlugins: [NOTE] ==== -The `package_name` under `dynamicPlugins.frontend` must match the `scalprum.name` value in your plugin's `package.json` to ensure the dynamic plugin loads correctly during runtime. +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. -The `module` field is optional and allows specifying which set of assets should be accessed within the dynamic plugin. By default, the system uses the `PluginRoot` module. +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. ==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-adding-application-providers.adoc b/modules/dynamic-plugins/proc-adding-application-providers.adoc index e0671cd58b..616e313706 100644 --- a/modules/dynamic-plugins/proc-adding-application-providers.adoc +++ b/modules/dynamic-plugins/proc-adding-application-providers.adoc @@ -21,5 +21,5 @@ dynamicPlugins: [NOTE] ==== . You can configure multiple application providers by adding entries to the `mountPoints` field. -. 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. +. 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. ==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc b/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc index df8bda6dea..976d745feb 100644 --- a/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc +++ b/modules/dynamic-plugins/proc-binding-to-existing-plugins.adoc @@ -19,7 +19,7 @@ plugins: - name: barPlugin # (Required): Explicit import name that reference a BackstagePlugin<{}> implementation. importName: barPlugin - # (Optional): Same as key in `scalprum.exposedModules` key in plugin's `package.json` + # # (Optional): Same as key in `scalprum.exposedModules` key in the `package.json` file of the plugin. module: CustomModule bindings: - bindTarget: "barPlugin.externalRoutes" # (Required): One of the supported or imported bind targets diff --git a/modules/dynamic-plugins/proc-customizing-entity-page.adoc b/modules/dynamic-plugins/proc-customizing-entity-page.adoc index c49069b678..ece8186c77 100644 --- a/modules/dynamic-plugins/proc-customizing-entity-page.adoc +++ b/modules/dynamic-plugins/proc-customizing-entity-page.adoc @@ -146,7 +146,7 @@ Conditions are: * `isKind`: Accepts a string or a list of string with entity kinds. For example `isKind: component` renders the component only for entity of `kind: Component`. * `isType`: Accepts a string or a list of string with entity types. For example `isType: service` renders the component only for entities of `spec.type: 'service'`. * `hasAnnotation`: Accepts a string or a list of string with annotation keys. For example `hasAnnotation: my-annotation` renders the component only for entities that have defined `metadata.annotations['my-annotation']`. -* Condition imported from the plugin's `module`: Must be function name exported from the same `module` within the plugin. For example `isMyPluginAvailable` renders the component only if `isMyPluginAvailable` function returns `true`. The function must have the following signature: `(e: Entity) => boolean` +* Condition imported from the plugin's `module`: Must be function name exported from the same `module` within the plugin. For example `isMyPluginAvailable` renders the component only if `isMyPluginAvailable` function returns `true`. The function must have the following signature: `(e: Entity) => boolean`. The entity page supports adding more items to the context menu at the top right of the page. The exported component is a form of dialog wrapper component that accepts an `open` boolean property and an `onClose` event handler property as shown in the following example: @@ -158,7 +158,7 @@ export type SimpleDialogProps = { }; ---- -You can configure the context menu entry using the props configuration entry for the mount point. The `title` and `icon` properties sets the menu item's text and icon. You can use any system icon or icon added through a dynamic plugin. The following is an example configuration: +You can configure the context menu entry using the props configuration entry for the mount point. The `title` and `icon` properties sets the text and icon of the menu item. You can use any system icon or icon added through a dynamic plugin. The following is an example configuration: [source,yaml] ---- diff --git a/modules/dynamic-plugins/proc-defining-dynamic-routes-for-new-plugin-pages.adoc b/modules/dynamic-plugins/proc-defining-dynamic-routes-for-new-plugin-pages.adoc index 28e6143e6c..e75b26bdb4 100644 --- a/modules/dynamic-plugins/proc-defining-dynamic-routes-for-new-plugin-pages.adoc +++ b/modules/dynamic-plugins/proc-defining-dynamic-routes-for-new-plugin-pages.adoc @@ -35,7 +35,7 @@ plugins: + The `menuItem` accepts the following properties: -* `text`: The label shown to the user +* `text`: The label shown to the user. * `icon`: The Backstage system icon name. * `enabled`: Optional: Allows the user to remove a menuItem from the sidebar when it is set to false. * `importName`: Specifies the optional name of an exported `SidebarItem` component. diff --git a/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc b/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc index cb4fe94301..d0bb49e142 100644 --- a/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc +++ b/modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc @@ -5,7 +5,7 @@ You can use the internal catalog to fetch icons for configured routes with sidebar navigation menu entry. .Procedure -* Add a custom icon to the internal icon catalog for use in a plugin's menu item by using the `appIcons` configuration as shown in the following example: +* Add a custom icon to the internal icon catalog for use in the menu item of a plugin by using the `appIcons` configuration as shown in the following example: [source,yaml] ---- diff --git a/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc b/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc index 1e933c0054..db8a405d13 100644 --- a/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc +++ b/modules/dynamic-plugins/proc-provide-additional-utility-apis.adoc @@ -13,7 +13,7 @@ dynamicPlugins: my-dynamic-plugin-package-with-api-factories: {} ---- -However, when the dynamic plugin is not exporting the plugin object, explicitly configure each API factory that should be registered with the `createApp` API using the `apiFactories` configuration as shown in the following example: +However, when the dynamic plugin is not exporting the plugin object, explicitly configure each API factory that must be registered with the `createApp` API using the `apiFactories` configuration as shown in the following example: [source,yaml] ---- From a23e9356d1da2e2608f5162b14922a54ae6bb08e Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 18 Aug 2025 14:12:48 +0200 Subject: [PATCH 6/6] Add frontend plugn wiring section --- modules/dynamic-plugins/proc-customizing-entity-page.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/dynamic-plugins/proc-customizing-entity-page.adoc b/modules/dynamic-plugins/proc-customizing-entity-page.adoc index ece8186c77..5a7b2f3c40 100644 --- a/modules/dynamic-plugins/proc-customizing-entity-page.adoc +++ b/modules/dynamic-plugins/proc-customizing-entity-page.adoc @@ -146,7 +146,7 @@ Conditions are: * `isKind`: Accepts a string or a list of string with entity kinds. For example `isKind: component` renders the component only for entity of `kind: Component`. * `isType`: Accepts a string or a list of string with entity types. For example `isType: service` renders the component only for entities of `spec.type: 'service'`. * `hasAnnotation`: Accepts a string or a list of string with annotation keys. For example `hasAnnotation: my-annotation` renders the component only for entities that have defined `metadata.annotations['my-annotation']`. -* Condition imported from the plugin's `module`: Must be function name exported from the same `module` within the plugin. For example `isMyPluginAvailable` renders the component only if `isMyPluginAvailable` function returns `true`. The function must have the following signature: `(e: Entity) => boolean`. +* Condition imported from the `module` of the plugin: Must be function name exported from the same `module` within the plugin. For example `isMyPluginAvailable` renders the component only if `isMyPluginAvailable` function returns `true`. The function must have the following signature: `(e: Entity) => boolean`. The entity page supports adding more items to the context menu at the top right of the page. The exported component is a form of dialog wrapper component that accepts an `open` boolean property and an `onClose` event handler property as shown in the following example: