Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update addon.tab API Docs #499

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Update addon.tab API Docs #499

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
64a7b54
remove options from displayNoneWhileDisabled
Samq64 Oct 16, 2024
49d7a41
Add resizeEvent to waitForElement
Samq64 Oct 16, 2024
2c129f1
update addon.tab.copyImage description
Samq64 Oct 16, 2024
2bf35ab
Remove addon.tab.loadWorker
Samq64 Oct 16, 2024
2ba4316
Turn some notices into actual notices
Samq64 Oct 16, 2024
47ac931
remove displayNoneWhileDisabled example
Samq64 Oct 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 26 additions & 58 deletions content/docs/reference/addon-api/addon.tab/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,11 @@ while (true) {
### 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 though that is not the default value for images.
```js
/* userscript.js */
const img = document.createElement("img");
img.classList.add("sa-example-img");
addon.tab.displayNoneWhileDisabled(img, { display: "flex" });
addon.tab.displayNoneWhileDisabled(img);
const btn = document.createElement("btn");
btn.onclick = () => {
// We want to hide the image
Expand All @@ -54,7 +53,7 @@ We also set the `display` CSS property of the image to `flex` when visible, even
.sa-example-img-hide {
/* We want to hide the image if the button was clicked,
even if the addon is enabled */
display: none !important;
display: none;
}
```

Expand Down Expand Up @@ -174,6 +173,13 @@ The writing direction for the language of the Scratch website.
<td><code>[]</code></td>
<td>An array of Redux events that must be dispatched before resolving the selector.</td>
</tr>
<tr>
<td>resizeEvent</td>
<td><code>Boolean</code></td>
<td>No</td>
<td><code>false</code></td>
<td>Whether the selector should be resolved on a window resize, in addition to reduxEvents.</td>
</tr>
</table>
</td>
</tr>
Expand Down Expand Up @@ -205,34 +211,10 @@ Options `condition`, `reduxCondition` and `reduxEvents` should be used as optimi
<td>Yes</td>
<td>Element to hide</td>
</tr>
<tr>
<td>options</td>
<td><code>Object</code></td>
<td>No</td>
<td>
<table>
<tr>
<th>Property</th>
<th>Type</th>
<th>Required</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td>display</td>
<td><code>String</code></td>
<td>No</td>
<td><code>""</code></td>
<td>The <code>display</code> CSS value to use when the addon is enabled.</td>
</tr>
</table>
</td>
</tr>
</table>

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 `div`s and `inline` for `span`s), 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.
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;` on the element.
Samq64 marked this conversation as resolved.
Show resolved Hide resolved

### `addon.tab.copyImage`
<table>
Expand Down Expand Up @@ -267,8 +249,8 @@ If you want to manually hide the element in situations where the addon is enable
</table>

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 and Edge.
Only run this in response of the user explicitly clicking a button or pressing Ctrl+C.
Internally uses `browser.clipboard.setImageData` in Firefox versions below 127 and `navigator.clipboard.write` everywhere else.

### `addon.tab.scratchClass`
<table>
Expand Down Expand Up @@ -680,7 +662,11 @@ Similar to `window.prompt`, except it's asynchronous and uses Scratch's styles.
Adds a context menu item for any of the context menus in the code editor.

### `addon.tab.createEditorContextMenu`
**Documentation for this is a WIP. Not all possible types are listed for some settings.**

{{< admonition info >}}
Documentation for this is a work in progress. Not all possible types are listed for some settings.
{{< /admonition >}}

<table>
<tr>
<th>Parameter</th>
Expand Down Expand Up @@ -853,7 +839,11 @@ Adds a context menu item for any of the context menus in the code editor.
Adds a context menu item for any of the non-Blockly context menus, such as the context menu for the sprites list.

### `addon.tab.addBlock`
**Do not use this unless you are adding blocks to the debugger addon.**

{{< admonition warning >}}
Do not use this unless you are adding blocks to the debugger addon.
{{< /admonition >}}

<table>
<tr>
<th>Parameter</th>
Expand Down Expand Up @@ -949,7 +939,10 @@ Adds a new block to the Debugger category in the block palette.
Removes a block that was previously added to the Debugger category in the block palette.

### `addon.tab.loadScript`
**In most cases, you should use the [`userscripts` property of the addon manifest](/docs/reference/addon-manifest/#userscripts-and-userstyles) instead.**

{{< admonition warning >}}
In most cases, you should use the [`userscripts` property of the addon manifest](/docs/reference/addon-manifest/#userscripts-and-userstyles) instead.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we officially deprecate this and also mention not importing 3rd-party libraries with it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure, but we could write down that usually we prefer addons that don't import any libraries.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In most cases, you should use the [`userscripts` property of the addon manifest](/docs/reference/addon-manifest/#userscripts-and-userstyles) instead.
Use the standard browser import instead.

Copy link
Member Author

@Samq64 Samq64 Oct 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure, but we could write down that usually we prefer addons that don't import any libraries.

I think that fits better in the best practices page and I want to try to keep this PR to just the API.

{{< /admonition >}}

<table>
<tr>
Expand All @@ -975,31 +968,6 @@ Removes a block that was previously added to the Debugger category in the block

Runs the specified script file relative to the extension's root (e.g. `chrome-extension://aeepldbjfoihffgcaejikpoeppffnlbd/`) in a `<script>` tag.

### `addon.tab.loadWorker`
<table>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
<tr>
<td>path</td>
<td><code>String</code></td>
<td>Yes</td>
<td>The path pointing to the worker.</td>
</tr>
</table>

<table>
<tr>
<td>Return value</td>
<td><code>Promise&lt;Worker></code></td>
</tr>
</table>

Loads the specified Web Worker.

## Events
### `urlChange`
<table>
Expand Down