From 5721f81c499114c85facc89a5752974968824fc7 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Mon, 6 Jul 2020 12:59:32 -0700 Subject: [PATCH 1/5] Move ESNext to Javascript tutorial --- .../tutorials/create-block/block-anatomy.md | 8 ++++++-- .../developers/tutorials/create-block/readme.md | 11 +++++------ .../developers/tutorials/create-block/wp-plugin.md | 2 +- .../{create-block => javascript}/esnext-js.md | 0 .../developers/tutorials/javascript/readme.md | 3 +-- .../tutorials/javascript/versions-and-building.md | 2 ++ docs/toc.json | 3 ++- 7 files changed, 17 insertions(+), 12 deletions(-) rename docs/designers-developers/developers/tutorials/{create-block => javascript}/esnext-js.md (100%) diff --git a/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md b/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md index a4473da3d82d9..5eb57972002b5 100644 --- a/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md +++ b/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md @@ -1,6 +1,10 @@ -# Anatomy of a Gutenberg Block +# Anatomy of a Block -At its simplest, a block in Gutenberg is a JavaScript object with a specific set of properties. Here is the complete code for registering a block: +At its simplest, a block in Gutenberg is a JavaScript object with a specific set of properties. + +**Note:** Block development uses ESNext syntax, this refers to the latest JavaScript standard. If this is unfamiliar, I recommend reviewing the [ESNext synatx documentation](/docs/designers-developers/developers/tutorials/javascript/esnext-js.md) to familiarize yourself with the newer syntax used in modern JavaScript development. + +Here is the complete code for registering a block: ```js import { registerBlockType } from '@wordpress/blocks'; diff --git a/docs/designers-developers/developers/tutorials/create-block/readme.md b/docs/designers-developers/developers/tutorials/create-block/readme.md index ef00b74b85155..4846270097b7e 100644 --- a/docs/designers-developers/developers/tutorials/create-block/readme.md +++ b/docs/designers-developers/developers/tutorials/create-block/readme.md @@ -24,9 +24,8 @@ After activated, go to the block editor and use the inserter to search and add y 1. [Development Environment](devenv.md) 2. [WordPress Plugin](wp-plugin.md) -3. [ESNext Syntax](esnext-js.md) -4. [Anatomy of a Gutenberg Block](block-anatomy.md) -5. [Block Attributes](block-attributes.md) -6. [Code Implementation](block-code.md) -7. [Authoring Experience](author-experience.md) -8. [Finishing Touches](finishing.md) +3. [Anatomy of a Gutenberg Block](block-anatomy.md) +4. [Block Attributes](block-attributes.md) +5. [Code Implementation](block-code.md) +6. [Authoring Experience](author-experience.md) +7. [Finishing Touches](finishing.md) diff --git a/docs/designers-developers/developers/tutorials/create-block/wp-plugin.md b/docs/designers-developers/developers/tutorials/create-block/wp-plugin.md index 4c4d58a6a2e02..1fb3b15b43c7f 100644 --- a/docs/designers-developers/developers/tutorials/create-block/wp-plugin.md +++ b/docs/designers-developers/developers/tutorials/create-block/wp-plugin.md @@ -156,4 +156,4 @@ For more info, see the build section of the [Getting Started with JavaScript tut Hopefully, at this point, you have your plugin created and activated. We have the package.json with the `@wordpress/scripts` dependency, that defines the build and start scripts. The basic block is in place and can be added to the editor. -Next Section: [ESNext Syntax](esnext-js.md) +Next Section: [Anatomy of a Block](block-anatomy.md) diff --git a/docs/designers-developers/developers/tutorials/create-block/esnext-js.md b/docs/designers-developers/developers/tutorials/javascript/esnext-js.md similarity index 100% rename from docs/designers-developers/developers/tutorials/create-block/esnext-js.md rename to docs/designers-developers/developers/tutorials/javascript/esnext-js.md diff --git a/docs/designers-developers/developers/tutorials/javascript/readme.md b/docs/designers-developers/developers/tutorials/javascript/readme.md index af06c6c4c6aca..c0a80e1b3e20c 100644 --- a/docs/designers-developers/developers/tutorials/javascript/readme.md +++ b/docs/designers-developers/developers/tutorials/javascript/readme.md @@ -8,7 +8,6 @@ JavaScript is a programming language which is loaded and executed in your web br The block editor introduced in WordPress 5.0 is written in JavaScript, with the code run in the browser, and not on the server, this allows for a richer and more dynamic user experience. It also requires you to learn how to use JavaScript to extend and enhance the block editor. - ### Table of Contents 1. [Plugins Background](/docs/designers-developers/developers/tutorials/javascript/plugins-background.md) @@ -18,4 +17,4 @@ The block editor introduced in WordPress 5.0 is written in JavaScript, with the 5. [JavaScript Versions and Building](/docs/designers-developers/developers/tutorials/javascript/versions-and-building.md) 6. [Scope your code](/docs/designers-developers/developers/tutorials/javascript/scope-your-code.md) 7. [JavaScript Build Step](/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md) - +8. [ESNext Syntax](/docs/designers-developers/developers/tutorials/javascript/esnext-js.md) diff --git a/docs/designers-developers/developers/tutorials/javascript/versions-and-building.md b/docs/designers-developers/developers/tutorials/javascript/versions-and-building.md index f0593324b09a0..ccd02f71aca0b 100644 --- a/docs/designers-developers/developers/tutorials/javascript/versions-and-building.md +++ b/docs/designers-developers/developers/tutorials/javascript/versions-and-building.md @@ -11,3 +11,5 @@ Additionally, the ESNext code examples in the handbook include [JSX syntax](http For simplicity, the JavaScript tutorial uses the ES5 definition, without JSX. This code can run straight in your browser and does not require an additional build step. In many cases, it is perfectly fine to follow the same approach for simple plugins or experimenting. As your codebase grows in complexity it might be a good idea to switch to ESNext. You will find the majority of code and documentation across the block editor uses ESNext. See the [JavaScript Build Setup documentation](/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md) for setting up a development environment using ESNext syntax. + +See the [ESNext syntax documentation](/docs/designers-developers/developers/tutorials/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and ESNext. diff --git a/docs/toc.json b/docs/toc.json index d18e4db1c67af..f6ff27a3ae166 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -98,7 +98,8 @@ { "docs/designers-developers/developers/tutorials/javascript/troubleshooting.md": [] }, { "docs/designers-developers/developers/tutorials/javascript/versions-and-building.md": [] }, { "docs/designers-developers/developers/tutorials/javascript/scope-your-code.md": [] }, - { "docs/designers-developers/developers/tutorials/javascript/js-build-setup.md": [] } + { "docs/designers-developers/developers/tutorials/javascript/js-build-setup.md": [] }, + { "docs/designers-developers/developers/tutorials/javascript/esnext-js.md": [] } ] }, { "docs/designers-developers/developers/tutorials/block-tutorial/readme.md": [ { "docs/designers-developers/developers/tutorials/block-tutorial/writing-your-first-block-type.md": [] }, From 935f2c713d4dae276338a39b81d91f26a877037b Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Mon, 6 Jul 2020 13:00:03 -0700 Subject: [PATCH 2/5] Update manifest --- docs/manifest.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/manifest.json b/docs/manifest.json index 6186b532ecf51..00b3eb4a95aed 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -503,6 +503,12 @@ "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/js-build-setup.md", "parent": "javascript" }, + { + "title": "ESNext Syntax", + "slug": "esnext-js", + "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/esnext-js.md", + "parent": "javascript" + }, { "title": "Blocks", "slug": "block-tutorial", From da8f3156bea055a1577d61efdb7dd775e90186a4 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Mon, 6 Jul 2020 13:48:14 -0700 Subject: [PATCH 3/5] Update ESNext, remove tutorial references --- .../developers/tutorials/javascript/esnext-js.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/javascript/esnext-js.md b/docs/designers-developers/developers/tutorials/javascript/esnext-js.md index e5661cd4d97d9..f478d1fd596ea 100644 --- a/docs/designers-developers/developers/tutorials/javascript/esnext-js.md +++ b/docs/designers-developers/developers/tutorials/javascript/esnext-js.md @@ -1,11 +1,9 @@ # ESNext Syntax -A brief aside to discuss JavaScript. - -## Background - The JavaScript language continues to evolve, the syntax used to write JavaScript code is not fixed but changes over time. [Ecma International](https://en.wikipedia.org/wiki/Ecma_International) is the organization that sets the standard for the language, officially called [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript). A new standard for JavaScript is published each year, the 6th edition published in 2015 is often referred to as ES6. Our usage would more appropriately be **ESNext** referring to the latest standard. The build step is what converts this latest syntax of JavaScript to a version understood by browsers. +Here are some common ESNext syntax patterns used throughout the Gutenberg project. + ## Destructuring Assignments The [destructuring assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) syntax allows you to pull apart arrays, or properties from objects into their own variable. @@ -123,5 +121,3 @@ Here are a few more resources that may help - [ES5 vs ES6 with example code](https://medium.com/recraftrelic/es5-vs-es6-with-example-code-9901fa0136fc) - [Top 10 ES6 Features by Example](https://blog.pragmatists.com/top-10-es6-features-by-example-80ac878794bb) - [ES6 Syntax and Feature Overview](https://www.taniarascia.com/es6-syntax-and-feature-overview/) - -Next Section: [Anatomy of a Gutenberg Block](block-anatomy.md) From e4c53e7ff13b179ba51243f647ec6a8ff3658e39 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Thu, 9 Jul 2020 06:33:48 -0700 Subject: [PATCH 4/5] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Greg Ziółkowski --- .../developers/tutorials/create-block/block-anatomy.md | 2 +- .../developers/tutorials/create-block/readme.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md b/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md index 5eb57972002b5..f879f4cc4220b 100644 --- a/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md +++ b/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md @@ -1,6 +1,6 @@ # Anatomy of a Block -At its simplest, a block in Gutenberg is a JavaScript object with a specific set of properties. +At its simplest, a block in the WordPress block editor is a JavaScript object with a specific set of properties. **Note:** Block development uses ESNext syntax, this refers to the latest JavaScript standard. If this is unfamiliar, I recommend reviewing the [ESNext synatx documentation](/docs/designers-developers/developers/tutorials/javascript/esnext-js.md) to familiarize yourself with the newer syntax used in modern JavaScript development. diff --git a/docs/designers-developers/developers/tutorials/create-block/readme.md b/docs/designers-developers/developers/tutorials/create-block/readme.md index 4846270097b7e..613d881f734dc 100644 --- a/docs/designers-developers/developers/tutorials/create-block/readme.md +++ b/docs/designers-developers/developers/tutorials/create-block/readme.md @@ -24,7 +24,7 @@ After activated, go to the block editor and use the inserter to search and add y 1. [Development Environment](devenv.md) 2. [WordPress Plugin](wp-plugin.md) -3. [Anatomy of a Gutenberg Block](block-anatomy.md) +3. [Anatomy of a Block](block-anatomy.md) 4. [Block Attributes](block-attributes.md) 5. [Code Implementation](block-code.md) 6. [Authoring Experience](author-experience.md) From d4c18c2a2b8c8dcbdbeb3b47ba17ac8fb58cfd04 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Thu, 9 Jul 2020 06:57:35 -0700 Subject: [PATCH 5/5] Add link to new ESNext syntax from build step page --- .../tutorials/javascript/js-build-setup.md | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md index c917d1e59e796..101fb09d48e0a 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md @@ -1,16 +1,18 @@ # JavaScript Build Setup -This page covers how to set up your development environment to use the ESNext and [JSX](https://reactjs.org/docs/introducing-jsx.html) syntaxes. ESNext is JavaScript code written using features that are only available in a specification greater than ECMAScript 5 (ES5 for short). JSX is a custom syntax extension to JavaScript that allows you to write JavaScript in a more familiar tag syntax. +ESNext is JavaScript written using syntax and features only available in a version newer than browser support—the support browser versions is referred to as ECMAScript 5 (ES5). [JSX](https://reactjs.org/docs/introducing-jsx.html) is a custom syntax extension to JavaScript, created by React project, that allows you to write JavaScript using a familiar HTML tag-like syntax. -This documentation covers development for your plugin to work with the Gutenberg project (ie: the block editor). If you want to develop Gutenberg itself, see the [Getting Started](/docs/contributors/getting-started.md) documentation. +See the [ESNext syntax documentation](/docs/designers-developers/developers/tutorials/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and ESNext. -Most browsers cannot interpret or run ESNext and JSX syntaxes, so we use a transformation step to convert these syntaxes to code that browsers can understand. +Let's set up your development environment to use these syntaxes, we'll cover development for your plugin to work with the Gutenberg project (ie: the block editor). If you want to develop on Gutenberg itself, see the [Getting Started](/docs/contributors/getting-started.md) documentation. + +Browsers cannot interpret or run ESNext and JSX syntaxes, so we must use a transformation step to convert these syntaxes to code that browsers can understand. There are a few reasons to use ESNext and this extra step of transformation: -- It makes for simpler code that is easier to read and write. -- Using a transformation step allows for tools to optimize the code to work on the widest variety of browsers. -- By using a build step you can organize your code into smaller modules and files that can be bundled together into a single download. +- It makes for simpler code that is easier to read and write. +- Using a transformation step allows for tools to optimize the code to work on the widest variety of browsers. +- By using a build step you can organize your code into smaller modules and files that can be bundled together into a single download. There are different tools that can perform this transformation or build step; WordPress uses webpack and Babel. @@ -28,9 +30,9 @@ Both webpack and Babel are tools written in JavaScript and run using [Node.js](h First, you need to set up Node.js for your development environment. The steps required depend on your operating system, if you have a package manager installed, setup can be as straightforward as: -- Ubuntu: `apt install nodejs npm` -- macOS: `brew install node` -- Windows: `choco install node` +- Ubuntu: `apt install nodejs npm` +- macOS: `brew install node` +- Windows: `choco install node` If you are not using a package manager, see the [Node.js download page](https://nodejs.org/en/download/) for installers and binaries. @@ -42,14 +44,14 @@ The Node Package Manager (npm) is a tool included with node. npm allows you to i To start a new node project, first create a directory to work in: -``` +```sh mkdir myguten-block cd myguten-block ``` -You create a new package.json running `npm init` in your terminal. This will walk you through creating your package.json file: +You create a new package.json running `npm init` in your terminal. This will walk you through creating your package.json file: -``` +```sh npm init package name: (myguten-block) myguten-block