diff --git a/en/markdown/docs/develop/getting-started/addon-basics.md b/en/markdown/docs/develop/getting-started/addon-basics.md index 85a00832..b4d0579d 100644 --- a/en/markdown/docs/develop/getting-started/addon-basics.md +++ b/en/markdown/docs/develop/getting-started/addon-basics.md @@ -2,22 +2,23 @@ title: Addon Basics --- -## What's an addon, really? -Actually, an addon isn't much more than a userscript, a userstyle, or a combination of the two. If any of these are related, then we make them part of the same addon, under a single name. For example, the "Scratch 3 Developer Tools" addon has a userscript in charge of adding a find box to the editor, and a userstyle that adds CSS to that box. +## What is an addon? +An addon is a userscript, userstyle, or combination of both that runs on the Scratch website or project editor when enabled. For example, the "Editor find bar" addon has a userscript that adds a find box to the editor, and a userstyle that styles that box. -## What's a userscript? -A userscript is a piece of JavaScript code that runs together with a Scratch tab. You can specify where that userscript will run, for example, only project pages. Userscripts are similar to content scripts on browser extensions, and if you've ever used a userscript manager, you'll notice these are basically the same. -Userscripts are useful to change the behavior of the Scratch website, for example, adding or removing buttons to the navbar. +## What is a userscript? +A [userscript](/docs/develop/userscripts) is a JavaScript file that is executed every time the user loads a Scratch page. They can modify the document’s HTML, add new buttons, customize Scratch editor behavior, and so much more. -## What's a userstyle? -A userstyle is similar to a userscript; you can also specify URL patterns for them. However, userstyles inject CSS instead of JavaScript. They are often used along userscripts to style elements added by them, but they can also be used to style native Scratch elements. When that's the case, we usually call them "themes". +## What is a userstyle? +A [userstyle](/docs/develop/userstyles) is similar to a userscript; you can specify URL patterns for them. However, userstyles inject CSS instead of JavaScript. They are often used along userscripts to style elements added by them, but they can also be used to style native Scratch elements. When that's the case, we usually call them "themes". -## Conceptually, what should be an addon? -You might wonder if it's a better idea to create a new addon, or modify an existing one. -If 2 addons share some of these, they should probably be merged. +## What should be an addon? + + +You might wonder if it's a better idea to create a new addon, or modify an existing one. +If two addons share some of these, they should probably be merged. - Both need, or don't need, permissions that require user interaction (like notifications). - They share lots of code. - The user would expect that addon to offer both features. -- If being separated, they would interfere with each other. +- If being separated, they would interfere with each other. -Remember addons are customizable by the user - adding new functionality does not affect old users of the addon, unless we intentionally make it do so. \ No newline at end of file +Remember addons are customizable by the user - adding new functionality should not affect existing users of the addon, unless we intentionally decide to do so. diff --git a/en/markdown/docs/develop/getting-started/creating-an-addon.md b/en/markdown/docs/develop/getting-started/creating-an-addon.md index 2c237e9e..2224ad4f 100644 --- a/en/markdown/docs/develop/getting-started/creating-an-addon.md +++ b/en/markdown/docs/develop/getting-started/creating-an-addon.md @@ -1,88 +1,75 @@ --- title: Creating an Addon --- -Required software: text editor, Chrome. -If possible, disable the Scratch Addons extension you downloaded from the store before proceeding to avoid issues. +This page describes the basics on how to create an addon for Scratch Addons. Before proceeding, please read the [addon basics](../addon-basics/) and disable any other instances of Scratch Addons to avoid conflicts. {{< admonition info >}} -If you plan to submit the addon you are developing as a pull request to our GitHub repository, please read our [contributing guidelines](https://github.com/ScratchAddons/ScratchAddons/blob/master/.github/CONTRIBUTING.md) first. +If you plan to submit the addon you are developing as a pull request to our GitHub repository, please read our [contributing guidelines](https://github.com/ScratchAddons/ScratchAddons/blob/master/.github/CONTRIBUTING.md) first. +{{< /admonition >}} -In case there is no existing GitHub issue in that repository related to your new addon idea, please [create one](https://github.com/ScratchAddons/ScratchAddons/issues/new/choose). However, if there is already an issue related to your feature idea, we suggest that you leave a comment on it stating your intention to develop the addon. This will enable other contributors to provide feedback on whether the addon could be accepted, or if further discussion is required. +## Requirements +Scratch Addons does not require any software for development except a text editor and a Chromium-based browser (121+), but we also recommend having Git, Firefox (121+) and Visual Studio Code installed. -However, if you are creating an addon for personal use, you may proceed with this guide. -{{< /admonition >}} +## Installation +To install the extension for development, see [Installing from source](/docs/getting-started/installing/#from-source). + +## Creating the addon folder +Each addon has its own internal ID used by the extension and other addons. Addon IDs should not contain any spaces or special characters except hyphens and should be self-descriptive, but not too long. + +New addons should not use an ID that was included in a stable version of the extension but later removed. These include: + +- `a11y` +- `data-category-tweaks` +- `featured-dangos` +- `fix-buttons` +- `redirect-mobile-forums` +- `tutorials-button` + +Open the `addons.json` file in the `addons` folder, insert a new addon ID near the bottom of the file, then create a sub-folder with the same name. -## Step 1: Read about [addon basics](/docs/develop/getting-started/addon-basics/) -Make sure to read that article to be familiar with the terminology. - -## Step 2: Fork/clone the [repo](https://github.com/ScratchAddons/ScratchAddons) -Follow [these instructions](/docs/getting-started/installing/#from-source) to download the source code locally. - -## Step 3: Load the extension into Chrome -*Note: Chrome is recommended for working on addons. Nevertheless, addons are expected to work on Firefox and Edge.* -Now that you have the extension in your filesystem, go to `chrome://extensions` and toggle "developer mode". -Click "load unpacked", then select the folder where Scratch Addons is located. If you're having issues with this, make sure to be selecting the folder where `manifest.json` is located. -That's it, you loaded the extension! It should look similar to this: -![image](https://user-images.githubusercontent.com/17484114/91502527-accfd580-e89e-11ea-9e16-7daa2b808379.png) -Note: you can safely ignore it says "errors". That's just a warning for an unrecognized manifest key that's required by Firefox. - -## Step 4: What's your addon about? -Now comes the fun part! -What will your addon do? Think of a self descriptive addon ID (no spaces or special characters, except hyphens). -Got it? - -## Step 5: Create the folder for the addon -Using a file explorer, go to the folder where Scratch Addons resides in your filesystem. Locate the `addons` folder. -Then, create a new folder with your epic addon ID as its name. - -## Step 6: Add an addon manifest -The addon manifest tells Scratch Addons how your addon works. Make sure to get this right to avoid headaches. -Inside the folder you just created, create an `addon.json` file. -This is a base you can use to start coding, make sure to change it in the future: +## The addon manifest +Each addon has it's own [manifest](/docs/reference/addon-manifest/) that handles how it is displayed on the settings page, any settings the addon may have, which userscripts or userstyles to run and where to run them. + +Addon manifests are located in each addon's folder and named `addon.json`. +Here is a minimal addon manifest: ```json { - "name": "Epic placeholder text in place of addon name", - "description": "Hello World! It would be really smart to replace this placeholder text with a description.", - "tags": ["community"], - "enabledByDefault": false + "name": "My addon", + "description": "TODO", + "tags": ["community"] } ``` -For more information on what you can declare in the manifest, check [this article](/docs/reference/addon-manifest/). - - -## Step 7: Tell Scratch Addons what your addon's ID is -Scratch Addons can't find new folders by itself, so you have to add the name to a special file. -Go to `scratchAddonsFolder/addons/addons.json` and add the ID of your addon to the array. - -## Step 8: Hello world -Your addon does nothing at the moment, so it's a good time to check if everything we made previously worked. -Go to `chrome://extensions` and reload Scratch Addons by clicking the refresh symbol on its card. -Now, right-click the Scratch Addons icon, and click "options". -You should see your addon on the list! Once you find it, enable it, and set any settings that you may have. - -## Step 9: The fun part, code! -*Before proceeding, make sure you read the wiki article linked in step 1.* - -Here comes the fun part: create your own JS or CSS files! -Protip: after making any change to your addon, make sure to refresh the Scratch Addons extension like you did in step 8. - -Depending on what you want your addon to do, you should now check these wiki pages: -- [Userscripts](/docs/develop/userscripts) -- [Userstyles](/docs/develop/userstyles) - -## Step 10: Make your addon customizable -If you want, you can make your addon customizable! -Users of your addon will be able to toggle settings, enter numbers, and more! -To get started, see [how to declare settings in the addon manifest](/docs/reference/addon-manifest/#settings-object). -Then, head to the [addon.settings documentation](/docs/reference/addon-api/addon.settings) to learn how to access user choices from userscripts. - -## Step 11: Before publishing your addon -Now that your addon works, let's make sure we can add it to the addon library. -Make sure your addon's manifest is suitable, [more info here](/docs/reference/addon-manifest). Keep close attention to the name, description and tags of your addon. Make sure to set `"enabledByDefault"` to `false` or remove it. -Make sure your addon doesn't break other addons. -Make sure your code is understandable; having unnecessary comments is better than no comments. - -## Step 12: Send a pull request! -Follow the steps on our [contributing guidelines](https://github.com/ScratchAddons/ScratchAddons/blob/master/.github/CONTRIBUTING.md). Simply put, fork the repo if you haven't already, commit your new addon and send a PR! -Keep in mind we might request you to make some changes, however, we will probably accept your addon as long as it's minimally suitable. + +For more information on what can be declared in the manifest, see the [the Addon Manifest reference](/docs/reference/addon-manifest/). + +The addon does not do anything yet, but it should appear in the popup and settings page after reloading the extension. + +## Userscripts and userstyles +[Userscripts](/docs/develop/userscripts/) and [userstyles](/docs/develop/userstyles/) are what make the addon work. Userscripts run JavaScript code and userstyles inject CSS styles. Addons may have a combination of userstyles and userscripts. + +Userscripts have access to [addon APIs](/docs/reference/addon-api/) to make Scratch-specific tasks such as fetching the currently logged in user easier. + +When adding a userscript or userstyle to the addon's folder, it must be declared in the addon manifest or it will not run. + +## Addon settings +The [settings object](/docs/reference/addon-manifest/#settings-object) in the addon manifest allows adding options such as toggles, text boxes or color pickers to your addon on the settings page to make it customizable by users. + +See the [addon.settings](/docs/reference/addon-api/addon.settings) documentation on how to access user choices from userscripts and userstyles. + +## Before contributing +{{< admonition info >}} +In case there is no existing GitHub issue in that repository related to your new addon idea, please create one. However, if there is already an issue related to your feature idea, we suggest that you leave a comment on it stating your intention to develop the addon. This will enable other contributors to provide feedback on whether the addon could be accepted, or if further discussion is required. + +Also note that GitHub's terms of service require users to be 13+ to create an account with them. +{{< /admonition >}} + +If you want to submit your addon to the Scratch Addons GitHub repository, so it can be added to the addon library, ensure the addon works as expected, with and without other addons enabled and that it does not break other addons. The addon's manifest should have a good name and description, `versionAdded` should be set to the next version of the extension and the addon should not be enabled by default. Addons should support dynamic enable and disable, but it is not required. +Make sure the code is understandable; having unnecessary comments is better than no comments. + +## Sending a pull request +Follow the steps on our [contributing guidelines](https://github.com/ScratchAddons/ScratchAddons/blob/master/.github/CONTRIBUTING.md). Simply put, fork the repository if you haven't already, commit your new addon and send a pull request. + +If your addon isn't finished or you need help with something, create a draft pull request. + +Keep in mind we might request you to make some changes, and the review process may be slow, however, we will probably accept your addon as long as it's minimally suitable and Scratch-specific. diff --git a/en/markdown/docs/getting-started/installing.md b/en/markdown/docs/getting-started/installing.md index 61c47317..4a2e1d63 100644 --- a/en/markdown/docs/getting-started/installing.md +++ b/en/markdown/docs/getting-started/installing.md @@ -14,18 +14,22 @@ Scratch Addons is available in these stores. ## From source +{{< admonition info >}} +Unlike the store releases, installing from source requires a browser based on Chromium 121+ or Firefox 121+. +{{< /admonition >}} + ### About GitHub releases [The releases page](https://github.com/ScratchAddons/ScratchAddons/releases) contains the code and installation files for all development builds of Scratch Addons, as well as the mirror of the store builds. ### Cloning the repository -This is the recommended way to install Scratch Addons for development purposes. This assumes you have Git installed. +This is the recommended way to install Scratch Addons for development purposes, assuming you have Git installed. -To download the repository, simply clone `https://github.com/ScratchAddons/ScratchAddons.git`. +If you plan on contributing, fork the repository on GitHub first and then clone the fork, replacing `` with your Github username. ```sh -$ git clone https://github.com/ScratchAddons/ScratchAddons.git +$ git clone https://github.com//ScratchAddons.git ``` To update Scratch Addons, first `cd` into its folder, and then run the following commands. @@ -34,57 +38,61 @@ $ git fetch $ git pull ``` -This will update Scratch Addons and get it ready for code editing. Note that you will need to see the finish updating section [here](#install-on-google-chrome) if you are using Google Chrome. +Remember to also update Scratch Addons from the browser. + +### Downloading the Zip -### Downloading the zipball +{{< admonition warning >}} + This method is not recommended for development unless Git cannot be installed on the system since it will need to be manually repeated every time you update Scratch Addons. +{{< /admonition >}} -If you don't have Git installed, you can try this method instead. Note that you will need to manually repeat this process every time you want to update Scratch Addons. +If you don not have Git installed, use this method instead. 1. Go to the [repository](https://github.com/ScratchAddons/ScratchAddons) and find the download code button. - ![Download code button screenshot](/assets/img/docs/download-code-button.png) +1. Click it and select "Download ZIP". -2. Click it and select "Download ZIP". +1. Extract the archive into a folder. - ![Download ZIP button screenshot](/assets/img/docs/download-zipball-button.png) +### Installing on Google Chrome or Microsoft Edge -3. Extract the archive into a folder. +To load the extension into Google Chrome and most Chromium-based browsers such as Microsoft Edge, Opera, Brave or Vivaldi: -### Installing on Google Chrome or Microsoft Edge +1. Go to [chrome://extensions](chrome://extensions) -1. Type `chrome://extensions` into your address bar to open the Extension Management page. +1. Turn on "Developer mode" in the top-right corner -2. Click the toggle next to `Developer mode` to turn on the Developer Mode. This allows you to install extensions from a folder or file. +1. Click "Load unpacked" and select the `ScratchAddons` folder. - ![Extension Management top bar screenshot](/assets/img/docs/developer-mode-toggle.png) +To update the extension when testing, click the refresh icon on the extension's card. -3. You should see the `Load unpacked` button appear. Clicking it will allow you to select a folder to upload. +{{< admonition info >}} + The "Unrecognized manifest key" warnings may safely be ignored, since they are required by Firefox. +{{< /admonition >}} - ![Load unpacked button screenshot](/assets/img/docs/load-unpacked-button.png) -4. Select the extracted folder. -5. The extension should now be loaded. +### Installing on Mozilla Firefox -To finish updating (assuming you followed the updating steps [here](#cloning-the-repository)), click the `Update` button: +To load the extension into Mozilla Firefox: -![Update button screenshot](/assets/img/docs/update-button.png) +{{< admonition info >}} + Addons loaded into Firefox this way are temporary and must be reloaded every time the browser is restarted. Because of this Chrome is recommended for development, but everything is still expected to work on Firefox. +{{< /admonition >}} +1. Go to [about:debugging](about:debugging) -### Installing on Mozilla Firefox +1. Click "This Firefox" on the sidebar + +1. Click "Load Temporary Add-on..." -1. Type `about:debugging` into your address bar to open the debugging page. +1. Select the `manifest.json` file in the `ScratchAddons` folder. -2. Click `This Firefox` on the left-hand menu. - - ![Left-hand menu screenshot](/assets/img/docs/left-hand-menu.png) +1. If a permission tab opens, click the "Enable" button. -4. Click `Load Temporary Add-on...`. - - ![Load Temporary Add-on button screenshot](/assets/img/docs/load-addon.png) - -6. Select the manifest.json file inside the extracted folder. -7. The extension should now be loaded. +To reload the extension when testing, click the "Reload" button on the extension's card. -Note: Firefox temporary add-ons are actually temporary. Restarting Firefox will remove them, so if you want to use the development version of Scratch Addons all the time, it is recommended that you use a Chromium-based browser like Google Chrome. +{{< admonition info >}} + The unexpected WebExtension manifest property warnings may safely be ignored, since they are required by Chrome. +{{< /admonition >}}