From bb23f336c1ab0719d54ced7940e10adcead569e1 Mon Sep 17 00:00:00 2001 From: Jim Ehrismann Date: Fri, 6 Nov 2020 18:24:03 -0500 Subject: [PATCH] Extension Guides documentation Signed-off-by: Jim Ehrismann --- docs/extensions/guides/README.md | 28 ++++++++ docs/extensions/guides/main-extension.md | 70 ++++++++++++++++++++ docs/extensions/guides/renderer-extension.md | 36 ++++++++++ mkdocs.yml | 1 + 4 files changed, 135 insertions(+) create mode 100644 docs/extensions/guides/main-extension.md diff --git a/docs/extensions/guides/README.md b/docs/extensions/guides/README.md index e69de29bb2..2917090212 100644 --- a/docs/extensions/guides/README.md +++ b/docs/extensions/guides/README.md @@ -0,0 +1,28 @@ +# Extension Guides + +The basics of the Lens Extension API are covered in [Your First Extension](../get-started/your-first-extension.md). In this section detailed code guides and samples are used to explain how to use specific Lens Extension APIs. + +Each guide or sample will include: + +- Clearly commented source code. +- Instructions for running the sample extension. +- Image of the sample extension's appearance and usage. +- Listing of Extension API being used. +- Explanation of Extension API concepts. + +## Guides + +| Guide | APIs | +| ----- | ----- | +| [Main process extension](main-extension.md) | LensMainExtension | +| [Renderer process extension](renderer-extension.md) | LensRendererExtension | +| [Stores](stores.md) | | +| [Components](components.md) | | +| [KubeObjectListLayout](kube-object-list-layout.md) | | + +## Samples + +| Sample | APIs | +| ----- | ----- | +[helloworld](https://github.com/lensapp/lens-extension-samples/tree/master/helloworld-sample) | LensMainExtension
LensRendererExtension
Component.Icon
Component.IconProps | +[minikube](https://github.com/lensapp/lens-extension-samples/tree/master/minikube-sample) | LensMainExtension
Store.clusterStore
Store.workspaceStore | \ No newline at end of file diff --git a/docs/extensions/guides/main-extension.md b/docs/extensions/guides/main-extension.md new file mode 100644 index 0000000000..4df7ebca82 --- /dev/null +++ b/docs/extensions/guides/main-extension.md @@ -0,0 +1,70 @@ +# Main Extension + +The main extension api is the interface to Lens' main process (Lens runs in main and renderer processes). It allows you to access, configure, and customize Lens data, add custom application menu items, and generally run custom code in Lens' main process. + +## LensMainExtension Class + +To create a main extension simply extend the `LensMainExtension` class: + +``` +import { LensMainExtension } from "@k8slens/extensions"; + +export default class ExampleExtensionMain extends LensMainExtension { + onActivate() { + console.log('custom main process extension code started'); + } + + onDeactivate() { + console.log('custom main process extension de-activated'); + } +} +``` + +There are two methods that you can override to facilitate running your custom code. `onActivate()` is called when your extension has been successfully enabled. By overriding `onActivate()` you can initiate your custom code. `onDeactivate()` is called when the extension is disabled (typically from the [Lens Extensions Page]()) and when overridden gives you a chance to clean up after your extension, if necessary. The example above simply logs messages when the extension is enabled and disabled. + +The following example is a little more interesting in that it accesses some Lens state data and periodically logs the name of the currently active cluster in Lens. + +``` +import { LensMainExtension, Store } from "@k8slens/extensions" + +const clusterStore = Store.clusterStore + +export class CurrentClusterExtensionMain extends LensMainExtension { + + timer: NodeJS.Timeout + + onActivate() { + this.timer = setInterval(() => { + console.log("current cluster is ", clusterStore.activeCluster) + }, 5000) + } + + onDeactivate() { + clearInterval(this.timer) + } +} +``` + +See the [Stores]() guide for more details on accessing Lens state data. + +### `appMenus` + +The only UI feature customizable in the main extension api is the application menu. Custom menu items can be inserted and linked to custom functionality, such as navigating to a specific page. The following example demonstrates adding a menu item to the Help menu. + +``` +import { LensMainExtension } from "@k8slens/extensions"; + +export default class SamplePageMainExtension extends LensMainExtension { + appMenus = [ + { + parentId: "help", + label: "Sample", + click() { + console.log("Sample clicked"); + } + } + ] +} +``` + +`appMenus` is an array of objects satisfying the `MenuRegistration` interface. `MenuRegistration` extends React's `MenuItemConstructorOptions` interface. `parentId` is the id of the menu to put this menu item under (todo: is this case sensitive and how do we know what the available ids are?), `label` is the text to show on the menu item, and `click()` is called when the menu item is selected. In this example we simply log a message, but typically you would navigate to a specific page or perform some operation. \ No newline at end of file diff --git a/docs/extensions/guides/renderer-extension.md b/docs/extensions/guides/renderer-extension.md index fc4f9b8bdd..4b81ae9235 100644 --- a/docs/extensions/guides/renderer-extension.md +++ b/docs/extensions/guides/renderer-extension.md @@ -1 +1,37 @@ # Renderer Extension + +The renderer extension api is the interface to Lens' renderer process (Lens runs in main and renderer processes). It allows you to access, configure, and customize Lens data, add custom Lens UI elements, and generally run custom code in Lens' renderer process. The custom Lens UI elements that can be added include global pages, cluster pages, cluster features, app preferences, status bar items, KubeObject menu items, and KubeObject details items. + +## LensRendererExtension Class + +To create a renderer extension simply extend the `LensRendererExtension` class: + +``` +import { LensRendererExtension } from "@k8slens/extensions"; + +export default class ExampleExtensionMain extends LensRendererExtension { + onActivate() { + console.log('custom renderer process extension code started'); + } + + onDeactivate() { + console.log('custom renderer process extension de-activated'); + } +} +``` + +There are two methods that you can override to facilitate running your custom code. `onActivate()` is called when your extension has been successfully enabled. By overriding `onActivate()` you can initiate your custom code. `onDeactivate()` is called when the extension is disabled (typically from the [Lens Extensions Page]()) and when overridden gives you a chance to clean up after your extension, if necessary. The example above simply logs messages when the extension is enabled and disabled. + +### globalPages + +### clusterPages + +### clusterFeatures + +### appPreferences + +### statusBarItems + +### kubeObjectMenuItems + +### kubeObjectDetailItems diff --git a/mkdocs.yml b/mkdocs.yml index 7101f6897d..cf0c066dc8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,6 +30,7 @@ nav: - Color Reference: extensions/capabilities/color-reference.md - Extension Guides: - Overview: extensions/guides/README.md + - Main Extension: extensions/guides/main-extension.md - Renderer Extension: extensions/guides/renderer-extension.md - Testing and Publishing: - Testing Extensions: extensions/testing-and-publishing/testing.md