Add frontend plugn wiring section

Author: GitHub Actions

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]

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]
 ====

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]
 ====

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: <header_component> # <3>
+        - mountPoint: application/header # Adds the header as a global header
+          importName: <header_component> # 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.

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: <exported listener component>
 ----
-<1> Specify the plugin package name.
 
 [NOTE]
 ====

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: /<route>
-          importName: Component # <2>
+          importName: Component # The component to load on the route
       mountPoints:
         - mountPoint: application/provider
           importName: <exported provider component>
 ----
-<1> Specify the plugin package name.
-<2> Specify the component you want to load on the route.
 
 [NOTE]
 ====

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.
+
+[NOTE]
+====
+`provider` looks up the corresponding API factory for the authentication provider to connect the provider's Sign In/Sign Out button.
+====

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

@@ -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`
 

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:
 

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,42 +118,37 @@ plugins:
     pluginConfig:
       dynamicPlugins:
         frontend:
-          my-plugin: # <1>
-            mountPoints: # <2>
+          my-plugin: # The plugin package name
+            mountPoints: # (Optional): Uses existing mount points
               - mountPoint: <mountPointName>/[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 `<EntitySwitch.Case if={<here>}`.
+                  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 `<EntitySwitch.Case if={<here>}`.
-<6> 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:
+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]
 ----