OSDOCS-12022: Dynamic plugin updates

Author: opayne1

modules/build-image-docker.adoc

@@ -6,7 +6,7 @@
 [id="build-image-with-docker_{context}"]
 = Build an image with Docker
 
-To deploy your plugin on a cluster, you need to build an image and push it to an image registry.
+To deploy your plugin on a cluster, you need to build an image and push it to an image registry first.
 
 .Procedure
 

modules/deployment-plug-in-cluster.adoc

@@ -6,7 +6,15 @@
 [id="deploy-on-cluster_{context}"]
 = Deploy your plugin on a cluster
 
-After pushing an image with your changes to a registry, you can deploy the plugin to a cluster.
+After pushing an image with your changes to a registry, you can deploy the plugin to a cluster using a Helm chart.
+
+.Prerequisites
+* You must have the location of the image containing the plugin that was previously pushed.
++
+[NOTE]
+====
+You can specify additional parameters based on the needs of your plugin. The link:https://github.com/openshift/console-plugin-template/blob/main/charts/openshift-console-plugin/values.yaml[`values.yaml`] file provides a full set of suported parameters.
+====
 
 .Procedure
 
@@ -25,6 +33,11 @@ Where:
 `--create-namespace`:: Optional: If deploying to a new namespace, use this parameter.
 `--set plugin.image=my-plugin-image-location`:: Specifies the location of the image within the `plugin.image` parameter.
 --
++
+[NOTE]
+====
+If you are deploying on {product-title} 4.10 and later, it is recommended to exclude configurations related to pod security by adding the parameter `--set plugin.securityContext.enabled=false`.
+====
 
 . Optional: You can specify any additional parameters by using the set of supported parameters in the `charts/openshift-console-plugin/values.yaml` file.
 +

modules/disabling-plug-in-browser.adoc

@@ -16,5 +16,5 @@ Console users can use the `disable-plugins` query parameter to disable specific
 
 [NOTE]
 ====
-Cluster administrators can disable plugins in the *Cluster Settings* page of the web console
+Cluster administrators can disable plugins in the *Cluster Settings* page of the web console.
 ====

modules/dynamic-plug-in-development.adoc

@@ -9,14 +9,22 @@
 You can run the plugin using a local development environment. The {product-title} web console runs in a container connected to the cluster you have logged into.
 
 .Prerequisites
-* You must have an OpenShift cluster running.
-* You must have the OpenShift CLI (`oc`) installed.
+* You must have cloned the link:https://github.com/openshift/console-plugin-template[`console-plugin-template`] repository, which contains a template for creating plugins.
++
+[IMPORTANT]
+====
+Red{nbsp}Hat does not support custom plugin code. Only link:https://access.redhat.com/solutions/5893251[Cooperative community support] is available for your plugin.
+====
+* You must have an {product-title} cluster running.
+* You must have the {oc-first} installed.
 * You must have link:https://yarnpkg.com/[`yarn`] installed.
-* You must have link:https://www.docker.com/[Docker] v3.2.0 or newer or link:https://podman.io/[Podman] installed and running.
+* You must have link:https://www.docker.com/[Docker] v3.2.0 or later or link:https://podman.io/[Podman] v3.2.0 or later installed and running.
 
 .Procedure
 
-. In your terminal, run the following command to install the dependencies for your plugin using yarn.
+. Open two terminal windows.
+
+. In one terminal window, run the following command to install the dependencies for your plugin using yarn.
 
 +
 [source,terminal]
@@ -45,6 +53,19 @@ $ oc login
 ----
 $ yarn run start-console
 ----
++
+[NOTE]
+====
+The `yarn run start-console` command runs an `amd64` image and might fail when run with Apple Silicon and Podman. You can work around it with `qemu-user-static` by running the following commands:
+
+[source,terminal]
+----
+$ podman machine ssh
+$ sudo -i
+$ rpm-ostree install qemu-user-static
+$ systemctl reboot
+----
+====
 
 .Verification
-* Visit link:http://localhost:9000/example[localhost:9000] to view the running plugin. Inspect the value of `window.SERVER_FLAGS.consolePlugins` to see the list of plugins which load at runtime.
+* Visit link:http://localhost:9000/example[localhost:9000] to view the running plugin. Inspect the value of `window.SERVER_FLAGS.consolePlugins` to see the list of plugins which load at runtime.

