Skip to content

Commit df0477d

Browse files
mikehoffmsmikehoffms
committed
half restructured sample 2
1 parent 32fd63b commit df0477d

1 file changed

Lines changed: 94 additions & 52 deletions

File tree

‎microsoft-edge/extensions-chromium/getting-started/part2-content-scripts.md‎

Lines changed: 94 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,24 @@
11
---
22
title: "Sample: Insert an image in the webpage"
3-
description: Dynamically inserting a NASA picture below the page body tag by using content scripts.
3+
description: Uses JavaScript to insert a .png file below the <body> start-tag of the current webpage.
44
author: MSEdgeTeam
55
ms.author: msedgedevrel
66
ms.topic: conceptual
77
ms.service: microsoft-edge
88
ms.subservice: extensions
9-
ms.date: 10/04/2024
9+
ms.date: 12/03/2024
1010
---
1111
# Sample: Insert an image in the webpage
1212

13-
The [Part 2 sample: Use JavaScript to insert an image in the webpage](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2) uses JavaScript code to insert the `stars.jpeg` image into the top of the currently opened webpage. The extension's pop-up contains a title and an HTML button that's labelled **Display**. When you click the **Display** button, JavaScript sends a message from the extension icon's pop-up, and dynamically inserts JavaScript running as content in the browser tab.
13+
This sample uses JavaScript code to insert the `stars.jpeg` image into the top of the current webpage, below the `<body>` start-tag. The extension's pop-up contains a title and an HTML button that's labelled **Display**. When you click the **Display** button, JavaScript sends a message from the extension icon's pop-up, and dynamically inserts JavaScript running as content in the browser tab.
1414

15-
The Part 2 sample uses the following extension technologies:
15+
This sample uses the following extension technologies:
1616
* Injecting JavaScript libraries into an extension.
1717
* Exposing extension assets to browser tabs.
1818
* Including content webpages in existing browser tabs.
1919
* Having content webpages listen for messages from pop-ups and respond.
2020

21-
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:
21+
As a 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:
2222

