diff --git a/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc b/assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc index 464fbb9817..d1d9590fb4 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-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] 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..a9c390a4bc --- /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 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. +==== \ 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 new file mode 100644 index 0000000000..d08158ddd4 --- /dev/null +++ b/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: + 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 `` 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. +==== \ 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 new file mode 100644 index 0000000000..86599a6083 --- /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}"] += 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. \ 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 new file mode 100644 index 0000000000..42deea1b89 --- /dev/null +++ b/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. \ No newline at end of file