addon.tab

Available in userscripts ✔️
Available in persistent scripts
Available in popup scripts
Required manifest permissions None

Description

Allows addon userscripts to get information about the tab they’re currently running on.

Examples

Using addon.tab.waitForElement

We can use addon.tab.waitForElement with {"markAsSeen": true} inside a while(true) loop to store the IDs of all comments in the page.
Using addon.tab.waitForElement, we don’t need to have code that waits until comments have loaded. This way, we also store the IDs of newly posted comments and new loaded comments when the user clicks “load more comments”.

const commentIds = [];
while (true) {
  const comment = await addon.tab.waitForElement("div.comment", {
      markAsSeen: true,
  });
  commentIds.push(comment.id);
}

Using addon.tab.displayNoneWhileDisabled (dynamicDisable)

We use addon.tab.displayNoneWhileDisabled to hide an image when the addon gets disabled.
We create a button to hide the image when clicked, and the image succesfully gets hidden, even if the addon is enabled.
We also set the display CSS property of the image to flex when visible, even tho that is not the default value for images.

  /* userscript.js */
  const img = document.createElement("img");
  img.classList.add("sa-example-img");
  addon.tab.displayNoneWhileDisabled(img, { display: "flex" });
  const btn = document.createElement("btn");
  btn.onclick = () => {
    // We want to hide the image
    // We cannot do `img.style.display = "none"` because we
    // used displayNoneWhileDisabled with the same element
    img.classList.add("sa-example-img-hide");
  };
/* userstyle.css */
.sa-example-img {
  display: flex;
}
.sa-example-img-hide {
  /* We want to hide the image if the button was clicked, 
  even if the addon is enabled */
  display: none !important;
}

Reacting to URL dynamically changed

addon.tab.addEventListener("urlChange", function(event) {
  console.log(`URL changed! It was previously ${event.detail.oldUrl}, it's now ${event.detail.newUrl}`);
});

Sub-APIs

addon.tab.traps

Allows addons to get direct references to objects, which are particularly useful for enhancing the editor, like the Scratch VM or the Blockly instance.

addon.tab.redux

TODO

Properties

addon.tab.clientVersion

Value "scratch-www" | "scratchr2"
Nullable Yes

The Scratch client for the current tab (scratch-www or scratchr2).
The Scratch community website has 2 working clients used throughout the site.
scratch-www is React/Redux based and client side rendered. This client is the one used in the homepage.
scratchr2 is Django/jQuery/Backbone.js based and mostly server side rendered. This client is the one used in profile pages.

addon.tab.editorMode

Value "projectpage" | "editor" | "fullscreen" | "embed"
Nullable Yes

The current viewing mode for the project (projectpage, editor, fullscreen or embed).
Will be null if the current tab is not a project.

addon.tab.direction

Value "ltr" | "rtl"
Nullable No

The writing direction for the language of the Scratch website.

Methods

addon.tab.waitForElement

Parameter Type Required Description
selector String Yes One or more selectors to match. Same parameter as document.querySelector.
options Object No
Property Type Required Default Description
markAsSeen Boolean No false Whether it should mark resolved elements to be skipped next time or not.
condition Function No () => true A function that returns whether to resolve the selector or not. No arguments are passed.
reduxCondition Function No () => true A function that returns whether to resolve the selector or not. addon.tab.redux is passed as an argument.
reduxEvents String[] No [] An array of Redux events that must be dispatched before resolving the selector.
Return value Promise<HTMLElement>

Waits until an element exists, then returns the element.
Internally, a MutationObserver that reacts to any DOM tree change is used. This observer does not react to attribute-only DOM updates.
Option markAsSeen should be set to true if you’re using this method inside a while(true) loop.
Options condition, reduxCondition and reduxEvents should be used as optimizations, in order to avoid multiple calls to document.querySelector when it’s guaranteed the element will not exist yet.

addon.tab.displayNoneWhileDisabled

Parameter Type Required Description
element HTMLElement Yes Element to hide
options Object No
Property Type Required Default Description
display String No "" The display CSS value to use when the addon is enabled.

Hides the given element with display: none when the addon is disabled, until it is reenabled.
If the intended display CSS property value for the provided element when visible is not the default value for the type of provided element (for example, block for divs and inline for spans), you should provide that value inside the options parameter.
If you want to manually hide the element in situations where the addon is enabled, you should use a dedicated class name for that, instead of manually setting el.style.display = "none";. Use a class name selector in a userstyle to set display: none !important; on the element.

addon.tab.copyImage

Required manifest permissions clipboardWrite
Parameter Type Required Description
dataURL String Yes Data URL of a PNG image.
Return value Promise<void>
Promise rejects if Image could not be copied.

Copies a PNG image to the clipboard.
Only run this in response of the user explicitly pressing Ctrl+C.
Internally uses browser.clipboard.setImageData in Firefox and navigator.clipboard.write in Chrome.

addon.tab.scratchClass

Parameter Type Required Description
unhashedClassName String Min 1 One or many unhashed Scratch stylesheet class names, as one argument each.
opts Object No
Property Type Required Description
others String | String[] Yes Non-Scratch class(es) to merge
Return value String

Gets the hashed class name for a Scratch stylesheet class name.

addon.tab.scratchMessage

Parameter Type Required Description
key String Yes The Scratch translation key.
Return value String | ""

Gets Scratch translation from the current Scratch tab.
Note that these are Scratch locales, not Scratch Addons locales.
If the message isn’t found, "" is returned and a warning is logged in the console.
Internally uses window.django.gettext or window._messages.

addon.tab.appendToSharedSpace

See addon.tab.appendToSharedSpace.

Events

urlChange

Event detail property Type Description
oldUrl String The URL before it was dynamically changed
newUrl String The new current URL value

Fires when Scratch dynamically changes the URL of the page.
This happens when going inside/outside the editor, or switching tabs in scratch-www studio pages.
This will not fire if location.hash changed.


Section Pages


Last updated at 12 July 2021 by Hans5958 on commit d07183b. Improve this page.