2323
![Clicking the extension's icon to open the extension](./part2-content-scripts-images/open-the-extension.png)
2424

@@ -30,32 +30,99 @@ When you click the **Display** button, JavaScript code temporarily inserts `star
3030

3131
![The image showing in browser](./part2-content-scripts-images/part2-showingimage.png)
3232

33-
If you want to immediately install and run the completed extension, or view its finished code, either:
34-
* Clone the [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions) repo to your local drive. Use repo directory `/extension-getting-started-part2/`.
35-
* Download the source code from the [/extension-getting-started-part2/](https://github.com/microsoft/MicrosoftEdge-Extensions/tree/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2) folder of the MicrosoftEdge-Extensions repo.
33+
Obtain and run the sample as follows.
3634

37-
Then you can install and run the finished extension that's in the repo, per [Sideload an extension to install and test it locally](extension-sideloading.md). The tab must contain a webpage before opening the extension.
35+
36+
<!-- ====================================================================== -->
37+
## Clone the MicrosoftEdge-Extensions repo
38+
39+
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.
40+
41+
To clone the `MicrosoftEdge-Extensions` repo to your local drive:
42+
43+
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.
44+
45+
1. Go to [MicrosoftEdge-Extensions](https://github.com/microsoft/MicrosoftEdge-Extensions).
46+
47+
1. Click the **Code** button, and then select **Open with GitHub Desktop**.
48+
49+
A dialog opens, saying **This site is trying to open GitHubDesktop.exe.**
50+
51+
1. Click the **Open** button.
52+
53+
GitHub Desktop opens, with the **MicrosoftEdge-Extensions** repo selected in the upper left dropdown list.
54+
55+
1. In GitHub Desktop, click the **Branch** menu, and then click **New branch**.
56+
57+
The **Create a branch** dialog opens.
58+
59+
1. In the **Name** text box, enter a branch name, such as **ext-sample-1**, and then click the **Create branch** button.
60+
61+
In the upper middle and lower left of GitHub Desktop, the current branch is shown, such as **ext-sample-1**.
62+
63+
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.
64+
65+
<!-- See also: -->
66+
<!-- * [Step 2: Create a branch](https://docs.github.com/en/get-started/start-your-journey/hello-world#step-2-create-a-branch) in _Hello World_. -->
67+
68+
69+
<!-- ====================================================================== -->
70+
## Install the sample locally
71+
72+
<!-- todo: inline steps to install -->
73+
74+
75+
76+
<!-- ====================================================================== -->
77+
## Run the sample
78+
79+
80+
<!-- todo: inline steps to run -->
81+
Do the steps in [Sideload an extension to install and test it locally](extension-sideloading.md) to locally update the extension and then run the extension. The tab must contain a webpage before opening the extension.
82+
83+
A pop-up opens, containing a small HTML page with a title, instructions, and a **Display** button:
84+
85+
![popup.html after clicking the Extension's icon](./part2-content-scripts-images/part2-popupdialog.png)
86+
87+
88+
1. Install or update the extension, in the Manage Extensions page; see [Sideload an extension to install and test it locally](extension-sideloading.md).
89+
90+
1. Go to a webpage, such as [Microsoft.com](https://www.microsoft.com), in a new window or tab. The tab must not be empty, and must not be the Manage Extensions page.
91+
92+
1. Click the **Extensions** (![Extensions icon](./part2-content-scripts-images/extensions-icon.png)) button, next to the Address bar. Or, select **Settings and more** (...) > **Extensions**.
93+
94+
![Clicking the extension's icon to open the extension](./part2-content-scripts-images/open-the-extension.png)
95+
96+
1. Click the icon or name of the **NASA picture of the day viewer** extension.
97+
98+
The extension's pop-up opens:
99+
100+
![popup.html display after selecting the Extension icon](./part2-content-scripts-images/part2-popupdialog.png)
101+
102+
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:
103+
104+
![The image showing in browser](./part2-content-scripts-images/part2-showingimage.png)
105+
106+
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.
107+
108+
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.
38109

39110

40111
<!-- ====================================================================== -->
41-
## Step 1: Update popup.html to include a button
112+
## Files and directories
42113

43-
To use this article, first do the steps in [Sample: Display an image in a pop-up](./part1-simple-extension.md); that is, clone the MicrosoftEdge-Extensions repo, install the Part 1 demo, and run that demo.
44114

45-
This step has already been done in [popup.html](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/popup/popup.html) in the MicrosoftEdge-Extensions repo.
46115

47-
The hypothetical starting state for this Part 2 article, if you were to manually build-up the sample to add JavaScript, is that a directory exists for the part 2 code, containing the same directories and files that are created in the Part 1 article. These can be sibling directories for Part 1 and Part 2, as done in the MicrosoftEdge-Extensions repo.
116+
<!-- ====================================================================== -->
117+
<!-- SORT/MERGE INTO ABOVE SECTIONS -->
48118

49-
It's possible to install the completed Part 1 and Part 2 demos from the MicrosoftEdge-Extensions repo, side-by-side. We recommend first cloning the repo and installing and running the demos, before (or instead of) starting with an empty directory and then manually creating directories, creating files, and pasting code into the files.
50119

51-
To manually expand the completed Part 1 demo to create the Part 2 demo, you would need to do the following:
52-
1. In the folder that contains the `popup.html` file for Part 2 (initially a copy of the Part 1 file), add tagging that displays a title with a button.
53-
1. Include a reference to a JavaScript file, `popup.js`.
54-
1. Program that button.
120+
<!-- ====================================================================== -->
121+
## The default initial popup webpage (`popup.html`)
55122

56-
Below is the sample HTML file:
123+
`popup.html` is specified in the manifest file as the initial, default webpage to display in the extension popup. This webpage contains a title, instructions, and a **Display** button.
57124

58-
`/popup/popup.html` (complete):
125+
`/popup/popup.html`:<!-- (complete listing) -->
59126

60127
```html
61128
<!DOCTYPE html>
@@ -85,12 +152,6 @@ Below is the sample HTML file:
85152
</html>
86153
```
87154

88-
Do the steps in [Sideload an extension to install and test it locally](extension-sideloading.md) to locally update the extension and then run the extension. The tab must contain a webpage before opening the extension.
89-
90-
After updating and opening the extension, a pop-up opens, containing a small HTML page with a title, instructions, and a **Display** button:
91-
92-
![popup.html after clicking the Extension's icon](./part2-content-scripts-images/part2-popupdialog.png)
93-
94155

95156
<!-- ====================================================================== -->
96157
## Step 2: Update the webpage to insert the image at the top
@@ -234,11 +295,13 @@ The `matches` attribute is set to `<all_urls>`, which means that all files in `c
234295
<!-- ------------------------------ -->
235296
#### Add jQuery
236297

237-
This step has already been done in [jquery.min.js](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/lib/jquery.min.js) in the MicrosoftEdge-Extensions repo.
298+
`jquery.min.js` is a predefined, minified file.
299+
300+
[jquery.min.js](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/lib/jquery.min.js) in the MicrosoftEdge-Extensions repo.
238301

239-
In the content scripts that you're injecting, plan on using jQuery (`$`). You added a minified version of jQuery and put it in your extension package as `lib\jquery.min.js`.
302+
In the content scripts that you're injecting, it's common to use jQuery (`$`). This sample includes a minified version of jQuery, residing in the extension package<!-- todo: check 'package' --> as `lib\jquery.min.js`.
240303

241-
These content scripts run in individual sandboxes, which means that the jQuery injected into the `popup.js` page isn't shared with the content.
304+
A content script runs in an individual sandbox, which means that the jQuery that's injected into the `popup.js` page isn't shared with the current webpage.
242305

243306

244307
<!-- ------------------------------ -->
@@ -251,11 +314,11 @@ Even if the browser tab has JavaScript running on it on the loaded web page, any
251314
<!-- ====================================================================== -->
252315
## Step 6: Add the content script message listener
253316

254-
To continue manually building-up the Part 2 demo, you would need to create this file. This step has already been done in [content.js](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/content-scripts/content.js) in the MicrosoftEdge-Extensions repo.
317+
[content.js](https://github.com/microsoft/MicrosoftEdge-Extensions/blob/main/Extension%20samples/extension-getting-started-part2/extension-getting-started-part2/content-scripts/content.js) in the MicrosoftEdge-Extensions repo.
255318

256319
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`:
257320

258-
`/content-scripts/content.js` (complete):
321+
`/content-scripts/content.js` (complete listing):
259322

260323
```javascript
261324
chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
@@ -294,27 +357,6 @@ When an event is processed by the listener, the function that is the first param
294357
<!-- ====================================================================== -->
295358
## Step 7: Install and test the extension
296359

297-
1. Install or update the extension, in the Manage Extensions page; see [Sideload an extension to install and test it locally](extension-sideloading.md).
298-
299-
1. Go to a webpage, such as [Microsoft.com](https://www.microsoft.com), in a new window or tab. The tab must not be empty, and must not be the Manage Extensions page.
300-
301-
1. Click the **Extensions** (![Extensions icon](./part2-content-scripts-images/extensions-icon.png)) button, next to the Address bar. Or, select **Settings and more** (...) > **Extensions**.
302-
303-
![Clicking the extension's icon to open the extension](./part2-content-scripts-images/open-the-extension.png)
304-
305-
1. Click the icon or name of the **NASA picture of the day viewer** extension.
306-
307-
The extension's pop-up opens:
308-
309-
![popup.html display after selecting the Extension icon](./part2-content-scripts-images/part2-popupdialog.png)
310-
311-
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:
312-
313-
![The image showing in browser](./part2-content-scripts-images/part2-showingimage.png)
314-
315-
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.
316-
317-
Congratulations! You've created an extension that sends a message from the extension icon's pop-up, and dynamically inserts JavaScript running as content in the browser tab. The injected content sets the image element to display `stars.jpeg` in the top of the current webpage, and then removes the image when you click the image.
318360

319361

320362
<!-- ====================================================================== -->

0 commit comments

Comments
 (0)