Add script-on-click example and related content

[rebloor]

Add a tutorial using script-on-click: an example of how to create a cross-browser MV3 extension example that uses a service worker on browsers that support it and an event page on browsers that do not support it (Firefox in particular).

The code sample was part of a presentation that shows this progression:

• background.scripts, works in Firefox (and Safari), code on slides available at script-on-click-1
• background.service_worker, works in Chrome (and Safari), code on slides available at script-on-click-2
• A single cross-browser manifest, works across all browsers, code already linked before at https://github.com/Rob--W/fosdem-2024-ext/tree/main/code-samples/script-on-click

Note on preferred_environment: Neither Firefox nor Safari requires background.preferred_environment, if both scripts and service_worker are specified, both browsers choose scripts. preferred_environment should only be used if the dev prefs to use service_worker where available. This behavior is documented in detail at https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background#browser_support.

...and if you need even more context on the design of the feature and the cross-browser behavior, there is more to read at https://github.com/w3c/webextensions/issues/282MDN Web Docsbackground - Mozilla | MDN Use the background key to include one or more background scripts, a background page, or a Service worker in your extension.

[danyalahmed1995]

I can take a pass at this.

Before opening a PR, would you prefer this to be added as a new standalone WebExtensions tutorial/example page, or folded into an existing page such as the background manifest documentation?

My current understanding is that the example should show a single MV3 manifest using both background.scripts and background.service_worker, while noting that background.preferred_environment is only needed when the author specifically wants to prefer the service worker where available.

[Adlinke]

Thanks for opening this and for the sample links — this looks useful.

Quick note on process for adding runnable examples to mdn/content:

• Please add the runnable demo to one of our approved hosts (CodeSandbox, jsFiddle, or our self-hosted sandbox) and include the demo id in examples/manifest.json.
• In the PR, either add a new standalone tutorial page or propose folding the example into the existing background manifest docs; maintainers will advise on placement.
• If you want help migrating the sample from the linked repo to an approved host, we can assist.

Labeling this needs triage and assigning a maintainer now.
Adila Linke

[danyalahmed1995]

I folded the content into the existing manifest.json/background documentation rather than creating a standalone tutorial page. The change documents the cross-browser MV3 pattern using both background.scripts and background.service_worker, and clarifies that background.preferred_environment is only needed when the author specifically wants to prefer service_worker where available.

[Rob--W]

For context - I wrote the description that ended up in the initial issue comment here. The examples as written were already ready for inclusion in mdn a few years ago, but I never got to do so because of the lack of time to come up with a good way to integrate in MDN. The main task here (which @rebloor would work on) is to come up with a good plan of getting it documented, in a way that is readable yet provides the opportunity for a deep dive for those who want to learn about it.

Upon seeing the proposed changes in mdn/content#44108 I see that it replaces the example that was added in mdn/content#30097 . That existing example covers the "how to write a cross-browser extension using a background script" aspect of the MDN documentation. I wouldn't add more unnecessary code (scripting/activeTab) in the content of the background key article itself to avoid information overload in what ought to demonstrate a cross-browser background page.

However, we lack an example in webextensions-examples that demonstrates a cross-browser way to run a content script on demand from the background script. To address that need, it would make sense to extract that existing example from mdn/content and include it in https://github.com/mdn/webextensions-examples .

I evaluated what we should do with script-on-click. Right now, what we have in terms of code execution examples:

• https://github.com/mdn/webextensions-examples/tree/main/beastify
  beastify is a MV3 example that calls scripting.executeScript from a browser action popup. By using the extension popup as a trigger, it side steps the question of how to create a cross-browser background page. A comparable example that avoids the background page in the same way is at https://github.com/Rob--W/fosdem-2024-ext/tree/main/code-samples/script-on-click-without-background . Back then some browsers did not load an extension that specified background.scripts and background.service_worker, so it made sense to have a way to run scripts without a background page. These days, the need for such an example is less pressing.
• https://github.com/mdn/webextensions-examples/tree/main/imagify
  imagify is a MV2 extension that calls tabs.executeScript from a sidebar. This sidebar implementation is not cross-browser (we're working on one in the WECG, but not ready yet). Sidebars are not even available on Firefox for Android. But this shows yet another example of how "avoid background script" can work: simply choosing another browser UI surface to host an extension page.
• https://github.com/mdn/webextensions-examples/blob/main/borderify
  borderify is a MV3 example that runs a content script unconditionally, and avoids the need for a background page.
• https://github.com/mdn/webextensions-examples/tree/main/menu-remove-element
  menu-remove-element demonstrates the menus.getTargetElement API, which is Firefox-only. This example is currently MV2, and even if we convert it to MV3, it cannot be a cross-browser example due to the use of a Firefox-only API.
• https://github.com/mdn/webextensions-examples/blob/main/menu-demo
  menu-demo uses the menus namespace. The contextMenus namespace would be a cross-browser way to demonstrate the functionality. It also has to be rewritten to work with event pages / MV3. This would be a good example to demonstrate writing a cross-browser extension (with special background syntax, using contextMenus API)

The above analysis shows that there are no example of a cross-browser extension of running a simple script in a web page on demand. So it would make sense to add that example, and link that from the relevant API references.

[danyalahmed1995]

@Rob--W Thanks for the detailed breakdown, that makes sense.

I understand now that the background manifest article should stay focused on demonstrating the cross-browser background page/service worker setup, and not grow into a scripting.executeScript / activeTab example.

I’m happy to adjust direction here. Based on your explanation, the better path seems to be adding a focused cross-browser MV3 example to mdn/webextensions-examples that runs a content script on demand from the background script, then linking it from the relevant MDN reference pages.

I can revise/close mdn/content#44108 depending on what maintainers prefer, and I’m happy to take a pass at the webextensions-examples side if that direction sounds right.

[rebloor]

@Rob--W to clarify, from #635 (comment) are you suggesting it makes more sense to update https://github.com/mdn/webextensions-examples/blob/main/menu-demo to demonstrate writing a cross-browser extension rather than adding script-on-click

[Rob--W]

@Rob--W to clarify, from #635 (comment) are you suggesting it makes more sense to update https://github.com/mdn/webextensions-examples/blob/main/menu-demo to demonstrate writing a cross-browser extension rather than adding script-on-click

Both are good candidates for demonstrating a cross-browser extension.

[rebloor]

The linked PR addressed some content changes, but didn't add the new example. Moving to extension examples.