addon.tab.appendToSharedSpace

The shared spaces API provides a standard way for addons to add their own custom UI elements to areas (“spaces”) inside Scratch.

For example, both the “mouse position” and “clone counter” addons add their own HTML elements to the project player stage header, after the stop button.

Example

As an example, this is how the “pause button” addon could be adding an element to the afterGreenFlag space:

// Creating an element and listening to events works like usually
const pauseButton = document.createElement("img");
pauseButton.src = addon.self.dir + "/play.svg";
pauseButton.addEventListener("click", changePauseState);

// Wait until the stage header exists before adding the pause button, like usually
await addon.tab.waitForElement("[class^='green-flag']");

// This number was reserved for the pause button.
// No other addon should use this order number in the `afterGreenFlag` space.
const PAUSE_BUTTON_ORDER_NUMBER = 0;

// appendToSharedSpace is used below, instead of typical element.appendChild()
addon.tab.appendToSharedSpace({
  space: "afterGreenFlag",
  element: pauseButton,
  order: PAUSE_BUTTON_ORDER_NUMBER
});

Description

Order numbers prevent adding new UI elements from being a racy operation, where users would observe that the order of UI elements added by third-party browser extensions varies unpredictably on each page session.

Regarding order numbers

• Each shared space has its own order number set, independent from all other shared spaces.
• Order numbers are typically positive integers, but negative and decimal numbers are also supported.
• The element with the lowest number will always become the first child of the corresponding HTML element.
• Any addon can theoretically call this method with any order number, and no error will be thrown. Order numbers aren’t logically reserved. Developers are in charge of making sure each addon is calling this method with a suitable order number.
• Multiple order numbers may be reserved for a single addon within a shared space.
• In some cases, 2 or more addons may use the same order number within the same shared space, as long as only one of the elements can be visible at once.

Defining shared spaces

The list of existing shared spaces is hardcoded inside the code definition of the method (addon-api/content-script/Tab.js).
Each shared space has a name, and is defined by these properties:

1. Space parent element: the HTML element where addons would typically add their UI elements inside of. This will be the parent element of all elements added to the shared space.
2. Space starting bound (optional): the sibling after which shared space items should always be added.
3. Space ending bound (optional): the sibling before which shared space items should always be added.
4. Accepts scope option: whether a space can exist multiple times per page. In those cases, addons should manually provide an HTML element that contains the wanted parent element.

As an example, the definition of the afterGreenFlag shared space calls document.querySelector('div[class^="controls_controls-container"]') to find the space parent element. Additionally, this space does not use the scope option, because there can only be 1 project player per document.

Method

List of shared spaces

Scratch editor spaces

stageHeader

Elements added to this space will be positioned next to the “small stage” and “big stage” buttons.
This is typically the right side of the stage header. This might not be true in RTL languages, or if the editor-buttons-reverse-order addon is enabled.

This shared space may exist in 5 different situations:

1. Project in editor mode, small stage disabled (default).
2. Project in editor mode, small stage enabled. Elements from this space are often hidden in this situation.
3. Project in editor mode, hide-stage addon functionality triggered by the user.
4. Project in projectpage mode.
5. Project in embed mode.

This shared space will not exist while on fullscreen mode. See fullscreenStageHeader.

Typical CSS properties: margin-right: 0.2rem (LTR), margin-left: 0.2rem (RTL)

fullscreenStageHeader

See stageHeader. Full screen can be triggered both from the project page and from inside the editor.

Typical CSS properties: margin-right: 0.2rem (LTR), margin-left: 0.2rem (RTL)

afterGreenFlag

Elements added to this space will be positioned between the green flag and the stop button.
This space will exist in all situations where a project player also exists.

Typical CSS properties: padding: 0.375rem

afterStopButton

Elements added to this space will be positioned after the project control buttons.
This space will exist in all situations where a project player also exists.

Typical CSS properties: padding-left: 0.25rem; padding-right: 0.25rem

afterSoundTab

Elements added to this space will be positioned after the “sounds” tab.

Typical DOM classes for elements added to this space: addon.tab.scratchClass("react-tabs_react-tabs__tab", "gui_tab")

The order number typically matches the reserved value for redux.state.scratchGui.editorTab.activeTabIndex.

Scratch website spaces

afterCopyLinkButton

Elements added to this space will be positioned after the “copy link” button in project pages.

Typical DOM classes for elements added to this space: button, action-button

beforeRemixButton

Elements added to this space will be positioned before the “remix” or “see inside” buttons in project pages.

Scratch forums spaces

forumsBeforePostReport

Elements added to this space will be positioned before the “report” button in a specific post.

If the “report” button does not exist (user is logged out), a visible placeholder dot will be added to the post automatically to act as a separator between the forumsBeforePostReport and forumsAfterPostReport spaces.

Addition of the | separator is handled by the shared spaces API.

forumsAfterPostReport

Elements added to this space will be positioned after the “report” button in a specific post.

See forumsBeforePostReport for more information.