From 10465a5b0b4730fb56044d7777734eb5de3117dc Mon Sep 17 00:00:00 2001 From: Hawk Ticehurst Date: Tue, 5 Apr 2022 12:59:11 -0700 Subject: [PATCH 1/2] Update README based on string review feedback --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 9ae04fd0..25c78645 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,12 @@ The Webview UI Toolkit is a component library for building [webview-based extensions](https://code.visualstudio.com/api/extension-guides/webview) in Visual Studio Code. -Features of the library include: +Some of the library's features include: -- **Implements the Visual Studio Code design language:** All components follow the design language of Visual Studio Code – enabling developers to create extensions that have a consistent look and feel with the rest of the editor. -- **Automatic support for color themes:** All components are designed with theming in mind and will automatically display the current editor theme. -- **Use any tech stack:** The library ships as a set of web components, meaning developers can use the toolkit no matter what tech stack (React, Vue, Svelte, etc.) their extension is built with. -- **Accessible out of the box:** All components ship with web standard compliant ARIA labels and keyboard navigation. +- **Visual Studio Code design language:** All components follow the design language of Visual Studio Code, which enables developers to create extensions that have a consistent look and feel with the rest of the editor. +- **Automatic support for color themes:** All components are designed with theming in mind, and will automatically display the current editor theme. +- **Tech stacks:** The library ships as a set of web components. This means developers can use the toolkit no matter which tech stack – React, Vue, Svelte, etc. – their extension is built with. +- **Immediate accessibility:** All components ship with web-standard compliant ARIA labels and keyboard navigation. ## Getting started @@ -31,7 +31,7 @@ npm install --save @vscode/webview-ui-toolkit ## Documentation -Further documentation can be found in the following places: +For more information, check out the following documentation: - [Component Docs](./docs/components.md) - [Toolkit Extension Samples](https://github.com/microsoft/vscode-webview-ui-toolkit-samples) @@ -43,15 +43,15 @@ Further documentation can be found in the following places: ## A note on webview usage -Webviews are a powerful way to add custom functionality that is beyond what the VS Code API supports. They are fully customizable, which has historically meant that the responsibility of developing UI that aligns with the VS Code design language and follows our [webview guidelines](https://code.visualstudio.com/api/references/extension-guidelines#webviews) lies in the hands of extension authors. +Webviews are a powerful way to add custom functionality beyond what the Visual Studio Code API supports. They're fully customizable, which, historically, has meant that the responsibility of developing UI which aligns with the Visual Studio Code design language and follows our [webview guidelines](https://code.visualstudio.com/api/references/extension-guidelines#webviews) lies in the hands of extension authors. -The Webview UI Toolkit shifts _some_ of this responsibility away from extension developers by providing core components that make it easier to build higher quality webview UIs in VS Code. +The Webview UI Toolkit shifts _some_ of this responsibility away from extension developers. It does this by providing core components that make it easier to build higher quality webview UIs in Visual Studio Code. -With all this said, we still strongly encourage a careful review of whether your extension needs to use webviews or not before building. While webviews provide a great way to add custom functionality it often comes at the cost of performance and accessibility. +With all this said, we still strongly encourage you to carefully review whether or not your extension needs to use webviews before building. While webviews provide a great way to add custom functionality, oftentimes, they come at the cost of performance and accessibility. -The core VS Code API provides a vast array of building blocks for highly performant, accessible, and tighly integrated extension experiences and we will generally encourage their usage before webviews. If you haven't already, feel free to check out this [overview of API capabilities](https://code.visualstudio.com/api/extension-capabilities/overview) to get an idea of what's possible. +The core Visual Studio Code API provides a vast array of building blocks for highly performant, accessible, and tightly integrated extension experiences. Generally, we encourage you to use them before webviews. If you haven't already, check out this [overview of API capabilities](https://code.visualstudio.com/api/extension-capabilities/overview) to get an idea of what's possible. -Finally, if you are ever unsure if your extension should make use of webviews or not, please open an issue and we would be more than happy to give some feedback and guidance. +Finally, if you're ever unsure if your extension should use webviews or not, you should open an issue and we'll give you some feedback and guidance. ## Release @@ -59,7 +59,7 @@ The Webview UI Toolkit is currently in a public preview with the goal of reachin ## Contributing -See the [contributing](./CONTRIBUTING.md) documentation. +Read the [contributing](./CONTRIBUTING.md) documentation. ## Legal notices From aab76ebac8e7f9cad06beda8039a37e3d698eaf8 Mon Sep 17 00:00:00 2001 From: Hawk Ticehurst Date: Tue, 5 Apr 2022 13:39:28 -0700 Subject: [PATCH 2/2] Update getting started guide based on string review feedback --- docs/getting-started.md | 82 ++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 42 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index c3dfe100..e0a2c29e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,13 +6,13 @@ This guide will cover the following steps to get you up and running with the Web 2. Install and set up the toolkit 3. Set up message passing between the extension and webview -_If you get stuck at any point (or just want a pre-configured starter extension template), feel free to install our [completed hello world sample extension](https://github.com/microsoft/vscode-webview-ui-toolkit-samples/tree/main/default/hello-world) based on this guide._ +_If you get stuck at any point or if you just want a pre-configured starter extension template, install our [completed hello world sample extension](https://github.com/microsoft/vscode-webview-ui-toolkit-samples/tree/main/default/hello-world) based on this guide._ ## Part 1: Create a webview-based extension -Before installing the toolkit we need to create a webview-based extension to use the toolkit in. The following steps are taken directly from the Visual Studio Code [Your First Extension Guide](https://code.visualstudio.com/api/get-started/your-first-extension) and [Webview API Guide](https://code.visualstudio.com/api/extension-guides/webview). +Before installing the toolkit, you need to create a webview-based extension to use the toolkit in. The following steps are taken directly from the Visual Studio Code [Your First Extension](https://code.visualstudio.com/api/get-started/your-first-extension) guide and [Webview API](https://code.visualstudio.com/api/extension-guides/webview) guide. -To generate a basic extension we can use [Yeoman](https://yeoman.io/) and the [Visual Studio Code Extension Generator](https://www.npmjs.com/package/generator-code). Make sure you have [Node.js](https://nodejs.org/en/) and [Git](https://git-scm.com/) installed first, then install Yeoman and the generator using the following command: +To generate a basic extension, we can use [Yeoman](https://yeoman.io/) and the [Visual Studio Code Extension Generator](https://www.npmjs.com/package/generator-code). First, though, make sure you have [Node.js](https://nodejs.org/en/) and [Git](https://git-scm.com/) installed. Then, install Yeoman and the generator using the following command: ```bash npm install -g yo generator-code @@ -38,7 +38,7 @@ code ./hello-world ### Create a webview -With this basic extension created, we now need to create a webview. The following steps are an adapted version of those provided in the [Webview API Guide](https://code.visualstudio.com/api/extension-guides/webview)––for more information about webviews visit the guide. +With this basic extension created, you now need to create a webview. The following steps are an adapted version of those provided in the [Webview API](https://code.visualstudio.com/api/extension-guides/webview) guide – for more info about webviews, read the guide. Start by navigating to the `extensions.ts` file inside the `src` directory and replacing the contents of the `activate` function with the following: @@ -54,18 +54,18 @@ export function activate(context: vscode.ExtensionContext) { } ``` -At this point you'll probably have noticed that there is an error because `HelloWorldPanel` does not exist, so let's fix that! +At this point, you probably have noticed that there's an error because `HelloWorldPanel` doesn't exist. Here's how to fix that. ### Create a webview panel class Create a new directory/file at `src/panels/HelloWorldPanel.ts`. -Inside this file we're going to create a class that manages the state and behavior of Hello World webview panels. +Inside this file, create a class that manages the state and behavior of Hello World webview panels. -It will contain all the data and methods for: +It'll contain all the data and methods for: - Creating and rendering Hello World webview panels -- Properly cleaning up and disposing of webview resources when the panel is closed +- Properly cleaning up and disposing webview resources when the panel is closed - Setting the HTML content of the webview panel - Setting message listeners so data can be passed between the webview and extension @@ -91,7 +91,7 @@ export class HelloWorldPanel { **Render method** -We can now add the render method which will be responsible for rendering the current webview panel if it exists or creating and a displaying a new webview panel if it does not. +Now, add the render method. This will be responsible for rendering the current webview panel – if it exists – or creating and displaying a new webview panel. ```typescript // file: src/panels/HelloWorldPanel.ts @@ -113,7 +113,7 @@ export class HelloWorldPanel { } ``` -At this point we can also go back to the `src/extension.ts` file and add an import statement to resolve the error from earlier. +At this point, you can also go back to the `src/extension.ts` file and add an import statement to resolve the earlier error. ```typescript // file: src/extension.ts @@ -126,7 +126,7 @@ import { HelloWorldPanel } from "./panels/HelloWorldPanel"; **Dispose method** -Back in the `HelloWorldPanel` class we now need to define a `dispose` method so that webview resources are cleaned up when the webview panel is closed by the user or closed programmatically. +Back in the `HelloWorldPanel` class, you now need to define a `dispose` method so that webview resources are cleaned up when the webview panel is closed by the user or closed programmatically. ```typescript // file: src/panels/HelloWorldPanel.ts @@ -149,7 +149,7 @@ export class HelloWorldPanel { } ``` -With the `dispose` method defined we also need to update the constructor method by adding an `onDidDispose` event listener so the method can be triggered when the webview panel is closed. +With the `dispose` method defined, you also need to update the constructor method. To do this, add an `onDidDispose` event listener, so the method can be triggered when the webview panel is closed. ```typescript // file: src/panels/HelloWorldPanel.ts @@ -165,7 +165,7 @@ private constructor(panel: vscode.WebviewPanel) { The `_getWebviewContent` method is where the UI of the extension will be defined. -This is also the place where references to CSS and JavaScript files/packages are created and inserted into the webview HTML. We will configure the Webview UI Toolkit here, in the second part of this guide. +This is also where references to CSS and JavaScript files/packages are created and inserted into the webview HTML. You'll configure the Webview UI Toolkit here, in the second part of this guide. ```typescript // file: src/panels/HelloWorldPanel.ts @@ -192,7 +192,7 @@ export class HelloWorldPanel { } ``` -This is another point where we need to update our constructor method to set the HTML content for the webview panel. +This is another point in which you need to update the constructor method to set the HTML content for the webview panel. ```typescript // file: src/panels/HelloWorldPanel.ts @@ -206,21 +206,21 @@ private constructor(panel: vscode.WebviewPanel) { **Set message listener method** -We'll handle message passing in the third part of this guide. +Message passing is handled in the third part of this guide. -### Test that it all works +### Test that everything works -Congratulations! You have officially created a basic webview extension. +Congratulations! You officially created a basic webview extension. -To test that everything is working, inside the editor, press `F5`. This will compile and run the extension in a new Extension Development Host window. +Inside the editor, press `F5` to test that everything is working. This will compile and run the extension in a new Extension Development Host window. -When the host window opens, open the Command Palette (`Crtl + Shift + P` or `Cmd + Shift + P` on Mac), type "Hello World", and click `enter` to run the command which should display the webview panel. +When the host window opens, open the Command Palette (`Crtl + Shift + P` or `Cmd + Shift + P` on Mac), type "Hello World", and click `enter` to run the command – which should display the webview panel. ![Testing That The Webview Extension Works](./assets/images/webview-test.gif) ## Part 2: Install and set up the toolkit -With an extension created, we can now install the toolkit package using this command. +With an extension created, install the toolkit package using this command: ``` npm install --save @vscode/webview-ui-toolkit @@ -228,7 +228,7 @@ npm install --save @vscode/webview-ui-toolkit ### Using the toolkit inside a webview -With the package installed, we need to adjust the project so the toolkit is usable within our webview. We'll start by updating the `_getWebviewContent` method to accept two new parameters. +With the package installed, you need to adjust the project so the toolkit is usable within your webview. To do this, start by updating the `_getWebviewContent` method to accept two new parameters. ```typescript // file: src/panels/HelloWorldPanel.ts @@ -238,7 +238,7 @@ private _getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) { } ``` -With this change we also need to update the parameters of a few other methods and method calls. +With this change, you also need to update the parameters of a few other methods and method calls. Update the `constructor` method with the following: @@ -264,7 +264,7 @@ public static render(extensionUri: vscode.Uri) { } ``` -Finally update the call to the `render` method: +Finally, update the call to the `render` method: ```typescript // file: src/extension.ts @@ -274,7 +274,7 @@ HelloWorldPanel.render(context.extensionUri); ### Create a webview uri -With those changes we can now use some Visual Studio Code APIs to create a URI pointing to the toolkit package. These API calls can get a bit verbose, however, so we'll also create a small helper function to keep our code clean. +With those changes, you can now use some Visual Studio Code APIs to create a URI pointing to the toolkit package. Just a heads-up: These API calls can get a bit verbose, so you also need to create a small helper function to keep your code clean. Create a new file at `src/utilities/getUri.ts` with the following: @@ -288,7 +288,7 @@ export function getUri(webview: Webview, extensionUri: Uri, pathList: string[]) } ``` -We can use that helper function to get a webview URI which points to the toolkit package. +You can use that helper function to get a webview URI which points to the toolkit package. ```typescript // file: src/panels/HelloWorldPanel.ts @@ -312,7 +312,7 @@ private _getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) { ### Pass the uri into the webview -With access to the toolkit URI we can pass it into our webview context with a regular `