<commit_before># Getting Started Guide

This guide will cover the following steps to get you up and running with the VS Code Webview Toolkit.

1. Create a webview-based extension.
2. Install and set up the toolkit.

## 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 VS Code [Your First Extension Guide](https://code.visualstudio.com/api/get-started/your-first-extension).

To generate a basic extension we can use [Yeoman](https://yeoman.io/) and the [VS 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:

```bash
npm install -g yo generator-code
```

The generator scaffolds a TypeScript or JavaScript project ready for development. Run the generator and fill out a few fields for a TypeScript project:

```bash
yo code

# ? What type of extension do you want to create? New Extension (TypeScript)
# ? What's the name of your extension? helloworld
### Press <Enter> to choose default for all options below ###

# ? What's the identifier of your extension? helloworld
# ? What's the description of your extension? LEAVE BLANK
# ? Initialize a git repository? Yes
# ? Bundle the source code with webpack? No
# ? Which package manager to use? npm

code ./helloworld
```

### Create A Webview

With this basic extension created, we now need to create a webview. The following steps are an adapted version of the steps provided in the [Webview API Guide](https://code.visualstudio.com/api/extension-guides/webview)––for more information about Webviews visit 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:

```typescript
export function activate(context: vscode.ExtensionContext) {
	let panel: vscode.WebviewPanel | undefined;

	const startCommand = vscode.commands.registerCommand("helloworld.helloWorld", () => {
		if (panel) {
			// If the webview panel already exists reveal it
			panel.reveal(vscode.ViewColumn.One);
		} else {
			// If a webview panel does not already exist create and show a new one
			panel = vscode.window.createWebviewPanel("helloworld", "Hello World", vscode.ViewColumn.One, {
				enableScripts: true,
			});

			// Set the HTML content for the new webview panel
			panel.webview.html = getWebviewContent();
		}
	});

	context.subscriptions.push(startCommand);
}
```

At this point you'll probably have noticed that there is an error because `getWebviewContent` is an undefined function, so let's fix that! Scroll to the bottom of the file and include the following:

```typescript
function getWebviewContent() {
	return `
		<!DOCTYPE html>
		<html lang="en">
			<head>
				<meta charset="UTF-8">
				<meta name="viewport" content="width=device-width, initial-scale=1.0">
				<title>Hello World!</title>
			</head>
			<body>
				<h1>Hello World!</h1>
			</body>
		</html>
	`;
}
```

### Test That It All Works

Congratulations! You have 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.

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/webview-test.gif)

## Install & Set Up The Toolkit

With an extension created, we can now install the toolkit with the following command.

```bash
npm install --save @microsoft/vscode-webview-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` content function we defined earlier to accept two new parameters.

```typescript
function getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) {
	// ... Implementation details should be left unchanged for now ...
}

// ❗️ Also update the getWebviewContent function call inside of the activate function. ❗️
export function activate(context: vscode.ExtensionContext) {
	// ... Other code ...

	panel.webview.html = getWebviewContent(panel.webview, context.extensionUri);

	// ... Other code ...
}
```

### Create A Toolkit URI

With those changes we can now use some VS 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.

```typescript
function getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) {
	const toolkitUri = getUri(webview, extensionUri, ["node_modules", "vscode-webview-toolkit", "dist", "toolkit.js"]);

	// ... Other implementation details should be left unchanged for now ...
}

function getUri(webview: vscode.Webview, extensionUri: vscode.Uri, pathList: string[]) {
	return webview.asWebviewUri(vscode.Uri.joinPath(extensionUri, ...pathList));
}
```

### Pass The URI Into The Webview

With access to the toolkit URI we can pass it into our webview context via a regular `<script>` tag like so:

```typescript
function getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) {
	const toolkitUri = getUri(webview, extensionUri, ["node_modules", "vscode-webview-toolkit", "dist", "toolkit.js"]);

	return `
		<!DOCTYPE html>
		<html lang="en">
			<head>
				<meta charset="UTF-8">
				<meta name="viewport" content="width=device-width, initial-scale=1.0">
				<script type="module" src="${toolkitUri}"></script>
				<title>Hello World!</title>
			</head>
			<body>
				<h1>Hello World!</h1>
			</body>
		</html>
	`;
}
```

### Test That It All Works

Let's check that everything works by adding some toolkit components to the webview and then opening the extension in the Extension Development Host window by pressing `F5`.

_Note that all toolkit components must be a child of the `<vscode-design-system-provider>` element with the `use-defaults` attribute set._

```typescript
function getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) {
	const toolkitUri = getUri(webview, extensionUri, ["node_modules", "vscode-webview-toolkit", "dist", "toolkit.js"]);

	return `
		<!DOCTYPE html>
		<html lang="en">
			<head>
				<meta charset="UTF-8">
				<meta name="viewport" content="width=device-width, initial-scale=1.0">
				<script type="module" src="${toolkitUri}"></script>
				<title>Hello World!</title>
			</head>
			<body>
				<h1>Hello World!</h1>
				<vscode-design-system-provider use-defaults>
					<vscode-button>Howdy!</vscode-button>
				</vscode-design-system-provider>
			</body>
		</html>
	`;
}
```

![Testing That The Toolkit Works](./assets/toolkit-button-test.gif)

Finally, component theming is built right into the components so feel free to test that out too!

Open the Command Pallette (`Crtl + Shift + P` or `Cmd + Shift + P` on Mac), search for "Preferences: Color Theme", and cycle through all the themes to see the components change!

![Testing That The Toolkit Theme Utilities Work](./assets/toolkit-theme-test.gif)

## Next Steps<commit_msg>Update Getting Started Guide (#89)<commit_after># Getting Started Guide

This guide will cover the following steps to get you up and running with the VS Code Webview Toolkit.

1. Create a webview-based extension.
2. Install and set up the toolkit.

## 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 VS Code [Your First Extension Guide](https://code.visualstudio.com/api/get-started/your-first-extension).

To generate a basic extension we can use [Yeoman](https://yeoman.io/) and the [VS 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:

```bash
npm install -g yo generator-code
```

The generator scaffolds a TypeScript or JavaScript project ready for development. Run the generator and fill out a few fields for a TypeScript project:

```bash
yo code

# ? What type of extension do you want to create? New Extension (TypeScript)
# ? What's the name of your extension? helloworld
### Press <Enter> to choose default for all options below ###

# ? What's the identifier of your extension? helloworld
# ? What's the description of your extension? LEAVE BLANK
# ? Initialize a git repository? Yes
# ? Bundle the source code with webpack? No
# ? Which package manager to use? npm

code ./helloworld
```

### Create A Webview

With this basic extension created, we now need to create a webview. The following steps are an adapted version of the steps provided in the [Webview API Guide](https://code.visualstudio.com/api/extension-guides/webview)––for more information about Webviews visit 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:

```typescript
export function activate(context: vscode.ExtensionContext) {
	let panel: vscode.WebviewPanel | undefined;

	const startCommand = vscode.commands.registerCommand("helloworld.helloWorld", () => {
		if (panel) {
			// If the webview panel already exists reveal it
			panel.reveal(vscode.ViewColumn.One);
		} else {
			// If a webview panel does not already exist create and show a new one
			panel = vscode.window.createWebviewPanel("helloworld", "Hello World", vscode.ViewColumn.One, {
				enableScripts: true,
			});

			// Set the HTML content for the new webview panel
			panel.webview.html = getWebviewContent();
		}
	});

	context.subscriptions.push(startCommand);
}
```

At this point you'll probably have noticed that there is an error because `getWebviewContent` is an undefined function, so let's fix that! Scroll to the bottom of the file and include the following:

```typescript
function getWebviewContent() {
	return `
		<!DOCTYPE html>
		<html lang="en">
			<head>
				<meta charset="UTF-8">
				<meta name="viewport" content="width=device-width, initial-scale=1.0">
				<title>Hello World!</title>
			</head>
			<body>
				<h1>Hello World!</h1>
			</body>
		</html>
	`;
}
```

### Test That It All Works

Congratulations! You have 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.

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/webview-test.gif)

## Install & Set Up The Toolkit

With an extension created, we can now install the toolkit with the following command.

```bash
npm install --save @microsoft/vscode-webview-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` content function we defined earlier to accept two new parameters.

```typescript
function getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) {
	// ... Implementation details should be left unchanged for now ...
}

// ❗️ Also update the getWebviewContent function call inside of the activate function. ❗️
export function activate(context: vscode.ExtensionContext) {
	// ... Other code ...

	panel.webview.html = getWebviewContent(panel.webview, context.extensionUri);

	// ... Other code ...
}
```

### Create A Toolkit URI

With those changes we can now use some VS 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.

```typescript
function getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) {
	const toolkitUri = getUri(webview, extensionUri, ["node_modules", "vscode-webview-toolkit", "dist", "toolkit.js"]);

	// ... Other implementation details should be left unchanged for now ...
}

function getUri(webview: vscode.Webview, extensionUri: vscode.Uri, pathList: string[]) {
	return webview.asWebviewUri(vscode.Uri.joinPath(extensionUri, ...pathList));
}
```

### Pass The URI Into The Webview

With access to the toolkit URI we can pass it into our webview context via a regular `<script>` tag like so:

```typescript
function getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) {
	const toolkitUri = getUri(webview, extensionUri, ["node_modules", "vscode-webview-toolkit", "dist", "toolkit.js"]);

	return `
		<!DOCTYPE html>
		<html lang="en">
			<head>
				<meta charset="UTF-8">
				<meta name="viewport" content="width=device-width, initial-scale=1.0">
				<script type="module" src="${toolkitUri}"></script>
				<title>Hello World!</title>
			</head>
			<body>
				<h1>Hello World!</h1>
			</body>
		</html>
	`;
}
```

### Test That It All Works

Let's check that everything works by adding a `<vscode-button>` to the webview and then opening the extension in the Extension Development Host window by pressing `F5`.

```typescript
function getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri) {
	const toolkitUri = getUri(webview, extensionUri, ["node_modules", "vscode-webview-toolkit", "dist", "toolkit.js"]);

	return `
		<!DOCTYPE html>
		<html lang="en">
			<head>
				<meta charset="UTF-8">
				<meta name="viewport" content="width=device-width, initial-scale=1.0">
				<script type="module" src="${toolkitUri}"></script>
				<title>Hello World!</title>
			</head>
			<body>
				<h1>Hello World!</h1>
				<vscode-button>Howdy!</vscode-button>
			</body>
		</html>
	`;
}
```

![Testing That The Toolkit Works](./assets/toolkit-button-test.gif)

Finally, component theming is built right into the components so feel free to test that out too!

Open the Command Pallette (`Crtl + Shift + P` or `Cmd + Shift + P` on Mac), search for "Preferences: Color Theme", and cycle through all the themes to see the components change!

![Testing That The Toolkit Theme Utilities Work](./assets/toolkit-theme-test.gif)

## Next Steps
{'fraction_non_alphanumeric': 0.11032831737346101, 'fraction_numerical': 0.0027359781121751026, 'mean_word_length': 4.318661331393234, 'pattern_counts': {'":': 0, '<': 101, '<?xml version=': 0, '>': 103, 'https://': 12, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3674932', 'n_tokens_mistral': 4635, 'n_tokens_neox': 4248, 'n_words': 1675}