diff --git a/microsoft-edge/developer/index.yml b/microsoft-edge/developer/index.yml index fd2a3ec521..e56d83f7b5 100644 --- a/microsoft-edge/developer/index.yml +++ b/microsoft-edge/developer/index.yml @@ -101,7 +101,7 @@ landingContent: - text: Register as a Microsoft Edge extension developer url: ../extensions-chromium/publish/create-dev-account.md - - text: "Tutorial part 1: Display an image in a pop-up" + - text: "Sample: Display an image in a pop-up" url: ../extensions-chromium/getting-started/part1-simple-extension.md # ----------------------------------------------------------------------------- diff --git a/microsoft-edge/devtools-guide-chromium/sources/index.md b/microsoft-edge/devtools-guide-chromium/sources/index.md index 01e27344b7..852044d6b6 100644 --- a/microsoft-edge/devtools-guide-chromium/sources/index.md +++ b/microsoft-edge/devtools-guide-chromium/sources/index.md @@ -187,7 +187,7 @@ When the debugger steps into code that you don't recognize, you might want to ad See also: * [Content scripts](https://developer.mozilla.org/Add-ons/WebExtensions/Content_scripts) -* [Tutorial part 2: Use JavaScript to insert an image in the webpage](../../extensions-chromium/getting-started/part2-content-scripts.md) +* [Sample: Insert an image in the webpage](../../extensions-chromium/getting-started/part2-content-scripts.md) diff --git a/microsoft-edge/extensions-chromium/developer-guide/sidebar.md b/microsoft-edge/extensions-chromium/developer-guide/sidebar.md index 1db4b2773d..80fc9bfa09 100644 --- a/microsoft-edge/extensions-chromium/developer-guide/sidebar.md +++ b/microsoft-edge/extensions-chromium/developer-guide/sidebar.md @@ -316,8 +316,8 @@ See [Types](https://developer.chrome.com/docs/extensions/reference/sidePanel/#ty * [Supported APIs for Microsoft Edge extensions](../developer-guide/api-support.md) * [Declare API permissions in the manifest](../developer-guide/declare-permissions.md) * [Manifest file format for extensions](../getting-started/manifest-format.md) -* [Tutorial part 1: Display an image in a pop-up](../getting-started/part1-simple-extension.md) -* [Tutorial part 2: Use JavaScript to insert an image in the webpage](../getting-started/part2-content-scripts.md) +* [Sample: Display an image in a pop-up](../getting-started/part1-simple-extension.md) +* [Sample: Insert an image in the webpage](../getting-started/part2-content-scripts.md) diff --git a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading.md b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading.md index 200ccd56e4..68decad6df 100644 --- a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading.md +++ b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading.md @@ -32,11 +32,11 @@ To sideload an extension into Microsoft Edge, so that it's locally installed in 1. Select the directory that contains the extension's source files, such as `manifest.json`, and then click the **Select Folder** button. - Example path for [Tutorial part 1: Display an image in a pop-up](./part1-simple-extension.md): + Example path for [Sample: Display an image in a pop-up](./part1-simple-extension.md): `C:\Users\myUsername\GitHub\MicrosoftEdge-Extensions\Extension samples\extension-getting-started-part1\part1\` - Example path for [Tutorial part 2: Use JavaScript to insert an image in the webpage](./part2-content-scripts.md): + Example path for [Sample: Insert an image in the webpage](./part2-content-scripts.md): `C:\Users\myUsername\GitHub\MicrosoftEdge-Extensions\Extension samples\extension-getting-started-part2\extension-getting-started-part2\` @@ -83,5 +83,5 @@ To remove an extension that's been installed locally (sideloaded) in your browse ## See also -* [Tutorial part 1: Display an image in a pop-up](./part1-simple-extension.md) -* [Tutorial part 2: Use JavaScript to insert an image in the webpage](./part2-content-scripts.md) +* [Sample: Display an image in a pop-up](./part1-simple-extension.md) +* [Sample: Insert an image in the webpage](./part2-content-scripts.md) diff --git a/microsoft-edge/extensions-chromium/getting-started/index.md b/microsoft-edge/extensions-chromium/getting-started/index.md index b2856d098a..c4be31e8b3 100644 --- a/microsoft-edge/extensions-chromium/getting-started/index.md +++ b/microsoft-edge/extensions-chromium/getting-started/index.md @@ -73,4 +73,4 @@ An extension provides opt-in permissions at install time. You specify the exten ## Next steps -For information on getting started with your extension, see [Tutorial part 1: Display an image in a pop-up](part1-simple-extension.md). +For information on getting started with your extension, see [Sample: Display an image in a pop-up](part1-simple-extension.md). diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/clone-a-repo-dbox-ghd.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/clone-a-repo-dbox-ghd.png new file mode 100644 index 0000000000..86b088b976 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/clone-a-repo-dbox-ghd.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/developermode-toggle.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/developermode-toggle.png new file mode 100644 index 0000000000..a0cf6d91d4 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/developermode-toggle.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extension-running.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extension-running.png index 948540c0ff..ccc46691e7 100644 Binary files a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extension-running.png and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extension-running.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-icon.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-icon.png new file mode 100644 index 0000000000..55436f3956 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-icon.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup-no-extensions.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup-no-extensions.png new file mode 100644 index 0000000000..094911af72 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup-no-extensions.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup-with-launch-icon.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup-with-launch-icon.png new file mode 100644 index 0000000000..7c64d37706 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup-with-launch-icon.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup.png new file mode 100644 index 0000000000..e92681a89d Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/icon-png-toolbar.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/icon-png-toolbar.png new file mode 100644 index 0000000000..1571d40200 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/icon-png-toolbar.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/load-unpacked-icon.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/load-unpacked-icon.png new file mode 100644 index 0000000000..ccc526dbba Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/load-unpacked-icon.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/part1-badge1.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/part1-badge1.png deleted file mode 100644 index f39969a870..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/part1-badge1.png and /dev/null differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/part1-installed-extension.png b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/part1-installed-extension.png new file mode 100644 index 0000000000..1faba70da3 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/part1-installed-extension.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension.md b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension.md index aa439664cf..e881220614 100644 --- a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension.md +++ b/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension.md @@ -1,189 +1,251 @@ --- -title: "Tutorial part 1: Display an image in a pop-up" -description: Build an extension that displays an image file in a webpage in a pop-up, without JavaScript. +title: "Sample: Display an image in a pop-up" +description: An extension that displays an image file in a webpage in a pop-up, without JavaScript. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: conceptual ms.service: microsoft-edge ms.subservice: extensions -ms.date: 10/04/2024 +ms.date: 01/13/2025 --- -# Tutorial part 1: Display an image in a pop-up +# Sample: Display an image in a pop-up -The [Part 1 sample: Display an image in a pop-up](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part1/part1) is a simple static extension, without JavaScript, that displays the `stars.jpeg` image in a small webpage in a pop-up in any Microsoft Edge tab: +This sample is a simple static extension, without JavaScript, that displays the `stars.jpeg` image in a small webpage in a pop-up in any Microsoft Edge tab: -![The simple extension running](./part1-simple-extension-images/extension-running.png) +![The simple extension running](./part1-simple-extension-images/extension-running.png) -You create this type of extension by doing the following: -1. Create a manifest.json file. -1. Add icons for launching the extension. -1. Open a default pop-up dialog. -Along the way, you install (or update) and test the extension. + +## Clone the MicrosoftEdge-Extensions repo + + +You can use various tools to clone a GitHub repo. You can download a selected directory, or clone the entire repo. These instructions use GitHub Desktop to clone the repo and switch to a working branch. + +To clone the `MicrosoftEdge-Extensions` repo to your local drive: + +1. If not done already, install GitHub desktop: go to [https://github.com/apps/desktop](https://github.com/apps/desktop), and then click the **Download now** button. + +1. Go to [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions). + +1. Click the **Code** button, and then select **Open with GitHub Desktop**. + + A dialog opens, saying **This site is trying to open GitHubDesktop.exe.** + +1. Click the **Open** button. + + GitHub Desktop opens, with the **MicrosoftEdge-Extensions** repo selected in the upper left dropdown list. + + Or, in GitHub Desktop, the **Clone a repository** dialog opens: + + ![The "Clone a repository" dialog in GitHub Desktop](./part1-simple-extension-images/clone-a-repo-dbox-ghd.png) + +1. Specify the local drive path to place the cloned repo directory into; for example: `C:\Users\accountname\GitHub\`. + +1. Click the **Clone** button. + + + **Create working branch:** + +1. In GitHub Desktop, make sure that in the upper left of GitHub desktop, **Current repository** is **MicrosoftEdge-Extensions**. -If you want to immediately install and run the completed extension, or view its finished code, either: -* Clone the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo to your local drive. Use the directory `/extension-getting-started-part1/`. -* Download the source code from the [/part1/](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part1/part1) folder of the MicrosoftEdge-Extensions repo. + In the **Current branch** drop-down list, it says **main**. -Then you can install and run the finished extension that's in the repo, per [Sideload an extension to install and test it locally](extension-sideloading.md). +1. In the **Current branch** drop-down list, click the **Branches** tab, and then click the **New branch** button. + + The **Create a branch** dialog opens. + +1. In the **Name** text box, enter a branch name, such as **ext-sample-1**, and then click the **Create branch** button. + + In the upper middle and lower left of GitHub Desktop, the current branch is shown, such as **ext-sample-1**. + +You are now free to modify the code in your working branch, without altering the code that's in the "main" branch of the repo. Later you might want to switch back to the "main" branch, or create a different branch based off the "main" branch. + + -## Step 1: Create a manifest.json file +## Install the sample locally -Every extension package must have a `manifest.json` file at the root. The manifest provides details of your extension, the extension package version, the extension name and description, and so on. +Instead of installing the sample from the Store, you'll install the sample locally, so that you can possibly modify it and quickly test the changes. Installing locally is sometimes called _sideloading_ an extension. -All the coding steps in this article have already been done in the Part 1 demo in the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. We recommend first cloning the repo and installing and running the Part 1 demo, before (or instead of) starting with an empty directory and then manually creating directories, creating files, and pasting code into the files. +1. In Microsoft Edge, click the **Extensions** (![Extensions icon](./part1-simple-extension-images/extensions-icon.png)) button, next to the Address bar, if this icon is displayed. Or, select **Settings and more** (...) > **Extensions**. The **Extensions** pop-up opens: -This step has already been done in [manifest.json](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part1/part1/manifest.json) in the MicrosoftEdge-Extensions repo. If you want to manually create the Part 1 extension by starting with an empty directory: + ![The Extensions popup when no extensions are installed](./part1-simple-extension-images/extensions-popup-no-extensions.png) -* In a directory on your machine, using an editor, such as Visual Studio Code, create a `manifest.json` file that contains the following lines: +1. Click **Manage extensions**. The **Extensions** management page opens in a new tab: - ```json - { - "name": "NASA picture of the day pop-up", - "version": "0.0.0.1", - "manifest_version": 3, - "description": "A basic extension that displays an image in a pop-up.", - } - ``` + ![Turning on Developer Mode](./part1-simple-extension-images/developermode-toggle.png) + +1. Turn on the **Developer mode** toggle. + +1. When installing your extension for the first time, click the **Load unpacked** (![The "Load unpacked" icon](./part1-simple-extension-images/load-unpacked-icon.png)) button. The **Select the extension directory** dialog opens. + +1. Select the directory that contains the extension's source files, such as `manifest.json`, and then click the **Select Folder** button. + + Example path: + + `C:\Users\myUsername\GitHub\MicrosoftEdge-Extensions\Extension samples\extension-getting-started-part1\part1\` + + The extension is installed in the browser, similar to an extension that's installed from the store: + + ![Installed extensions page, showing a sideloaded extension](./part1-simple-extension-images/part1-installed-extension.png) -## Step 2: Add icons for launching the extension - -This step has already been done in the Part 1 demo in the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. If you want to manually create the Part 1 extension, continue with the following steps. - -1. Create an `icons` directory in your project, in the same directory as the manifest file, to store the icon image files. The icons are used as the background image for the button that the user clicks to launch the extension: - - ![Icon on the toolbar to open your extension](./part1-simple-extension-images/part1-badge1.png) - - For icons: - * We recommend using `PNG` format, but you can also use `BMP`, `GIF`, `ICO` or `JPEG` formats. - * We recommend using images that are 128 x 128 px, which are resized by the browser if necessary. - -1. Make sure the directories of your project are similar to the following structure: - - ```shell - └── part1 - ├── manifest.json - └── icons - ├── nasapod16x16.png - ├── nasapod32x32.png - ├── nasapod48x48.png - └── nasapod128x128.png - ``` - -1. Obtain the `.png` files from the repo: - * `nasapod16x16.png` - * `nasapod32x32.png` - * `nasapod48x48.png` - * `nasapod128x128.png` - - For example, individually download the files from the [/icons/](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part1/part1/icons) folder of the MicrosoftEdge-Extensions repo and place them in your `/icons/` directory. - -1. List the icons in the `manifest.json` file, as follows: - - ```json - { - "name": "NASA picture of the day pop-up", - "version": "0.0.0.1", - "manifest_version": 3, - "description": "A basic extension that displays an image in a pop-up.", - "icons": { - "16": "icons/nasapod16x16.png", - "32": "icons/nasapod32x32.png", - "48": "icons/nasapod48x48.png", - "128": "icons/nasapod128x128.png" - } - } - ``` +## Run the sample + +1. Go to a webpage, such as [TODO app](https://microsoftedge.github.io/Demos/demo-to-do/), in a new window or tab. For this sample, this step is optional and is just to match the screenshots; this sample doesn't require a webpage to be open. + +1. In the upper right of Microsoft Edge, click the **Extensions** (![Extensions icon](./part1-simple-extension-images/extensions-icon.png)) button. Or, select **Settings and more** (...) > **Extensions**. + + The **Extensions** pop-up opens: + + ![The Extensions pop-up](./part1-simple-extension-images/extensions-popup.png) + +1. Click the extension's icon or name (**NASA picture of the day pop-up**). + + The extension opens, and the extension's icon is added next to the Address bar and **Extensions** (![Extensions icon](./part1-simple-extension-images/extensions-icon.png)) icon. The extension displays `popup.html`, containing `stars.jpeg`, in a pop-up: + + ![The simple extension running](./part1-simple-extension-images/extension-running.png) + + You can open this particular sample extension in any tab, including an empty tab or the **Manage Extensions** tab. + +See also: +* [Sideload an extension to install and test it locally](./extension-sideloading.md) -## Step 3: Open a default pop-up dialog - -This step has already been done in [popup.html](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part1/part1/popup/popup.html) in the MicrosoftEdge-Extensions repo. If you want to manually create the Part 1 extension, continue with the following steps. - -Create a `HTML` file to run when the user launches your extension. When the user clicks the icon to launch the extension, this file will be displayed as a modal dialog. - -1. Create the HTML file named `popup.html` in a directory named `popup`. - -1. Add the following code to `popup.html`, to display the stars image: - - ```html - - - - NASA picture of the day - - -
- Stars -
- - - ``` - -1. Add the file `stars.jpeg` in the `images` folder. For example, download [stars.jpeg](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part1/part1/images/stars.jpeg) from the MicrosoftEdge-Extensions repo. - -1. Make sure the directories of your project are similar to the following structure: - - ```shell - └── part1 - ├── manifest.json - ├── icons - │ ├── nasapod16x16.png - │ ├── nasapod32x32.png - │ ├── nasapod48x48.png - │ └── nasapod128x128.png - ├── images - │ └── stars.jpeg - └── popup - └── popup.html - ``` - -1. Register the pop-up in `manifest.json` under `action`, as follows: - - ```json - { - "name": "NASA picture of the day pop-up", - "version": "0.0.0.1", - "manifest_version": 3, - "description": "A basic extension that displays an image in a pop-up.", - "icons": { - "16": "icons/nasapod16x16.png", - "32": "icons/nasapod32x32.png", - "48": "icons/nasapod48x48.png", - "128": "icons/nasapod128x128.png" - }, - "action": { - "default_popup": "popup/popup.html" - } - } - ``` +## Study the sample -That's everything you need to develop a simple extension. +In the following sections, you study the sample. After that, to develop your own Microsoft Edge extension, you can copy and modify the sample's directory, and install and test the resulting extension. -## Step 4: Install and test the extension +## Files and directories + +The sample has the following directory structure: + +Example path for the sample: +`C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension samples\extension-getting-started-part1\part1\` + +Directories and files in the `\part1\` directory: -Install and run the extension; see [Sideload an extension to install and test it locally](extension-sideloading.md). The extension displays `popup.html`, containing `stars.jpeg`, in a pop-up: +```shell +/icons/ + nasapod16x16.png + nasapod32x32.png + nasapod48x48.png + nasapod128x128.png +/images/ + stars.jpeg +/popup/ + popup.html +manifest.json +``` + +* The `/icons/` directory contains versions of a `.png` file that's used to represent the extension near the browser's Address bar. +* The `/images/` directory contains `stars.jpeg`, which is displayed in the extension's pop-up. +* The `/popup/` directory contains `popup.html`, which defines the webpage content that's displayed in the extension's pop-up. +* `manifest.json` contains basic information about the extension. + + + +## The manifest file (`manifest.json`) + +Every extension package must have a `manifest.json` file at the root. The manifest provides details of your extension, the extension package version, and the extension name and description. + +`manifest.json` contains the following lines: + +```json +{ + "name": "NASA picture of the day pop-up", + "version": "0.0.0.1", + "manifest_version": 3, + "description": "A basic extension that displays an image in a pop-up.", + "icons": { + "16": "icons/nasapod16x16.png", + "32": "icons/nasapod32x32.png", + "48": "icons/nasapod48x48.png", + "128": "icons/nasapod128x128.png" + }, + "action": { + "default_popup": "popup/popup.html" + } +} +``` -![The simple extension running](./part1-simple-extension-images/extension-running.png) -You can open this Part 1 demo extension in any tab, including an empty tab or the Manage Extensions tab. + +## Icons for launching the extension + +The `/icons/` directory contains the icon image files. The icons are used as the background image for the button that you click to launch the extension: + +![The extension's icon in the Extensions pop-up list](./part1-simple-extension-images/extensions-popup-with-launch-icon.png) + + +When the extension is running, one of the icons is displayed on the toolbar, next to the Address bar: + +![Icon on the toolbar](./part1-simple-extension-images/icon-png-toolbar.png) + +To close the extension, click the extension's icon on the toolbar, or click the **Extensions** (![Extensions icon](./part1-simple-extension-images/extensions-icon.png)) button. + +Recommendations for icons: +* Use `PNG` format, but you can also use `BMP`, `GIF`, `ICO` or `JPEG` formats. +* If you provide a single icon file, use 128 x 128 px, which can be resized by the browser if necessary. + + + +## The pop-up dialog (`popup.html`) + +`popup.html` in the `popup` directory runs when you launch the extension. When you click the icon to launch the extension, this file is displayed as a modal dialog. + +`popup.html` contains the following code, to display a title and the stars image: + +```html + + + + NASA picture of the day + + +
+ Stars +
+ + +``` + +The popup (`popup.html`) is registered as the `"default_popup"` in `manifest.json`, in the `action` key section: + +`manifest.json` (portion) + +```json +{ + ... + "action": { + "default_popup": "popup/popup.html" + } +} +``` + + + +## Next steps + +To develop your own Microsoft Edge extension, you can copy and modify the sample's directory, and install and test the resulting extension. -After running and testing the extension, you can continue on to [Tutorial part 2: Use JavaScript to insert an image in the webpage](./part2-content-scripts.md). +After running and testing this extension sample, you can continue on to [Sample: Insert an image in the webpage](./part2-content-scripts.md), which dynamically inserts JavaScript running as content in the browser tab. ## See also -* [Sideload an extension to install and test it locally](extension-sideloading.md) -* [Tutorial part 2: Use JavaScript to insert an image in the webpage](./part2-content-scripts.md) +* [Sideload an extension to install and test it locally](./extension-sideloading.md) +* [Sample: Insert an image in the webpage](./part2-content-scripts.md) GitHub: * [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/clone-a-repo-dbox-ghd.png b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/clone-a-repo-dbox-ghd.png new file mode 100644 index 0000000000..86b088b976 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/clone-a-repo-dbox-ghd.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/developermode-toggle.png b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/developermode-toggle.png new file mode 100644 index 0000000000..b4caf5a41e Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/developermode-toggle.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/extensions-popup-no-extensions.png b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/extensions-popup-no-extensions.png new file mode 100644 index 0000000000..3c687c5143 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/extensions-popup-no-extensions.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/load-unpacked-icon.png b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/load-unpacked-icon.png new file mode 100644 index 0000000000..ccc526dbba Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/load-unpacked-icon.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/open-the-extension.png b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/open-the-extension.png index 1b3318847a..ada8e5a426 100644 Binary files a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/open-the-extension.png and b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/open-the-extension.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-installed-extension.png b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-installed-extension.png new file mode 100644 index 0000000000..fd1a693cfc Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-installed-extension.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-popupdialog.png b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-popupdialog.png index 64bab42daf..2d9d5360e7 100644 Binary files a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-popupdialog.png and b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-popupdialog.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-showingimage.png b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-showingimage.png index a4589639ae..139e71285f 100644 Binary files a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-showingimage.png and b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-showingimage.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts.md b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts.md index 4abd5cd830..aa78fbce0b 100644 --- a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts.md +++ b/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts.md @@ -1,23 +1,28 @@ --- -title: "Tutorial part 2: Use JavaScript to insert an image in the webpage" -description: Dynamically inserting a NASA picture below the page body tag by using content scripts. +title: "Sample: Insert an image in the webpage" +description: Uses JavaScript to insert a .jpeg image file inside the element of the current webpage. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: conceptual ms.service: microsoft-edge ms.subservice: extensions -ms.date: 10/04/2024 +ms.date: 01/13/2025 --- -# Tutorial part 2: Use JavaScript to insert an image in the webpage +# Sample: Insert an image in the webpage -The [Part 2 sample: Use JavaScript to insert an image in the webpage](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2) uses JavaScript code to insert the `stars.jpeg` image into the top of the currently opened webpage. The extension's pop-up contains a title and an HTML button that's labelled **Display**. When you click the **Display** button, JavaScript sends a message from the extension icon's pop-up, and dynamically inserts JavaScript running as content in the browser tab. +This sample uses JavaScript code to insert the `stars.jpeg` image at the top of the current webpage, inside the `` element. The extension's pop-up contains a title and an HTML button that's labelled **Display**. When you click the **Display** button, the extension's JavaScript code sends a message from the extension icon's pop-up, and dynamically inserts JavaScript that runs in the browser tab. + +This sample demonstrates the following extension features: -The Part 2 sample uses the following extension technologies: * Injecting JavaScript libraries into an extension. * Exposing extension assets to browser tabs. * Including content webpages in existing browser tabs. * Having content webpages listen for messages from pop-ups and respond. + + +## Preview of the sample + You'll open the Part 2 extension from the **Extensions** (![Extensions icon](./part2-content-scripts-images/extensions-icon.png)) button after installing the extension via the **Manage Extensions** tab: ![Clicking the extension's icon to open the extension](./part2-content-scripts-images/open-the-extension.png) @@ -26,36 +31,189 @@ The extension displays a small HTML page in a pop-up, containing a title, instru ![popup.html display after selecting the Extension icon](./part2-content-scripts-images/part2-popupdialog.png) -When you click the **Display** button, JavaScript code temporarily inserts `stars.jpeg` at the top of the current webpage, pushing down the content of the webpage to below the image. The injected content sets the image element to display `stars.jpeg` in the top of the current webpage, and then removes the image when you click the image: +When you click the **Display** button, JavaScript code temporarily inserts `stars.jpeg` at the top of the current webpage, pushing down the content of the webpage to below the image. The injected content sets the image element to display the static image `stars.jpeg` in the top of the current webpage: ![The image showing in browser](./part2-content-scripts-images/part2-showingimage.png) -If you want to immediately install and run the completed extension, or view its finished code, either: -* Clone the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo to your local drive. Use repo directory `/extension-getting-started-part2/`. -* Download the source code from the [/extension-getting-started-part2/](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2) folder of the MicrosoftEdge-Extensions repo. +When you click the image, the injected JavaScript removes the image from the DOM tree and webpage. -Then you can install and run the finished extension that's in the repo, per [Sideload an extension to install and test it locally](extension-sideloading.md). The tab must contain a webpage before opening the extension. +Obtain, install, and run the sample as follows. -## Step 1: Update popup.html to include a button +## Clone the MicrosoftEdge-Extensions repo + + +You can use various tools to clone a GitHub repo. You can download a selected directory, or clone the entire repo. These instructions use GitHub Desktop to clone the repo and switch to a working branch. + +To clone the `MicrosoftEdge-Extensions` repo to your local drive: + +1. If not done already, install GitHub desktop: go to [https://github.com/apps/desktop](https://github.com/apps/desktop), and then click the **Download now** button. + +1. Go to [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions). + +1. Click the **Code** button, and then select **Open with GitHub Desktop**. + + A dialog opens, saying **This site is trying to open GitHubDesktop.exe.** + +1. Click the **Open** button. -To use this article, first do the steps in [Tutorial part 1: Display an image in a pop-up](./part1-simple-extension.md); that is, clone the MicrosoftEdge-Extensions repo, install the Part 1 demo, and run that demo. + GitHub Desktop opens, with the **MicrosoftEdge-Extensions** repo selected in the upper left dropdown list. -This step has already been done in [popup.html](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/popup/popup.html) in the MicrosoftEdge-Extensions repo. + Or, in GitHub Desktop, the **Clone a repository** dialog opens: -The hypothetical starting state for this Part 2 article, if you were to manually build-up the sample to add JavaScript, is that a directory exists for the part 2 code, containing the same directories and files that are created in the Part 1 article. These can be sibling directories for Part 1 and Part 2, as done in the MicrosoftEdge-Extensions repo. + ![The "Clone a repository" dialog in GitHub Desktop](./part2-content-scripts-images/clone-a-repo-dbox-ghd.png) -It's possible to install the completed Part 1 and Part 2 demos from the MicrosoftEdge-Extensions repo, side-by-side. We recommend first cloning the repo and installing and running the demos, before (or instead of) starting with an empty directory and then manually creating directories, creating files, and pasting code into the files. +1. Specify the local drive path to place the cloned repo directory into; for example: `C:\Users\accountname\GitHub\`. -To manually expand the completed Part 1 demo to create the Part 2 demo, you would need to do the following: -1. In the folder that contains the `popup.html` file for Part 2 (initially a copy of the Part 1 file), add tagging that displays a title with a button. -1. Include a reference to a JavaScript file, `popup.js`. -1. Program that button. +1. Click the **Clone** button. -Below is the sample HTML file: -`/popup/popup.html` (complete): + **Create working branch:** + +1. In GitHub Desktop, make sure that in the upper left of GitHub desktop, **Current repository** is **MicrosoftEdge-Extensions**. + + In the **Current branch** drop-down list, it says **main**. + +1. In the **Current branch** drop-down list, click the **Branches** tab, and then click the **New branch** button. + + The **Create a branch** dialog opens. + +1. In the **Name** text box, enter a branch name, such as **ext-sample-2**, and then click the **Create branch** button. + + In the upper middle and lower left of GitHub Desktop, the current branch is shown, such as **ext-sample-2**. + +You are now free to modify the code in your working branch, without altering the code that's in the "main" branch of the repo. Later you might want to switch back to the "main" branch, or create a different branch based off the "main" branch. + + + + + +## Install the sample locally + +Instead of installing the sample from the Store, you'll install the sample locally, so that you can possibly modify it and quickly test the changes. Installing locally is sometimes called _sideloading_ an extension. + +1. In Microsoft Edge, click the **Extensions** (![Extensions icon](./part2-content-scripts-images/extensions-icon.png)) button, next to the Address bar, if this icon is displayed. Or, select **Settings and more** (...) > ![Extensions icon](./part2-content-scripts-images/extensions-icon.png) **Extensions**. The **Extensions** pop-up opens: + + ![The Extensions popup when no extensions are installed](./part2-content-scripts-images/extensions-popup-no-extensions.png) + +1. Click **Manage extensions**. The **Extensions** management page opens in a new tab: + + ![Turning on Developer Mode](./part2-content-scripts-images/developermode-toggle.png) + +1. Turn on the **Developer mode** toggle. + +1. When installing the sample extension for the first time, click the **Load unpacked** (![The "Load unpacked" icon](./part2-content-scripts-images/load-unpacked-icon.png)) button. The **Select the extension directory** dialog opens. + +1. Select the directory that contains the extension's source files, such as `manifest.json`. + + Example path: + + `C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension samples\extension-getting-started-part2\extension-getting-started-part2` + +1. Click the **Select Folder** button. + + The **Select the extension directory** dialog closes. + + The extension is installed in the browser, similar to an extension that's installed from the store: + + ![Installed extensions page, showing a sideloaded extension](./part2-content-scripts-images/part2-installed-extension.png) + + + +## Run the sample + +1. Go to a webpage, such as [TODO app](https://microsoftedge.github.io/Demos/demo-to-do/), in a new window or tab. The tab must not be empty, and must not be the Manage Extensions page, because this sample inserts content into the current webpage. + +1. In Microsoft Edge to the right of the Address bar, if this icon is displayed, click the **Extensions** (![Extensions icon](./part2-content-scripts-images/extensions-icon.png)) button. Or, select **Settings and more** (...) > **Extensions**. + + The **Extensions** pop-up opens: + + ![Clicking the extension's icon to open the extension](./part2-content-scripts-images/open-the-extension.png) + +1. Click the extension's icon or name (**NASA picture of the day viewer**). + + The extension opens, and the extension's icon is added next to the Address bar and **Extensions** (![Extensions icon](./part2-content-scripts-images/extensions-icon.png)) icon. + + A pop-up opens, containing a small HTML page with a title, instructions, and a **Display** button: + + ![popup.html after clicking the Extension's icon](./part2-content-scripts-images/part2-popupdialog.png) + +1. Click the **Display** button. `stars.jpeg` is inserted into the top of the current webpage in the current tab, pushing the webpage's content down below the image: + + ![The image showing in browser](./part2-content-scripts-images/part2-showingimage.png) + +1. Click the `stars.jpeg` image that's filling the top of the webpage. That image element is removed from the DOM tree and webpage, and the current webpage is restored, shifting its content back up to the top of the tab. + +The extension sends a message from the extension icon's pop-up, and dynamically inserts JavaScript running as content in the browser tab. The injected content sets the image element to display `stars.jpeg` in the top of the current webpage, and then removes the image when you click the image. + +See also: +* [Sideload an extension to install and test it locally](./extension-sideloading.md) + + + +## Study the sample + +In the following sections, you study the sample. After that, to develop your own Microsoft Edge extension, you can copy and modify the sample's directory, and install and test the resulting extension. + + + +## Files and directories + +The sample has the following directory structure and files. + +Example path for the sample: +`C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension samples\extension-getting-started-part2\extension-getting-started-part2` + +Directories and files in the `\extension-getting-started-part2\` directory: + +```shell +/content-scripts/ + content.js +/icons/ + nasapod16x16.png + nasapod32x32.png + nasapod48x48.png + nasapod128x128.png +/images/ + stars.jpeg +/lib/ + jquery.min.js +/popup/ + popup.html + popup.js +manifest.json +``` + +* The `/content-scripts/` directory contains `content.js`, which is the injected script that's injected into the current webpage. +* The `/icons/` directory contains versions of a `.png` file that's used to represent the extension near the browser's Address bar. +* The `/images/` directory contains `stars.jpeg`, which is displayed in the extension's pop-up. +* The `/lib/` directory contains `jquery.min.js`, which is a predefined, minified file, a minified version of jQuery, used in content scripts that you're injecting. +* The `/popup/` directory contains `popup.html`, which defines the webpage content that's displayed in the extension's pop-up. +* `manifest.json` contains basic information about the extension. + + + +## Strategy to update the webpage to insert the image at the top (`stars.jpeg`) + +This sample includes a content script that's injected into the webpage that's loaded in the current browser tab. + +1. When you run the extension sample, the initial popup HTML page is displayed (`popup.html`), showing a title, instructions, and the **Display** button. + +1. When you click the **Display** button, the JavaScript (`popup.js`) for the initial popup page sends a message to the content script (`content.js`) that's running on the tab page. The message specifies which image file should be displayed. + +1. The content script (`content.js`) running on the tab page receives the message, and displays the specified image file (`stars.jpeg`). + + + +## The initial popup webpage (`popup.html`) + +`popup.html` is specified in the manifest file as the webpage to display in the extension's initial popup. The manifest file contains the key field `"default_popup": "popup/popup.html"`. This sample's `popup.html` file is a small webpage that contains a title, instructions, and a **Display** button. + +`/popup/popup.html`: ```html @@ -85,31 +243,15 @@ Below is the sample HTML file: ``` -Do the steps in [Sideload an extension to install and test it locally](extension-sideloading.md) to locally update the extension and then run the extension. The tab must contain a webpage before opening the extension. - -After updating and opening the extension, a pop-up opens, containing a small HTML page with a title, instructions, and a **Display** button: - -![popup.html after clicking the Extension's icon](./part2-content-scripts-images/part2-popupdialog.png) - - - -## Step 2: Update the webpage to insert the image at the top - -After adding the **Display** button, the next task will be to make the button display the `images/stars.jpeg` image file at the top of the webpage that's in the active tab. - -Each tab page (and extension) runs in its own thread. In a step below, you'll create a content script that is injected into the tab page. The injected script will send a message from your pop-up to that content script that's running on the tab page. The content script will receive the message, which describes which image should be displayed. +The **Display** button is added by the above code. -## Step 3: Create the pop-up JavaScript to send a message - -This step has already been done in [popup.js](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/popup/popup.js) in the MicrosoftEdge-Extensions repo. If you want to manually create the Part 2 extension, continue with the following steps. +## JavaScript (`popup.js`) for the initial pop-up page, to send a message to the injected JavaScript -Create the `popup/popup.js` file, and then add the following code in that file. +`popup.js` sends a message to the content script (`content.js`) that's temporarily injected into the browser tab. To do that, `popup.js` adds an `onclick` event to the pop-up webpage's **Display** button, which has the ID `sendmessageid`: -This code sends a message to your not-yet-created content script that you must momentarily create and inject into your browser tab. To do that, the following code adds an `onclick` event to your pop-up **Display** button: - -`/popup/popup.js` (initial): +`/popup/popup.js` (portion): ```javascript const sendMessageId = document.getElementById("sendmessageid"); @@ -120,15 +262,15 @@ if (sendMessageId) { } ``` -In the `onclick` event, find the current browser tab. Then, use the `chrome.tabs.sendmessage` Extension API to send a message to that tab. +In the following `popup.js` code, the sample uses `chrome.tabs.query` to find the current browser tab, and then uses `chrome.tabs.sendMessage` to send a message to that tab. In that message, you must include the URL to the image you want to display. Make sure that you send a unique ID to assign to the inserted image. To send a unique ID to assign to the inserted image, a couple different approaches are possible: -* Approach 1: Let the content insertion JavaScript generate that image ID. We won't use that approach here, for reasons that become apparent later. +* Approach 1: Let the content insertion JavaScript generate that image ID. We won't use that approach here, for reasons explained below. * Approach 2: Generate that unique ID here in `popup.js`, and then pass that ID to the not-yet-created content script. We'll use this approach. -The following code outlines the updated code in `popup/popup.js`. You also pass in the current tab ID, which is used later in this article: +The sample also passes in the current tab ID, which is described later in this article: `/popup/popup.js` (complete): @@ -161,17 +303,54 @@ if (sendMessageId) { -## Step 4: Make your `stars.jpeg` available from any browser tab +## The content script message listener (`content.js`) -This step has already been done in [manifest.json](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/manifest.json) in the MicrosoftEdge-Extensions repo. If you want to manually create the Part 2 extension, continue with the following steps. +Here's the `content-scripts\content.js` file that gets injected into every browser tab page based on the `content-scripts` section in `manifest.json`: -To make `images/stars.jpeg` available from any browser tab, you must use the `chrome.runtime.getURL` API. +```javascript +chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) { + $("body").prepend( + ` ` + ); + $("head").prepend( + `` + ); + $(`#${request.imageDivId}`).click(function() { + $(`#${request.imageDivId}`).remove(`#${request.imageDivId}`); + }); + sendResponse({ fromcontent: "This message is from content.js" }); +}); +``` -The reason is that you're injecting the image using the `src` attribute of the `img` element into the content page. The content page is running on a unique thread that isn't the same as the thread running the extension. You must expose the static image file as a web asset for it to work correctly. +This code registers a `listener` by using the `chrome.runtime.onMessage.addListener` Extension API method. This listener waits for messages like the one you sent from the `popup.js` described earlier with the `chrome.tabs.sendMessage` Extension API method. -Add another entry in the `manifest.json` file to declare that the image is available to all browser tabs. +The first parameter of the `addListener` method is a function whose first parameter, request, is the details of the message being passed in. Remember, from `popup.js`, when you used the `sendMessage` method, those attributes of the first parameter are `url` and `imageDivId`. + +When an event is processed by the listener, the function that is the first parameter is run. The first parameter of that function is an object that has attributes as assigned by `sendMessage`. That function simply processes the three jQuery script lines. + +* The first script line appends an `img` element right below the `body` of the browser tab that has the `slide-image` class assigned as well as the `imageDivId` as the ID of that image element. + +* The second script line dynamically inserts into the DOM header a **\** section that's assigned as a `slide-image` class to the `img` element. + +* The third script line adds a `click` event that covers the entire image allowing the user to select anywhere on the image and that image is removed from the page (along with it is event listener). + + + +## How `stars.jpeg` is made available from any browser tab + +To make `images/stars.jpeg` available from any browser tab: +* `popup.js` (above) uses the `chrome.runtime.getURL` API. +* The manifest (below) specifies that `web_accessible_resources` of type `.jpeg` match all URLs. -That entry is as follows (you should see it in the full `manifest.json` file below when you add the content script declaration coming up): +The sample injects the image by using the `src` attribute of the `img` element into the content page. The content page is running on a unique thread that isn't the same as the thread running the extension. The static image file must be exposed as a web asset, for it to work correctly. + +Another entry is added in the `manifest.json` file to declare that the image is available to all browser tabs: `/manifest.json` (portion): @@ -184,15 +363,13 @@ That entry is as follows (you should see it in the full `manifest.json` file bel ] ``` -You've now written the code in your `popup.js` file to send a message to the content page that is embedded on the current active tab page. +The code in the `popup.js` file sends a message to the content page that's embedded in the current active tab page. -## Step 5: Update your `manifest.json` for new content and web access - -Next, you'll create and inject the content page that's embedded on the current active tab page. This step has already been done in [manifest.json](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/manifest.json) in the MicrosoftEdge-Extensions repo. +## How resources are listed in the manifest (`manifest.json`) -The updated `manifest.json` that includes the `content-scripts` and `web_accessible_resources` is as follows: +The sample creates and inject the content page that's embedded on the current active tab page. `manifest.json` includes the `content-scripts` and `web_accessible_resources`, as follows: `/manifest.json` (complete): @@ -228,100 +405,46 @@ The updated `manifest.json` that includes the `content-scripts` and `web_accessi } ``` -The `matches` attribute is set to ``, which means that all files in `content_scripts` are injected into all browser tab pages when each tab is loaded. The allowed files types that can be injected are JavaScript and CSS. You also added `lib\jquery.min.js`. You can copy that file from the [/lib/](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/lib) folder of the MicrosoftEdge-Extensions repo. - -#### Add jQuery +#### The manifest's `content_scripts` section injects JavaScript into all browser tabs -This step has already been done in [jquery.min.js](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/lib/jquery.min.js) in the MicrosoftEdge-Extensions repo. +In the `content_scripts` key section of the manifest file, the `matches` attribute is set to ``, which means that `.js` (or `.css`) files that are specified in the `content_scripts` key section are injected into all browser tab pages when each tab is loaded. The allowed files types that can be injected are JavaScript (`.js`) and CSS (`.css`). -In the content scripts that you're injecting, plan on using jQuery (`$`). You added a minified version of jQuery and put it in your extension package as `lib\jquery.min.js`. - -These content scripts run in individual sandboxes, which means that the jQuery injected into the `popup.js` page isn't shared with the content. +In this sample, the following files are specified: +* `content-scripts/content.js` +* `lib/jquery.min.js` -#### Understanding the thread +#### How jQuery support is added (`jquery.min.js`) -Even if the browser tab has JavaScript running on it on the loaded web page, any content that's injected doesn't have access to that JavaScript. The injected JavaScript only has access to the actual DOM that's loaded in that browser tab. - +`jquery.min.js` is a predefined, minified file to support jQuery expressions starting with `$` in `content.js`. +In injected content scripts, it's common to use jQuery (`$`). This sample includes a minified version of jQuery, residing in the extension package as `lib\jquery.min.js`. - -## Step 6: Add the content script message listener - -To continue manually building-up the Part 2 demo, you would need to create this file. This step has already been done in [content.js](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/content-scripts/content.js) in the MicrosoftEdge-Extensions repo. +The content script (`content.js`) runs in its own sandbox, which means that the jQuery that's injected into `content.js` isn't shared with the current webpage. -Here's the `content-scripts\content.js` file that gets injected into every browser tab page based on the `content-scripts` section in `manifest.json`: -`/content-scripts/content.js` (complete): - -```javascript -chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) { - $("body").prepend( - ` ` - ); - $("head").prepend( - `` - ); - $(`#${request.imageDivId}`).click(function() { - $(`#${request.imageDivId}`).remove(`#${request.imageDivId}`); - }); - sendResponse({ fromcontent: "This message is from content.js" }); -}); -``` - -All that the above JavaScript does is to register a `listener` using the `chrome.runtime.onMessage.addListener` Extension API method. This listener waits for messages like the one you sent from the `popup.js` described earlier with the `chrome.tabs.sendMessage` Extension API method. - -The first parameter of the `addListener` method is a function whose first parameter, request, is the details of the message being passed in. Remember, from `popup.js`, when you used the `sendMessage` method, those attributes of the first parameter are `url` and `imageDivId`. - -When an event is processed by the listener, the function that is the first parameter is run. The first parameter of that function is an object that has attributes as assigned by `sendMessage`. That function simply processes the three jQuery script lines. + +#### Understanding the thread -* The first script line appends an `img` element right below the `body` of your browser tab that has the `slide-image` class assigned as well as the `imageDivId` as the ID of that image element. +Each tab page (and extension) runs in its own thread. -* The second script line dynamically inserts into the DOM header a **\** section that you must assign as a `slide-image` class to your `img` element. - -* The third script line adds a `click` event that covers the entire image allowing the user to select anywhere on the image and that image is removed from the page (along with it is event listener). +Even if the browser tab contains a webpage that runs JavaScript code, the `content.js` script that's injected in that browser tab by the extension doesn't have access to that JavaScript code. The injected content script only has access to the DOM of the webpage. -## Step 7: Install and test the extension - -1. Install or update the extension, in the Manage Extensions page; see [Sideload an extension to install and test it locally](extension-sideloading.md). - -1. Go to a webpage, such as [Microsoft.com](https://www.microsoft.com), in a new window or tab. The tab must not be empty, and must not be the Manage Extensions page. - -1. Click the **Extensions** (![Extensions icon](./part2-content-scripts-images/extensions-icon.png)) button, next to the Address bar. Or, select **Settings and more** (...) > **Extensions**. - - ![Clicking the extension's icon to open the extension](./part2-content-scripts-images/open-the-extension.png) - -1. Click the icon or name of the **NASA picture of the day viewer** extension. - - The extension's pop-up opens: - - ![popup.html display after selecting the Extension icon](./part2-content-scripts-images/part2-popupdialog.png) - -1. Click the **Display** button. `stars.jpeg` is inserted into the top of the current webpage in the current tab, pushing the webpage's content down below the image: - - ![The image showing in browser](./part2-content-scripts-images/part2-showingimage.png) - -1. Click the `stars.jpeg` image that's filling the top of the webpage. That image element is removed from the DOM tree and webpage, and the current webpage is restored, shifting its content back up to the top of the tab. +## Next steps -Congratulations! You've created an extension that sends a message from the extension icon's pop-up, and dynamically inserts JavaScript running as content in the browser tab. The injected content sets the image element to display `stars.jpeg` in the top of the current webpage, and then removes the image when you click the image. +To develop your own Microsoft Edge extension, you can copy and modify the sample's directory, and install and test the resulting extension. ## See also -* [Tutorial part 1: Display an image in a pop-up](./part1-simple-extension.md) +* [Sample: Display an image in a pop-up](./part1-simple-extension.md) * [Sideload an extension to install and test it locally](extension-sideloading.md) GitHub: diff --git a/microsoft-edge/extensions-chromium/landing/index.yml b/microsoft-edge/extensions-chromium/landing/index.yml index 42ef727be8..1e3778b123 100644 --- a/microsoft-edge/extensions-chromium/landing/index.yml +++ b/microsoft-edge/extensions-chromium/landing/index.yml @@ -49,10 +49,10 @@ landingContent: - text: Extension concepts and architecture url: ../getting-started/index.md - - text: "Tutorial part 1: Display an image in a pop-up" + - text: "Sample: Display an image in a pop-up" url: ../getting-started/part1-simple-extension.md - - text: "Tutorial part 2: Use JavaScript to insert an image in the webpage" + - text: "Sample: Insert an image in the webpage" url: ../getting-started/part2-content-scripts.md - text: Sideload an extension to install and test it locally diff --git a/microsoft-edge/index.yml b/microsoft-edge/index.yml index e061ab93ad..6f998a9c84 100644 --- a/microsoft-edge/index.yml +++ b/microsoft-edge/index.yml @@ -257,7 +257,7 @@ conceptualContent: url: ./extensions-chromium/publish/create-dev-account.md itemType: how-to-guide - - text: "Tutorial part 1: Display an image in a pop-up" + - text: "Sample: Display an image in a pop-up" url: ./extensions-chromium/getting-started/part1-simple-extension.md itemType: how-to-guide diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 92df9a21d7..ca73c3bba7 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -1012,10 +1012,10 @@ - name: Extension concepts and architecture href: extensions-chromium/getting-started/index.md - - name: "Tutorial part 1: Display an image in a pop-up" + - name: "Sample: Display an image in a pop-up" href: extensions-chromium/getting-started/part1-simple-extension.md - - name: "Tutorial part 2: Use JavaScript to insert an image in the webpage" + - name: "Sample: Insert an image in the webpage" href: extensions-chromium/getting-started/part2-content-scripts.md - name: Sideload an extension to install and test it locally