Plugins Functionality
Headlamp’s plugins exist for changing or adding functionlity related to the user interface and experience.
Plugins Lib
The @kinvolk/headlamp-plugin
module ships a library
(@kinvolk/headlamp-plugin/lib
) where all the Headlamp-related development
modules can be found.
The main ones are:
- K8s: Kubernetes related functionality
- Registry: The plugin registry, used to register functionality
- Headlamp: To register plugins
- CommonComponents: React components commonly used in the Headlamp UI
- Notification: This module contains two exported members one is Notification, a class which can be used to prepare notifications that are accepted by headlamp and the other one is setNotificationsInStore it is a dispatcher function which accepts a notification object prepared from the Notification class and when called it brings the notifications from plugin land to headlamp ecosystem so that headlamp can parse the notification and display it.
- Router: To get or generate routes
Shared Modules
Headlamp ships many of the common npm modules that should be shared by both the plugins and Headlamp itself, and includes the config files for editors like VS Code to find them.
These are:
- react
- @iconify-react
- react-redux
- @material-ui/core
- @material-ui/styles
- lodash
- notistack
- recharts
Thus, plugins only need to install dependencies that are not yet provided by Headlamp.
Yet, if any dependencies already covered by Headlamp are intalled by the plugins, you
just need to make sure they are te same version that Headlamp supports, as these will
not be bundled when
building the plugin
.
Particularly, the mentioned modules will be replaced by their version that’s included
in a global objects called pluginLib
.
Older plugin development guides still asked developers to use e.g. React in the following
way const React = window.pluginLib.React
, but this is not longer needed.
Registration
Apart from the modules mentioned above, Headlamp also adds an important method
for registering plugins (Headlamp.registerPlugin
).
Funcionality
The plugin registers makes functionality available to plugins in an easy way.
The idea is to make more and more functionality available to plugins. Here is what we have so far:
Sidebar Items
registerSidebarItem(parentName: string, itemName: string,
itemLabel: string, url: string,
opts = {useClusterURL: true})
This method allows to set entries in the sidebar.
The arguments are as follows:
parentName
: The name of the parent entry. If the string is empty, then there is no parent, and that means the entry is a top-level one. For knowing which names exist already in the Sidebar, at the moment you have to check the configuration for that component, which can be found in Headlamp’ssrc/components/Sidebar.tsx
.itemName
: The logical name for the item, i.e. the name other sub-entries will use when setting this item as a parent.itemLabel
: The text to be displayed for the entry in the Sidebar.url
: The URL to go to when clicking this entry.opts
: The options related to registering this item. At the moment, only theuseClusterUrl
(defaults totrue
) can be used. This option indicates whether the URL we are using for this entry should be prefixed with the current cluster URL or not. Most cluster related actions should have URLs that are prefixed by the cluster name and that’s managed automatically with this option.
Routes
registerRoute(routeSpec: Route)
interface Route {
path: string;
exact?: boolean;
noCluster?: boolean;
noAuthRequired?: boolean;
sidebar: string | null;
component: () => JSX.Element;
}
This method allows to register a route (i.e. a known URL that resolves to a component displayed in Headlamp’s main area).
The routeSpec
is an object with the following members:
path
: The URL path for the route.exact
(optional): There it should be an exact match between the URL’s path and the one defined in the route spec (see ReactRouter ’s docs for more context). By default it isfalse
.noCluster
(optional): Whether the route doesn’t belongs to a cluster (in which case the URL produced for it will have the cluster prefix). By default it isfalse
.noAuthRequired
(optional): Whether authentication is not required for this route (example, non-cluster routes such as settings). By default it isfalse
.sidebar
: Which sidebar entry to select when this route is on (the value used should be an item name of the sidebar).component
: The component to render in Headlamp’s main area.
Details Views' Header Actions
registerDetailsViewHeaderAction(actionName: string,
actionFunc: (item: object) => JSX.Element | null)
This method allows to add a component to the top right area of details views (in the area of the screenshot below that’s highlighted as yellow).
Details views are the views used for displaying information about each cluster’s resource.
The arguments are as follows:
actionName
: The name for this action.actionFunc
: A function that takes an item and returns an element (or null, if nothing should be done).
App Bar Actions
registerAppBarAction(actionName: string, actionFunc: () => JSX.Element | null))
This method allows to add a component to the top right area of the app bar (top bar).
The arguments are as follows:
actionName
: The name for this action.actionFunc
: A function that returns an element.