RHDHBUGS-2300: Improve Documentation on When and Why Frontend Plugin Wiring Is Required

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-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]
+
+// When to perform frontend wiring
+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]
 

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 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:
+
+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.
+====

modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc

@@ -0,0 +1,85 @@
+:_mod-docs-content-type: CONCEPT
+[id="con-dynamic-front-end-plugins-for-application-use_{context}"]
+
+= Dynamic front-end plugins for application use
+
+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"]
+|===
+|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`
+|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`
+|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`
+|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`
+|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`
+|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`
+|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`
+|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`
+|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`
+|Provide new translation files or override default plugin translations.
+|===
+
+.Example of Front-end wiring workflow
+
+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, such as adding a new page with a sidebar link.
+
+[source,yaml]
+----
+# dynamic-plugins-config.yaml
+plugins:
+  - plugin: <plugin_path_or_url>
+    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
+----
+
+When the application loads, it performs the following steps:
+
+. It parses the `dynamic-plugins-config.yaml`.
+. It uses the `<plugin_path_or_url>` to download the plugin bundle using the dynamic loading mechanism.
+. 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.
+
+[NOTE]
+====
+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.
+====

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}"]
+= Front-end plugin wiring
+
+Front-end plugin wiring integrates dynamic front-end plugin components, such as new pages, UI extensions, icons, and APIs, into {product}.
+
+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.

modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: CONCEPT
+[id="con-understand-why-front-end-wiring-is-required_{context}"]
+
+= 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 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:
+
+* {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`)
+
+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.