hendrik/lens
1
0 Fork 0
mirror of https://github.com/lensapp/lens.git synced 2025-05-20 05:10:56 +00:00
Code Issues Projects Releases Wiki Activity

Resolved conflicts in Your First Extension, Styling, and Color Reference after rebasing from master (#1379)

Browse Source 
Signed-off-by: Paul Williams <pawilliams@mirantis.com>
This commit is contained in:
pauljwil authored and GitHub committed 2020-11-16 11:14:33 +02:00
1 parent f98d11a0be
commit 656797abc7
13 files changed
+90 -95
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/extensions/get-started/anatomy.md
+17 -16
View File
@@ -1,14 +1,14 @@
# Extension Anatomy
You've now learnt how to get basic extension running. In this topic you will learn some fundamental concepts to Lens Extension development; How does it work under the hood?
In the [previous section](your-first-extension.md) you learned how to create your first extension. In this section you will learn how this extension works under the hood.
`Hello World` extension does three things:
The Hello World sample extension does three things:
- Hooks on `onActivate()` and ouputs message into console.
- Hooks on `onDectivate()` and ouputs message into console.
- Registers `ClusterPage` so that page is visible in the sidebars of cluster dashboards.
- Implements `onActivate()` and outputs a message to the console.
- Implements `onDectivate()` and outputs a message to the console.
- Registers `ClusterPage` so that the page is visible in the left-side menu of the cluster dashboard.
Let's take a closer look at Hello World sample's source code and see how to achieve these things.
Let's take a closer look at our Hello World sample's source code and see how these three things are achieved.
## Extension File Structure
@@ -26,16 +26,16 @@ Let's take a closer look at Hello World sample's source code and see how to achi
├── webpack.config.js // Webpack configuration
```
Extension directory contains extension's entry files and few configuration files. Let's focus on `package.json`, `main.ts` and `renderer.tsx` which are essential to understanding the `Hello World` extension.
The extension directory contains the extension's entry files and a few configuration files. Three files: `package.json`, `main.ts` and `renderer.tsx` are essential to understanding the Hello World sample extension. We'll look at those first.
### Extension Manifest
Each Lens extension must have `package.json`. The `package.json` contains a mix of Node.js fields such as scripts and dependencies and Lens specific fields such as `publisher` and `contributes`. Here are some most important fields:
Each Lens extension must have a `package.json` file. It contains a mix of Node.js fields, including scripts and dependencies, and Lens-specific fields such as `publisher` and `contributes`. Some of the most-important fields include:
- `name` and `publisher`: Lens uses `@<publisher>/<name>` as a unique ID for the extension. For example, the Hello World sample has the ID `@lensapp-samples/helloworld-sample`. Lens uses the ID to uniquely identify your extension
- `main`: The extension's entry point run in `main` process.
- `renderer`: The extension's entry point run in `renderer` process.
- `engines.lens`: This specifies the minimum version of Lens API that the extension depends on.
- `name` and `publisher`: Lens uses `@<publisher>/<name>` as a unique ID for the extension. For example, the Hello World sample has the ID `@lensapp-samples/helloworld-sample`. Lens uses this ID to uniquely identify your extension.
- `main`: the extension's entry point run in `main` process.
- `renderer`: the extension's entry point run in `renderer` process.
- `engines.lens`: the minimum version of Lens API that the extension depends upon.
``` javascript
{
@@ -70,11 +70,12 @@ Each Lens extension must have `package.json`. The `package.json` contains a mix
```
## Extension Entry Files
Lens extensions can have two separate entry files. One file that is used in `main` process of Lens application and antoher that is used in `renderer` process. `main` entry file should export class that extends `LensMainExtension` and `renderer` entry file should export class that extends `LensRendererExtension`.
Both extensions classes have `onActivate` and `onDeactivate` methods. `onActivate` is executed when your extension activation happens. You may want to initialize something in your extension at this point. `onDeactivate` gives you a chance to clean up before your extension becomes deactivated. For many extensions, explicit cleanup may not be required, and you don't need to override this method. However, if an extension needs to perform an operation when Lens is shutting down or the extension is disabled or uninstalled, this is the method to do so.
Lens extensions can have two separate entry files. One file is used in the `main` process of the Lens application and the other is used in the `renderer` process. The `main` entry file exports the class that extends `LensMainExtension`, and the `renderer` entry file exports the class that extends `LensRendererExtension`.
`Hello world` extension does not do anything special on `main` process, so let's focus on the `renderer` side. On `renderer` entry point, `Hello world` extension defines one `Cluster Page` object that registers `/extension-example` path that renders `ExamplePage` React component. It registers also `MenuItem` component that displays `ExampleIcon` React component and "Hello World" text in the sidebar of cluster dashboards. These React components are defined in additional `./src/page.tsx` file.
Both extension classes have `onActivate` and `onDeactivate` methods. The `onActivate` method is executed when your extension is activated. If you need to initialize something in your extension, this is where such an operation should occur. The `onDeactivate` method gives you a chance to clean up before your extension becomes deactivated. For extensions where explicit cleanup is not required, you don't need to override this method. However, if an extension needs to perform an operation when Lens is shutting down (or if the extension is disabled or uninstalled), this is the method where such an operation should occur.
The Hello World sample extension does not do anything on the `main` process, so we'll focus on the `renderer` process, instead. On the `renderer` entry point, the Hello World sample extension defines the `Cluster Page` object. The `Cluster Page` object registers the `/extension-example` path, and this path renders the `ExamplePage` React component. It also registers the `MenuItem` component that displays the `ExampleIcon` React component and the "Hello World" text in the left-side menu of the cluster dashboard. These React components are defined in the additional `./src/page.tsx` file.
``` typescript
import { LensRendererExtension } from "@k8slens/extensions";
@@ -93,4 +94,4 @@ export default class ExampleExtension extends LensRendererExtension {
}
```
`Hello World` extension uses only one capability (`Cluster Page`) of Lens extensions. The [Extension Capabilities Overview](/extensions/capabilities/) topic helps you find the right capabilities you can use with your own extension.
The Hello World sample extension uses the `Cluster Page` capability, which is just one of the Lens extension API's capabilities. The [Common Capabilities](../capabilities/common-capabilities.md) page will help you home in on the right capabilities to use with your own extensions.
docs/extensions/get-started/overview.md
+6 -7
View File
@@ -1,20 +1,19 @@
# Extension Development Overview
This is a general overview to how the development of an extension will procede. For building extensions there will be a few things that you should have installed, and some that might help.
This is a general overview to how the development of an extension will procede. For building extensions there will be a few things that you should have installed, and some other things that might be of help.
### Required:
- [Node.js](https://www.nodejs.org/en/)
- [Git](https://www.git-scm.com/)
- Some sort of text editor, we recommend [VSCode](https://code.visualstudio.com/)
- Some sort of text editor – we recommend [VSCode](https://code.visualstudio.com/)
- We use [Webpack](https://www.webpack.js.org/) for compilation. All extension need to be at least compatable with a webpack system.
### Recommened:
-
### Recommended:
All *Lens* extensions are javascript packages. We recommend that you program in [Typescript](https://www.typescriptlang.org/) because it catches quite a few easily to make errors around passing data around in javascript.
All Lens extensions are javascript packages. We recommend that you program in [Typescript](https://www.typescriptlang.org/) because it catches many common errors.
*Lens* is a standard [Electron](https://www.electronjs.org/) application which both main and renderer processes. An extension is made up of two parts, one for each of *Lens*'s core processes. When an extension is loaded each part is loaded and then notified that it has been loaded. From there the extension can start doing is work.
Lens is a standard [Electron](https://www.electronjs.org/) application with both main and renderer processes. An extension is made up of two parts, one for each of Lens's core processes. When an extension is loaded, each part is first loaded and issues a notification that it has been loaded. From there, the extension can start doing is work.
*Lens* uses [React](https://www.reactjs.org/) as it UI framework and even provides some of our own components for reuse by extensions. An extension is resonsible for the lifetime of any resources it spins up. If an extension's main part starts new processes they all must be stopped and cleaned up when the extension is deactivated or unloaded.
Lens uses [React](https://www.reactjs.org/) as its UI framework and provides some of Lens's own components for reuse with extensions. An extension is resonsible for the lifetime of any resources it spins up. If an extension's main part starts new processes they all must be stopped and cleaned up when the extension is deactivated or unloaded.
See [Your First Extension](your-first-extension.md) to get started.
docs/extensions/get-started/wrapping-up.md
+6 -6
View File
@@ -1,18 +1,18 @@
# Wrapping Up
In the [Your First Extension](your-first-extension.md) topic, you learned how to create and run an extension. In the [Extension Anatomy](anatomy.md) topic, you learned fundamental concepts to Lens extension development. However, this is just a small glimpse of what can be created with Lens Extensions. Below are some suggested routes for furthering your Lens extension development skills.
In [Your First Extension](your-first-extension.md), you learned how to create and run an extension. In [Extension Anatomy](anatomy.md), you learned in detail how a basic extension works. This is just a glimpse into what can be created with Lens extensions. Below are some suggested routes for learning more.
## Extension Capabilities
In this section, we split the Lens extension points into a few categories, each with short descriptions as to what your extension could achieve. Validate that your extension idea is achievable by reading the [Extension Capabilities](../capabilities/overview.md) section for new extension ideas.
In this section, you'll find information on common extension capabilities, styling information, and a color reference guide. Determine whether your idea for an extension is doable and get ideas for new extensions by reading through the [Common Capabilities](../capabilities/common-capabilities.md) page.
## Guides & Samples
## Guides and Samples
We have a great collection of sample extensions that you can adapt from, and some of them include a detailed guide that explains the source code. You can find all Samples & Guides in the [lens-extension-samples](https://github.com/lensapp/lens-extension-samples) repository.
Here you'll find a collection of sample extensions that you can use as a base to work from. Some of these samples include a detailed guide that explains the source code. You can find all samples and guides in the [lens-extension-samples](https://github.com/lensapp/lens-extension-samples) repository.
## Testing and Publishing
This section includes topics that help you develop high-quality Lens extensions. For example, you can learn
In this section, you can learn:
* How to add [integration tests](../testing-and-publishing/testing.md) for your extension
* How to add [integration tests](../testing-and-publishing/testing.md) to your extension
* How to [publish your extension](../testing-and-publishing/publishing.md)
docs/extensions/get-started/your-first-extension.md
+26 -26
View File
@@ -1,38 +1,35 @@
# Your First Extension
In this topic, we'll teach you the fundamental concepts for building extensions.
In this topic, you'll learn the basics of building extensions by creating an extension that adds a "Hello World" page to a cluster menu.
## Installing and Building the extension
## Install the Extension
Simple Lens extension that adds "Hello World" page to a cluster menu.
### Setup the extension directory
First you will need to clone the [Lens Extension samples](https://github.com/lensapp/lens-extension-samples) repository to your local machine:
To install the extension, clone the [Lens Extension samples](https://github.com/lensapp/lens-extension-samples) repository to your local machine:
```sh
git clone https://github.com/lensapp/lens-extension-samples.git
```
Next you need to create a symlink from the directory that Lens will monitor for user installed extensions to the sample extension, in this case **helloworld-sample**:
Next you need to create a symlink. A symlink connects the directory that Lens will monitor for user-installed extensions to the sample extension. In this case the sample extension is `helloworld-sample`.
### Linux & macOS
**Linux & MacOS**
```sh
mkdir -p ~/.k8slens/extensions
cd ~/.k8slens/extensions
ln -s lens-extension-samples/helloworld-sample helloworld-sample
```
**Windows**
### Windows
Create the directory that Lens will monitor for user installed extensions:
Create the directory that Lens will monitor for user-installed extensions:
```sh
mkdir C:\Users\<user>\.k8slens\extensions -force
cd C:\Users\<user>\.k8slens\extensions
```
If you have administrator rights, you can create symlink to the sample extension, in this case **helloworld-sample**:
If you have administrator rights, you can create symlink to the sample extension – in this case `helloworld-sample`:
```sh
cmd /c mklink /D helloworld-sample lens-extension-samples\helloworld-sample
@@ -44,7 +41,7 @@ Without administrator rights, you need to copy the extensions sample directory i
Copy-Item 'lens-extension-samples\helloworld-sample' 'C:\Users\<user>\.k8slens\extensions\helloworld-sample'
```
### Build the extension
## Build the Extension
To build the extension you can use `make` or run the `npm` commands manually:
@@ -53,7 +50,7 @@ cd <lens-extension-samples directory>/helloworld-sample
make build
```
OR
To run the `npm` commands, enter:
```sh
cd <lens-extension-samples directory>/helloworld-sample
@@ -61,27 +58,30 @@ npm install
npm run build
```
If you want to watch for any source code changes and automatically rebuild the extension you can use:
Optionally, automatically rebuild the extension by watching for changes to the source code. To do so, enter:
```sh
cd <lens-extension-samples directory>/helloworld-sample
npm run dev
```
Finally, if you already have Lens open you will need to quit and restart Lens for the extension to be loaded. After this initial restart you can reload Lens and it will pick up any new builds of the extension. Within Lens connect to an existing cluster or [create a new one](../../clusters/adding-clusters.md). You should see then see the "Hello World" page in the Lens sidebar cluster menu.
You must restart Lens for the extension to load. After this initial restart, reload Lens and it will automatically pick up changes any time the extension rebuilds.
## Developing the extension
With Lens running, either connect to an existing cluster or [create a new one](../../clusters/adding-clusters.md). You will see the "Hello World" page in the left-side cluster menu.
Let's make a change to the message that our helloworld-sample extension displays:
## Develop the Extension
* Navigate to `<lens-extension-samples directory>/helloworld-sample`.
* Change the message from HelloWorld! to **Hello Lens Extensions** in `page.tsx`.
* Rebuild the extension or, if you used `npm run dev`, the extension should automatically rebuild.
* Reload the Lens window and click on the Hello World page.
* You should see the updated message showing up.
Finally, you'll make a change to the message that our Hello World sample extension displays:
## Next steps
1. Navigate to `<lens-extension-samples directory>/helloworld-sample`.
2. In `page.tsx`, change the message from `HelloWorld!` to `Hello Lens Extensions`.
3. Rebuild the extension. If you used `npm run dev`, the extension will rebuild automatically.
4. Reload the Lens window.
5. Click on the Hello World page.
6. The updated message will appear.
In the next topic, [Extension Anatomy](anatomy.md), we'll take a closer look at the source code of the Hello World sample and explain key concepts.
## Next Steps
You can find the source code of this tutorial at: [lensapp/lens-extension-samples](https://github.com/lensapp/lens-extension-samples/tree/master/helloworld-sample). The [Extension Guides](../guides/overview.md) topic contains other samples, each illustrating a different Lens Extension API.
In the [next topic](anatomy.md), we'll take a closer look at the source code of our Hello World sample.
You can find the source code for this tutorial at: [lensapp/lens-extension-samples](https://github.com/lensapp/lens-extension-samples/tree/master/helloworld-sample). [Extension Guides](../guides/README.md) contains additional samples.