mirror of
https://github.com/lensapp/lens.git
synced 2025-05-20 05:10:56 +00:00
Add back in extension documents
Signed-off-by: Steve Richards <srichards@mirantis.com>
This commit is contained in:
1 parent
02882e1b15
commit
a804b8101f
35 files changed
+2628
No files matched your search
Whitespace-only changes.
@@ -0,0 +1,283 @@
|
||||
# Common Capabilities
|
||||
|
||||
Here we will discuss common and important building blocks for your extensions, and explain how you can use them.
|
||||
Almost all extensions use some of these functionalities.
|
||||
|
||||
## Main Extension
|
||||
|
||||
The main extension runs in the background.
|
||||
It adds app menu items to the Lens UI.
|
||||
In order to see logs from this extension, you need to start Lens from the command line.
|
||||
|
||||
### Activate
|
||||
|
||||
This extension can register a custom callback that is executed when an extension is activated (started).
|
||||
|
||||
``` javascript
|
||||
import { LensMainExtension } from "@k8slens/extensions"
|
||||
|
||||
export default class ExampleMainExtension extends LensMainExtension {
|
||||
async onActivate() {
|
||||
console.log("hello world")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Deactivate
|
||||
|
||||
This extension can register a custom callback that is executed when an extension is deactivated (stopped).
|
||||
|
||||
``` javascript
|
||||
import { LensMainExtension } from "@k8slens/extensions"
|
||||
|
||||
export default class ExampleMainExtension extends LensMainExtension {
|
||||
async onDeactivate() {
|
||||
console.log("bye bye")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### App Menus
|
||||
|
||||
This extension can register custom app menus that will be displayed on OS native menus.
|
||||
|
||||
Example:
|
||||
|
||||
```typescript
|
||||
import { LensMainExtension, windowManager } from "@k8slens/extensions"
|
||||
|
||||
export default class ExampleMainExtension extends LensMainExtension {
|
||||
appMenus = [
|
||||
{
|
||||
parentId: "help",
|
||||
label: "Example item",
|
||||
click() {
|
||||
windowManager.navigate("https://k8slens.dev");
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Renderer Extension
|
||||
|
||||
The renderer extension runs in a browser context, and is visible in Lens's main window.
|
||||
In order to see logs from this extension you need to check them via **View** > **Toggle Developer Tools** > **Console**.
|
||||
|
||||
### Activate
|
||||
|
||||
This extension can register a custom callback that is executed when an extension is activated (started).
|
||||
|
||||
``` javascript
|
||||
import { LensRendererExtension } from "@k8slens/extensions"
|
||||
|
||||
export default class ExampleExtension extends LensRendererExtension {
|
||||
async onActivate() {
|
||||
console.log("hello world")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Deactivate
|
||||
|
||||
This extension can register a custom callback that is executed when an extension is deactivated (stopped).
|
||||
|
||||
``` javascript
|
||||
import { LensRendererExtension } from "@k8slens/extensions"
|
||||
|
||||
export default class ExampleMainExtension extends LensRendererExtension {
|
||||
async onDeactivate() {
|
||||
console.log("bye bye")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Global Pages
|
||||
|
||||
This extension can register custom global pages (views) to Lens's main window.
|
||||
The global page is a full-screen page that hides all other content from a window.
|
||||
|
||||
```typescript
|
||||
import React from "react"
|
||||
import { Component, LensRendererExtension } from "@k8slens/extensions"
|
||||
import { ExamplePage } from "./src/example-page"
|
||||
|
||||
export default class ExampleRendererExtension extends LensRendererExtension {
|
||||
globalPages = [
|
||||
{
|
||||
id: "example",
|
||||
components: {
|
||||
Page: ExamplePage,
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
globalPageMenus = [
|
||||
{
|
||||
title: "Example page", // used in icon's tooltip
|
||||
target: { pageId: "example" }
|
||||
components: {
|
||||
Icon: () => <Component.Icon material="arrow"/>,
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### App Preferences
|
||||
|
||||
This extension can register custom app preferences.
|
||||
It is responsible for storing a state for custom preferences.
|
||||
|
||||
```typescript
|
||||
import React from "react"
|
||||
import { LensRendererExtension } from "@k8slens/extensions"
|
||||
import { myCustomPreferencesStore } from "./src/my-custom-preferences-store"
|
||||
import { MyCustomPreferenceHint, MyCustomPreferenceInput } from "./src/my-custom-preference"
|
||||
|
||||
|
||||
export default class ExampleRendererExtension extends LensRendererExtension {
|
||||
appPreferences = [
|
||||
{
|
||||
title: "My Custom Preference",
|
||||
components: {
|
||||
Hint: () => <MyCustomPreferenceHint/>,
|
||||
Input: () => <MyCustomPreferenceInput store={myCustomPreferencesStore}/>
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Cluster Pages
|
||||
|
||||
This extension can register custom cluster pages.
|
||||
These pages are visible in a cluster menu when a cluster is opened.
|
||||
|
||||
```typescript
|
||||
import React from "react"
|
||||
import { LensRendererExtension } from "@k8slens/extensions";
|
||||
import { ExampleIcon, ExamplePage } from "./src/page"
|
||||
|
||||
export default class ExampleExtension extends LensRendererExtension {
|
||||
clusterPages = [
|
||||
{
|
||||
id: "extension-example", // optional
|
||||
exact: true, // optional
|
||||
components: {
|
||||
Page: () => <ExamplePage extension={this}/>,
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
clusterPageMenus = [
|
||||
{
|
||||
url: "/extension-example", // optional
|
||||
title: "Example Extension",
|
||||
components: {
|
||||
Icon: ExampleIcon,
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Cluster Features
|
||||
|
||||
This extension can register installable features for a cluster.
|
||||
These features are visible in the "Cluster Settings" page.
|
||||
|
||||
```typescript
|
||||
import React from "react"
|
||||
import { LensRendererExtension } from "@k8slens/extensions"
|
||||
import { MyCustomFeature } from "./src/my-custom-feature"
|
||||
|
||||
export default class ExampleExtension extends LensRendererExtension {
|
||||
clusterFeatures = [
|
||||
{
|
||||
title: "My Custom Feature",
|
||||
components: {
|
||||
Description: () => {
|
||||
return (
|
||||
<span>
|
||||
Just an example.
|
||||
</span>
|
||||
)
|
||||
}
|
||||
},
|
||||
feature: new MyCustomFeature()
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Status Bar Items
|
||||
|
||||
This extension can register custom icons and text to a status bar area.
|
||||
|
||||
```typescript
|
||||
import React from "react";
|
||||
import { Component, LensRendererExtension, Navigation } from "@k8slens/extensions";
|
||||
|
||||
export default class ExampleExtension extends LensRendererExtension {
|
||||
statusBarItems = [
|
||||
{
|
||||
components: {
|
||||
Item: (
|
||||
<div className="flex align-center gaps hover-highlight" onClick={() => this.navigate("/example-page")} >
|
||||
<Component.Icon material="favorite" />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Kubernetes Object Menu Items
|
||||
|
||||
This extension can register custom menu items (actions) for specified Kubernetes kinds/apiVersions.
|
||||
|
||||
```typescript
|
||||
import React from "react"
|
||||
import { LensRendererExtension } from "@k8slens/extensions";
|
||||
import { CustomMenuItem, CustomMenuItemProps } from "./src/custom-menu-item"
|
||||
|
||||
export default class ExampleExtension extends LensRendererExtension {
|
||||
kubeObjectMenuItems = [
|
||||
{
|
||||
kind: "Node",
|
||||
apiVersions: ["v1"],
|
||||
components: {
|
||||
MenuItem: (props: CustomMenuItemProps) => <CustomMenuItem {...props} />
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Kubernetes Object Details
|
||||
|
||||
This extension can register custom details (content) for specified Kubernetes kinds/apiVersions.
|
||||
|
||||
```typescript
|
||||
import React from "react"
|
||||
import { LensRendererExtension } from "@k8slens/extensions";
|
||||
import { CustomKindDetails, CustomKindDetailsProps } from "./src/custom-kind-details"
|
||||
|
||||
export default class ExampleExtension extends LensRendererExtension {
|
||||
kubeObjectDetailItems = [
|
||||
{
|
||||
kind: "CustomKind",
|
||||
apiVersions: ["custom.acme.org/v1"],
|
||||
components: {
|
||||
Details: (props: CustomKindDetailsProps) => <CustomKindDetails {...props} />
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.1 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 408 KiB |
@@ -0,0 +1,163 @@
|
||||
# Styling an Extension
|
||||
|
||||
Lens provides a set of global styles and UI components that can be used by any extension to preserve the look and feel of the application.
|
||||
|
||||
## Layout
|
||||
|
||||
For layout tasks, Lens uses the [flex.box](https://www.npmjs.com/package/flex.box) library which provides helpful class names to specify some of the [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox) properties.
|
||||
For example, consider the following HTML and its associated CSS properties:
|
||||
|
||||
```html
|
||||
<div className="flex column align-center"></div>
|
||||
```
|
||||
|
||||
```css
|
||||
div {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
}
|
||||
```
|
||||
|
||||
However, you are free to use any styling technique or framework you like, including [Emotion](https://github.com/emotion-js/emotion) or even plain CSS.
|
||||
|
||||
### Layout Variables
|
||||
|
||||
There is a set of CSS variables available for for basic layout needs.
|
||||
They are located inside `:root` and are defined in [app.scss](https://github.com/lensapp/lens/blob/master/src/renderer/components/app.scss):
|
||||
|
||||
```css
|
||||
--unit: 8px;
|
||||
--padding: var(--unit);
|
||||
--margin: var(--unit);
|
||||
--border-radius: 3px;
|
||||
```
|
||||
|
||||
These variables are intended to set consistent margins and paddings across components.
|
||||
For example:
|
||||
|
||||
```css
|
||||
.status {
|
||||
padding-left: calc(var(--padding) * 2);
|
||||
border-radius: var(--border-radius);
|
||||
}
|
||||
```
|
||||
|
||||
## Themes
|
||||
|
||||
Lens uses two built-in themes defined in [the themes directory](https://github.com/lensapp/lens/tree/master/src/renderer/themes) – one light and one dark.
|
||||
|
||||
### Theme Variables
|
||||
|
||||
When Lens is loaded, it transforms the selected theme's `json` file into a list of [CSS Custom Properties (CSS Variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
|
||||
This list then gets injected into the `:root` element so that any of the down-level components can use them.
|
||||

|
||||
|
||||
When the user changes the theme, the above process is repeated, and new CSS variables appear, replacing the previous ones.
|
||||
|
||||
If you want to preserve Lens's native look and feel, with respect to the lightness or darkness of your extension, you can use the provided variables and built-in Lens components such as `Button`, `Select`, `Table`, and so on.
|
||||
|
||||
There is a set of CSS variables available for extensions to use for theming.
|
||||
They are all located inside `:root` and are defined in [app.scss](https://github.com/lensapp/lens/blob/master/src/renderer/components/app.scss):
|
||||
|
||||
```css
|
||||
--font-main: 'Roboto', 'Helvetica', 'Arial', sans-serif;
|
||||
--font-monospace: Lucida Console, Monaco, Consolas, monospace;
|
||||
--font-size-small: calc(1.5 * var(--unit));
|
||||
--font-size: calc(1.75 * var(--unit));
|
||||
--font-size-big: calc(2 * var(--unit));
|
||||
--font-weight-thin: 300;
|
||||
--font-weight-normal: 400;
|
||||
--font-weight-bold: 500;
|
||||
```
|
||||
|
||||
as well as in [the theme modules](https://github.com/lensapp/lens/tree/master/src/renderer/themes):
|
||||
|
||||
```
|
||||
--blue: #3d90ce;
|
||||
--magenta: #c93dce;
|
||||
--golden: #ffc63d;
|
||||
--halfGray: #87909c80;
|
||||
--primary: #3d90ce;
|
||||
--textColorPrimary: #555555;
|
||||
--textColorSecondary: #51575d;
|
||||
--textColorAccent: #333333;
|
||||
--borderColor: #c9cfd3;
|
||||
--borderFaintColor: #dfdfdf;
|
||||
--mainBackground: #f1f1f1;
|
||||
--contentColor: #ffffff;
|
||||
--layoutBackground: #e8e8e8;
|
||||
--layoutTabsBackground: #f8f8f8;
|
||||
--layoutTabsActiveColor: #333333;
|
||||
--layoutTabsLineColor: #87909c80;
|
||||
...
|
||||
```
|
||||
|
||||
These variables can be used in the following form: `var(--magenta)`.
|
||||
For example:
|
||||
|
||||
```css
|
||||
.status {
|
||||
font-size: var(--font-size-small);
|
||||
background-color: var(--colorSuccess);
|
||||
}
|
||||
```
|
||||
|
||||
### Theme Switching
|
||||
|
||||
When the light theme is active, the `<body>` element gets a "theme-light" class, or: `<body class="theme-light">`.
|
||||
If the class isn't there, the theme defaults to dark. The active theme can be changed in the **Preferences** page:
|
||||

|
||||
|
||||
There is a way of detect active theme and its changes in JS. [MobX observer function/decorator](https://github.com/mobxjs/mobx-react#observercomponent) can be used for this purpose.
|
||||
|
||||
```js
|
||||
import React from "react"
|
||||
import { observer } from "mobx-react"
|
||||
import { App, Component, Theme } from "@k8slens/extensions";
|
||||
|
||||
@observer
|
||||
export class SupportPage extends React.Component {
|
||||
render() {
|
||||
return (
|
||||
<div className="SupportPage">
|
||||
<h1>Active theme is {Theme.getActiveTheme().name}</h1>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`Theme` entity from `@k8slens/extensions` provides active theme object and `@observer` decorator makes component reactive - so it will rerender each time any of the observables (active theme in our case) will be changed.
|
||||
|
||||
Working example provided in [Styling with Emotion](https://github.com/lensapp/lens-extension-samples/tree/master/styling-emotion-sample) sample extension.
|
||||
|
||||
## Injected Styles
|
||||
|
||||
Every extension is affected by the list of default global styles defined in [app.scss](https://github.com/lensapp/lens/blob/master/src/renderer/components/app.scss). These are basic browser resets and element styles, including:
|
||||
|
||||
- setting the `box-sizing` property for every element
|
||||
- default text and background colors
|
||||
- default font sizes
|
||||
- basic heading (h1, h2, etc) formatting
|
||||
- custom scrollbar styling
|
||||
|
||||
Extensions may overwrite these defaults if needed. They have low CSS specificity, so overriding them should be fairly easy.
|
||||
|
||||
## CSS-in-JS
|
||||
|
||||
If an extension uses a system like `Emotion` to work with styles, it can use CSS variables as follows:
|
||||
|
||||
```javascript
|
||||
const Container = styled.div(() => ({
|
||||
backgroundColor: 'var(--mainBackground)'
|
||||
}));
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
You can explore samples for each styling technique that you can use for extensions:
|
||||
|
||||
- [Styling with Sass](https://github.com/lensapp/lens-extension-samples/tree/master/styling-sass-sample)
|
||||
- [Styling with Emotion](https://github.com/lensapp/lens-extension-samples/tree/master/styling-emotion-sample)
|
||||
- [Styling with CSS Modules](https://github.com/lensapp/lens-extension-samples/tree/master/styling-css-modules-sample)
|
||||
Reference in new issue
Block a user