modules/dynamic-plugin-api.adoc

@@ -1611,6 +1611,49 @@ const Component: React.FC = (props) => {
 .Returns
 A tuple containing the current active namespace and setter callback.
 
+[discrete]
+== `useUserSettings`
+
+Hook that provides a user setting value and a callback for setting the user setting value.
+
+.Example
+[source,tsx,subs="+quotes,+macros"]
+----
+const Component: React.FC = (props) ++=>++ {
+   const [state, setState, loaded] = useUserSettings(
+     ++'devconsole.addPage.showDetails'++,
+     true,
+     true,
+   );
+   return loaded ++? (++
+      ++<WrappedComponent {...props} userSettingState={state} setUserSettingState={setState} />++
+    ) : null;
+};
+----
+
+.Returns
+A tuple containing the user setting vauel, a setter callback, and a loaded boolean.
+
+[discrete]
+== `useQuickStartContext`
+
+Hook that provides the current quick start context values. This allows plugins to interoperate with console quick start functionality.
+
+.Example
+[source,tsx,subs="+quotes,+macros"]
+----
+const OpenQuickStartButton ++= ({ quickStartId }) => {++
+   const { setActiveQuickStart } = useQuickStartContext();
+   const ++onClick = React.useCallback(() => {++
+       setActiveQuickStart(quickStartId);
+   }, [quickStartId]);
+   ++return <button onClick={onClick}>{t('Open Quick Start')}</button>++
+};
+----
+
+.Reterns
+Quick start context values object.
+
 [discrete]
 == `PerspectiveContext`
 

modules/dynamic-plugin-localization.adoc

@@ -0,0 +1,80 @@
+// Module included in the following assemblies:
+//
+// * web_console/dynamic-plugin/overview-dynamic-plugin.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="dynamic-plugin-api_{context}"]
+= Translating messages with react-i18next
+
+The link:https://github.com/openshift/console-plugin-template[plugin template] demonstrates how you can translate messages with link:https://www.i18next.com/[react-i18next].
+
+.Prerequisites
+* You must have the plugin template cloned locally.
+* Optional: To test your plugin locally, run the {product-title} web console in a container. You can use either Docker or Podman 3.2.0 or later.
+
+.Procedure
+
+. Prefix the name with `plugin\__` to avoid any naming conflicts. The plugin template uses the `plugin__console-plugin-template` namespace by default, and you must update when you rename your plugin for example, `plugin__my-plugin`.  You can use the `useTranslation` hook, for example:
++
+[source,tsx,subs="+quotes,+macros"]
+----
+conster Header: React.FC = () ++=>++ {
+  const ++{ t } = useTranslation('plugin__console-demo-plugin');++
+  ++return <h1>{t('Hello, World!')}</h1>;++
+++};++
+----
++
+[IMPORTANT]
+====
+You must match the `i18n` namespace with the name of the `ConsolePlugin` resource.
+====
+
+. Set the `spec.i18n.loadType` field based on needed behavior.
++
+.`plugin__console-demo-plugin`
+[example]
+====
+[source,yaml,subs="+quotes,+macros"]
+----
+spec:
+  backend:
+    service:
+      basePath: ++/++
+      name: console-demo-plugin
+      namespace: console-demo-plugin
+      port: 9001
+    type: Service
+  displayName: OpenShift Console Demo Plugin
+  i18n:
+    loadType: Preload <1>
+----
+<1> Loads all the plugin's localization resources from the `i18n` namespace after the dynamic plugin during loading.
+====
+
+. Use the format `++%plugin__console-plugin-template~My Label%++` for labels in `console-extensions.json`. The console replaces the value with the message for the current language from the `plugin__console-plugin-template` namespace. For example:
++
+[source,json,subs="+quotes,+macros"]
+----
+  {
+    ++"type": "console.navigation/section"++,
+    ++"properties": {++
+      ++"id": "admin-demo-section"++,
+      ++"perspective": "admin"++,
+      ++"name": "%plugin__console-plugin-template~Plugin Template%"++
+    }
+  }
+----
+
+. Include a comment in a TypeScript file for link:https://github.com/i18next/i18next-parser[i18next-parser] to add the message from `console-extensions.json` to your message catalog. For example:
++
+[source,tsx,subs="+quotes,+macros"]
+----
+++// t('plugin__console-demo-plugin~Demo Plugin')++
+----
+
+. To update the JSON files in the `locales` folder of the plugin template when adding or changing a message, run the following command:
++
+[source,terminal]
+----
+$ yarn i18n
+----

web_console/dynamic-plugin/overview-dynamic-plugin.adoc

@@ -9,7 +9,9 @@ toc::[]
 [id="dynamic-plug-in-overview"]
 == About dynamic plugins
 
-Dynamic plugins are deployed as workloads on the cluster. They allow you to add custom pages and other extensions to your console user interface at runtime. The `ConsolePlugin` custom resource registers plugins with the console, and a cluster administrator enables plugins in the `console-operator` configuration.
+Dynamic plugins are loaded and interpreted from remote sources at runtime. One way to deliver and expose dynamic plugins to the console is through OLM Operators. The Operator creates a deployment on the platform with an HTTP server to host the plugin and exposes it using a Kubernetes service.
+
+Dynamic plugins allow you to add custom pages and other extensions to your console user interface at runtime. The `ConsolePlugin` custom resource registers plugins with the console, and a cluster administrator enables plugins in the console Operator configuration.
 
 [id="dynamic-plugins-features"]
 == Key features
@@ -30,16 +32,21 @@ When creating your plugin, follow these general guidelines:
 * Maintain a consistent look, feel, and behavior with other console pages.
 * Follow link:https://www.i18next.com/[react-i18next] localization guidelines when creating your plugin. You can use the `useTranslation` hook like the one in the following example:
 +
-[source,typescript]
+[source,tsx,subs="+quotes,+macros"]
 ----
-conster Header: React.FC = () => {
-  const { t } = useTranslation('plugin__console-demo-plugin');
-  return <h1>{t('Hello, World!')}</h1>;
-};
+conster Header: React.FC ++= () => {++
+  ++const { t } = useTranslation('plugin__console-demo-plugin');++
+  ++return <h1>{t('Hello, World!')}</h1>;++
+++};++
 ----
 
 * Avoid selectors that could affect markup outside of your plugins components, such as element selectors. These are not APIs and are subject to change. Using them might break your plugin. Avoid selectors like element selectors that could affect markup outside of your plugins components.
 * Provide valid JavaScript Multipurpose Internet Mail Extension (MIME) type using the `Content-Type` response header for all assets served by your plugin web server. Each plugin deployment should include a web server that hosts the generated assets of the given plugin.
+* You must build your plugin with Webpack using Webpack version 5 and later.
+* You should prefix CSS class names with your plugin name to avoid collisions. For example, `my-plugin_\_heading` and `my-plugin_\_icon`.
+* You should maintain a consistent look, feel, and behavior with other console pages.
+* You should avoid selectors that could affect markup outside of your plugin components, such as element selectors. These are not APIs and are subject to change.
+* You must provide a valid JavaScript Multipurpose Internet Mail Extension (MIME) type using the `Content-Type` response header for all assets served by your plugin web server. Each plugin deployment should include a web server that hosts the generated assets of the given plugin.
 
 [discrete]
 == PatternFly guidelines
@@ -49,5 +56,7 @@ When creating your plugin, follow these guidelines for using PatternFly:
 ** Use Patternfly 4.x if you are using {product-title} versions 4.14 and earlier.
 ** Use Patternfly 5.x if you are using {product-title} 4.15 or later.
 * Make your plugin accessible by following link:https://www.patternfly.org/accessibility/accessibility-fundamentals/[PatternFly's accessibility fundamentals].
-* Avoid using other CSS libraries such as Bootstrap or Tailwind. They can conflict with PatternFly and will not match the console look and feel. Plugins should only include styles that are specific to their user interfaces to be evaluated on top of base PatternFly styles. Avoid importing styles such as `@patternfly/react-styles/**/*.css` or any styles from `@patternfly/patternfly` package in your plugin.
+* Avoid using other CSS libraries such as Bootstrap or Tailwind. They might conflict with PatternFly and not match the rest of the console. Plugins should only include styles that are specific to their user interfaces to be evaluated on top of base PatternFly styles. Avoid importing styles such as `@patternfly/react-styles/**/*.css` or any styles from the `@patternfly/patternfly` package in your plugin.
 * The console application is responsible for loading base styles for all supported PatternFly version(s).
+
+include::modules/dynamic-plugin-localization.adoc[leveloffset=+2]