diff --git a/CI-CD.md b/CI-CD.md new file mode 100644 index 000000000..26ac951d8 --- /dev/null +++ b/CI-CD.md @@ -0,0 +1,56 @@ +# Continuous Integration & Deployment + +If you followed the steps outlined in the README's [Making an Extension](./README.md#🔨-making-an-extension) section, you should have created a new branch off of the `dev` branch where you implemented your extension. + +## Automatic Deployment to Temperorary URL + +Whenever you [push]() on this new branch, a [github action]() will automatically deploy your extension to a URL corresponding to your branch name. + +For example, if my branch is called `myNewExtension`, whenever I succesfully push up code on this branch, I should be able to see my changes at: https://playground.raise.mit.edu/myNewExtension/ + +> NOTE: The github action(s) that manages deployment can take anywhere from 10 - 30 minutes. View the status of actions in the repo's [Actions tab](https://github.com/mitmedialab/prg-extension-boilerplate/actions). In order for your site to be succesfully deployed, both an action titled with your commmit message and one after it titled ***pages build and deployment*** must complete succesfully. + +Though this branch-specific URL can be very helpful for sharing your extension quickly, we **require** that you don't use this URL for _official_ purposes -- instead you should follow the instructions in [Integrating Your Extension into the main Branch](#integrating-your-extension-into-the-main-branch) if you want to share extension as part of a curricullum, to an outside organization, etc. + +So this means you can use your branch-specific URL to share your extension with colleagues, get feedback, and quickly iterate on your extension. However, if you want to share your extension externally, especially with students, it must first be integrated into the `main` branch, and then you can direct them to: https://playground.raise.mit.edu/main/ + +## Integrating Your Extension into the `main` Branch + +The extensions pushed into the `main` branch should represent all of the extensions PRG officially supports, and thus what PRG is committed to maintaining now and into the future. + +Thus, you should only _officially_ share extensions via the `main` branch and corresponding [main site](https://playground.raise.mit.edu/main/) (https://playground.raise.mit.edu/main/). In other words, if an outside party (student, teacher, organization, etc.) reports a bug about an extension (or the platform), they should be doing so based on their usage of the main site -- not a branch-specific site that no other team members know about. + +By adhering to this practice, as well as a regimented process for [merging](https://git-scm.com/docs/git-merge) changes to the `dev` and `main` branches, we can ensure both the best experinece for our users and the least amount of headache for us as developers / maintainers. + +Here's the process for getting your extension into the `main` branch and deployed to https://playground.raise.mit.edu/main/: + +1. Get your development branch current with the `dev` branch + ```bash + cd prg-extension-boilerplate/ # Change directory (cd) to prg-extension-boilerplate/, if not already there + + git checkout # Checkout your brnahc, if not already checked out + + git pull # Fetch the latest changes from all remote branches. + # NOTE: using `git fetch` would do the same, but it's yet another git command to remember... + + git merge origin/dev # Merge the latest changes from the remote (i.e. origin) dev branch into your development branch + ``` +2. Create a Pull Request (PR) from your branch into `dev` + 1. Go to the [Pull Requests tab](https://github.com/mitmedialab/prg-extension-boilerplate/pulls) + 2. Click **New Pull Request** + 3. Set _base_ to `dev` and _compare_ to the name of your branch + - The flow should look like: `dev` <-- `` + 4. Select **Create Pull Request** + - Do this enough times so that the pull request is actually created -- github's UI seems to be a little redunant +3. Set [pmalacho-mit](https://github.com/pmalacho-mit) (Parker Malachowsky) as the reviewer of the PR + - NOTE: If anyone's interested in being a reviewer please also talk to Parker and he will add you above. +4. Work with your reviewer to get your PR approved, and then **YOUR REVIEWER** will merge your PR and your changes will go into `dev` 🎉🎉🎉. In this way, you and the reviewer are equally responsible for keeping the `dev` branch bug-free. + - Your reviewer will review your code, test your extension, and leave comments for you to respond to. + - You can speed up the review process by doing the following: + - Writing readable code and leaving necessary (but [_only necessary_](https://levelup.gitconnected.com/please-dont-comment-your-code-d0830785bdc9)) comments + - Use [JSDoc comments](https://jsdoc.app/about-getting-started.html) where possible (e.g. on functions, classes, method parameters, etc.) + - [Writing tests for your extension]() (coming soon) + - [Creating tutorials for your extension]() (coming soon) +5. Once your code is in `dev`, your work is done! The code base's maintainer (Parker, at this time) will then semiweekly merge the `dev` branch into the `main` branch. +6. Once Parker has notified you that your changes are live, you can direct your audience to the deployed `main` branch: https://playground.raise.mit.edu/main/ + - Check out the [URL Parameters]() section to see how you can customize this link to automatically add your extension, tutorials, demo project, etc. when the page is loaded. \ No newline at end of file diff --git a/README.md b/README.md index 349ac3e5e..cb933dcd1 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,14 @@ -# ✨ PRG Scratch Extension Development Environment +# ✨ PRG RAISE Playground [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mitmedialab/prg-extension-boilerplate/tree/dev) This repository is your one-stop-shop for developing [scratch extensions](https://en.scratch-wiki.info/wiki/Extension) for PRG curricula. -It's a fullblown [fork](https://en.wikipedia.org/wiki/Fork_(software_development)) of the official Scratch codebase, which the [Personal Robotics Group](https://robots.media.mit.edu/) (PRG) manages and extends to meet its needs. +It [forks](https://en.wikipedia.org/wiki/Fork_(software_development)) a few of the official Scratch codebases, which the [Personal Robotics Group](https://robots.media.mit.edu/) (PRG) manages and extends to meet its needs. These exist as [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) located inside of the [scratch-packages/](./scratch-packages/) folder. +- [scratch-packages/scratch-gui/](./scratch-packages/scratch-gui/) + - [prg-raise-playground-scratch-gui](https://github.com/mitmedialab/prg-raise-playground-scratch-gui) forks the [scratch-gui](https://github.com/scratchfoundation/scratch-gui) package. See [our changes](https://github.com/mitmedialab/prg-raise-playground-scratch-gui/pull/7). +- [scratch-packages/scratch-vm/](./scratch-packages/scratch-vm/) + - [prg-raise-playground-scratch-vm](https://github.com/mitmedialab/prg-raise-playground-scratch-vm) forks the [scratch-vm](https://github.com/scratchfoundation/scratch-vm) package. See [our changes](https://github.com/mitmedialab/prg-raise-playground-scratch-vm/pull/2). Looking for the old documentation (<= Sept. 2022)? Head [here](./BACKGROUND.md). @@ -14,7 +18,7 @@ Looking for the old documentation (<= Sept. 2022)? Head [here](./BACKGROUND.md). ## ⚡ Quick Start -This section contains concise explanations on how to accomplish something (often just a couple of commands to run). If you need more info please check out one of the lower sections. +This section contains concise explanations on how to accomplish something (often just a couple of [terminal commands](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line) to run). If you need more info please check out one of the lower sections. ### 🚧 Project setup @@ -41,7 +45,7 @@ git checkout dev pnpm install # This will symlink the packages together to allow for seamless local development, and installs dependencies for each package. # This should only need to be ran once (unless you checkout a branch that adds new package dependencies). -# Takes ~1.5 minutes +# Takes ~1.5 minutes the first time it runs, and is much quicker (a few seconds) for later installs / updates pnpm dev -i examples # This starts up a development server, serving the two "example" extensions. @@ -103,60 +107,7 @@ As long as the development server is running (meaning the `pnpm dev` command is ### 📦 Committing, pushing, and deploying an extension -If you followed the steps outlined in [Making an Extension](#🔨-making-an-extension), you should have created a new branch off of the `dev` branch where you implemented your extension. - -#### Automatic Deployment to Temperorary URL - -Whenever you [push]() on this new branch, a [github action]() will automatically deploy your extension to a URL corresponding to your branch name. - -For example, if my branch is called `myNewExtension`, whenever I succesfully push up code on this branch, I should be able to see my changes at: https://playground.raise.mit.edu/myNewExtension/ - -> NOTE: The github action(s) that manages deployment can take anywhere from 10 - 30 minutes. View the status of actions in the repo's [Actions tab](https://github.com/mitmedialab/prg-extension-boilerplate/actions). In order for your site to be succesfully deployed, both an action titled with your commmit message and one after it titled ***pages build and deployment*** must complete succesfully. - -Though this branch-specific URL can be very helpful for sharing your extension quickly, we **require** that you don't use this URL for _official_ purposes -- instead you should follow the instructions in [Integrating Your Extension into the main Branch](#integrating-your-extension-into-the-main-branch) if you want to share extension as part of a curricullum, to an outside organization, etc. - -So this means you can use your branch-specific URL to share your extension with colleagues, get feedback, and quickly iterate on your extension. However, if you want to share your extension externally, especially with students, it must first be integrated into the `main` branch, and then you can direct them to: https://playground.raise.mit.edu/main/ - -#### Integrating Your Extension into the `main` Branch - -The extensions pushed into the `main` branch should represent all of the extensions PRG officially supports, and thus what PRG is committed to maintaining now and into the future. - -Thus, you should only _officially_ share extensions via the `main` branch and corresponding [main site](https://playground.raise.mit.edu/main/) (https://playground.raise.mit.edu/main/). In other words, if an outside party (student, teacher, organization, etc.) reports a bug about an extension (or the platform), they should be doing so based on their usage of the main site -- not a branch-specific site that no other team members know about. - -By adhering to this practice, as well as a regimented process for [merging](https://git-scm.com/docs/git-merge) changes to the `dev` and `main` branches, we can ensure both the best experinece for our users and the least amount of headache for us as developers / maintainers. - -Here's the process for getting your extension into the `main` branch and deployed to https://playground.raise.mit.edu/main/: - -1. Get your development branch current with the `dev` branch - ```bash - cd prg-extension-boilerplate/ # Change directory (cd) to prg-extension-boilerplate/, if not already there - - git checkout # Checkout your brnahc, if not already checked out - - git pull # Fetch the latest changes from all remote branches. - # NOTE: using `git fetch` would do the same, but it's yet another git command to remember... - - git merge origin/dev # Merge the latest changes from the remote (i.e. origin) dev branch into your development branch - ``` -2. Create a Pull Request (PR) from your branch into `dev` - 1. Go to the [Pull Requests tab](https://github.com/mitmedialab/prg-extension-boilerplate/pulls) - 2. Click **New Pull Request** - 3. Set _base_ to `dev` and _compare_ to the name of your branch - - The flow should look like: `dev` <-- `` - 4. Select **Create Pull Request** - - Do this enough times so that the pull request is actually created -- github's UI seems to be a little redunant -3. Set [pmalacho-mit](https://github.com/pmalacho-mit) (Parker Malachowsky) as the reviewer of the PR - - NOTE: If anyone's interested in being a reviewer please also talk to Parker and he will add you above. -4. Work with your reviewer to get your PR approved, and then **YOUR REVIEWER** will merge your PR and your changes will go into `dev` 🎉🎉🎉. In this way, you and the reviewer are equally responsible for keeping the `dev` branch bug-free. - - Your reviewer will review your code, test your extension, and leave comments for you to respond to. - - You can speed up the review process by doing the following: - - Writing readable code and leaving necessary (but [_only necessary_](https://levelup.gitconnected.com/please-dont-comment-your-code-d0830785bdc9)) comments - - Use [JSDoc comments](https://jsdoc.app/about-getting-started.html) where possible (e.g. on functions, classes, method parameters, etc.) - - [Writing tests for your extension]() (coming soon) - - [Creating tutorials for your extension]() (coming soon) -5. Once your code is in `dev`, your work is done! The code base's maintainer (Parker, at this time) will then semiweekly merge the `dev` branch into the `main` branch. -6. Once Parker has notified you that your changes are live, you can direct your audience to the deployed `main` branch: https://playground.raise.mit.edu/main/ - - Check out the [URL Parameters]() section to see how you can customize this link to automatically add your extension, tutorials, demo project, etc. when the page is loaded. +To learn how to manage git-tracking and deploying your extension, please head to the [CICD.md](./CI-CD.md) (continuous integration & continuous delivery / deployment) documentation. ## 🔎 How to program an extension @@ -170,7 +121,7 @@ Also, try hovering over fields to view their documentation (typically a [summary ![Gif of video hovering over fields to peak documentation](//.assets/hover.gif) -Still stuck? Check out our [From 0 to Extension guide](#-from-0-to-extension) and/or contact more experienced extension developers, like [Parker](https://github.com/pmalacho-mit) or [Randi](https://github.com/randi-c-dubs) +Still stuck? Check out our [From 0 to Extension guide](#-from-0-to-extension) and/or contact more experienced extension developers, like [Parker](https://github.com/pmalacho-mit) or [Maya](https://github.com/mayarajan3) ### 🪜 From 0 to Extension diff --git a/extensions/src/.templates/default.ts b/extensions/src/.templates/default.ts index 8b6294c05..9f57cfc2d 100644 --- a/extensions/src/.templates/default.ts +++ b/extensions/src/.templates/default.ts @@ -1,5 +1,4 @@ -import { ArgumentType, BlockType, BlockUtilityWithID, Environment, ExtensionMenuDisplayDetails, extension, scratch } from "$common"; -import BlockUtility from "$scratch-vm/engine/block-utility"; +import { scratch, extension, type ExtensionMenuDisplayDetails, type BlockUtilityWithID, type Environment } from "$common"; /** 👋 Hi! @@ -7,10 +6,11 @@ Below is a working Extension that you should adapt to fit your needs. It makes use of JSDoc comments (anything inside of the '/** * /' regions) to add explanations to what you're seeing. These do not affect the code -and can be delete when you no longer need them. +and can be deleted whenever you no longer need them. Anywhere you find something that looks like: @see {ExplanationOfSomething} -hover over the 'ExplanationOfSomething' part to get a popup that tells you more about the code. +hover over the 'ExplanationOfSomething' part (the text inside of the {...} curly brackets) +to get a popup that tells you more about that concept. Try out hovering by reviewing the below terminology. NOTE: When the documentation refers to these terms, they will be capitalized. @@ -33,9 +33,9 @@ const details: ExtensionMenuDisplayDetails = { }; /** @see {ExplanationOfClass} */ -/** @see {ExplanationOfInitMethod} */ export default class ExtensionNameGoesHere extends extension(details) { + /** @see {ExplanationOfInitMethod} */ init(env: Environment) { this.exampleField = 0; } @@ -43,27 +43,36 @@ export default class ExtensionNameGoesHere extends extension(details) { /** @see {ExplanationOfField} */ exampleField: number; - /** @see {ExplanationOfBlockType} */ - /** @see {ExplanationOfReporterBlock} */ - @(scratch.reporter`This increments an internal field and then reports it's value`) + /** @see {ExplanationOfExampleReporter}*/ + @(scratch.reporter`This is the block's display text (so replace me with what you want the block to say)`) exampleReporter() { return ++this.exampleField; } - - /** @see {ExplanationOfCommandBlock} */ - @(scratch.command( - (instance, $) => - /** @see {ExplanationOfBlockArg} */ - $`This is the block's display text with inputs here --> ${"string"} and here --> ${{type: "number", defaultValue: instance.exampleField}}` - )) - exampleCommand(exampleString: string, exampleNumber: number) { - alert(`This is a command! Here's what it received: ${exampleString} and ${exampleNumber}`); // Replace with what the block should do! + + /** @see {ExplanationOfReporterWithArguments}*/ + @(scratch.reporter`This is the block's display text with inputs here --> ${"string"} and here --> ${{ type: "number", defaultValue: 1 }}`) + reporterThatTakesTwoArguments(exampleString: string, exampleNumber: number) { + return exampleString + exampleNumber; + } + + /** @see {ExplanationOfExampleCommand} */ + @(scratch.command`This is the block's display text`) + exampleCommand() { + alert("This is a command!"); + } + + /** @see {ExplanationOfCommandWithExtendDefinition} */ + @(scratch.command((instance, tag) => { + console.log("Creating a block for extension: ", instance.id); + return tag`This is the block's display text`; + })) + exampleCommandWithExtendedDefinition() { + alert("This is a command defined using the extended definition strategy!"); } - /** @see {ExplanationOfHatBlock} */ + /** @see {ExplanationOfExampleHatAndBlockUtility} */ @(scratch.hat`Should the below block execute: ${"Boolean"}`) - /** @see {ExplanationOfBlockUtilityWithID} */ - async exampleHat(condition: boolean, util: BlockUtilityWithID) { + async exampleHatThatUsesBlockUtility(condition: boolean, util: BlockUtilityWithID) { return util.stackFrame.isLoop === condition; } } \ No newline at end of file diff --git a/extensions/src/common/extension/decorators/taggedTemplate.ts b/extensions/src/common/extension/decorators/taggedTemplate.ts index 43c9b091c..1d3660553 100644 --- a/extensions/src/common/extension/decorators/taggedTemplate.ts +++ b/extensions/src/common/extension/decorators/taggedTemplate.ts @@ -1,6 +1,6 @@ import { BlockMetadata, Argument, ReturnTypeByBlockType, ScratchBlockType, NoArgsBlock, OneArgBlock, BlockUtilityWithID, InlineImage, InlineImageSpecifier } from "$common/types"; import { block } from "$common/extension/decorators/blocks"; -import { ExtensionInstance } from ".."; +import { extension, ExtensionInstance } from ".."; import { TypedMethodDecorator } from "."; import type BlockUtility from "$scratch-vm/engine/block-utility"; @@ -84,5 +84,9 @@ export const scratch = { reporter: makeDecorator("reporter"), command: makeDecorator("command"), button: makeDecorator("button"), - hat: makeDecorator("hat") + hat: makeDecorator("hat"), + boolean: makeDecorator("Boolean"), + conditional: makeDecorator("conditional"), + event: makeDecorator("event"), + loop: makeDecorator("loop"), } \ No newline at end of file diff --git a/extensions/src/common/globals.ts b/extensions/src/common/globals.ts index c95f50f04..daa93b925 100644 --- a/extensions/src/common/globals.ts +++ b/extensions/src/common/globals.ts @@ -5,7 +5,7 @@ export const AuxiliaryExtensionInfo = "AuxiliaryExtensionInfo"; /** * Literal values that control the interaction between the extension framework and the Scratch GUI, - * specifically how dropdowns (tied to dynamic menus) are co-opted to support custom block arguments. + * specifically how dropdowns (tied to dynamic menus) are co-opted to support custom block arguments (and their UIs). */ export const guiDropdownInterop = { runtimeKey: "prgDropdownCustomization", diff --git a/extensions/src/common/templateDocs.ts b/extensions/src/common/templateDocs.ts index 5aad4c213..f50505ab4 100644 --- a/extensions/src/common/templateDocs.ts +++ b/extensions/src/common/templateDocs.ts @@ -1,5 +1,11 @@ + type Documentation = "See documentation below:"; +/** + * Nice job! You hovered over a JSDoc type to see more information about it. + */ +type ExplanationOfSomething = Documentation; + /** * An Extension is the [class](https://www.typescriptlang.org/docs/handbook/2/classes.html) that you'll implement that adds new functionality to the Block Programming Environment by constructing new Blocks. * @@ -38,7 +44,7 @@ type Extension = Documentation; * **NOTE:** Ignore the `.` in front of the `@` symbol -- this is just so JSDoc doesn't mess with the formatting. * ```ts * .@(scratch.command`This is the text that will display on the block`) - * exampleMethod(someText: string, noteValue: number) { + * exampleMethod() { * ... * } * ``` @@ -62,7 +68,7 @@ type BlockProgrammingEnvironment = Documentation; * The below object describes how your extension will display in the extensions menu. * * These details will be passed as the first argument to the `extension` function below - * (see the class defintion below to see how we [extend]() the value returned by the `extension` function). + * (see the class defintion below to see how we [extend]() the base class returned by the `extension` function). * * Hover over any of the fields below (e.g. `name`, `description`) to see documentation about what it is/does. */ @@ -96,54 +102,55 @@ type ExplanationOfField = Documentation; */ type ExplanationOfInitMethod = Documentation; -/** - * Below is an example of a 'Reporter' Block, which is a Block that takes 0 or more arguments - * and returns a value (likely a `string` or `number`). - * - * Hover over `exampleReporter` below to observe it's type signature and that it returns a `number` - * (which is _inferred_ by Typescript, but you could also be [explicitly stated](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#return-type-annotations)). - * - * As described in the definiton of Block above (hover over it if you need a refresher), we turn the `exampleReporter` method into a method tied to a Block by "decorating" it with the `scratch.reporter` decorator function - * (the use of the `@` tell us that it is a [decorator](https://www.typescriptlang.org/docs/handbook/decorators.html#method-decorators)). - * - * In this scenario, `scratch.reporter` serves as a [Tagged Template Literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates). This means we can use the passed-in [Template String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) to provide - * all the necessary information for the Block Programming Environment to create a Reporter Block - * tied to our method, with input fields at the positions of the templated arguments. - * - */ -type ExplanationOfReporterBlock = Documentation; - /** * Below, we define a method `exampleCommand` and decorate it with the `@scratch.command` function (similiar to above). * This is an example of a "command" block, as the underlying method takes 0 or more arguments, and returns nothing ([void](https://www.typescriptlang.org/docs/handbook/basic-types.html#void)). * * Hover over `exampleCommand` below to observe it's type signature and how it returns `void`. * + */ +type ExplanationOfExampleCommand = Documentation; + +/** + * TODO + * * **NOTE:** Here, instead of using a tagged template literal (as above), we pass another function to the `scratch` decorator. * This function takes two parameters, the first of which is a reference to our specific Extension. * As you can see in the definition of the `defaultValue` of our second argument, * this allows us to pull values off of our extension when defining our block. * The second argument references the tagged template literal we use to create the text and arguments of the block. */ -type ExplanationOfCommandBlock = Documentation; +type ExplanationOfCommandWithExtendDefinition = Documentation; /** - * We can use the `scratch` decorator functions to define four types of blocks: a command block, - * a reporter block, a button block, or a hat block. - */ -type ExplanationOfBlockType = Documentation; - -/** - * Because the underlying `exampleCommand` method takes arguments, we use a [Template String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) with placeholders that match the arguments of the method, - * which will auto-magically cause the resulting Blocks to have input fields at the positions of the templated arguments. + * Below is an example of how you define a "Reporter" Block in Scratch, which is a Block that takes 0 or more arguments and returns a value (likely a `string` or `number`). + * + * The definition has two different parts: + * - **The method (line 48):** The [method]() `exampleReporter` is the function that runs when the associated Scratch Block is executed. + * - * Hover over `exampleReporter` below to observe it's type signature and that it returns a `number` + * (which is _inferred_ by Typescript, but you could also be [explicitly stated](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#return-type-annotations)). + * - **The decorator (line 47):** The `@(scratch.reporter...)` bit above the `exampleReporter` definition is a [decorator](https://www.typescriptlang.org/docs/handbook/decorators.html) for that method (specifically, the `@` symbol is what denotes that it is a decorator). + * - This "decorator" is what allows you to associate your extension's method with a Scratch Block, as well as configure how that Block will look and behave. + * + * The `scratch.reporter` decorator function is a [Tagged Template Literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) + * which is why you see the "\`" backtick marks around some text after it. This text is actually the text that will be displayed on the associated Scratch Block. + * + * Tagged template literals will be used in a more interesting way below (see `ExplanationOfReporterWithArguments`), but for now you can just think of them as a function that takes a string argument, which would normally be invoked like this: + * `myTemplateFunction("some text");`, but is instead invoked like this ```myTemplateFunction`some text`;```. */ -type ExplanationOfBlockTextFunction = Documentation; +type ExplanationOfExampleReporter = Documentation; /** - * Because our method accepts two arguments, we must define a template literal with two placeholders. - * Each placeholder will correspond to the types of the method's arguments. + * Please read the documentation for `ExplanationOfExampleReporter` if you haven't. + * + * The below method and its `scratch.reporter` decorator are very similar to the `exampleReporter` method above, + * however `reporterThatTakesTwoArguments` is a method that takes two arguments. + * + * You can see this in the method signature of `reporterThatTakesTwoArguments` on line 54 -- it takes a `string` and a `number` as arguments. + * + * TODO not finished... */ -type ExplanationOfBlockArgs = Documentation; +type ExplanationOfReporterWithArguments = Documentation; /** * Below is an example of yet another type of Block, in this case a "Hat", which is used to determine if a stack of connected Blocks should execute or not. @@ -151,26 +158,12 @@ type ExplanationOfBlockArgs = Documentation; * Accordingly, this block must return a [boolean](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#the-primitives-string-number-and-boolean) (a true / false value). * * The best way to understand what a Hat Block does (and really all blocks) is to [start a development](https://github.com/mitmedialab/prg-extension-boilerplate#-running-an-extension) and server and play with them yourself. - */ -type ExplanationOfHatBlock = Documentation; - -/** - * Because our block method only takes one argument (besides the BlockUtility, explained below), - * we provide an `arg` field instead of `args` like we did above. * - * The `arg` field accepts only a single _Argument_ value corresponding to the specific type of our method's argument. - * - * As was the case for the `args` field above, - * it is necessary to hover over the `arg` field to understand the different forms in which you can define an _Argument_. - */ -type ExplanationOfBlockArg = Documentation; - -/** * You should notice that the final argument of our method is of type `BlockUtilityWithID`. * * For every Block method, you can optionally add a final parameter of type `BlockUtilityWithID` * which can be used to accomplish more [advanced behaviours](https://github.com/mitmedialab/prg-extension-boilerplate/tree/dev/extensions#making-use-of-the-block-utility). - * No need to worry too much about when you're first starting out, though! + * No need to worry too much about this when you're first starting out, though! * * As is the case here, note that the inclusion of a `BlockUtilityWithID` argument does not "count" * as an Argument for your Block. @@ -178,4 +171,4 @@ type ExplanationOfBlockArg = Documentation; * Thus, if your method **_only_** accepts a `BlockUtilityWithID` argument, then the `block` function will **not** * require (or allow) you to add a placeholder in the template literal -- similiar to the `exampleReporter` method / Block above. */ -type ExplanationOfBlockUtilityWithID = Documentation; \ No newline at end of file +type ExplanationOfExampleHatAndBlockUtility = Documentation; \ No newline at end of file