[WIP] OSDOCS:2475 Adds new assembly for the dynamic plugin TP

_topic_maps/_topic_map.yml

@@ -570,6 +570,9 @@ Topics:
 - Name: Customizing the web console
   File: customizing-the-web-console
   Distros: openshift-enterprise,openshift-origin
+- Name: Dynamic plug-ins
+  File: dynamic-plug-ins
+  Distros: openshift-enterprise,openshift-origin
 - Name: Developer perspective
   File: odc-about-developer-perspective
 - Name: Web terminal

modules/about-dynamic-plug-ins.adoc

@@ -0,0 +1,34 @@
+// Module is included in the following assemblies:
+//
+// * openshift-docs/web_console/dynamic-plug-ins.adoc
+
+:_content-type: CONCEPT
+[id="about-dynamic-plugins_{context}"]
+= About dynamic plug-ins
+
+A dynamic plug-in allows you to add custom pages and other extensions to your interface at runtime. The `ConsolePlugin` custom resource registers plug-ins with the console, and a cluster administrator enables plug-ins in the `console-operator` configuration.
+
+[id="dynamic-plugins-features"]
+== Key features
+
+A dynamic plug-in allows you to make the following customizations to the {product-title} experience:
+
+* Add custom pages.
+* Add perspectives and update navigation items.
+* Add tabs and actions to resource pages.
+
+== PatternFly 4 guidelines
+When creating your plug-in, follow these guidelines for using PatternFly:
+
+* Use link:https://www.patternfly.org/v4/[PatternFly4] components and PatternFly CSS variables. Core PatternFly components are available through the SDK. Using PatternFly components and variables will help your plug-in look consistent in future console versions.
+* Make your plug-in accessible by following link:https://www.patternfly.org/v4/accessibility/accessibility-fundamentals/[PatternFly's accessibility fundamentals].
+* _Do not_ use other CSS libraries such as Bootstrap or Tailwind. They can conflict with PatternFly and will not match the console look and feel.
+
+[id="general-plug-in-guidelines"]
+== General guidelines
+When creating your plug-in, follow these general guidelines:
+
+* Prefix your CSS class names with your plug-in name to avoid collisions. For example, `my-plugin_\_heading` and `my-plugin_\_icon`.
+* Maintain a consistent look, feel, and behavior with other console pages.
+* Use link:https://github.com/openshift/enhancements/blob/master/enhancements/console/dynamic-plugins.md#localization[react-i18next] for localization.
+* _Do not_ use console CSS classes in your markup or override console CSS classes. These are not APIs and are subject to change. Using them might break your plug-in. Avoid selectors like element selectors that could affect markup outside of your plug-in’s components.

modules/adding-new-extension-dynamic-plug-in.adoc

@@ -0,0 +1,8 @@
+// Module included in the following assemblies:
+//
+// * web_console/dynamic-plug-ins.adoc
+
+:_content-type: CONCEPT
+[id="adding-new-extension-dynamic-plugin_{context}"]
+= Adding a new extension to your plug-in
+You can add extensions to your plug-in that are loaded at runtime. 

modules/adding-tab-pods-page.adoc

