1. Documentation
×

Overview of dynamic plugins

About dynamic plugins

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.

Key features

A dynamic plugin allows you to make the following customizations to the OKD experience:

  • Add custom pages.

  • Add perspectives beyond administrator and developer.

  • Add navigation items.

  • Add tabs and actions to resource pages.

General guidelines

When creating your plugin, follow these general guidelines:

  • Node.js and yarn are required to build and run your plugin.

  • Prefix your CSS class names with your plugin name to avoid collisions. For example, my-plugin__heading and my-plugin_\_icon.

  • Maintain a consistent look, feel, and behavior with other console pages.

  • Follow react-i18next localization guidelines when creating your plugin. You can use the useTranslation hook like the one in the following example:

    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.

PatternFly guidelines

When creating your plugin, follow these guidelines for using PatternFly:

  • Use PatternFly components and PatternFly CSS variables. Core PatternFly components are available through the SDK. Using PatternFly components and variables help your plugin look consistent in future console versions.

    • Use Patternfly 4.x if you are using OKD versions 4.14 and earlier.

    • Use Patternfly 5.x if you are using OKD 4.15 or later.

  • Make your plugin accessible by following PatternFly’s accessibility fundamentals.

  • 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).

Translating messages with react-i18next

The plugin template demonstrates how you can translate messages with react-i18next.

Prerequisites

  • You must have the plugin template cloned locally.

  • Optional: To test your plugin locally, run the OKD web console in a container. You can use either Docker or Podman 3.2.0 or later.

Procedure

  1. 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:

    conster Header: React.FC = () => {
  const { t } = useTranslation('plugin__console-demo-plugin');
  return <h1>{t('Hello, World!')}</h1>;
};

    You must match the i18n namespace with the name of the ConsolePlugin resource.

  2. Set the spec.i18n.loadType field based on needed behavior.

    Example 1. plugin__console-demo-plugin
    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.

  3. 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:

      {
    "type": "console.navigation/section",
    "properties": {
      "id": "admin-demo-section",
      "perspective": "admin",
      "name": "%plugin__console-plugin-template~Plugin Template%"
    }
  }

  4. Include a comment in a TypeScript file for i18next-parser to add the message from console-extensions.json to your message catalog. For example:

    // t('plugin__console-demo-plugin~Demo Plugin')

  5. To update the JSON files in the locales folder of the plugin template when adding or changing a message, run the following command:

    $ yarn i18n