Skip to content

Commit 94a6de3

Browse files
jmagakGitHub Actions
jmagak
and
GitHub Actions
authored
RHDHBUGS-2300: Improve Documentation on When and Why Frontend Plugin Wiring Is Required (#1622) (#1629)
Co-authored-by: GitHub Actions <github-actions@github.com>
1 parent 0e2fe35 commit 94a6de3

File tree

5 files changed

+138
-0
lines changed

5 files changed

+138
-0
lines changed

‎assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,18 @@
44

55
You can configure front-end plugins to customize icons, integrate components at mount points, and provide or replace utility APIs.
66

7+
// Frontend plugin wiring
8+
include::../modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc[leveloffset=+1]
9+
10+
// Understand frontend wiring
11+
include::../modules/dynamic-plugins/con-understand-why-front-end-wiring-is-required.adoc[leveloffset=+2]
12+
13+
// Consequences of skipping front-end wiring
14+
include::../modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc[leveloffset=+2]
15+
16+
// When to perform frontend wiring
17+
include::../modules/dynamic-plugins/con-dynamic-front-end-plugins-for-application-use.adoc[leveloffset=+2]
18+
719
// Extending the internal icon catalog
820
include::../modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc[leveloffset=+1]
921

‎modules/dynamic-plugins/con-consequences-of-skipping-front-end-wiring.adoc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
:_mod-docs-content-type: CONCEPT
2+
[id="con-consequences-of-skipping-front-end-wiring_{context}"]
3+
4+
= Consequences of skipping front-end wiring
5+
6+
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.
7+
8+
You can expect the following behavior when you skip front-end wiring:
9+
10+
Disabled functionality:: The {product-custom-resource-type} application cannot integrate or use the plugin exports.
11+
Invisible components:: New pages, sidebar links, or custom cards do not render in the application UI.
12+
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.
13+
Unused assets:: Icons, translations, and themes are not registered or available for use.
14+
15+
[TIP]
16+
====
17+
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.
18+
====

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

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
:_mod-docs-content-type: CONCEPT
2+
[id="con-dynamic-front-end-plugins-for-application-use_{context}"]
3+
4+
= Dynamic front-end plugins for application use
5+
6+
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:
7+
8+
[cols="1,1,2"]
9+
|===
10+
|Scenario|Wiring configuration|Description
11+
12+
|{installing-and-viewing-plugins-book-link}#proc-customizing-and-extending-entity-tabs.adoc_assembly-front-end-plugin-wiring[Extending entity tabs]
13+
|`entityTabs`
14+
|Add or customize a tab on the *Catalog entity* view.
15+
16+
|{installing-and-viewing-plugins-book-link}#proc-binding-to-existing-plugins.adoc_assembly-front-end-plugin-wiring[Binding routes]
17+
|`routeBindings`
18+
|Link a route in one plugin to an external route defined by another plugin.
19+
20+
|{installing-and-viewing-plugins-book-link}#proc-provide-additional-utility-apis.adoc_assembly-front-end-plugin-wiring[Integrating custom APIs]
21+
|`apiFactories`
22+
|Provide a custom utility API implementation or override an existing one.
23+
24+
|{installing-and-viewing-plugins-book-link}#proc-defining-dynamic-routes-for-new-plugin-pages.adoc_assembly-front-end-plugin-wiring[Enabling new pages/Routes]
25+
|`dynamicRoutes`
26+
|Add a new page and route to the application (for example, `/my-plugin`).
27+
28+
|{installing-and-viewing-plugins-book-link}#proc-using-mount-points.adoc_assembly-front-end-plugin-wiring[Extending existing pages/UI]
29+
|`mountPoints`
30+
|Inject custom widgets, cards, listeners, or providers into existing pages (for example, the *Catalog entity* page).
31+
32+
|{installing-and-viewing-plugins-book-link}#proc-defining-dynamic-routes-for-new-plugin-pages.adoc_assembly-front-end-plugin-wiring[Customizing sidebar navigation]
33+
|`dynamicRoutes.menuItem`, `menuItems`
34+
|Add a new entry to the main sidebar or customize its order and nesting.
35+
36+
|{installing-and-viewing-plugins-book-link}#proc-extending-internal-icon-catalog.adoc_assembly-front-end-plugin-wiring[Adding icons/Theming]
37+
|`appIcons`, `themes`
38+
|Add custom icons to the application catalog or define a new {product-custom-resource-type} theme.
39+
40+
|{installing-and-viewing-plugins-book-link}#con-providing-custom-scaffolder-field-extensions.adoc_assembly-front-end-plugin-wiring[Scaffolder/TechDocs extensions]
41+
|`scaffolderFieldExtensions`, `techdocsAddons`
42+
|Expose custom field extensions for the Scaffolder or new Addons for TechDocs.
43+
44+
|{installing-and-viewing-plugins-book-link}#proc-extensions-enabling-plugins-installation_rhdh-extensions-plugins[Translation resources]
45+
|`translationResources`
46+
|Provide new translation files or override default plugin translations.
47+
|===
48+
49+
.Example of Front-end wiring workflow
50+
51+
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`).
52+
53+
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.
54+
55+
[source,yaml]
56+
----
57+
# dynamic-plugins-config.yaml
58+
plugins:
59+
- plugin: <plugin_path_or_url>
60+
disabled: false
61+
pluginConfig:
62+
dynamicPlugins:
63+
frontend:
64+
my-plugin-package-name: # The plugin's unique package name
65+
dynamicRoutes: # Wiring for a new page/route
66+
- path: /my-new-page # The desired URL path
67+
importName: FooPluginPage # The exported component name
68+
menuItem: # Wiring for the sidebar entry
69+
icon: favorite # A registered icon name
70+
text: My Custom Page
71+
----
72+
73+
When the application loads, it performs the following steps:
74+
75+
. It parses the `dynamic-plugins-config.yaml`.
76+
. It uses the `<plugin_path_or_url>` to download the plugin bundle using the dynamic loading mechanism.
77+
. 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.
78+
. It uses the configuration block (`dynamicRoutes`, `menuItem`) to:
79+
* Add an entry to the internal router mapping `/my-new-page` to the `FooPluginPage` component.
80+
* Construct and render a new sidebar item labeled _My Custom Page_, pointing to the `/my-new-page` route.
81+
82+
[NOTE]
83+
====
84+
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.
85+
====

‎modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
:_mod-docs-content-type: CONCEPT
2+
[id="con-frontend-dynamic-plugin-wiring_{context}"]
3+
= Front-end plugin wiring
4+
5+
Front-end plugin wiring integrates dynamic front-end plugin components, such as new pages, UI extensions, icons, and APIs, into {product}.
6+
7+
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‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
:_mod-docs-content-type: CONCEPT
2+
[id="con-understand-why-front-end-wiring-is-required_{context}"]
3+
4+
= Understand why front-end wiring is required
5+
6+
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).
7+
8+
Front-end wiring provides the metadata and instructions necessary to bridge this gap, informing the applications on how to:
9+
10+
* {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`)
11+
* {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`)
12+
* {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`)
13+
* {installing-and-viewing-plugins-book-link}#proc-customizing-sidebar-menu-items.adoc_assembly-front-end-plugin-wiring[Add new menu items]. (using `menuItems`)
14+
* {installing-and-viewing-plugins-book-link}#proc-binding-to-existing-plugins.adoc_assembly-front-end-plugin-wiring[Bind to existing plugins]. (using `routeBindings`)
15+
16+
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.

0 commit comments

Comments
 (0)