From ad4045c0e7e0afb88ec1fb1a533fe00a7ffb0609 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 3 Dec 2025 23:40:56 +0100 Subject: [PATCH 01/11] Update documentation with why frontend wiring is necessary --- .../assembly-front-end-plugin-wiring.adoc | 12 +++ .../con-frontend-dynamic-plugin-wiring.adoc | 7 ++ ...r-plugin-features-for-application-use.adoc | 90 +++++++++++++++++++ ...amically-loaded-plugin-is-not-visible.adoc | 13 +++ ...ing-is-required-for-plugin-deployment.adoc | 16 ++++ 5 files changed, 138 insertions(+) create mode 100644 modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc create mode 100644 modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc create mode 100644 modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc create mode 100644 modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc diff --git a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc index 464fbb9817..85befe202c 100644 --- a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc +++ b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc @@ -6,6 +6,18 @@ You can configure front-end plugins to customize icons, integrate components at mount points, and provide or replace utility APIs. +// Frontend plugin wiring +include::../modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc[leveloffset=+1] + +// Understand frontend wiring +include::../modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc[leveloffset=+2] + +// When you skip frontend wiring +include::../modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc[leveloffset=+2] + +// When to perform frontend wiring +include::../modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc[leveloffset=+2] + // Extending the internal icon catalog include::../modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc[leveloffset=+1] diff --git a/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc b/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc new file mode 100644 index 0000000000..2a1f6aa36a --- /dev/null +++ b/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc @@ -0,0 +1,7 @@ +:_mod-docs-content-type: CONCEPT +[id="con-frontend-dynamic-plugin-wiring_{context}"] += Frontend plugin wiring + +Frontend plugin wiring allows dynamically loaded frontend plugins to integrate their functionality, such as new pages, UI extensions, icons, and APIs, into {product}. + +Dynamic frontend plugins are loaded at runtime. Therefore, the core application must discover and connect the exported assets of the plugin to the appropriate locations and systems within the user interface. \ No newline at end of file diff --git a/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc b/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc new file mode 100644 index 0000000000..42f9440c5a --- /dev/null +++ b/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc @@ -0,0 +1,90 @@ +:_mod-docs-content-type: CONCEPT +[id="con-identify-and-register-plugin-features-for-application-use_{context}"] + += Identify and register plugin features for application use + +Frontend wiring must be performed whenever a dynamic frontend plugin exports a feature that needs to be integrated into the main {product-custom-resource-type} application UI. + +Wiring is specifically required for, but not limited to, the following scenarios: + +[cols="1,1,2"] +|=== +|Scenario|Wiring configuration|Description + +|Enabling new pages/Routes +|`dynamicRoutes` +|When adding a full new page and route to the application (for example, `/my-plugin`). + +|Extending existing pages/UI +|`mountPoints` +|When injecting custom widgets, cards, listeners, or providers into existing pages (for example, the Catalog entity page). + +|Customizing sidebar navigation +|`dynamicRoutes.menuItem`, `menuItems` +|When adding a new entry to the main sidebar or customizing its order/nesting. + +|Integrating custom APIs +|`apiFactories` +|When a plugin provides a custom utility API implementation or overrides an existing one. + +|Extending entity tabs +|`entityTabs` +|When adding a new tab to the Catalog entity view or customizing an existing one. + +|Binding routes +|`routeBindings` +|When linking a route in one plugin to an external route defined by another plugin. + +|Adding icons/Theming +|`appIcons`, `themes` +|When adding custom icons to the application catalog or defining a new {product-custom-resource-type} theme. + +|Scaffolder/TechDocs extensions +|`scaffolderFieldExtensions`, `techdocsAddons` +|When exposing custom field extensions for the Scaffolder or new Addons for TechDocs. + +|Translation resources +|`translationResources` +|When providing new translation files or overriding default translations of a plugin. +|=== + +.Example of Frontend wiring workflow + +The fundamental process for frontend wiring involves configuring the plugin exports in the `{my-app-config-file}` or a dedicated `dynamic-plugins-config.yaml` file. + +The dynamic plugin is built to expose components, routes, or APIs. A plugin component (`FooPluginPage`) is exported as an export from a module (for example, `PluginRoot`). + +The application administrator defines the wiring in the configuration file, using the plugin package name to register the exports. This step adds a new full page with a sidebar link. + +[source,yaml] +.dynamic-plugins-config.yaml +---- +# dynamic-plugins-config.yaml +plugins: + - plugin: + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + my-plugin-package-name: # The plugin's unique package name + dynamicRoutes: # Wiring for a new page/route + - path: /my-new-page # The desired URL path + importName: FooPluginPage # The exported component name + menuItem: # Wiring for the sidebar entry + icon: favorite # A registered icon name + text: My Custom Page +---- + +The application follows these steps when it loads: + +. It parses the `dynamic-plugins-config.yaml`. +. It uses the `` to download the plugin bundle using the dynamic loading mechanism. +. If the plugin exports the plugin object, the application adds this to the list of plugins provided to the Backstage `createApp` API, registering the plugin properly with the Backstage frontend application. +. It uses the configuration block (`dynamicRoutes`, `menuItem`) to: +* Add an entry to the internal router mapping `/my-new-page` to the `FooPluginPage` component. +* Construct and render a new sidebar item labeled _My Custom Page_, pointing to the `/my-new-page` route. + +[NOTE] +==== +If the configuration is missing, steps 1 and 2 might still happen, but the final wiring in step 3 is skipped, and you do not see any change. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc b/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc new file mode 100644 index 0000000000..a8e1530110 --- /dev/null +++ b/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: CONCEPT +[id="con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible_{context}"] + += Troubleshoot why a dynamically loaded plugin is not visible + +If you skip frontend wiring, the plugin is discovered but not loaded into the application frontend. As a result, the plugin features do not appear or function. This is expected because backend plugins are automatically discovered and loaded, but frontend plugins are only loaded based on the list defined in the `dynamicPlugins.frontend` configuration. + +You can expect the following behavior when you skip frontend wiring: + +Functionality is disabled:: The Backstage application does not know how to integrate the plugin exports. +Invisible components:: New pages, sidebar links, or custom cards are not rendered. +Unregistered APIs:: Custom utility APIs or API overrides provided by the plugin fail to register in the application API system, causing plugins or components to fail. +Unused assets:: Icons, translations, and themes are not registered or made available for use. \ No newline at end of file diff --git a/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc b/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc new file mode 100644 index 0000000000..013c7f233c --- /dev/null +++ b/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc @@ -0,0 +1,16 @@ +:_mod-docs-content-type: CONCEPT +[id="con-understand-why-wiring-is-required-for-plugin-deployment_{context}"] + += Understand why wiring is required for plugin deployment + +Frontend wiring bridges the gap between the dynamically loaded plugin code and the structured components of the {product-short} application. + +Frontend components need instructions on where to be registered in the application UI. The application does not automatically know where the UI components of a plugin must appear. + +Wiring tells the application the following: + +* "Add new pages and routes to the main application." (using `dynamicRoutes`) +* "Inject custom components into existing UI pages." (using `mountPoints`) +* "Customize the application with new icons or themes." (using `appIcons`) + +Wiring configuration, typically located in `{my-app-config-file}` or `dynamic-plugins-config.yaml`, provides the application with the metadata (including the component names, paths, and integration points) needed to render and use the plugin features. \ No newline at end of file From 5c1ea1f72b5f760e93a1ed6b736f96e0ed154897 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 4 Dec 2025 00:06:15 +0100 Subject: [PATCH 02/11] Update documentation with why frontend wiring is necessary --- .../con-frontend-dynamic-plugin-wiring.adoc | 6 +++--- ...-and-register-plugin-features-for-application-use.adoc | 8 ++++---- ...ot-why-a-dynamically-loaded-plugin-is-not-visible.adoc | 4 ++-- ...tand-why-wiring-is-required-for-plugin-deployment.adoc | 4 ++-- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc b/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc index 2a1f6aa36a..846a471aab 100644 --- a/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc +++ b/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc @@ -1,7 +1,7 @@ :_mod-docs-content-type: CONCEPT [id="con-frontend-dynamic-plugin-wiring_{context}"] -= Frontend plugin wiring += Front-end plugin wiring -Frontend plugin wiring allows dynamically loaded frontend plugins to integrate their functionality, such as new pages, UI extensions, icons, and APIs, into {product}. +Front-end plugin wiring allows dynamically loaded front-end plugins to integrate their functionality, such as new pages, UI extensions, icons, and APIs, into {product}. -Dynamic frontend plugins are loaded at runtime. Therefore, the core application must discover and connect the exported assets of the plugin to the appropriate locations and systems within the user interface. \ No newline at end of file +Dynamic front-end plugins are loaded at runtime. Therefore, the core application must discover and connect the exported assets of the plugin to the appropriate locations and systems within the user interface. \ No newline at end of file diff --git a/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc b/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc index 42f9440c5a..cf4c964dd6 100644 --- a/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc +++ b/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc @@ -3,7 +3,7 @@ = Identify and register plugin features for application use -Frontend wiring must be performed whenever a dynamic frontend plugin exports a feature that needs to be integrated into the main {product-custom-resource-type} application UI. +Front-end wiring must be performed whenever a dynamic front-end plugin exports a feature that needs to be integrated into the main {product-custom-resource-type} application UI. Wiring is specifically required for, but not limited to, the following scenarios: @@ -48,9 +48,9 @@ Wiring is specifically required for, but not limited to, the following scenarios |When providing new translation files or overriding default translations of a plugin. |=== -.Example of Frontend wiring workflow +.Example of Front-end wiring workflow -The fundamental process for frontend wiring involves configuring the plugin exports in the `{my-app-config-file}` or a dedicated `dynamic-plugins-config.yaml` file. +The fundamental process for front-end wiring involves configuring the plugin exports in the `{my-app-config-file}` or a dedicated `dynamic-plugins-config.yaml` file. The dynamic plugin is built to expose components, routes, or APIs. A plugin component (`FooPluginPage`) is exported as an export from a module (for example, `PluginRoot`). @@ -79,7 +79,7 @@ The application follows these steps when it loads: . It parses the `dynamic-plugins-config.yaml`. . It uses the `` to download the plugin bundle using the dynamic loading mechanism. -. If the plugin exports the plugin object, the application adds this to the list of plugins provided to the Backstage `createApp` API, registering the plugin properly with the Backstage frontend application. +. If the plugin exports the plugin object, the application adds this to the list of plugins provided to the Backstage `createApp` API, registering the plugin properly with the Backstage front-end application. . It uses the configuration block (`dynamicRoutes`, `menuItem`) to: * Add an entry to the internal router mapping `/my-new-page` to the `FooPluginPage` component. * Construct and render a new sidebar item labeled _My Custom Page_, pointing to the `/my-new-page` route. diff --git a/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc b/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc index a8e1530110..b53b2083b6 100644 --- a/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc +++ b/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc @@ -3,9 +3,9 @@ = Troubleshoot why a dynamically loaded plugin is not visible -If you skip frontend wiring, the plugin is discovered but not loaded into the application frontend. As a result, the plugin features do not appear or function. This is expected because backend plugins are automatically discovered and loaded, but frontend plugins are only loaded based on the list defined in the `dynamicPlugins.frontend` configuration. +If you skip front-end wiring, the plugin is discovered but not loaded into the application front-end. As a result, the plugin features do not appear or function. This is expected because backend plugins are automatically discovered and loaded, but front-end plugins are only loaded based on the list defined in the `dynamicPlugins.front-end` configuration. -You can expect the following behavior when you skip frontend wiring: +You can expect the following behavior when you skip front-end wiring: Functionality is disabled:: The Backstage application does not know how to integrate the plugin exports. Invisible components:: New pages, sidebar links, or custom cards are not rendered. diff --git a/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc b/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc index 013c7f233c..f5f335ff47 100644 --- a/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc +++ b/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc @@ -3,9 +3,9 @@ = Understand why wiring is required for plugin deployment -Frontend wiring bridges the gap between the dynamically loaded plugin code and the structured components of the {product-short} application. +Front-end wiring bridges the gap between the dynamically loaded plugin code and the structured components of the {product-short} application. -Frontend components need instructions on where to be registered in the application UI. The application does not automatically know where the UI components of a plugin must appear. +Front-end components need instructions on where to be registered in the application UI. The application does not automatically know where the UI components of a plugin must appear. Wiring tells the application the following: From 2c69a4f6dcea7aae517d6c62cb1b96d33eeb02de Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 4 Dec 2025 14:34:30 +0100 Subject: [PATCH 03/11] Update documentation with why frontend wiring is necessary --- titles/plugins-rhdh-configure/master.adoc | 3 +++ titles/plugins-rhdh-install/master.adoc | 3 --- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/titles/plugins-rhdh-configure/master.adoc b/titles/plugins-rhdh-configure/master.adoc index ffabb847cf..796753998e 100644 --- a/titles/plugins-rhdh-configure/master.adoc +++ b/titles/plugins-rhdh-configure/master.adoc @@ -7,3 +7,6 @@ include::artifacts/attributes.adoc[] :abstract: As a platform engineer, you can configure dynamic plugins in {product} ({product-very-short}) to access your development infrastructure or software development tools. include::assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc[] + +// frontend plugin wiring +include::assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc[leveloffset=+1] \ No newline at end of file diff --git a/titles/plugins-rhdh-install/master.adoc b/titles/plugins-rhdh-install/master.adoc index 882c881495..431a2c0d76 100644 --- a/titles/plugins-rhdh-install/master.adoc +++ b/titles/plugins-rhdh-install/master.adoc @@ -32,8 +32,5 @@ include::assemblies/dynamic-plugins/assembly-extensions-plugins.adoc[leveloffset // Troubleshooting plugins include::modules/dynamic-plugins/proc-plugins-troubleshooting.adoc[leveloffset=+1] -// frontend plugin wiring -include::assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc[leveloffset=+1] - // Plugin indicators and support types include::assemblies/dynamic-plugins/assembly-plugin-indicators-and-support-types.adoc[leveloffset=+1] \ No newline at end of file From 2fecab1989296295e488c93fc13cd8aec7f67bab Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 4 Dec 2025 17:23:37 +0100 Subject: [PATCH 04/11] Apply new suggestions --- .../assembly-front-end-plugin-wiring.adoc | 2 +- ...ster-plugin-features-for-application-use.adoc | 2 +- ...wiring-is-required-for-plugin-deployment.adoc | 16 ---------------- .../con-understand-why-wiring-is-required.adoc | 16 ++++++++++++++++ titles/plugins-rhdh-configure/master.adoc | 3 --- titles/plugins-rhdh-install/master.adoc | 3 +++ 6 files changed, 21 insertions(+), 21 deletions(-) delete mode 100644 modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc create mode 100644 modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc diff --git a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc index 85befe202c..fcd84b3ed0 100644 --- a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc +++ b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc @@ -10,7 +10,7 @@ You can configure front-end plugins to customize icons, integrate components at include::../modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc[leveloffset=+1] // Understand frontend wiring -include::../modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc[leveloffset=+2] +include::../modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc[leveloffset=+2] // When you skip frontend wiring include::../modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc[leveloffset=+2] diff --git a/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc b/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc index cf4c964dd6..291f6896a8 100644 --- a/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc +++ b/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc @@ -79,7 +79,7 @@ The application follows these steps when it loads: . It parses the `dynamic-plugins-config.yaml`. . It uses the `` to download the plugin bundle using the dynamic loading mechanism. -. If the plugin exports the plugin object, the application adds this to the list of plugins provided to the Backstage `createApp` API, registering the plugin properly with the Backstage front-end application. +. If the package exports the plugin object, the application adds it to the list provided to the {product-custom-resource-type} `createApp` API, registering the plugin properly with the front-end application. . It uses the configuration block (`dynamicRoutes`, `menuItem`) to: * Add an entry to the internal router mapping `/my-new-page` to the `FooPluginPage` component. * Construct and render a new sidebar item labeled _My Custom Page_, pointing to the `/my-new-page` route. diff --git a/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc b/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc deleted file mode 100644 index f5f335ff47..0000000000 --- a/modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc +++ /dev/null @@ -1,16 +0,0 @@ -:_mod-docs-content-type: CONCEPT -[id="con-understand-why-wiring-is-required-for-plugin-deployment_{context}"] - -= Understand why wiring is required for plugin deployment - -Front-end wiring bridges the gap between the dynamically loaded plugin code and the structured components of the {product-short} application. - -Front-end components need instructions on where to be registered in the application UI. The application does not automatically know where the UI components of a plugin must appear. - -Wiring tells the application the following: - -* "Add new pages and routes to the main application." (using `dynamicRoutes`) -* "Inject custom components into existing UI pages." (using `mountPoints`) -* "Customize the application with new icons or themes." (using `appIcons`) - -Wiring configuration, typically located in `{my-app-config-file}` or `dynamic-plugins-config.yaml`, provides the application with the metadata (including the component names, paths, and integration points) needed to render and use the plugin features. \ No newline at end of file diff --git a/modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc b/modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc new file mode 100644 index 0000000000..0a461ffc9d --- /dev/null +++ b/modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc @@ -0,0 +1,16 @@ +:_mod-docs-content-type: CONCEPT +[id="con-understand-why-wiring-is-required_{context}"] + += Understand why wiring is required + +Dynamic front-end plugins load their code at runtime, but the {product-short} application does not automatically know where the components of a plugin must appear in the user interface (UI). + +Front-end wiring provides the metadata and instructions that bridge this gap by telling the application the following: + +* {installing-and-viewing-plugins-book-link}#proc-defining-dynamic-routes-for-new-plugin-pages.adoc_assembly-front-end-plugin-wiring[Add new pages and routes to the main application]. (using `dynamicRoutes`) +* {installing-and-viewing-plugins-book-link}#proc-using-mount-points.adoc_assembly-front-end-plugin-wiring[Inject custom components into existing UI pages]. (using `mountPoints`) +* {installing-and-viewing-plugins-book-link}#proc-extending-internal-icon-catalog.adoc_assembly-front-end-plugin-wiring[Configure application-wide customizations, such as new icons or themes]. (using `appIcons`) +* {installing-and-viewing-plugins-book-link}#proc-customizing-sidebar-menu-items.adoc_assembly-front-end-plugin-wiring[Add new menu items]. (using `menuItems`) +* {installing-and-viewing-plugins-book-link}#proc-binding-to-existing-plugins.adoc_assembly-front-end-plugin-wiring[Bind to existing plugins]. (using `routeBindings`) + +Wiring configuration, typically located in `{my-app-config-file}` or `dynamic-plugins-config.yaml`, provides the application with the metadata (including the component names, paths, and integration points) needed to render and use the plugin features. \ No newline at end of file diff --git a/titles/plugins-rhdh-configure/master.adoc b/titles/plugins-rhdh-configure/master.adoc index 796753998e..ffabb847cf 100644 --- a/titles/plugins-rhdh-configure/master.adoc +++ b/titles/plugins-rhdh-configure/master.adoc @@ -7,6 +7,3 @@ include::artifacts/attributes.adoc[] :abstract: As a platform engineer, you can configure dynamic plugins in {product} ({product-very-short}) to access your development infrastructure or software development tools. include::assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc[] - -// frontend plugin wiring -include::assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc[leveloffset=+1] \ No newline at end of file diff --git a/titles/plugins-rhdh-install/master.adoc b/titles/plugins-rhdh-install/master.adoc index 431a2c0d76..882c881495 100644 --- a/titles/plugins-rhdh-install/master.adoc +++ b/titles/plugins-rhdh-install/master.adoc @@ -32,5 +32,8 @@ include::assemblies/dynamic-plugins/assembly-extensions-plugins.adoc[leveloffset // Troubleshooting plugins include::modules/dynamic-plugins/proc-plugins-troubleshooting.adoc[leveloffset=+1] +// frontend plugin wiring +include::assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc[leveloffset=+1] + // Plugin indicators and support types include::assemblies/dynamic-plugins/assembly-plugin-indicators-and-support-types.adoc[leveloffset=+1] \ No newline at end of file From 631a9bd9f1270ddfec4f61e5807dff1a735b464d Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 4 Dec 2025 19:28:59 +0100 Subject: [PATCH 05/11] Apply new suggestions --- .../assembly-front-end-plugin-wiring.adoc | 2 +- ...ront-end-plugins-for-application-use.adoc} | 24 +++++++++---------- ...amically-loaded-plugin-is-not-visible.adoc | 13 ++++++---- 3 files changed, 22 insertions(+), 17 deletions(-) rename modules/dynamic-plugins/{con-identify-and-register-plugin-features-for-application-use.adoc => con-dynamic-front-end-plugins-for-application-use.adoc} (68%) diff --git a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc index fcd84b3ed0..27b8fa78de 100644 --- a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc +++ b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc @@ -16,7 +16,7 @@ include::../modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc[l include::../modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc[leveloffset=+2] // When to perform frontend wiring -include::../modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc[leveloffset=+2] +include::../modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc[leveloffset=+2] // Extending the internal icon catalog include::../modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc[leveloffset=+1] diff --git a/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc b/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc similarity index 68% rename from modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc rename to modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc index 291f6896a8..15cca74983 100644 --- a/modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc +++ b/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc @@ -1,9 +1,9 @@ :_mod-docs-content-type: CONCEPT -[id="con-identify-and-register-plugin-features-for-application-use_{context}"] +[id="con-dynamic-front-end-plugins-for-application-use_{context}"] -= Identify and register plugin features for application use += Dynamic front-end plugins for application use -Front-end wiring must be performed whenever a dynamic front-end plugin exports a feature that needs to be integrated into the main {product-custom-resource-type} application UI. +Front-end wiring must be performed whenever a dynamic front-end plugin exports a feature for integration into the main {product-custom-resource-type} application UI. Wiring is specifically required for, but not limited to, the following scenarios: @@ -11,39 +11,39 @@ Wiring is specifically required for, but not limited to, the following scenarios |=== |Scenario|Wiring configuration|Description -|Enabling new pages/Routes +|{installing-and-viewing-plugins-book-link}#proc-defining-dynamic-routes-for-new-plugin-pages.adoc_assembly-front-end-plugin-wiring[Enabling new pages/Routes] |`dynamicRoutes` |When adding a full new page and route to the application (for example, `/my-plugin`). -|Extending existing pages/UI +|{installing-and-viewing-plugins-book-link}#proc-using-mount-points.adoc_assembly-front-end-plugin-wiring[Extending existing pages/UI] |`mountPoints` |When injecting custom widgets, cards, listeners, or providers into existing pages (for example, the Catalog entity page). -|Customizing sidebar navigation +|{installing-and-viewing-plugins-book-link}#proc-defining-dynamic-routes-for-new-plugin-pages.adoc_assembly-front-end-plugin-wiring[Customizing sidebar navigation] |`dynamicRoutes.menuItem`, `menuItems` |When adding a new entry to the main sidebar or customizing its order/nesting. -|Integrating custom APIs +|{installing-and-viewing-plugins-book-link}#proc-provide-additional-utility-apis.adoc_assembly-front-end-plugin-wiring[Integrating custom APIs] |`apiFactories` |When a plugin provides a custom utility API implementation or overrides an existing one. -|Extending entity tabs +|{installing-and-viewing-plugins-book-link}#proc-customizing-and-extending-entity-tabs.adoc_assembly-front-end-plugin-wiring[Extending entity tabs] |`entityTabs` |When adding a new tab to the Catalog entity view or customizing an existing one. -|Binding routes +|{installing-and-viewing-plugins-book-link}#proc-binding-to-existing-plugins.adoc_assembly-front-end-plugin-wiring[Binding routes] |`routeBindings` |When linking a route in one plugin to an external route defined by another plugin. -|Adding icons/Theming +|{installing-and-viewing-plugins-book-link}#proc-extending-internal-icon-catalog.adoc_assembly-front-end-plugin-wiring[Adding icons/Theming] |`appIcons`, `themes` |When adding custom icons to the application catalog or defining a new {product-custom-resource-type} theme. -|Scaffolder/TechDocs extensions +|{installing-and-viewing-plugins-book-link}#con-providing-custom-scaffolder-field-extensions.adoc_assembly-front-end-plugin-wiring[Scaffolder/TechDocs extensions] |`scaffolderFieldExtensions`, `techdocsAddons` |When exposing custom field extensions for the Scaffolder or new Addons for TechDocs. -|Translation resources +|{installing-and-viewing-plugins-book-link}#proc-extensions-enabling-plugins-installation_rhdh-extensions-plugins[Translation resources] |`translationResources` |When providing new translation files or overriding default translations of a plugin. |=== diff --git a/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc b/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc index b53b2083b6..2f7bc2b675 100644 --- a/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc +++ b/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc @@ -7,7 +7,12 @@ If you skip front-end wiring, the plugin is discovered but not loaded into the a You can expect the following behavior when you skip front-end wiring: -Functionality is disabled:: The Backstage application does not know how to integrate the plugin exports. -Invisible components:: New pages, sidebar links, or custom cards are not rendered. -Unregistered APIs:: Custom utility APIs or API overrides provided by the plugin fail to register in the application API system, causing plugins or components to fail. -Unused assets:: Icons, translations, and themes are not registered or made available for use. \ No newline at end of file +Disabled functionality:: The {product-custom-resource-type} application is unable to integrate or use the plugin exports. +Invisible components:: New pages, sidebar links, or custom cards do not render in the application UI. +Unregistered APIs:: Custom utility APIs or API overrides provided by the plugin are not registered in the application API system, potentially causing plugins or components to fail. +Unused assets:: Icons, translations, and themes are not registered or made available for use. + +[TIP] +==== +Sometimes a plugin might not be visible even if there is front-end wiring, which indicates it is misconfigured. To troubleshoot this, check the *Console* tab in the _Developer Tools_ of your browser for specific error messages or warnings. +==== \ No newline at end of file From 52712a00c744efbf466936f0b50417740ca45b15 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 4 Dec 2025 20:45:47 +0100 Subject: [PATCH 06/11] Apply new suggestions --- ...front-end-plugins-for-application-use.adoc | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc b/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc index 15cca74983..191b1b2ab0 100644 --- a/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc +++ b/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc @@ -11,6 +11,18 @@ Wiring is specifically required for, but not limited to, the following scenarios |=== |Scenario|Wiring configuration|Description +|{installing-and-viewing-plugins-book-link}#proc-customizing-and-extending-entity-tabs.adoc_assembly-front-end-plugin-wiring[Extending entity tabs] +|`entityTabs` +|When adding a new tab to the Catalog entity view or customizing an existing one. + +|{installing-and-viewing-plugins-book-link}#proc-binding-to-existing-plugins.adoc_assembly-front-end-plugin-wiring[Binding routes] +|`routeBindings` +|When linking a route in one plugin to an external route defined by another plugin. + +|{installing-and-viewing-plugins-book-link}#proc-provide-additional-utility-apis.adoc_assembly-front-end-plugin-wiring[Integrating custom APIs] +|`apiFactories` +|When a plugin provides a custom utility API implementation or overrides an existing one. + |{installing-and-viewing-plugins-book-link}#proc-defining-dynamic-routes-for-new-plugin-pages.adoc_assembly-front-end-plugin-wiring[Enabling new pages/Routes] |`dynamicRoutes` |When adding a full new page and route to the application (for example, `/my-plugin`). @@ -23,18 +35,6 @@ Wiring is specifically required for, but not limited to, the following scenarios |`dynamicRoutes.menuItem`, `menuItems` |When adding a new entry to the main sidebar or customizing its order/nesting. -|{installing-and-viewing-plugins-book-link}#proc-provide-additional-utility-apis.adoc_assembly-front-end-plugin-wiring[Integrating custom APIs] -|`apiFactories` -|When a plugin provides a custom utility API implementation or overrides an existing one. - -|{installing-and-viewing-plugins-book-link}#proc-customizing-and-extending-entity-tabs.adoc_assembly-front-end-plugin-wiring[Extending entity tabs] -|`entityTabs` -|When adding a new tab to the Catalog entity view or customizing an existing one. - -|{installing-and-viewing-plugins-book-link}#proc-binding-to-existing-plugins.adoc_assembly-front-end-plugin-wiring[Binding routes] -|`routeBindings` -|When linking a route in one plugin to an external route defined by another plugin. - |{installing-and-viewing-plugins-book-link}#proc-extending-internal-icon-catalog.adoc_assembly-front-end-plugin-wiring[Adding icons/Theming] |`appIcons`, `themes` |When adding custom icons to the application catalog or defining a new {product-custom-resource-type} theme. From 640a0a7587355ec1ca64f8eefaacb7335bf53428 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 5 Dec 2025 10:53:08 +0100 Subject: [PATCH 07/11] Apply new suggestions --- .../assembly-front-end-plugin-wiring.adoc | 6 ++-- ...equences-of-skipping-front-end wiring.adoc | 18 ++++++++++ ...front-end-plugins-for-application-use.adoc | 33 ++++++++----------- .../con-frontend-dynamic-plugin-wiring.adoc | 4 +-- ...amically-loaded-plugin-is-not-visible.adoc | 18 ---------- ...and-why-front-end-wiring-is-required.adoc} | 10 +++--- 6 files changed, 42 insertions(+), 47 deletions(-) create mode 100644 modules/dynamic-plugins/con-consequences-of-skipping-front-end wiring.adoc delete mode 100644 modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc rename modules/dynamic-plugins/{con-understand-why-wiring-is-required.adoc => con-understand-why-front-end-wiring-is-required.adoc} (58%) diff --git a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc index 27b8fa78de..40eb4a596d 100644 --- a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc +++ b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc @@ -10,10 +10,10 @@ You can configure front-end plugins to customize icons, integrate components at include::../modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc[leveloffset=+1] // Understand frontend wiring -include::../modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc[leveloffset=+2] +include::../modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc[leveloffset=+2] -// When you skip frontend wiring -include::../modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc[leveloffset=+2] +// Consequences of skipping front-end wiring +include::../modules/dynamic-plugins/con-consequences-of-skipping-front-end wiring.adoc[leveloffset=+2] // When to perform frontend wiring include::../modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc[leveloffset=+2] diff --git a/modules/dynamic-plugins/con-consequences-of-skipping-front-end wiring.adoc b/modules/dynamic-plugins/con-consequences-of-skipping-front-end wiring.adoc new file mode 100644 index 0000000000..4c2d547760 --- /dev/null +++ b/modules/dynamic-plugins/con-consequences-of-skipping-front-end wiring.adoc @@ -0,0 +1,18 @@ +:_mod-docs-content-type: CONCEPT +[id="con-consequences-of-skipping-front-end wiring_{context}"] + += Consequences of skipping front-end wiring + +If you skip front-end wiring, the plugin is discovered but not loaded into the application front-end. As a result, the plugin features do not appear or function. This behavior is expected because while back-end plug-ins are discovered and loaded automatically, the core application loads front-end plug-ins only based on the list defined in the `dynamicPlugins.front-end` configuration. + +You can expect the following behavior when you skip front-end wiring: + +Disabled functionality:: The {product-custom-resource-type} application cannot integrate or use the plugin exports. +Invisible components:: New pages, sidebar links, or custom cards do not render in the application UI. +Unregistered APIs:: Custom utility APIs or API overrides provided by the plugin are not registered in the application API system, which can cause plugins or components to fail. +Unused assets:: Icons, translations, and themes are not registered or available for use. + +[TIP] +==== +If a plugin is not visible even with front-end wiring, the plugin is likely misconfigured. Troubleshoot the issue by checking the *Console* tab in the _Developer Tools_ of your browser for specific error messages or warnings. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc b/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc index 191b1b2ab0..d08158ddd4 100644 --- a/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc +++ b/modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc @@ -3,9 +3,7 @@ = Dynamic front-end plugins for application use -Front-end wiring must be performed whenever a dynamic front-end plugin exports a feature for integration into the main {product-custom-resource-type} application UI. - -Wiring is specifically required for, but not limited to, the following scenarios: +A dynamic front-end plugin requires front-end wiring when it exports a feature for integration into the main {product-custom-resource-type} application UI. Wiring is required for the following scenarios: [cols="1,1,2"] |=== @@ -13,51 +11,48 @@ Wiring is specifically required for, but not limited to, the following scenarios |{installing-and-viewing-plugins-book-link}#proc-customizing-and-extending-entity-tabs.adoc_assembly-front-end-plugin-wiring[Extending entity tabs] |`entityTabs` -|When adding a new tab to the Catalog entity view or customizing an existing one. +|Add or customize a tab on the *Catalog entity* view. |{installing-and-viewing-plugins-book-link}#proc-binding-to-existing-plugins.adoc_assembly-front-end-plugin-wiring[Binding routes] |`routeBindings` -|When linking a route in one plugin to an external route defined by another plugin. +|Link a route in one plugin to an external route defined by another plugin. |{installing-and-viewing-plugins-book-link}#proc-provide-additional-utility-apis.adoc_assembly-front-end-plugin-wiring[Integrating custom APIs] |`apiFactories` -|When a plugin provides a custom utility API implementation or overrides an existing one. +|Provide a custom utility API implementation or override an existing one. |{installing-and-viewing-plugins-book-link}#proc-defining-dynamic-routes-for-new-plugin-pages.adoc_assembly-front-end-plugin-wiring[Enabling new pages/Routes] |`dynamicRoutes` -|When adding a full new page and route to the application (for example, `/my-plugin`). +|Add a new page and route to the application (for example, `/my-plugin`). |{installing-and-viewing-plugins-book-link}#proc-using-mount-points.adoc_assembly-front-end-plugin-wiring[Extending existing pages/UI] |`mountPoints` -|When injecting custom widgets, cards, listeners, or providers into existing pages (for example, the Catalog entity page). +|Inject custom widgets, cards, listeners, or providers into existing pages (for example, the *Catalog entity* page). |{installing-and-viewing-plugins-book-link}#proc-defining-dynamic-routes-for-new-plugin-pages.adoc_assembly-front-end-plugin-wiring[Customizing sidebar navigation] |`dynamicRoutes.menuItem`, `menuItems` -|When adding a new entry to the main sidebar or customizing its order/nesting. +|Add a new entry to the main sidebar or customize its order and nesting. |{installing-and-viewing-plugins-book-link}#proc-extending-internal-icon-catalog.adoc_assembly-front-end-plugin-wiring[Adding icons/Theming] |`appIcons`, `themes` -|When adding custom icons to the application catalog or defining a new {product-custom-resource-type} theme. +|Add custom icons to the application catalog or define a new {product-custom-resource-type} theme. |{installing-and-viewing-plugins-book-link}#con-providing-custom-scaffolder-field-extensions.adoc_assembly-front-end-plugin-wiring[Scaffolder/TechDocs extensions] |`scaffolderFieldExtensions`, `techdocsAddons` -|When exposing custom field extensions for the Scaffolder or new Addons for TechDocs. +|Expose custom field extensions for the Scaffolder or new Addons for TechDocs. |{installing-and-viewing-plugins-book-link}#proc-extensions-enabling-plugins-installation_rhdh-extensions-plugins[Translation resources] |`translationResources` -|When providing new translation files or overriding default translations of a plugin. +|Provide new translation files or override default plugin translations. |=== .Example of Front-end wiring workflow -The fundamental process for front-end wiring involves configuring the plugin exports in the `{my-app-config-file}` or a dedicated `dynamic-plugins-config.yaml` file. - -The dynamic plugin is built to expose components, routes, or APIs. A plugin component (`FooPluginPage`) is exported as an export from a module (for example, `PluginRoot`). +Front-end wiring is configured in the `{my-app-config-file}` or a dedicated `dynamic-plugins-config.yaml` file. The dynamic plugin exposes components, routes, or APIs. For example, a plugin component (`FooPluginPage`) is exported from a module (for example, `PluginRoot`). -The application administrator defines the wiring in the configuration file, using the plugin package name to register the exports. This step adds a new full page with a sidebar link. +The application administrator defines the wiring in the configuration file, using the plugin package name to register the exports, such as adding a new page with a sidebar link. [source,yaml] -.dynamic-plugins-config.yaml ---- # dynamic-plugins-config.yaml plugins: @@ -75,7 +70,7 @@ plugins: text: My Custom Page ---- -The application follows these steps when it loads: +When the application loads, it performs the following steps: . It parses the `dynamic-plugins-config.yaml`. . It uses the `` to download the plugin bundle using the dynamic loading mechanism. @@ -86,5 +81,5 @@ The application follows these steps when it loads: [NOTE] ==== -If the configuration is missing, steps 1 and 2 might still happen, but the final wiring in step 3 is skipped, and you do not see any change. +If the configuration is missing, steps 1 and 2 might still occur, but the final registration in step 3 and the wiring/rendering in step 4 are skipped, and no UI changes occur. ==== \ No newline at end of file diff --git a/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc b/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc index 846a471aab..f18ac2ad7c 100644 --- a/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc +++ b/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc @@ -2,6 +2,6 @@ [id="con-frontend-dynamic-plugin-wiring_{context}"] = Front-end plugin wiring -Front-end plugin wiring allows dynamically loaded front-end plugins to integrate their functionality, such as new pages, UI extensions, icons, and APIs, into {product}. +Front-end plugin wiring integrates dynamic front-end plugin components, such as new pages, UI extensions, icons, and APIs, into {product}. -Dynamic front-end plugins are loaded at runtime. Therefore, the core application must discover and connect the exported assets of the plugin to the appropriate locations and systems within the user interface. \ No newline at end of file +Because the dynamic plug-ins load at runtime, the core application must discover and connect the exported assets of the plug-in to the appropriate user interface systems and locations. \ No newline at end of file diff --git a/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc b/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc deleted file mode 100644 index 2f7bc2b675..0000000000 --- a/modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc +++ /dev/null @@ -1,18 +0,0 @@ -:_mod-docs-content-type: CONCEPT -[id="con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible_{context}"] - -= Troubleshoot why a dynamically loaded plugin is not visible - -If you skip front-end wiring, the plugin is discovered but not loaded into the application front-end. As a result, the plugin features do not appear or function. This is expected because backend plugins are automatically discovered and loaded, but front-end plugins are only loaded based on the list defined in the `dynamicPlugins.front-end` configuration. - -You can expect the following behavior when you skip front-end wiring: - -Disabled functionality:: The {product-custom-resource-type} application is unable to integrate or use the plugin exports. -Invisible components:: New pages, sidebar links, or custom cards do not render in the application UI. -Unregistered APIs:: Custom utility APIs or API overrides provided by the plugin are not registered in the application API system, potentially causing plugins or components to fail. -Unused assets:: Icons, translations, and themes are not registered or made available for use. - -[TIP] -==== -Sometimes a plugin might not be visible even if there is front-end wiring, which indicates it is misconfigured. To troubleshoot this, check the *Console* tab in the _Developer Tools_ of your browser for specific error messages or warnings. -==== \ No newline at end of file diff --git a/modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc b/modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc similarity index 58% rename from modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc rename to modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc index 0a461ffc9d..2cc8c0929b 100644 --- a/modules/dynamic-plugins/con-understand-why-wiring-is-required.adoc +++ b/modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc @@ -1,11 +1,11 @@ :_mod-docs-content-type: CONCEPT -[id="con-understand-why-wiring-is-required_{context}"] +[id="con-understand-why-front-end-wiring-is-required_{context}"] -= Understand why wiring is required += Understand why front-end wiring is required -Dynamic front-end plugins load their code at runtime, but the {product-short} application does not automatically know where the components of a plugin must appear in the user interface (UI). +Because dynamic front-end plugins load their code at runtime, the {product-short} application requires explicit instructions to integrate the components of a plugin must appear in the user interface (UI). -Front-end wiring provides the metadata and instructions that bridge this gap by telling the application the following: +Front-end wiring provides the metadata and instructions necessary to bridge this gap, informing the applications on how to: * {installing-and-viewing-plugins-book-link}#proc-defining-dynamic-routes-for-new-plugin-pages.adoc_assembly-front-end-plugin-wiring[Add new pages and routes to the main application]. (using `dynamicRoutes`) * {installing-and-viewing-plugins-book-link}#proc-using-mount-points.adoc_assembly-front-end-plugin-wiring[Inject custom components into existing UI pages]. (using `mountPoints`) @@ -13,4 +13,4 @@ Front-end wiring provides the metadata and instructions that bridge this gap by * {installing-and-viewing-plugins-book-link}#proc-customizing-sidebar-menu-items.adoc_assembly-front-end-plugin-wiring[Add new menu items]. (using `menuItems`) * {installing-and-viewing-plugins-book-link}#proc-binding-to-existing-plugins.adoc_assembly-front-end-plugin-wiring[Bind to existing plugins]. (using `routeBindings`) -Wiring configuration, typically located in `{my-app-config-file}` or `dynamic-plugins-config.yaml`, provides the application with the metadata (including the component names, paths, and integration points) needed to render and use the plugin features. \ No newline at end of file +The wiring configuration, typically located in `{my-app-config-file}` or `dynamic-plugins-config.yaml`, gives the application the necessary metadata (including the component names, paths, and integration points) to render and use the plugin features. \ No newline at end of file From 3912c353f95c872d4096cb22aa86de496e649c79 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 5 Dec 2025 11:04:43 +0100 Subject: [PATCH 08/11] Incorporate new suggestions --- ....adoc => con-consequences-of-skipping-front-end-wiring.adoc} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename modules/dynamic-plugins/{con-consequences-of-skipping-front-end wiring.adoc => con-consequences-of-skipping-front-end-wiring.adoc} (95%) diff --git a/modules/dynamic-plugins/con-consequences-of-skipping-front-end wiring.adoc b/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc similarity index 95% rename from modules/dynamic-plugins/con-consequences-of-skipping-front-end wiring.adoc rename to modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc index 4c2d547760..dce5e45872 100644 --- a/modules/dynamic-plugins/con-consequences-of-skipping-front-end wiring.adoc +++ b/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc @@ -1,5 +1,5 @@ :_mod-docs-content-type: CONCEPT -[id="con-consequences-of-skipping-front-end wiring_{context}"] +[id="con-consequences-of-skipping-front-end-wiring_{context}"] = Consequences of skipping front-end wiring From 49e67517533503fbefaeaddf2093006ce329645a Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 5 Dec 2025 11:09:41 +0100 Subject: [PATCH 09/11] Incorporate new suggestions --- .../dynamic-plugins/assembly-front-end-plugin-wiring.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc index 40eb4a596d..d1d9590fb4 100644 --- a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc +++ b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc @@ -13,7 +13,7 @@ include::../modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc[leve include::../modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc[leveloffset=+2] // Consequences of skipping front-end wiring -include::../modules/dynamic-plugins/con-consequences-of-skipping-front-end wiring.adoc[leveloffset=+2] +include::../modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc[leveloffset=+2] // When to perform frontend wiring include::../modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc[leveloffset=+2] From acc1661d103f7834d0c58dbc217f9960446996dd Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 5 Dec 2025 14:26:37 +0100 Subject: [PATCH 10/11] Incorporate new suggestions --- .../con-consequences-of-skipping-front-end-wiring.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc b/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc index dce5e45872..86e2be14ed 100644 --- a/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc +++ b/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc @@ -3,7 +3,7 @@ = Consequences of skipping front-end wiring -If you skip front-end wiring, the plugin is discovered but not loaded into the application front-end. As a result, the plugin features do not appear or function. This behavior is expected because while back-end plug-ins are discovered and loaded automatically, the core application loads front-end plug-ins only based on the list defined in the `dynamicPlugins.front-end` configuration. +If you skip front-end wiring, the plugin is discovered but not loaded into the application front-end. As a result, the plugin features do not appear or function. This behavior is expected because while back-end plug-ins are discovered and loaded automatically, the core application loads front-end plug-ins only based on the list defined in the `dynamicPlugins.frontend` configuration. You can expect the following behavior when you skip front-end wiring: From bb016c024247beb39e8254b240117b9754edac8b Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 5 Dec 2025 15:00:08 +0100 Subject: [PATCH 11/11] Incorporate new suggestions --- .../con-consequences-of-skipping-front-end-wiring.adoc | 2 +- modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc | 2 +- .../con-understand-why-front-end-wiring-is-required.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc b/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc index 86e2be14ed..a9c390a4bc 100644 --- a/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc +++ b/modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc @@ -3,7 +3,7 @@ = Consequences of skipping front-end wiring -If you skip front-end wiring, the plugin is discovered but not loaded into the application front-end. As a result, the plugin features do not appear or function. This behavior is expected because while back-end plug-ins are discovered and loaded automatically, the core application loads front-end plug-ins only based on the list defined in the `dynamicPlugins.frontend` configuration. +If you skip front-end wiring, the plugin is discovered but not loaded into the application front-end. As a result, the plugin features do not appear or function. This behavior is expected because while back-end plugins are discovered and loaded automatically, the core application loads front-end plugins only based on the list defined in the `dynamicPlugins.frontend` configuration. You can expect the following behavior when you skip front-end wiring: diff --git a/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc b/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc index f18ac2ad7c..86599a6083 100644 --- a/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc +++ b/modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc @@ -4,4 +4,4 @@ Front-end plugin wiring integrates dynamic front-end plugin components, such as new pages, UI extensions, icons, and APIs, into {product}. -Because the dynamic plug-ins load at runtime, the core application must discover and connect the exported assets of the plug-in to the appropriate user interface systems and locations. \ No newline at end of file +Because the dynamic plugins load at runtime, the core application must discover and connect the exported assets of the plugin to the appropriate user interface systems and locations. \ No newline at end of file diff --git a/modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc b/modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc index 2cc8c0929b..42deea1b89 100644 --- a/modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc +++ b/modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc @@ -3,7 +3,7 @@ = Understand why front-end wiring is required -Because dynamic front-end plugins load their code at runtime, the {product-short} application requires explicit instructions to integrate the components of a plugin must appear in the user interface (UI). +Because dynamic front-end plugins load their code at runtime, the {product-short} application requires explicit instructions to integrate the plugin components in the user interface (UI). Front-end wiring provides the metadata and instructions necessary to bridge this gap, informing the applications on how to: