diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 9932a5710d..df9263279b 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -147,6 +147,16 @@ Old redirects (to /archive/) "redirect_url": "/microsoft-edge/extensions-chromium/developer-guide/csp", "redirect_document_id": false }, + { + "source_path": "microsoft-edge/extensions-chromium/getting-started/part1-simple-extension.md", + "redirect_url": "/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage", + "redirect_document_id": false + }, + { + "source_path": "microsoft-edge/extensions-chromium/getting-started/part2-content-scripts.md", + "redirect_url": "/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script", + "redirect_document_id": false + }, /* Progressive Web Apps: */ { diff --git a/microsoft-edge/developer/index.yml b/microsoft-edge/developer/index.yml index e56d83f7b5..5416a8b16c 100644 --- a/microsoft-edge/developer/index.yml +++ b/microsoft-edge/developer/index.yml @@ -101,8 +101,8 @@ landingContent: - text: Register as a Microsoft Edge extension developer url: ../extensions-chromium/publish/create-dev-account.md - - text: "Sample: Display an image in a pop-up" - url: ../extensions-chromium/getting-started/part1-simple-extension.md + - text: "Sample: Picture viewer pop-up webpage" + url: ../extensions-chromium/getting-started/picture-viewer-popup-webpage.md # ----------------------------------------------------------------------------- # Card r1c3 diff --git a/microsoft-edge/devtools-guide-chromium/sources/index.md b/microsoft-edge/devtools-guide-chromium/sources/index.md index 852044d6b6..c15495002a 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) -* [Sample: Insert an image in the webpage](../../extensions-chromium/getting-started/part2-content-scripts.md) +* [Sample: Picture inserter using content script](../../extensions-chromium/getting-started/picture-inserter-content-script.md) diff --git a/microsoft-edge/extensions-chromium/developer-guide/sidebar.md b/microsoft-edge/extensions-chromium/developer-guide/sidebar.md index 80fc9bfa09..f2b185b156 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) -* [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) +* [Sample: Picture viewer pop-up webpage](../getting-started/picture-viewer-popup-webpage.md) +* [Sample: Picture inserter using content script](../getting-started/picture-inserter-content-script.md) diff --git a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/developermode-toggle.png b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/developermode-toggle.png similarity index 100% rename from microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/developermode-toggle.png rename to microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/developermode-toggle.png diff --git a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extension-running.png b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extension-running.png index 40e5e410be..0cb1e79b40 100644 Binary files a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extension-running.png and b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extension-running.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extensions-popup-no-extensions.png b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extensions-popup-no-extensions.png index 86814eaedc..094911af72 100644 Binary files a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extensions-popup-no-extensions.png and b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extensions-popup-no-extensions.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extensions-popup.png b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extensions-popup.png index 3b0516219d..9568c7f185 100644 Binary files a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extensions-popup.png and b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/extensions-popup.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/installed-extension.png b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/installed-extension.png new file mode 100644 index 0000000000..b4da5bde11 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/installed-extension.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/part1-developermode-toggle.png b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/part1-developermode-toggle.png deleted file mode 100644 index fac5effd24..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/part1-developermode-toggle.png and /dev/null differ diff --git a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/part1-installed-extension.png b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/part1-installed-extension.png deleted file mode 100644 index 080967f872..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/part1-installed-extension.png and /dev/null differ diff --git a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/settings-and-more-icon.png b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/settings-and-more-icon.png new file mode 100644 index 0000000000..69fd7b1251 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading-images/settings-and-more-icon.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading.md b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading.md index 68decad6df..4e7c21274f 100644 --- a/microsoft-edge/extensions-chromium/getting-started/extension-sideloading.md +++ b/microsoft-edge/extensions-chromium/getting-started/extension-sideloading.md @@ -6,67 +6,90 @@ ms.author: msedgedevrel ms.topic: conceptual ms.service: microsoft-edge ms.subservice: extensions -ms.date: 10/04/2024 +ms.date: 01/16/2025 --- # Sideload an extension to install and test it locally To test an extension quickly and safely, sideload the extension in your own copy of Microsoft Edge, which means locally installing the extension. You can then run and test your extension without having to upload the extension to the Microsoft Edge Add-ins website (the _store_) and then install the extension from there. + +## Prerequisite: Have an extension to install + +This article assumes that your local drive contains an extension that you want to load, such as a sample from the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. + +To obtain the samples, see [Clone the MicrosoftEdge-Extensions repo](./picture-viewer-popup-webpage.md#clone-the-microsoftedge-extensions-repo) in _Sample: Picture viewer pop-up webpage_. + + ## Locally installing and running an extension To sideload an extension into Microsoft Edge, so that it's locally installed in your browser for testing: -1. In Microsoft Edge, click the **Extensions** (![Extensions icon](./extension-sideloading-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: +1. Go to a webpage, such as [TODO app](https://microsoftedge.github.io/Demos/demo-to-do/), in a new window or tab. For some samples, this step is optional and is just to match the screenshots below; some samples don't require a webpage to be open. + +1. In Microsoft Edge to the right of the Address bar, if this icon is displayed, click the **Extensions** (![Extensions icon](./extension-sideloading-images/extensions-icon.png)) button. Or, select **Settings and more** (![The "Settings and more" icon](./extension-sideloading-images/settings-and-more-icon.png)) > **Extensions**. + + The **Extensions** pop-up opens: ![The Extensions popup when no extensions are installed](./extension-sideloading-images/extensions-popup-no-extensions.png) 1. Click **Manage extensions**. The **Extensions** management page opens in a new tab: - ![Turning on Developer Mode](./extension-sideloading-images/part1-developermode-toggle.png) + ![Turning on Developer Mode](./extension-sideloading-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](./extension-sideloading-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. +1. Select the directory that contains the extension's source files, such as `manifest.json`. - Example path for [Sample: Display an image in a pop-up](./part1-simple-extension.md): + Example paths resulting from cloning the **MicrosoftEdge-Extensions** repo: - `C:\Users\myUsername\GitHub\MicrosoftEdge-Extensions\Extension samples\extension-getting-started-part1\part1\` + `C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-viewer-popup-webpage` + `C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-inserter-content-script` - Example path for [Sample: Insert an image in the webpage](./part2-content-scripts.md): +1. Click the **Select Folder** button. - `C:\Users\myUsername\GitHub\MicrosoftEdge-Extensions\Extension samples\extension-getting-started-part2\extension-getting-started-part2\` + The **Select the extension directory** dialog closes. The extension is installed in your browser, similar to extensions that are installed from the store: - ![Installed extensions page, showing a sideloaded extension](./extension-sideloading-images/part1-installed-extension.png) + ![Installed extensions page, showing a sideloaded extension](./extension-sideloading-images/installed-extension.png) + +1. If the extension requires that a webpage is open, make sure a webpage is open, such as [TODO app](https://microsoftedge.github.io/Demos/demo-to-do/). -1. To run the extension, first open a webpage, if the extension requires that a webpage is open. For example, go to a webpage, such as [Microsoft.com](https://www.microsoft.com), in a new window or tab. +1. Refresh the webpage. This is sometimes required after reloading an extension. -1. In the upper right of Microsoft Edge, click the **Extensions** (![Extensions icon](./extension-sideloading-images/extensions-icon.png)) button. Or, select **Settings and more** (...) > **Extensions**. +1. In Microsoft Edge to the right of the Address bar, click the **Extensions** (![Extensions icon](./extension-sideloading-images/extensions-icon.png)) button. Or, select **Settings and more** (![The "Settings and more" icon](./extension-sideloading-images/settings-and-more-icon.png)) > **Extensions**. The **Extensions** pop-up opens: ![The Extensions pop-up](./extension-sideloading-images/extensions-popup.png) -1. Click the extension's icon or name. The extension opens, and the extension's icon is added next to the Address bar and Extensions (![Extensions icon](./extension-sideloading-images/extensions-icon.png)) icon: +1. Click the extension's icon or name. The extension opens, and the extension's icon is added next to the Address bar and **Extensions** (![Extensions icon](./extension-sideloading-images/extensions-icon.png)) button: ![An extension running](./extension-sideloading-images/extension-running.png) -## Locally updating an extension +## Locally updating an extension (Reload) To update an extension that's been installed locally (sideloaded) in your browser: -1. Make any required changes to the extension. +1. Make changes to the extension's source code, and save those changes. + +1. In Microsoft Edge, if the **Extensions** management tab is open, click it. + + Or, to the right of the Address bar, if this icon is displayed, click the **Extensions** (![Extensions icon](./extension-sideloading-images/extensions-icon.png)) button. The **Extensions** pop-up opens. Click **Manage extensions**. -1. Go to `edge://extensions`. + Or, select **Settings and more** (![The "Settings and more" icon](./extension-sideloading-images/settings-and-more-icon.png)) > **Extensions** > **Manage extensions**. -1. Click the **Reload** button for the sideloaded extension. The updated extension is reloaded. + The **Extensions** management tab is displayed. + +1. Click the **Reload** link in the extension's card. + +1. Refresh the webpage. This is sometimes required after reloading an extension. @@ -74,14 +97,42 @@ To update an extension that's been installed locally (sideloaded) in your browse To remove an extension that's been installed locally (sideloaded) in your browser: -1. Go to `edge://extensions`. +1. In Microsoft Edge, if the **Extensions** management tab is open, click it. + + Or, to the right of the Address bar, if this icon is displayed, click the **Extensions** (![Extensions icon](./extension-sideloading-images/extensions-icon.png)) button. The **Extensions** pop-up opens. Click **Manage extensions**. + + Or, select **Settings and more** (![The "Settings and more" icon](./extension-sideloading-images/settings-and-more-icon.png)) > **Extensions** > **Manage extensions**. + + The **Extensions** management tab is displayed. + +1. Click the **Remove** link in the extension's card. + + + +## Error reporting in the Extensions management page + +If running an extension causes an error, in some cases, an **Error** link is added in the extension's card in the **Extensions** management page between the **Remove** and **Reload** links. + +1. In Microsoft Edge, if the **Extensions** management tab is open, click it. + + Or, to the right of the Address bar, if this icon is displayed, click the **Extensions** (![Extensions icon](./extension-sideloading-images/extensions-icon.png)) button. The **Extensions** pop-up opens. Click **Manage extensions**. + + Or, select **Settings and more** (![The "Settings and more" icon](./extension-sideloading-images/settings-and-more-icon.png)) > **Extensions** > **Manage extensions**. + + The **Extensions** management tab is displayed. + +1. Click the **Error** link in the extension's card. + +1. Fix the error in the extension's code. + +1. In the **Extensions** management page, click the **Reload** link. -1. On the extension, click **Remove**. +1. To make the **Error** link in the extension's card go away, in the **Extensions** management page, click the **Clear errors** button. ## See also -* [Sample: Display an image in a pop-up](./part1-simple-extension.md) -* [Sample: Insert an image in the webpage](./part2-content-scripts.md) +* [Sample: Picture viewer pop-up webpage](./picture-viewer-popup-webpage.md) +* [Sample: Picture inserter using content script](./picture-inserter-content-script.md) diff --git a/microsoft-edge/extensions-chromium/getting-started/index.md b/microsoft-edge/extensions-chromium/getting-started/index.md index c4be31e8b3..b593d0aa1c 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 [Sample: Display an image in a pop-up](part1-simple-extension.md). +Next, install, run, and study [Sample: Picture viewer pop-up webpage](./picture-viewer-popup-webpage.md). 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 deleted file mode 100644 index ccc46691e7..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extension-running.png and /dev/null 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 deleted file mode 100644 index 7c64d37706..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup-with-launch-icon.png and /dev/null 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 deleted file mode 100644 index e92681a89d..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup.png and /dev/null 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 deleted file mode 100644 index 1571d40200..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/icon-png-toolbar.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 deleted file mode 100644 index 1faba70da3..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/part1-installed-extension.png and /dev/null 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 deleted file mode 100644 index e881220614..0000000000 --- a/microsoft-edge/extensions-chromium/getting-started/part1-simple-extension.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -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: 01/13/2025 ---- -# Sample: Display an image in a pop-up - -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) - - - -## 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**. - - 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-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. - - - - - -## 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](./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: - - ![The Extensions popup when no extensions are installed](./part1-simple-extension-images/extensions-popup-no-extensions.png) - -1. Click **Manage extensions**. The **Extensions** management page opens in a new tab: - - ![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) - - - -## 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) - - - -## 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: - -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: - -```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" - } -} -``` - - - -## 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 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) -* [Sample: Insert an image in the webpage](./part2-content-scripts.md) - -GitHub: -* [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. - * [/part1/](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part1/part1) - source code of the Part 1 sample. 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 deleted file mode 100644 index b4caf5a41e..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/developermode-toggle.png and /dev/null 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 deleted file mode 100644 index 3c687c5143..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/extensions-popup-no-extensions.png and /dev/null 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 deleted file mode 100644 index ada8e5a426..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/open-the-extension.png and /dev/null 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 deleted file mode 100644 index fd1a693cfc..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-installed-extension.png and /dev/null 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 deleted file mode 100644 index 2d9d5360e7..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-popupdialog.png and /dev/null 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 deleted file mode 100644 index 139e71285f..0000000000 Binary files a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/part2-showingimage.png and /dev/null 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 deleted file mode 100644 index aa78fbce0b..0000000000 --- a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts.md +++ /dev/null @@ -1,452 +0,0 @@ ---- -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: 01/13/2025 ---- -# Sample: Insert an image in the webpage - -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: - -* 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) - -The extension displays a small HTML page in a pop-up, containing a title, instructions, and a **Display** button: - -![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 the static image `stars.jpeg` in the top of the current webpage: - -![The image showing in browser](./part2-content-scripts-images/part2-showingimage.png) - -When you click the image, the injected JavaScript removes the image from the DOM tree and webpage. - -Obtain, install, and run the sample as follows. - - - -## 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](./part2-content-scripts-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**. - - 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 - - - - - - - -

Display the NASA picture of the day

-

(click the image to remove it from the webpage)

- - - - -``` - -The **Display** button is added by the above code. - - - -## JavaScript (`popup.js`) for the initial pop-up page, to send a message to the injected JavaScript - -`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`: - -`/popup/popup.js` (portion): - -```javascript -const sendMessageId = document.getElementById("sendmessageid"); -if (sendMessageId) { - sendMessageId.onclick = function() { - // do something - }; -} -``` - -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 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 sample also passes in the current tab ID, which is described later in this article: - -`/popup/popup.js` (complete): - -```javascript -const sendMessageId = document.getElementById("sendmessageid"); -if (sendMessageId) { - sendMessageId.onclick = function() { - chrome.tabs.query({ active: true, currentWindow: true }, function(tabs) { - chrome.tabs.sendMessage( - tabs[0].id, - { - url: chrome.runtime.getURL("images/stars.jpeg"), - imageDivId: `${guidGenerator()}`, - tabId: tabs[0].id - }, - function(response) { - window.close(); - } - ); - function guidGenerator() { - const S4 = function () { - return (((1 + Math.random()) * 0x10000) | 0).toString(16).substring(1); - }; - return (S4() + S4() + "-" + S4() + "-" + S4() + "-" + S4() + "-" + S4() + S4() + S4()); - } - }); - }; -} -``` - - - -## The content script message listener (`content.js`) - -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`: - -```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" }); -}); -``` - -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. - -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. - -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): - -```json -"web_accessible_resources": [ - { - "resources": ["images/*.jpeg"], - "matches": [""] - } - ] -``` - -The code in the `popup.js` file sends a message to the content page that's embedded in the current active tab page. - - - -## How resources are listed in the manifest (`manifest.json`) - -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): - -```json -{ - "name": "NASA picture of the day viewer", - "version": "0.0.0.1", - "manifest_version": 3, - "description": "An extension that uses JavaScript to insert an image at the top of the webpage.", - "icons": { - "16": "icons/nasapod16x16.png", - "32": "icons/nasapod32x32.png", - "48": "icons/nasapod48x48.png", - "128": "icons/nasapod128x128.png" - }, - "action": { - "default_popup": "popup/popup.html" - }, - "content_scripts": [ - { - "matches": [ - "" - ], - "js": ["lib/jquery.min.js","content-scripts/content.js"] - } - ], - "web_accessible_resources": [ - { - "resources": ["images/*.jpeg"], - "matches": [""] - } - ] -} -``` - - - -#### The manifest's `content_scripts` section injects JavaScript into all browser tabs - -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 this sample, the following files are specified: -* `content-scripts/content.js` -* `lib/jquery.min.js` - - - -#### How jQuery support is added (`jquery.min.js`) - -`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`. - -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. - - - -#### Understanding the thread - -Each tab page (and extension) runs in its own thread. - -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. - - - -## 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. - - - -## See also - - -* [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: -* [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. - * [/extension-getting-started-part2/](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2) - source code of the Part 2 sample. 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/picture-inserter-content-script-images/clone-a-repo-dbox-ghd.png similarity index 100% rename from microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/clone-a-repo-dbox-ghd.png rename to microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/clone-a-repo-dbox-ghd.png diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/current-webpage-with-image-inserted.png b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/current-webpage-with-image-inserted.png new file mode 100644 index 0000000000..089c9467ef Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/current-webpage-with-image-inserted.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/developermode-toggle.png b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/developermode-toggle.png new file mode 100644 index 0000000000..968e3ff4f4 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/developermode-toggle.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/picture-inserter-content-script-images/extensions-icon.png similarity index 100% rename from microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-icon.png rename to microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/extensions-icon.png diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/extensions-popup-no-extensions.png b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/extensions-popup-no-extensions.png new file mode 100644 index 0000000000..d1c9b635c9 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/extensions-popup-no-extensions.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/installed-extension.png b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/installed-extension.png new file mode 100644 index 0000000000..c002d4ef51 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/installed-extension.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/picture-inserter-content-script-images/load-unpacked-icon.png similarity index 100% rename from microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/load-unpacked-icon.png rename to microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/load-unpacked-icon.png diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/open-the-extension.png b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/open-the-extension.png new file mode 100644 index 0000000000..4202136032 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/open-the-extension.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/popup-webpage.png b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/popup-webpage.png new file mode 100644 index 0000000000..741fdbca55 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/popup-webpage.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/settings-and-more-icon.png b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/settings-and-more-icon.png new file mode 100644 index 0000000000..69fd7b1251 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script-images/settings-and-more-icon.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script.md b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script.md new file mode 100644 index 0000000000..ec4ac8633e --- /dev/null +++ b/microsoft-edge/extensions-chromium/getting-started/picture-inserter-content-script.md @@ -0,0 +1,524 @@ +--- +title: "Sample: Picture inserter using content script" +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: 01/16/2025 +--- +# Sample: Picture inserter using content script + + + + +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 **Insert picture**. When you click the **Insert picture** 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: + +* 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 install the extension sample by using the browser's **Manage Extensions** tab, click the **Extensions** (![Extensions icon](./picture-inserter-content-script-images/extensions-icon.png)) button to show the list of installed extensions, and then click this sample extension: + +![Clicking the extension's icon to open the extension](./picture-inserter-content-script-images/open-the-extension.png) + +The extension displays a small HTML webpage in a pop-up, containing a title, an **Insert picture** button, and instructions: + +![popup.html display after selecting the Extension icon](./picture-inserter-content-script-images/popup-webpage.png) + +When you click the **Insert picture** 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](./picture-inserter-content-script-images/current-webpage-with-image-inserted.png) + +When you click the image, the injected JavaScript removes the image from the DOM tree and webpage. + +Obtain, install, and run the sample as follows. + + + + +## 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. + +Clone the **MicrosoftEdge-Extensions** repo to your local drive, and then switch to a working branch, as follows. + + +##### [git bash command prompt](#tab/gitbash) + +1. In a command prompt, enter `git` to check whether git is installed. + +1. If not done yet, [download git](https://git-scm.com/downloads) and install it. + +1. If not done yet, start a command prompt where git is installed. + +1. Change to the directory where you want to clone the **MicrosoftEdge-Extensions** repo to. For example: + + ``` + cd C:/Users/localAccount/GitHub/ + ``` + +1. In Microsoft Edge, go to the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. + +1. Click the down-arrow on the right side of the green **Code** button, and then in the **Clone using the web URL** section, click the **Copy url to clipboard** button next to `https://github.com/microsoft/MicrosoftEdge-Extensions.git`. + +1. In the command prompt window, enter the command: + + ``` + git clone https://github.com/microsoft/MicrosoftEdge-Extensions.git + ``` + + The `/MicrosoftEdge-Extensions/` directory is added within the directory that you specified. + + + +#### Create a working branch and switch to it + +1. Check the list of directories: + + ``` + ls + ``` + + The `/MicrosoftEdge-Extensions/` directory is listed. + +1. Switch to the new directory: + + ``` + cd MicrosoftEdge-Extensions + ``` + +1. Create a working branch: + + ``` + git branch test + ``` + +1. Switch to the working branch: + + ``` + git switch test + ``` + + Returns: `Switched to branch 'test'` + +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. + + +##### [GitHub Desktop](#tab/githubdesktop) + +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 the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. + +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](./picture-viewer-popup-webpage-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 a working branch and switch to it + +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 **test**, and then click the **Create branch** button. + + In the upper middle and lower left of GitHub Desktop, the current branch is shown, such as **test**. + +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](./picture-inserter-content-script-images/extensions-icon.png)) button, next to the Address bar, if this icon is displayed. Or, select **Settings and more** (![The "Settings and more" icon](./picture-inserter-content-script-images/settings-and-more-icon.png)) > ![Extensions icon](./picture-inserter-content-script-images/extensions-icon.png) **Extensions**. The **Extensions** pop-up opens: + + ![The Extensions pop-up when no extensions are installed](./picture-inserter-content-script-images/extensions-popup-no-extensions.png) + +1. Click **Manage extensions**. The **Extensions** management page opens in a new tab: + + ![Turning on Developer Mode](./picture-inserter-content-script-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](./picture-inserter-content-script-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\picture-inserter-content-script` + +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](./picture-inserter-content-script-images/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. Refresh the webpage. This is sometimes required after reloading an extension. + +1. In Microsoft Edge to the right of the Address bar, if this icon is displayed, click the **Extensions** (![Extensions icon](./picture-inserter-content-script-images/extensions-icon.png)) button. Or, select **Settings and more** (![The "Settings and more" icon](./picture-inserter-content-script-images/settings-and-more-icon.png)) > **Extensions**. + + The **Extensions** pop-up opens: + + ![Clicking the extension's icon to open the extension](./picture-inserter-content-script-images/open-the-extension.png) + +1. Click the extension's icon or name (**Picture inserter using content script**). + + The extension opens, and the extension's icon is added next to the Address bar and **Extensions** (![Extensions icon](./picture-inserter-content-script-images/extensions-icon.png)) icon. + + A pop-up opens, containing a small HTML webpage with a title, an **Insert picture** button, and instructions: + + ![popup.html after clicking the Extension's icon](./picture-inserter-content-script-images/popup-webpage.png) + +1. Click the **Insert picture** 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](./picture-inserter-content-script-images/current-webpage-with-image-inserted.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\picture-inserter-content-script` + +Directories and files in the `/picture-inserter-content-script/` directory: + +```shell +/content-scripts/ + content.js +/icons/ + extension-icon16x16.png + extension-icon32x32.png + extension-icon48x48.png + extension-icon128x128.png +/images/ + stars.jpeg +/popup/ + popup.html + popup.js +manifest.json +``` + +* The `/content-scripts/` directory contains `content.js`, which is the 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, in the **Extensions** pop-up, and in the **Extensions** management page. +* The `/images/` directory contains `stars.jpeg`, which is displayed in the extension's pop-up. +* The `/popup/` directory contains the files: + * `popup.html` defines the content in the extension's initial pop-up webpage (a title, button, and instructions). + * `popup.js` for the initial pop-up webpage sends a message to the content script (`content.js`) that's running on the tab page, specifying which image file to display. +* `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 pop-up HTML page is displayed (`popup.html`), showing a title, instructions, and the **Insert picture** button. + +1. When you click the **Insert picture** button, the JavaScript (`popup.js`) for the initial pop-up page sends a message to the content script (`content.js`) that's running on the tab page. The message specifies which image file to display. + +1. The content script (`content.js`) running on the tab page receives the message, and displays the specified image file (`stars.jpeg`). + + + +## The initial pop-up webpage (`popup.html`) + +`/popup/popup.html` is specified in the manifest file as the webpage to display in the extension's initial pop-up. 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, an **Insert picture** button, and instructions. + +`popup.html`: + +```html + + + + + + + +

Picture inserter using a content script

+ + +

Click the displayed image to remove it from the webpage.

+ + +``` + + + +## JavaScript (`popup.js`) for the initial pop-up page, to send a message to the injected JavaScript + +`/popup/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 **Insert picture** button, which has the ID `sendmessageid`: + +`popup.js` (portion): + +```javascript +const sendMessageId = document.getElementById("sendmessageid"); +if (sendMessageId) { + sendMessageId.onclick = function() { + ... + }; +} +``` + +In `popup.js`, `chrome.tabs.query` finds the current browser tab, and then `chrome.tabs.sendMessage` sends a message to that tab. The sample passes in the current tab's ID. The message must include the URL for the image that will be displayed. + +You must send a unique ID to assign to the inserted image, in order to find the image element again later and delete it. To send a unique ID to assign to the inserted image, the unique ID is generated in `popup.js` and passed to the content script. + +`popup.js` (complete): + +```javascript +const sendMessageId = document.getElementById("sendmessageid"); +if (sendMessageId) { + sendMessageId.onclick = function() { + chrome.tabs.query({ active: true, currentWindow: true }, function(tabs) { + chrome.tabs.sendMessage( + tabs[0].id, + { + url: chrome.runtime.getURL("images/stars.jpeg"), + imageDivId: crypto.randomUUID(), + tabId: tabs[0].id + }, + function(response) { + window.close(); + } + ); + }); + }; +} +``` + + + +## The content script message listener (`content.js`) + +Here's the `content-scripts\content.js` file that gets injected into every browser tab page. This file is listed in the `content-scripts` section in `manifest.json`. + +`content.js` (complete): + +```javascript +chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) { + const img = document.createElement("img"); + img.id = request.imageDivId; + img.src = request.url; + img.style = "height: auto; width: 90vw;"; + document.body.prepend(img); + + img.addEventListener("click", () => { + img.remove(); + }, { once: true }); + + sendResponse({ fromcontent: "This message is from content.js" }); +}); +``` + +`content.js` registers a listener by using the `chrome.runtime.onMessage.addListener` Extension API method. This listener waits for the message that's sent when `popup.js` calls `chrome.tabs.sendMessage`. + +In `content.js`, the `addListener` method takes a single parameter that's a function. That function's first parameter, `request`, contains the details of the message that's being passed in. + +In `content.js`, when an event is processed by the listener, the listener function that's passed into `addListener` is run. The first parameter of the passed-in listener function is a `request` object that has attributes as assigned by `sendMessage`. + +In `popup.js`, for the `chrome.tabs.sendMessage` method call, the attributes of the second parameter for `sendMessage` are `url`, `imageDivId`, and `tabId`. + +Here's the isolated listener function that's passed into `addListener`: + +`content.js` (portion) + +```javascript +function(request, sender, sendResponse) { + const img = document.createElement("img"); + img.id = request.imageDivId; + img.src = request.url; + img.style = "height: auto; width: 90vw;"; + document.body.prepend(img); + + img.addEventListener("click", () => { + img.remove(); + }, { once: true }); + + sendResponse({ fromcontent: "This message is from content.js" }); +} +``` + +The first five lines in the listener function append an `img` element immediately below the `body` element in the browser tab. + +The second line in the listener function, `img.id = request.imageDivId;`, sets the ID of the `img` element to the `imageDivId` of the passed-in request. + +In the listener function, the `addEventListener` call adds a `click` event listener function that covers the entire image, allowing the user to click anywhere on the image. When you click the inserted image, the image is removed from the current webpage by the line `img.remove();`, and the event listener is also removed, by specifying `{ once: true }`. + + + +## 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. + +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): + +```json +"web_accessible_resources": [ + { + "resources": ["images/*.jpeg"], + "matches": [""] + } + ] +``` + +The code in the `popup.js` file sends a message to the content page that's embedded in the current active tab page. + + + +## How resources are listed in the manifest (`manifest.json`) + +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): + +```json +{ + "name": "Picture inserter using content script", + "version": "0.0.0.1", + "manifest_version": 3, + "description": "A browser extension that uses JavaScript to insert an image at the top of the current webpage.", + "icons": { + "16": "icons/extension-icon16x16.png", + "32": "icons/extension-icon32x32.png", + "48": "icons/extension-icon48x48.png", + "128": "icons/extension-icon128x128.png" + }, + "action": { + "default_popup": "popup/popup.html" + }, + "content_scripts": [ + { + "matches": [ + "" + ], + "js": ["content-scripts/content.js"] + } + ], + "web_accessible_resources": [ + { + "resources": ["images/*.jpeg"], + "matches": [""] + } + ] +} +``` + + + +## The manifest's `content_scripts` section injects JavaScript into all browser tabs + +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`). + +This sample's manifest specifies a single content script, `content-scripts/content.js`. + + + +## Each content script runs in its own thread, sandboxed + +Each tab page (and extension) runs in its own thread. 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. + + + +## 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. + + + +## See also + + +* [Sample: Picture viewer pop-up webpage](./picture-viewer-popup-webpage.md) +* [Sideload an extension to install and test it locally](extension-sideloading.md) + +GitHub: +* [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. + * [/picture-inserter-content-script/](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/picture-inserter-content-script) - source code of this sample. 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/picture-viewer-popup-webpage-images/clone-a-repo-dbox-ghd.png similarity index 100% rename from microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/clone-a-repo-dbox-ghd.png rename to microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/clone-a-repo-dbox-ghd.png diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/developermode-toggle.png b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/developermode-toggle.png new file mode 100644 index 0000000000..a0cf6d91d4 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/developermode-toggle.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extension-running.png b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extension-running.png new file mode 100644 index 0000000000..b0e3e1aa07 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extension-running.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/extensions-icon.png b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extensions-icon.png similarity index 100% rename from microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/extensions-icon.png rename to microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extensions-icon.png 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/picture-viewer-popup-webpage-images/extensions-popup-no-extensions.png similarity index 100% rename from microsoft-edge/extensions-chromium/getting-started/part1-simple-extension-images/extensions-popup-no-extensions.png rename to microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extensions-popup-no-extensions.png diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extensions-popup-with-launch-icon.png b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extensions-popup-with-launch-icon.png new file mode 100644 index 0000000000..d3f0add946 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extensions-popup-with-launch-icon.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extensions-popup.png b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extensions-popup.png new file mode 100644 index 0000000000..9568c7f185 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/extensions-popup.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/icon-png-toolbar.png b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/icon-png-toolbar.png new file mode 100644 index 0000000000..ecf37746c3 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/icon-png-toolbar.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/installed-extension.png b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/installed-extension.png new file mode 100644 index 0000000000..b4da5bde11 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/installed-extension.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/picture-viewer-popup-webpage-images/load-unpacked-icon.png similarity index 100% rename from microsoft-edge/extensions-chromium/getting-started/part2-content-scripts-images/load-unpacked-icon.png rename to microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/load-unpacked-icon.png diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/settings-and-more-icon.png b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/settings-and-more-icon.png new file mode 100644 index 0000000000..69fd7b1251 Binary files /dev/null and b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage-images/settings-and-more-icon.png differ diff --git a/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage.md b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage.md new file mode 100644 index 0000000000..fc44f3b4de --- /dev/null +++ b/microsoft-edge/extensions-chromium/getting-started/picture-viewer-popup-webpage.md @@ -0,0 +1,336 @@ +--- +title: "Sample: Picture viewer pop-up webpage" +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: 01/16/2025 +--- +# Sample: Picture viewer pop-up webpage + + + + +This sample is a browser extension, without JavaScript, that displays the `stars.jpeg` image in a small webpage in a pop-up in any Microsoft Edge tab: + +![The "Picture viewer pop-up webpage" extension running](./picture-viewer-popup-webpage-images/extension-running.png) + + + + +## 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. + +Clone the **MicrosoftEdge-Extensions** repo to your local drive, and then switch to a working branch, as follows. + + +##### [git bash command prompt](#tab/gitbash) + +1. In a command prompt, enter `git` to check whether git is installed. + +1. If not done yet, [download git](https://git-scm.com/downloads) and install it. + +1. If not done yet, start a command prompt where git is installed. + +1. Change to the directory where you want to clone the **MicrosoftEdge-Extensions** repo to. For example: + + ``` + cd C:/Users/localAccount/GitHub/ + ``` + +1. In Microsoft Edge, go to the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. + +1. Click the down-arrow on the right side of the green **Code** button, and then in the **Clone using the web URL** section, click the **Copy url to clipboard** button next to `https://github.com/microsoft/MicrosoftEdge-Extensions.git`. + +1. In the command prompt window, enter the command: + + ``` + git clone https://github.com/microsoft/MicrosoftEdge-Extensions.git + ``` + + The `/MicrosoftEdge-Extensions/` directory is added within the directory that you specified. + + + +#### Create a working branch and switch to it + +1. Check the list of directories: + + ``` + ls + ``` + + The `/MicrosoftEdge-Extensions/` directory is listed. + +1. Switch to the new directory: + + ``` + cd MicrosoftEdge-Extensions + ``` + +1. Create a working branch: + + ``` + git branch test + ``` + +1. Switch to the working branch: + + ``` + git switch test + ``` + + Returns: `Switched to branch 'test'` + +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. + + +##### [GitHub Desktop](#tab/githubdesktop) + +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 the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. + +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](./picture-viewer-popup-webpage-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 a working branch and switch to it + +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 **test**, and then click the **Create branch** button. + + In the upper middle and lower left of GitHub Desktop, the current branch is shown, such as **test**. + +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](./picture-viewer-popup-webpage-images/extensions-icon.png)) button, next to the Address bar, if this icon is displayed. Or, select **Settings and more** (![The "Settings and more" icon](./picture-viewer-popup-webpage-images/settings-and-more-icon.png)) > **Extensions**. The **Extensions** pop-up opens: + + ![The Extensions pop-up when no extensions are installed](./picture-viewer-popup-webpage-images/extensions-popup-no-extensions.png) + +1. Click **Manage extensions**. The **Extensions** management page opens in a new tab: + + ![Turning on Developer Mode](./picture-viewer-popup-webpage-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](./picture-viewer-popup-webpage-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\picture-viewer-popup-webpage` + +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](./picture-viewer-popup-webpage-images/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. 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. Refresh the webpage. This is sometimes required after reloading an extension. + +1. In Microsoft Edge to the right of the Address bar, if this icon is displayed, click the **Extensions** (![Extensions icon](./picture-viewer-popup-webpage-images/extensions-icon.png)) button. Or, select **Settings and more** (![The "Settings and more" icon](./picture-viewer-popup-webpage-images/settings-and-more-icon.png)) > **Extensions**. + + The **Extensions** pop-up opens: + + ![The Extensions pop-up](./picture-viewer-popup-webpage-images/extensions-popup.png) + +1. Click the extension's icon or name (**Picture viewer pop-up webpage**). + + The extension opens, and the extension's icon is added next to the Address bar and **Extensions** (![Extensions icon](./picture-viewer-popup-webpage-images/extensions-icon.png)) icon. The extension displays `popup.html`, containing `stars.jpeg`, in a pop-up: + + ![The simple extension running](./picture-viewer-popup-webpage-images/extension-running.png) + +1. Click the extension's button next to the Address bar. The pop-up window closes. + +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: + +Example path for the sample: + +`C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-viewer-popup-webpage` + +Directories and files in the `/picture-viewer-popup-webpage/` directory: + +```shell +/icons/ + extension-icon16x16.png + extension-icon32x32.png + extension-icon48x48.png + extension-icon128x128.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": "Picture viewer pop-up webpage", + "version": "0.0.0.1", + "manifest_version": 3, + "description": "A browser extension that displays an image in a pop-up webpage.", + "icons": { + "16": "icons/extension-icon16x16.png", + "32": "icons/extension-icon32x32.png", + "48": "icons/extension-icon48x48.png", + "128": "icons/extension-icon128x128.png" + }, + "action": { + "default_popup": "popup/popup.html" + } +} +``` + + + +## 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](./picture-viewer-popup-webpage-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](./picture-viewer-popup-webpage-images/icon-png-toolbar.png) + +To close the extension, click the extension's icon on the toolbar, or click the **Extensions** (![Extensions icon](./picture-viewer-popup-webpage-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 + + + + Picture viewer pop-up webpage + + +
+ Stars +
+ + +``` + +The pop-up webpage (`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 this extension sample, you can continue on to [Sample: Picture inserter using content script](./picture-inserter-content-script.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) +* [Sample: Picture inserter using content script](./picture-inserter-content-script.md) + +GitHub: +* [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo. + * [/picture-viewer-popup-webpage/](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/picture-viewer-popup-webpage) - source code of this sample. diff --git a/microsoft-edge/extensions-chromium/landing/index.yml b/microsoft-edge/extensions-chromium/landing/index.yml index 1e3778b123..a92a7661bd 100644 --- a/microsoft-edge/extensions-chromium/landing/index.yml +++ b/microsoft-edge/extensions-chromium/landing/index.yml @@ -49,11 +49,11 @@ landingContent: - text: Extension concepts and architecture url: ../getting-started/index.md - - text: "Sample: Display an image in a pop-up" - url: ../getting-started/part1-simple-extension.md + - text: "Sample: Picture viewer pop-up webpage" + url: ../getting-started/picture-viewer-popup-webpage.md - - text: "Sample: Insert an image in the webpage" - url: ../getting-started/part2-content-scripts.md + - text: "Sample: Picture inserter using content script" + url: ../getting-started/picture-inserter-content-script.md - text: Sideload an extension to install and test it locally url: ../getting-started/extension-sideloading.md diff --git a/microsoft-edge/index.yml b/microsoft-edge/index.yml index 6f998a9c84..44a8913a08 100644 --- a/microsoft-edge/index.yml +++ b/microsoft-edge/index.yml @@ -257,8 +257,8 @@ conceptualContent: url: ./extensions-chromium/publish/create-dev-account.md itemType: how-to-guide - - text: "Sample: Display an image in a pop-up" - url: ./extensions-chromium/getting-started/part1-simple-extension.md + - text: "Sample: Picture viewer pop-up webpage" + url: ./extensions-chromium/getting-started/picture-viewer-popup-webpage.md itemType: how-to-guide # ----------------------------------------------------------------------------- diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index ca73c3bba7..3a359a08c0 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -1012,11 +1012,11 @@ - name: Extension concepts and architecture href: extensions-chromium/getting-started/index.md - - name: "Sample: Display an image in a pop-up" - href: extensions-chromium/getting-started/part1-simple-extension.md + - name: "Sample: Picture viewer pop-up webpage" + href: extensions-chromium/getting-started/picture-viewer-popup-webpage.md - - name: "Sample: Insert an image in the webpage" - href: extensions-chromium/getting-started/part2-content-scripts.md + - name: "Sample: Picture inserter using content script" + href: extensions-chromium/getting-started/picture-inserter-content-script.md - name: Sideload an extension to install and test it locally href: extensions-chromium/getting-started/extension-sideloading.md