@@ -0,0 +1,57 @@
+// Module included in the following assemblies:
+//
+// * web_console/dynamic-plug-ins.adoc
+
+:_content-type: PROCEDURE
+[id="adding-tab-to-pods-page_{context}"]
+= Adding a tab to the pods page
+The following procedure adds a tab to the *Pod Details* page as an example extension to your plug-in.
+
+.Procedure
+
+. Add the following to the `console-extensions.json` file:
++
+[source,json]
+
+----
+{
+    "type": "console.page/resource/tab",
+    "properties": {
+        "name": "Example Tab",
+        "href": "example",
+        "model": {
+            "group": "core",
+            "version": "v1",
+            "kind": "Pod"
+        },
+        "component": { "$codeRef": "ExampleTab" }
+}
+----
+
+. Edit the `package.json` file to include the following changes:
++
+[source,json]
+
+----
+        "exposedModules": {
+            "ExamplePage": "./components/ExamplePage",
+            "ExampleTab": "./components/ExampleTab"
+        }
+----
+
+. Write a message to display on a new custom tab on the *Pods* page by creating a new file `src/components/ExampleTab.tsx` and adding the following script:
++
+[source,tsx]
+
+----
+import * as React from 'react';
+
+export default function ExampleTab() {
+    return (
+        <p>This is a custom tab added to a resource using a dynamic plug-in.</p>
+    );
+}
+----
+
+.Verification
+* Visit a *Pod* page to view the added tab.

modules/build-image-docker.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * web_console/dynamic-plug-ins.adoc
+
+:_content-type: PROCEDURE
+[id="build-image-with-docker_{context}"]
+= Build an image with Docker
+
+To deploy your plug-in on a cluster, you need to build an image and push it to an image registry.
+
+.Procedure
+
+. Build the image with the following command:
++
+[source,terminal]
+----
+$ docker build -t quay.io/my-repositroy/my-plugin:latest .
+----
+
+. Optional: If you want to test your image, run the following command:
++
+[source,terminal]
+----
+$ docker run -it --rm -d -p 9001:80 quay.io/my-repository/my-plugin:latest
+----
+
+. Push the image by running the following command:
++
+[source,terminal]
+----
+$ docker push quay.io/my-repository/my-plugin:latest
+----

modules/deployment-plug-in-cluster.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * web_console/dynamic-plug-ins.adoc
+
+:_content-type: PROCEDURE
+[id="deploy-on-cluster_{context}"]
+= Deploy your plug-in on a cluster
+
+After pushing an image with your changes to a registry, you can deploy the plug-in to a cluster.
+
+.Procedure
+
+. To deploy your plug-in to a cluster, instantiate the link:https://github.com/spadgett/console-plugin-template/blob/main/template.yaml[template] by running the following command:
++
+[source,terminal]
+----
+$ oc process -f template.yaml \
+  -p PLUGIN_NAME=my-plugin \ <1>
+  -p NAMESPACE=my-plugin-namespace \ <2>
+  -p IMAGE=quay.io/my-repository/my-plugin:latest \ <3>
+  | oc create -f -
+----
+<1> Update with the name of your plug-in.
+<2> Update with the namespace.
+<3> Update with the name of the image you created.
++
+This command runs a light-weight NGINX HTTP server to serve the assets for your plug-in.
+
+IMPORTANT: `PLUGIN_NAME` must match the plug-in name you used in the `consolePlugin` declaration of `package.json`.
+
+[start=2]
+. Patch the *Console Operator* configuration to enable the plug-in by running the following command:
++
+[source,terminal]
+
+----
+$ oc patch consoles.operator.openshift.io cluster --patch '{ "spec": { "plugins": ["my-plugin"] } }' --type=merge
+----

modules/dynamic-plug-ins-get-started.adoc

@@ -0,0 +1,46 @@
+// Module included in the following assemblies:
+//
+// * web_console/dynamic-plug-ins.adoc
+
+:_content-type: PROCEDURE
+[id="getting-started-with-dynamic-plugins_{context}"]
+= Getting started with dynamic plug-ins
+
+To get started using the dynamic plug-in, you must set up your environment to write a new OpenShift Console dynamic plug-in.
+
+.Prerequisites
+* Ensure you have link:https://nodejs.org/en/[`Node.js`] installed.
+* Ensure you have link:https://yarnpkg.com/[`yarn`] installed.
+
+.Procedure
+
+. Visit this link:https://github.com/spadgett/console-plugin-template[repository] containing a template for creating plug-ins.
+
+. Select `Use this Template` from the *<> Code* tab to create a GitHub repository.
+
+. Re-name the template with the name of your plug-in.
+
+. From your copied repository, clone it your local machine so you can edit the code.
+
+. Edit the plug-in metadata in the `consolePlugin` declaration of `package.json`.
++
+[source,json]
+
+----
+"consolePlugin": {
+  "name": "my-plugin", <1>
+  "version": "0.0.1", <2>
+  "displayName": "My Plugin", <3>
+  "description": "Enjoy this shiny, new console plugin!", <4>
+  "exposedModules": {
+    "ExamplePage": "./components/ExamplePage"
+  },
+  "dependencies": {
+    "@console/pluginAPI": "*"
+  }
+}
+----
+<1> Update the name of your plug-in.
+<2> Update the version.
+<3> Update the display name for your plug-in.
+<4> Update the description with a synopsis about your plug-in.

modules/running-your-dynamic-plug-in.adoc

@@ -0,0 +1,46 @@
+// Module included in the following assemblies:
+//
+// * web_console/dynamic-plug-ins.adoc
+
+:_content-type: PROCEDURE
+[id="running-your-dynamic-plugin_{context}"]
+= Running your dynamic plug-in
+
+You can run the plug-in using a local development environment. The OpenShift console runs in a container connected to the cluster you have logged into.
+
+.Prerequisites
+* You must have the OpenShift CLI (`oc`) installed.
+* You must have an OpenShift cluster running.
+* You must have link:https://www.docker.com/[Docker] or at least v3.2.0 of link:https://podman.io/[Podman] installed.
+
+.Procedure
+
+* Open two terminal windows in the local directory of your cloned repository.
++
+
+a. Run the following commands in the first terminal:
++
+[source,terminal]
+----
+$ yarn install
+----
++
+[source,terminal]
+----
+$ yarn run start
+----
+
+b. Run the following commands in the second terminal window:
++
+[source,terminal]
+----
+$ oc login
+----
++
+[source,terminal]
+----
+$ yarn run start-console
+----
+
+.Verification
+* Visit link:http://localhost:9000/example[local host] to view the running plug-in.

web_console/dynamic-plug-ins.adoc

@@ -0,0 +1,35 @@
+:_content-type: ASSEMBLY
+[id="adding-dynamic-plugin-to-console"]
+= Adding a dynamic plug-in to the {product-title} web console
+include::modules/common-attributes.adoc[]
+:context: dynamic-plugins
+
+toc::[]
+
+You can create and deploy a dynamic plug-in on your cluster that is loaded at run-time.
+
+:FeatureName: Creating a dynamic plug-in
+include::snippets/technology-preview.adoc[leveloffset=+1]
+//
+
+include::modules/about-dynamic-plug-ins.adoc[leveloffset=+1]
+
+include::modules/dynamic-plug-ins-get-started.adoc[leveloffset=+1]
+
+include::modules/running-your-dynamic-plug-in.adoc[leveloffset=+1]
+
+include::modules/adding-tab-pods-page.adoc[leveloffset=+2]
+
+include::modules/adding-new-extension-dynamic-plug-in.adoc[leveloffset=+1]
+
+include::modules/build-image-docker.adoc[leveloffset=+1]
+
+include::modules/deployment-plug-in-cluster.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="dynamic-plugin-additional-resources"]
+== Additional resources
+
+* link:https://github.com/spadgett/console-customization-plugin[Console customization plug-in].
+* link:https://github.com/openshift/console/tree/master/frontend/packages/console-dynamic-plugin-sdk#openshift-console-dynamic-plugins[Console plug-in SDK README]
+* link:https://github.com/openshift/enhancements/blob/master/enhancements/console/dynamic-plugins.md[Dynamic plug-in enhancement proposal]