Skip to content

Commit 31b555b

Browse files
mikehoffmsmikehoffms
committed
vheading for each file
1 parent 31047f8 commit 31b555b

1 file changed

Lines changed: 94 additions & 49 deletions

File tree

‎microsoft-edge/extensions-chromium/developer-guide/devtools-extension.md‎

Lines changed: 94 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ ms.author: msedgedevrel
66
ms.topic: conceptual
77
ms.service: microsoft-edge
88
ms.subservice: extensions
9-
ms.date: 11/12/2024
9+
ms.date: 11/18/2024
1010
---
1111
# Create a DevTools extension, adding a custom tool tab and panel
1212

@@ -71,45 +71,55 @@ You downloaded, installed, ran, and tested the provided, finished DevTools exten
7171

7272

7373
<!-- ====================================================================== -->
74-
## Step 1: Create a basic Microsoft Edge extension
74+
## Step 1: Create a basic Microsoft Edge extension that has a DevTools webpage
7575

7676
If you want to create the files for each major step below, install a code editor such as [Visual Studio Code](https://code.visualstudio.com/), to follow the tutorial steps below to manually re-create the above sample DevTools extension. You can read the code walkthrough below, presented as four major steps or phases.
7777

78-
A basic extension for Microsoft Edge consists of two files, as shown in [Step 1 code](https://github.com/MicrosoftEdge/Demos/tree/main/devtools-extension/sample%201):
78+
A basic extension for Microsoft Edge consists of a manifest file (`manifest.json`). Because this particular extension extends DevTools, this extension also includes a webpage file, `devtools.html`. The two files are provided in the `Microsoft Edge / Demos` repo > [/devtools-extension/sample 1/](https://github.com/MicrosoftEdge/Demos/tree/main/devtools-extension/sample%201) directory. The directory contains the files:
79+
* `devtools.html`
80+
* `manifest.json`
7981

80-
* A manifest file, containing key/value pairs. The top-level keys are called _members_. In this case, the file is named `manifest.json`:
8182

82-
```json
83-
{
84-
"name": "DevTools Sample Extension",
85-
"description": "A Basic DevTools Extension",
86-
"manifest_version": 3,
87-
"version": "1.0",
88-
"devtools_page": "devtools.html"
89-
}
90-
```
83+
<!-- ------------------------------ -->
84+
#### manifest.json
9185

92-
| Member | Description |
93-
|----------|-------------|
94-
| `name` | The name of the extension that will appear under `edge://extensions/`. |
95-
| `description` | The description of the extension that will be displayed under the name of the extension. |
96-
| `version` | The version of the extension that will appear next to the name of the extension. |
97-
| `manifest_version` | Determines the set of features that the extension will be using, such as service workers or network request modification. The current version is version `3`. To learn more about this version and the differences with version `2`, see [Overview and timelines for migrating to Manifest V3](./manifest-v3.md). |
98-
| `devtools_page` | The path to an HTML file that's run every time DevTools is opened, and loads the extension's JavaScript files. This page isn't rendered in DevTools. |
86+
`manifest.json` is a manifest file, containing key/value pairs. The top-level keys are called _members_:
9987

100-
* An HTML file to match the `devtools_page` field in the manifest file. In this case, the file is named `devtools.html`:
88+
```json
89+
{
90+
"name": "DevTools Sample Extension",
91+
"description": "A Basic DevTools Extension",
92+
"manifest_version": 3,
93+
"version": "1.0",
94+
"devtools_page": "devtools.html"
95+
}
96+
```
10197

102-
```html
103-
<!DOCTYPE html>
104-
<html>
105-
<head>
106-
<meta charset="UTF-8" />
107-
</head>
108-
<body>
109-
A Basic DevTools Extension.
110-
</body>
111-
</html>
112-
```
98+
| Member | Description |
99+
|----------|-------------|
100+
| `name` | The name of the extension that will appear under `edge://extensions/`. |
101+
| `description` | The description of the extension that will be displayed under the name of the extension. |
102+
| `version` | The version of the extension that will appear next to the name of the extension. |
103+
| `manifest_version` | Determines the set of features that the extension will be using, such as service workers or network request modification. The current version is version `3`. To learn more about this version and the differences with version `2`, see [Overview and timelines for migrating to Manifest V3](./manifest-v3.md). |
104+
| `devtools_page` | The path to an HTML file that's run every time DevTools is opened, and loads the extension's JavaScript files. This page isn't rendered in DevTools. |
105+
106+
107+
<!-- ------------------------------ -->
108+
#### devtools.html
109+
110+
`devtools.html` matches the `devtools_page` member in the manifest file:
111+
112+
```html
113+
<!DOCTYPE html>
114+
<html>
115+
<head>
116+
<meta charset="UTF-8" />
117+
</head>
118+
<body>
119+
A Basic DevTools Extension.
120+
</body>
121+
</html>
122+
```
113123

114124
In a later step, you'll add a `<script>` element in the above file, to load a JavaScript file. This HTML file isn't displayed in DevTools.
115125

@@ -144,11 +154,11 @@ See also:
144154

145155
In this step, you'll create a new panel (tool tab) in DevTools. You can either:
146156

147-
* Copy and paste the code from the `Microsoft Edge / Demos` repo > [/devtools-extension/sample 2/](https://github.com/MicrosoftEdge/Demos/tree/main/devtools-extension/sample%202) directory, which contains the following files:
157+
* Copy and paste the code from the `Microsoft Edge / Demos` repo > [/devtools-extension/sample 2/](https://github.com/MicrosoftEdge/Demos/tree/main/devtools-extension/sample%202) directory. That directory contains the following files:
148158
* `devtools.html`
149-
* `devtools.js`
159+
* `devtools.js` - Added in Step 2.
150160
* `manifest.json`
151-
* `panel.html`
161+
* `panel.html` - Added in Step 2.
152162

153163
* Copy and paste the code from the code listings below.
154164

@@ -171,19 +181,22 @@ To create a basic DevTools extension with a sample panel:
171181

172182
The `create` method has the following signature:
173183

174-
```js
175-
chrome.devtools.panels.create(
176-
title: string, // Tool tab's label in Activity bar.
177-
iconPath: string, // Icon to display in tool's tab.
178-
pagePath: string, // Webpage to display in tool's panel.
179-
callback: function // Code to run when tool is opened.
180-
)
181-
```
184+
```js
185+
chrome.devtools.panels.create(
186+
title: string, // Tool tab's label in Activity bar.
187+
iconPath: string, // Icon to display in tool's tab.
188+
pagePath: string, // Webpage to display in tool's panel.
189+
callback: function // Code to run when tool is opened.
190+
)
191+
```
182192

183193
Reference:
184194
* [chrome.devtools.panels](https://developer.chrome.com/docs/extensions/reference/devtools_panels/)
185195
* [create()](https://developer.chrome.com/docs/extensions/reference/api/devtools/panels#method-create)
186196

197+
198+
**devtools.html:**
199+
187200
1. Create a file named `devtools.html`.
188201

189202
1. Copy and paste the following code into `devtools.html`:
@@ -202,7 +215,10 @@ To create a basic DevTools extension with a sample panel:
202215

203216
In the manifest file (`manifest.json`), the `devtools_page` field specifies the above file (`devtools.html`). `devtools.html`, above, contains a `<script>` element that loads `devtools.js`.
204217

205-
1. Create the `panel.html` file that you referenced in the previous `chrome.devtools.panels.create` method call. This webpage will contain the user interface of the panel your extension is adding to DevTools.
218+
219+
**panel.html:**
220+
221+
1. Create the `panel.html` file that you referenced in the previous `chrome.devtools.panels.create` method call. This webpage will contain the user interface of the panel your extension is adding to DevTools.
206222

207223
```html
208224
<!DOCTYPE html>
@@ -216,6 +232,7 @@ To create a basic DevTools extension with a sample panel:
216232
</html>
217233
```
218234

235+
219236
<!-- ---------------------------------------------------------------------- -->
220237
#### Reload and test the DevTools extension
221238

@@ -241,7 +258,11 @@ To test your changes in Microsoft Edge, reload your extension from the `edge://e
241258
<!-- ====================================================================== -->
242259
## Step 3: Display memory information by calling extension APIs
243260

244-
In this step, you will use extension APIs to display memory information in your DevTools panel. To do this, we will need to update the `permissions` in the manifest file, the panel interface, and the devtools script. The source code for this step can be found in [Step 3 code](https://github.com/MicrosoftEdge/Demos/tree/main/devtools-extension/sample%203), or write it yourself by following the instructions below.
261+
In this step, you will use extension APIs to display memory information in your DevTools panel. To do this, we will need to update the `permissions` in the manifest file, the panel interface, and the devtools script. You can copy the source code files for this step from the `Microsoft Edge / Demos` repo > [/devtools-extension/sample 3/](https://github.com/MicrosoftEdge/Demos/tree/main/devtools-extension/sample%203) directory, or create the files yourself by following the instructions below. The directory contains the files:
262+
* `devtools.html`
263+
* `devtools.js` - Updated in Step 3.
264+
* `manifest.json` - Updated in Step 3.
265+
* `panel.html` - Updated in Step 3.
245266

246267
1. Use the `permissions` manifest member in your `manifest.json` file. This member defines which permissions your extension requires from the user. Some permissions are needed to use certain extension APIs.
247268

@@ -253,6 +274,9 @@ In this step, you will use extension APIs to display memory information in your
253274

254275
The `system-memory` permission is required, in order to use the extension APIs that you'll use later in this tutorial. To learn more about the available APIs and associated permissions, see [API reference](https://developer.chrome.com/docs/extensions/reference/) for extension APIs.
255276

277+
278+
**panel.html:**
279+
256280
1. Add the following to the body in the `panel.html` file to display the data in the panel.
257281

258282
```html
@@ -264,6 +288,9 @@ In this step, you will use extension APIs to display memory information in your
264288
</div>
265289
```
266290

291+
292+
**devtools.js:**
293+
267294
1. Update the `devtools.js` file with the following code.
268295

269296
```javascript
@@ -292,11 +319,11 @@ In this step, you will use extension APIs to display memory information in your
292319

293320
The above code snippet does the following:
294321

295-
1. It creates a new panel `Sample Panel` in DevTools.
322+
1. Creates a new panel `Sample Panel` in DevTools.
296323

297324
1. When the panel is displayed (`panel.onShown` listener), the `availableMemoryCapacity` and `totalMemoryCapacity` elements are retrieved from the DOM.
298325

299-
1. Next, a timer is set to run code every second after the panel is shown.
326+
1. Sets a timer to run code every second after the panel is shown.
300327

301328
1. When the timer fires, the `chrome.system.memory.getInfo` method is used to retrieve the available and total memory capacity of the device and these values are displayed in the corresponding DOM elements.
302329

@@ -335,7 +362,13 @@ In this step of the tutorial, you will add code that interacts with the inspecte
335362
1. Display the mouse click position in the DevTools extension panel.
336363
1. When the user clicks a button in the DevTools extension panel, display a greeting alert in the inspected webpage.
337364

338-
You can copy the files that are the end result of this step from [Step 4 code](https://github.com/MicrosoftEdge/Demos/tree/main/devtools-extension/sample%204), or create the files yourself by following the instructions below.
365+
You can copy the files that are the end result of this step from the `Microsoft Edge / Demos` repo > [/devtools-extension/sample 4/](https://github.com/MicrosoftEdge/Demos/tree/main/devtools-extension/sample%204) directory, or create the files yourself by following the instructions below. The directory contains the files:
366+
* `background.js` - added in Step 4.
367+
* `content_script.js` - added in Step 4.
368+
* `devtools.html`
369+
* `devtools.js` - updated in Step 4.
370+
* `manifest.json` - updated in Step 4.
371+
* `panel.html` - updated in Step 4.
339372

340373
The DevTools tool (panel) that you created so far doesn't have direct access to the inspected webpage, and doesn't run until DevTools is opened. For this you will use a content script and a background service worker.
341374

@@ -372,6 +405,9 @@ In this part of the tutorial, you'll detect the user clicks on a webpage by usin
372405
| `run_at` | Indicates when the browser injects the script onto the page. |
373406
| `js` | The javascript files to be injected. |
374407
408+
409+
**content_script.js:**
410+
375411
1. Create a file named `content_script.js`.
376412
377413
1. Copy and paste the following code into `content_script.js`:
@@ -392,6 +428,9 @@ In this part of the tutorial, you'll detect the user clicks on a webpage by usin
392428
393429
The above code snippet prints a message to the console when the script is injected in the page. It also adds a click event listener to the page that will send a message with mouse click position in the inspected page by using the `chrome.runtime.sendMessage` API.
394430
431+
432+
**panel.html:**
433+
395434
1. In the `panel.html` file, add a `sayHello` button and a `youClickedOn` label, as follows:
396435
397436
```html
@@ -401,7 +440,10 @@ In this part of the tutorial, you'll detect the user clicks on a webpage by usin
401440
402441
The above two elements are used to demo the interaction between the inspected page, the DevTools panel, and the background service worker. When the user clicks the `sayHello` button in the DevTools extension, it will display a greeting message in the inspected window. When the user clicks anywhere in the inspected page, it will display a message to show the mouse click position in the DevTools extension panel.
403442
404-
1. In the `devtools.js` file, use the `chrome.runtime.connect` method to create a connection to the background service worker, and then send the inspected window `tabId` to the service worker by using the `backgroundPageConnection.postMessage` method. Finally, add event listeners to the `sayHello` button and `youClickedOn` label that's defined in the `panel.html` file.
443+
444+
**devtools.js:**
445+
446+
1. In the `devtools.js` file (as shown below), use the `chrome.runtime.connect` method to create a connection to the background service worker, and then send the inspected window `tabId` to the service worker by using the `backgroundPageConnection.postMessage` method. Finally, add event listeners to the `sayHello` button and `youClickedOn` label that's defined in the `panel.html` file, as shown below:
405447

406448
```javascript
407449
let youClickedOn;
@@ -447,6 +489,9 @@ In this part of the tutorial, you'll detect the user clicks on a webpage by usin
447489

448490
When the user clicks anywhere in the inspected window, the DevTools extension will receive a message, from the background service worker, with `request.click == true` and the mouse position information.
449491

492+
493+
**background.js:**
494+
450495
1. Create a file named `background.js`.
451496

452497
1. Copy and paste the following code into `background.js`:

0 commit comments

Comments
 (0)