diff --git a/docs/contributors/documentation/README.md b/docs/contributors/documentation/README.md index b608565cda401..8bebe02c119db 100644 --- a/docs/contributors/documentation/README.md +++ b/docs/contributors/documentation/README.md @@ -88,26 +88,26 @@ An example, the link to this page is: `/docs/contributors/documentation/README.m The code example in markdown should be wrapped in three tick marks \`\`\` and should additionally include a language specifier. See this [GitHub documentation around fenced code blocks](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks). -A unique feature to the Gutenberg documentation is the `codetabs` toggle, this allows two versions of code to be shown at once. This is used for showing both `ESNext` and `ES5` code samples. For example, [on this block tutorial page](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md). +A unique feature to the Gutenberg documentation is the `codetabs` toggle, this allows two versions of code to be shown at once. This is used for showing both `JSX` and `Plain` code samples. For example, [on this block tutorial page](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md). Here is an example `codetabs` section: ````md - {% codetabs %} - {% ESNext %} + \{\% codetabs \%\} + \{\% JSX \%\} ```js - // ESNext code here + // JSX code here ``` - {% ES5 %} + \{\% Plain \%\} ```js - // ES5 code here + // Plain code here ``` - {% end %} + \{\% end \%\} ```` -The preferred format for code examples is ESNext, this should be the default view. The example placed first in source will be shown as the default. +The preferred format for code examples is JSX, this should be the default view. The example placed first in source will be shown as the default. -**Note:** it is not required to include ES5 code examples. The guidance is to include `ES5` code for beginner tutorials, but the majority of code in Gutenberg packages and across the larger React and JavaScript ecosystem is in ESNext. +**Note:** It is not required to include plain JavaScript code examples for every guide. The recommendation is to include plain code for beginner tutorials or short examples, but the majority of code in Gutenberg packages and across the larger React and JavaScript ecosystem are in JSX that requires a build process. ### Callout notices diff --git a/docs/how-to-guides/block-tutorial/README.md b/docs/how-to-guides/block-tutorial/README.md index d16645fdf45e0..b1ff5a19119c2 100644 --- a/docs/how-to-guides/block-tutorial/README.md +++ b/docs/how-to-guides/block-tutorial/README.md @@ -4,6 +4,6 @@ The purpose of this tutorial is to step through the fundamentals of creating a n To follow along with this tutorial, you can [download the accompanying WordPress plugin](https://github.com/WordPress/gutenberg-examples) which includes all of the examples for you to try on your own site. At each step along the way, experiment by modifying the examples with your own ideas, and observe the effects they have on the block's behavior. -Code snippets are provided in two formats "ES5" and "ESNext". ES5 refers to "classic" JavaScript (ECMAScript 5), while ESNext refers to the next versions of the language standard, plus JSX syntax. You can change between them using tabs found above each code example. Using ESNext, does require you to run [the JavaScript build step](/docs/how-to-guides/javascript/js-build-setup/) to compile your code to a browser compatible format. +Code snippets are provided in two formats "JSX" and "Plain". JSX refers to JavaScript code that uses JSX syntax which requires a build step. Plain refers to "classic" JavaScript that does not require building. You can change between them using tabs found above each code example. Using JSX, does require you to run [the JavaScript build step](/docs/how-to-guides/javascript/js-build-setup/) to compile your code to a browser compatible format. -Note that it is not required to use ESNext to create blocks or extend the editor, you can use classic JavaScript. However, once familiar with ESNext, developers find it is easier to read and write, thus most code examples you'll find use the ESNext syntax. +Note that it is not required to use JSX to create blocks or extend the editor, you can use classic JavaScript. However, once familiar with JSX and the build step, many developers tend to find it is easier to read and write, thus most code examples you'll find use the JSX syntax. diff --git a/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md index 7ffa80cb2d471..e7af2c308ebbb 100644 --- a/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md +++ b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md @@ -5,7 +5,7 @@ In the [previous section](/docs/how-to-guides/block-tutorial/writing-your-first- The editor will automatically generate a class name for each block type to simplify styling. It can be accessed from the object argument passed to the edit and save functions. In this section, we will create a stylesheet to use that class name. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx import { registerBlockType } from '@wordpress/blocks'; @@ -38,7 +38,7 @@ registerBlockType( 'gutenberg-examples/example-02-stylesheets', { } ); ``` -{% ES5 %} +{% Plain %} ```js ( function ( blocks, element, blockEditor ) { diff --git a/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md b/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md index 06492136e6337..0983babbd591d 100644 --- a/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md +++ b/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md @@ -11,7 +11,7 @@ When the user selects a block, a number of control buttons may be shown in a too You can also customize the toolbar to include controls specific to your block type. If the return value of your block type's `edit` function includes a `BlockControls` element, those controls will be shown in the selected block's toolbar. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx import { registerBlockType } from '@wordpress/blocks'; @@ -92,7 +92,7 @@ registerBlockType( 'gutenberg-examples/example-04-controls-esnext', { } ); ``` -{% ES5 %} +{% Plain %} ```js ( function ( blocks, blockEditor, element ) { diff --git a/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md b/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md index 770fa53ec7c15..abc58e6c5069b 100644 --- a/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md +++ b/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md @@ -18,7 +18,7 @@ Block attributes can be used for any content or setting you want to save for tha The following code example shows how to create a dynamic block that shows only the last post as a link. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx import { registerBlockType } from '@wordpress/blocks'; @@ -52,7 +52,7 @@ registerBlockType( 'gutenberg-examples/example-dynamic', { } ); ``` -{% ES5 %} +{% Plain %} ```js ( function ( blocks, element, data, blockEditor ) { @@ -155,7 +155,7 @@ Gutenberg 2.8 added the [``](/packages/server-side-render/READ _Server-side render is meant as a fallback; client-side rendering in JavaScript is always preferred (client rendering is faster and allows better editor manipulation)._ {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx import { registerBlockType } from '@wordpress/blocks'; @@ -182,7 +182,7 @@ registerBlockType( 'gutenberg-examples/example-dynamic', { } ); ``` -{% ES5 %} +{% Plain %} ```js ( function ( blocks, element, serverSideRender, blockEditor ) { @@ -219,4 +219,4 @@ registerBlockType( 'gutenberg-examples/example-dynamic', { {% end %} -Note that this code uses the `wp-server-side-render` package but not `wp-data`. Make sure to update the dependencies in the PHP code. You can use wp-scripts and ESNext setup for auto dependencies (see the [gutenberg-examples repo](https://github.com/WordPress/gutenberg-examples/tree/HEAD/01-basic-esnext) for PHP code setup). +Note that this code uses the `wp-server-side-render` package but not `wp-data`. Make sure to update the dependencies in the PHP code. You can use wp-scripts to automatically build dependencies (see the [gutenberg-examples repo](https://github.com/WordPress/gutenberg-examples/tree/HEAD/01-basic-esnext) for PHP code setup). diff --git a/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md b/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md index ed0a708c927d4..f35a5630a1a9e 100644 --- a/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md +++ b/docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md @@ -53,7 +53,7 @@ Because `RichText` allows for nested nodes, you'll most often use it in conjunct Here is the complete block definition for Example 03. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx import { registerBlockType } from '@wordpress/blocks'; @@ -108,7 +108,7 @@ registerBlockType( 'gutenberg-examples/example-03-editable-esnext', { } ); ``` -{% ES5 %} +{% Plain %} ```js ( function ( blocks, blockEditor, element ) { diff --git a/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md b/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md index decbb981fa20a..d1b28f84a651a 100644 --- a/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md +++ b/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md @@ -7,7 +7,7 @@ Note: A single block can only contain one `InnerBlock` component. Here is the basic InnerBlocks usage. {% codetabs %} -{% ESNext %} +{% JSX %} ```js import { registerBlockType } from '@wordpress/blocks'; @@ -38,7 +38,7 @@ registerBlockType( 'gutenberg-examples/example-06', { } ); ``` -{% ES5 %} +{% Plain %} ```js ( function ( blocks, element, blockEditor ) { @@ -92,7 +92,7 @@ Specifying this prop does not affect the layout of the inner blocks, but results Use the template property to define a set of blocks that prefill the InnerBlocks component when inserted. You can set attributes on the blocks to define their use. The example below shows a book review template using InnerBlocks component and setting placeholders values to show the block usage. {% codetabs %} -{% ESNext %} +{% JSX %} ```js const MY_TEMPLATE = [ @@ -113,7 +113,7 @@ const MY_TEMPLATE = [ }, ``` -{% ES5 %} +{% Plain %} ```js const MY_TEMPLATE = [ diff --git a/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md b/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md index b0a0551485238..5b312944df1a9 100644 --- a/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md +++ b/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md @@ -38,7 +38,7 @@ add_action( 'init', 'gutenberg_examples_01_register_block' ); Note the above example, shows using the [wp-scripts build step](/docs/how-to-guides/javascript/js-build-setup/) that automatically sets dependencies and versions the file. -If you were using the ES5 code, you would specify `array( 'wp-blocks', 'wp-element' )` as the dependency array. See the [example 01](https://github.com/WordPress/gutenberg-examples/blob/HEAD/01-basic/index.php) in Gutenberg Examples repository for full syntax. +If you were using the plain code, you would specify `array( 'wp-blocks', 'wp-element' )` as the dependency array. See the [example 01](https://github.com/WordPress/gutenberg-examples/blob/HEAD/01-basic/index.php) in Gutenberg Examples repository for full syntax. - **`wp-blocks`** includes block type registration and related functions - **`wp-element`** includes the [WordPress Element abstraction](/packages/element/README.md) for describing the structure of your blocks @@ -48,7 +48,7 @@ If you were using the ES5 code, you would specify `array( 'wp-blocks', 'wp-eleme With the script enqueued, let's look at the implementation of the block itself: {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx import { registerBlockType } from '@wordpress/blocks'; @@ -85,7 +85,7 @@ registerBlockType( 'gutenberg-examples/example-01-basic-esnext', { } ); ``` -{% ES5 %} +{% Plain %} ```js ( function ( blocks, element, blockEditor ) { diff --git a/docs/how-to-guides/internationalization.md b/docs/how-to-guides/internationalization.md index 4204a9680d936..fa28b78b37690 100644 --- a/docs/how-to-guides/internationalization.md +++ b/docs/how-to-guides/internationalization.md @@ -38,7 +38,7 @@ add_action( 'init', 'myguten_block_init' ); In your code, you can include the i18n functions. The most common function is **\_\_** (a double underscore) which provides translation of a simple string. Here is a basic block example: {% codetabs %} -{% ESNext %} +{% JSX %} ```js import { __ } from '@wordpress/i18n'; @@ -64,7 +64,7 @@ registerBlockType( 'myguten/simple', { } ); ``` -{% ES5 %} +{% Plain %} ```js const { __ } = wp.i18n; diff --git a/docs/how-to-guides/javascript/versions-and-building.md b/docs/how-to-guides/javascript/versions-and-building.md index afe4c365b51d7..dd2f63c946906 100644 --- a/docs/how-to-guides/javascript/versions-and-building.md +++ b/docs/how-to-guides/javascript/versions-and-building.md @@ -1,15 +1,14 @@ # JavaScript Versions and Build Step -The Block Editor Handbook shows JavaScript examples in two syntaxes: ES5 and ESNext. These are version names for the JavaScript language standard definitions. You may also see elsewhere the names ES6, or ECMAScript 2015 mentioned. See the [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript) Wikipedia article for all the details. +The Block Editor Handbook shows JavaScript examples in two syntaxes: JSX and Plain. -ES5 code is compatible with WordPress's minimum [target for browser support](https://make.wordpress.org/core/handbook/best-practices/browser-support/). +Plain refers to JavaScript code compatible with WordPress's minimum [target for browser support](https://make.wordpress.org/core/handbook/best-practices/browser-support/) without requiring a transpilation step. This step is commonly referred to as a build process. -"ESNext" doesn't refer to a specific version of JavaScript, but is "dynamic" and refers to the next language definitions, whatever they might be. Because some browsers won't support these features yet (because they're new or proposed), an extra build step is required to transform the code to a syntax that works in all browsers. Webpack and babel are the tools that perform this transformation step. +"JSX" doesn't refer to a specific version of JavaScript, but refers to the latest language definition plus +[JSX syntax](https://reactjs.org/docs/introducing-jsx.html), a syntax that blends HTML and JavaScript. JSX makes it easier to read and write markup code, but does require a build step to transpile into code compatible with browers. Webpack and babel are the tools that perform this transpilation step. -Additionally, the ESNext code examples in the handbook include [JSX syntax](https://reactjs.org/docs/introducing-jsx.html), a syntax that blends HTML and JavaScript. JSX makes it easier to read and write markup code, but does require a build step to transform into compatible code. +For simplicity, the JavaScript tutorial uses the Plain 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 JSX. You will find the majority of code and documentation across the block editor uses JSX. -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/how-to-guides/javascript/js-build-setup.md) for setting up a development environment using JSX syntax. -See the [JavaScript Build Setup documentation](/docs/how-to-guides/javascript/js-build-setup.md) for setting up a development environment using ESNext syntax. - -See the [ESNext syntax documentation](/docs/how-to-guides/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and ESNext. +See the [ESNext syntax documentation](/docs/how-to-guides/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and more modern approaches. diff --git a/docs/how-to-guides/metabox/meta-block-3-add.md b/docs/how-to-guides/metabox/meta-block-3-add.md index 09a1e74337f7b..c3c4f576cd18b 100644 --- a/docs/how-to-guides/metabox/meta-block-3-add.md +++ b/docs/how-to-guides/metabox/meta-block-3-add.md @@ -9,7 +9,7 @@ The hook `useEntityProp` can be used by the blocks to get or change meta values. Add this code to your JavaScript file (this tutorial will call the file `myguten.js`): {% codetabs %} -{% ESNext %} +{% JSX %} ```js import { registerBlockType } from '@wordpress/blocks'; @@ -54,7 +54,7 @@ registerBlockType( 'myguten/meta-block', { } ); ``` -{% ES5 %} +{% Plain %} ```js ( function ( wp ) { diff --git a/docs/how-to-guides/platform/custom-block-editor/README.md b/docs/how-to-guides/platform/custom-block-editor/README.md index 22a53e7224415..0db06e7193513 100644 --- a/docs/how-to-guides/platform/custom-block-editor/README.md +++ b/docs/how-to-guides/platform/custom-block-editor/README.md @@ -12,8 +12,6 @@ To follow along with this tutorial, you can [download the accompanying WordPress ## Code Syntax -Code snippets are provided in "ESNext". ESNext refers to the next versions of the language standard, plus JSX syntax. - -Note that it is not required to use ESNext to create blocks or extend the editor, you can use classic JavaScript. However, once familiar with ESNext, developers find it is easier to read and write, thus most code examples you'll find use the ESNext syntax. +Code snippets are provided using JSX syntax. Note it is not required to use JSX to create blocks or extend the editor, you can use plain JavaScript. However, once familiar with JSX, many developers tend find it is easier to read and write, thus most code examples you'll find use that syntax. - [Start custom block editor tutorial](/docs/reference-guides/platform/custom-block-editor/tutorial.md) diff --git a/docs/reference-guides/block-api/block-attributes.md b/docs/reference-guides/block-api/block-attributes.md index 844621a41dca3..de9b6e9bc139e 100644 --- a/docs/reference-guides/block-api/block-attributes.md +++ b/docs/reference-guides/block-api/block-attributes.md @@ -361,7 +361,7 @@ Attributes may be obtained from a post's meta rather than from the block's repre From here, meta attributes can be read and written by a block using the same interface as any attribute: {% codetabs %} -{% ESNext %} +{% JSX %} ```js edit( { attributes, setAttributes } ) { @@ -373,7 +373,7 @@ edit( { attributes, setAttributes } ) { }, ``` -{% ES5 %} +{% Plain %} ```js edit: function( props ) { diff --git a/docs/reference-guides/block-api/block-deprecation.md b/docs/reference-guides/block-api/block-deprecation.md index 7335ba88e604b..7408f33db3b27 100644 --- a/docs/reference-guides/block-api/block-deprecation.md +++ b/docs/reference-guides/block-api/block-deprecation.md @@ -15,9 +15,6 @@ For blocks with multiple deprecations, it may be easier to save each deprecation ### Example: -{% codetabs %} -{% ESNext %} - ```js const v1 = {}; const v2 = {}; @@ -25,17 +22,6 @@ const v3 = {}; const deprecated = [ v3, v2, v1 ]; ``` -{% ES5 %} - -```js -var v1 = {}; -var v2 = {}; -var v3 = {}; -var deprecated = [ v3, v2, v1 ]; -``` - -{% end %} - It is also recommended to keep [fixtures](https://github.com/WordPress/gutenberg/blob/HEAD/test/integration/fixtures/blocks/README.md) which contain the different versions of the block content to allow you to easily test that new deprecations and migrations are working across all previous versions of the block. Deprecations are defined on a block type as its `deprecated` property, an array of deprecation objects where each object takes the form: @@ -51,7 +37,7 @@ It's important to note that `attributes`, `supports`, and `save` are not automat ### Example: {% codetabs %} -{% ESNext %} +{% JSX %} ```js const { registerBlockType } = wp.blocks; @@ -83,7 +69,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', { } ); ``` -{% ES5 %} +{% Plain %} ```js var el = wp.element.createElement, @@ -127,7 +113,7 @@ Sometimes, you need to update the attributes set to rename or modify old attribu ### Example: {% codetabs %} -{% ESNext %} +{% JSX %} ```js const { registerBlockType } = wp.blocks; @@ -169,7 +155,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', { } ); ``` -{% ES5 %} +{% Plain %} ```js var el = wp.element.createElement, @@ -224,7 +210,7 @@ E.g: a block wants to migrate a title attribute to a paragraph innerBlock. ### Example: {% codetabs %} -{% ESNext %} +{% JSX %} ```js const { registerBlockType } = wp.blocks; @@ -268,7 +254,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', { } ); ``` -{% ES5 %} +{% Plain %} ```js var el = wp.element.createElement, diff --git a/docs/reference-guides/block-api/block-edit-save.md b/docs/reference-guides/block-api/block-edit-save.md index 90f94f85a36a6..e24f47e9ac71d 100644 --- a/docs/reference-guides/block-api/block-edit-save.md +++ b/docs/reference-guides/block-api/block-edit-save.md @@ -7,7 +7,7 @@ When registering a block, the `edit` and `save` functions provide the interface The `edit` function describes the structure of your block in the context of the editor. This represents what the editor will render when the block is used. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx import { useBlockProps } from '@wordpress/block-editor'; @@ -26,7 +26,7 @@ const blockSettings = { }; ``` -{% ES5 %} +{% Plain %} ```js var blockSettings = { @@ -51,7 +51,7 @@ The first thing to notice here is the use of the `useBlockProps` React hook on t If the element wrapper needs any extra custom HTML attributes, these need to be passed as an argument to the `useBlockProps` hook. For example to add a `my-random-classname` className to the wrapper, you can use the following code: {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx import { useBlockProps } from '@wordpress/block-editor'; @@ -72,7 +72,7 @@ const blockSettings = { }; ``` -{% ES5 %} +{% Plain %} ```js var blockSettings = { @@ -101,7 +101,7 @@ The `attributes` property surfaces all the available attributes and their corres In this case, assuming we had defined an attribute of `content` during block registration, we would receive and use that value in our edit function: {% codetabs %} -{% ESNext %} +{% JSX %} ```js edit: ( { attributes } ) => { @@ -111,7 +111,7 @@ edit: ( { attributes } ) => { }; ``` -{% ES5 %} +{% Plain %} ```js edit: function( props ) { @@ -134,7 +134,7 @@ The value of `attributes.content` will be displayed inside the `div` when insert The isSelected property is an object that communicates whether the block is currently selected. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx edit: ( { attributes, isSelected } ) => { @@ -151,7 +151,7 @@ edit: ( { attributes, isSelected } ) => { }; ``` -{% ES5 %} +{% Plain %} ```js edit: function( props ) { @@ -179,7 +179,7 @@ edit: function( props ) { This function allows the block to update individual attributes based on user interactions. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx edit: ( { attributes, setAttributes, isSelected } ) => { @@ -201,7 +201,7 @@ edit: ( { attributes, setAttributes, isSelected } ) => { }; ``` -{% ES5 %} +{% Plain %} ```js edit: function( props ) { @@ -233,7 +233,7 @@ edit: function( props ) { When using attributes that are objects or arrays it's a good idea to copy or clone the attribute prior to updating it: {% codetabs %} -{% ESNext %} +{% JSX %} ```js // Good - a new array is created from the old list attribute and a new list item: @@ -249,7 +249,7 @@ const addListItem = ( newListItem ) => { }; ``` -{% ES5 %} +{% Plain %} ```js // Good - cloning the old list @@ -276,7 +276,7 @@ Why do this? In JavaScript, arrays and objects are passed by reference, so this The `save` function defines the way in which the different attributes should be combined into the final markup, which is then serialized into `post_content`. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx save: () => { @@ -286,7 +286,7 @@ save: () => { }; ``` -{% ES5 %} +{% Plain %} ```js save: function() { @@ -327,7 +327,7 @@ Like the `edit` function, when rendering static blocks, it's important to add th As with `edit`, the `save` function also receives an object argument including attributes which can be inserted into the markup. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx save: ( { attributes } ) => { @@ -337,7 +337,7 @@ save: ( { attributes } ) => { }; ``` -{% ES5 %} +{% Plain %} ```js save: function( props ) { @@ -362,7 +362,7 @@ Here are a couple examples of using attributes, edit, and save all together. For ### Saving Attributes to Child Elements {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx attributes: { @@ -396,7 +396,7 @@ save: ( { attributes } ) => { }, ``` -{% ES5 %} +{% Plain %} ```js attributes: { @@ -444,7 +444,7 @@ Ideally, the attributes saved should be included in the markup. However, there a This example could be for a dynamic block, such as the [Latest Posts block](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/latest-posts/index.js), which renders the markup server-side. The save function is still required, however in this case it simply returns null since the block is not saving content from the editor. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx attributes: { @@ -474,7 +474,7 @@ save: () => { } ``` -{% ES5 %} +{% Plain %} ```js attributes: { diff --git a/docs/reference-guides/block-api/block-transforms.md b/docs/reference-guides/block-api/block-transforms.md index d3488c9f2995d..e1613c4664c4c 100644 --- a/docs/reference-guides/block-api/block-transforms.md +++ b/docs/reference-guides/block-api/block-transforms.md @@ -50,9 +50,6 @@ A transformation of type `block` is an object that takes the following parameter To declare this transformation we add the following code into the heading block configuration, which uses the `createBlock` function from the [`wp-blocks` package](/packages/blocks/README.md#createBlock). -{% codetabs %} -{% ESNext %} - ```js transforms: { from: [ @@ -69,33 +66,10 @@ transforms: { }, ``` -{% ES5 %} - -```js -transforms: { - from: [ - { - type: 'block', - blocks: [ 'core/paragraph' ], - transform: function ( attributes ) { - return createBlock( 'core/heading', { - content: attributes.content, - } ); - }, - }, - ] -}, -``` - -{% end %} - **Example: blocks that have InnerBlocks** A block with InnerBlocks can also be transformed from and to another block with InnerBlocks. -{% codetabs %} -{% ESNext %} - ```js transforms: { to: [ @@ -114,28 +88,6 @@ transforms: { }, ``` -{% ES5 %} - -```js -transforms: { - to: [ - { - type: 'block', - blocks: [ 'some/block-with-innerblocks' ], - transform: function( attributes, innerBlocks ) { - return createBlock( - 'some/other-block-with-innerblocks', - attributes, - innerBlocks - ); - }, - }, - ], -}, -``` - -{% end %} - ### Enter This type of transformations support the _from_ direction, allowing blocks to be created from some content introduced by the user. They're applied in a new block line after the user has introduced some content and hit the ENTER key. @@ -151,9 +103,6 @@ A transformation of type `enter` is an object that takes the following parameter To create a separator block when the user types the hypen three times and then hits the ENTER key we can use the following code: -{% codetabs %} -{% ESNext %} - ```js transforms = { from: [ @@ -166,24 +115,6 @@ transforms = { }; ``` -{% ES5 %} - -```js -transforms = { - from: [ - { - type: 'enter', - regExp: /^-{3,}$/, - transform: function ( value ) { - return createBlock( 'core/separator' ); - }, - }, - ], -}; -``` - -{% end %} - ### Files This type of transformations support the _from_ direction, allowing blocks to be created from files dropped into the editor. @@ -199,9 +130,6 @@ A transformation of type `files` is an object that takes the following parameter To create a File block when the user drops a file into the editor we can use the following code: -{% codetabs %} -{% ESNext %} - ```js transforms: { from: [ @@ -227,37 +155,6 @@ transforms: { } ``` -{% ES5 %} - -```js -transforms: { - from: [ - { - type: 'files', - isMatch: function ( files ) { - return files.length === 1; - }, - // By defining a lower priority than the default of 10, - // we make that the File block to be created as a fallback, - // if no other transform is found. - priority: 15, - transform: function ( files ) { - var file = files[ 0 ]; - var blobURL = createBlobURL( file ); - // File will be uploaded in componentDidMount() - return createBlock( 'core/file', { - href: blobURL, - fileName: file.name, - textLinkHref: blobURL, - } ); - }, - }, - ]; -} -``` - -{% end %} - ### Prefix This type of transformations support the _from_ direction, allowing blocks to be created from some text typed by the user. They're applied when, in a new block line, the user types some text and then adds a trailing space. @@ -273,9 +170,6 @@ A transformation of type `prefix` is an object that takes the following paramete If we want to create a custom block when the user types the question mark, we could use this code: -{% codetabs %} -{% ESNext %} - ```js transforms: { from: [ @@ -292,26 +186,6 @@ transforms: { } ``` -{% ES5 %} - -```js -transforms: { - from: [ - { - type: 'prefix', - prefix: '?', - transform: function ( content ) { - return createBlock( 'my-plugin/question', { - content, - } ); - }, - }, - ]; -} -``` - -{% end %} - ### Raw This type of transformations support the _from_ direction, allowing blocks to be created from raw HTML nodes. They're applied when the user executes the "Convert to Blocks" action from within the block setting UI menu, as well as when some content is pasted or dropped into the editor. @@ -329,9 +203,6 @@ A transformation of type `raw` is an object that takes the following parameters: If we want to create an Embed block when the user pastes some URL in the editor, we could use this code: -{% codetabs %} -{% ESNext %} - ```js transforms: { from: [ @@ -350,29 +221,6 @@ transforms: { } ``` -{% ES5 %} - -```js -transforms: { - from: [ - { - type: 'raw', - isMatch: function( node ) { - return node.nodeName === 'P' && - /^\s*(https?:\/\/\S+)\s*$/i.test( node.textContent ); - }, - transform: function( node ) { - return createBlock( 'core/embed', { - url: node.textContent.trim(), - } ); - }, - }, - ], -} -``` - -{% end %} - ### Shortcode This type of transformations support the _from_ direction, allowing blocks to be created from shortcodes. It's applied as part of the `raw` transformation process. @@ -389,9 +237,6 @@ A transformation of type `shortcode` is an object that takes the following param An existing shortcode can be transformed into its block counterpart. -{% codetabs %} -{% ESNext %} - ```js transforms: { from: [ @@ -425,42 +270,3 @@ transforms: { ] }, ``` - -{% ES5 %} - -```js -transforms: { - from: [ - { - type: 'shortcode', - tag: 'caption', - attributes: { - url: { - type: 'string', - source: 'attribute', - attribute: 'src', - selector: 'img', - }, - align: { - type: 'string', - // The shortcode function will extract - // the shortcode atts into a value - // to be sourced in the block's comment. - shortcode: function( attributes ) { - var align = attributes.named.align ? attributes.named.align : 'alignnone'; - return align.replace( 'align', '' ); - }, - }, - }, - // Prevent the shortcode to be converted - // into this block when it doesn't - // have the proper ID. - isMatch: function( attributes ) { - return attributes.named.id === 'my-id'; - }, - }, - ] -}, -``` - -{% end %} diff --git a/docs/reference-guides/filters/autocomplete-filters.md b/docs/reference-guides/filters/autocomplete-filters.md index e832335d365d8..1b00710b7b0ba 100644 --- a/docs/reference-guides/filters/autocomplete-filters.md +++ b/docs/reference-guides/filters/autocomplete-filters.md @@ -9,7 +9,7 @@ The `Autocomplete` component found in `@wordpress/block-editor` applies this fil Here is an example of using the `editor.Autocomplete.completers` filter to add an acronym completer. You can find full documentation for the autocompleter interface with the `Autocomplete` component in the `@wordpress/components` package. {% codetabs %} -{% ESNext %} +{% JSX %} ```jsx // Our completer @@ -46,7 +46,7 @@ wp.hooks.addFilter( ); ``` -{% ES5 %} +{% Plain %} ```js // Our completer diff --git a/docs/reference-guides/filters/block-filters.md b/docs/reference-guides/filters/block-filters.md index 9178b3277a7ec..8ce6322aa9c7e 100644 --- a/docs/reference-guides/filters/block-filters.md +++ b/docs/reference-guides/filters/block-filters.md @@ -148,7 +148,7 @@ Used to modify the block's `edit` component. It receives the original block `Blo _Example:_ {% codetabs %} -{% ESNext %} +{% JSX %} ```js const { createHigherOrderComponent } = wp.compose; @@ -176,7 +176,7 @@ wp.hooks.addFilter( ); ``` -{% ES5 %} +{% Plain %} ```js var el = wp.element.createElement; @@ -215,7 +215,7 @@ Used to modify the block's wrapper component containing the block's `edit` compo _Example:_ {% codetabs %} -{% ESNext %} +{% JSX %} ```js const { createHigherOrderComponent } = wp.compose; @@ -241,7 +241,7 @@ wp.hooks.addFilter( ); ``` -{% ES5 %} +{% Plain %} ```js var el = wp.element.createElement; @@ -273,42 +273,51 @@ Adding new properties to the block's wrapper component can be achieved by adding _Example:_ {% codetabs %} -{% ESNext %} +{% JSX %} + ```js const { createHigherOrderComponent } = wp.compose; const withMyWrapperProp = createHigherOrderComponent( ( BlockListBlock ) => { return ( props ) => { const wrapperProps = { - ...props.wrapperProps, - 'data-my-property': 'the-value', + ...props.wrapperProps, + 'data-my-property': 'the-value', }; return ; }; }, 'withMyWrapperProp' ); -wp.hooks.addFilter( 'editor.BlockListBlock', 'my-plugin/with-my-wrapper-prop', withMyWrapperProp ); +wp.hooks.addFilter( + 'editor.BlockListBlock', + 'my-plugin/with-my-wrapper-prop', + withMyWrapperProp +); ``` -{% ES5 %} + +{% Plain %} + ```js var el = wp.element.createElement; var hoc = wp.compose.createHigherOrderComponent; -var withMyWrapperProp = hoc( function( BlockListBlock ) { - return function( props ) { +var withMyWrapperProp = hoc( function ( BlockListBlock ) { + return function ( props ) { var newProps = { ...props, wrapperProps: { ...props.wrapperProps, - 'data-my-property': 'the-value' - } + 'data-my-property': 'the-value', + }, }; - return el( - BlockListBlock, - newProps - ); + return el( BlockListBlock, newProps ); }; }, 'withMyWrapperProp' ); -wp.hooks.addFilter( 'editor.BlockListBlock', 'my-plugin/with-my-wrapper-prop', withMyWrapperProp ); +wp.hooks.addFilter( + 'editor.BlockListBlock', + 'my-plugin/with-my-wrapper-prop', + withMyWrapperProp +); ``` + {% end %} ## Removing Blocks @@ -318,7 +327,7 @@ wp.hooks.addFilter( 'editor.BlockListBlock', 'my-plugin/with-my-wrapper-prop', w Adding blocks is easy enough, removing them is as easy. Plugin or theme authors have the possibility to "unregister" blocks. {% codetabs %} -{% ESNext %} +{% JSX %} ```js // my-plugin.js @@ -330,7 +339,7 @@ domReady( function () { } ); ``` -{% ES5 %} +{% Plain %} ```js // my-plugin.js diff --git a/docs/reference-guides/richtext.md b/docs/reference-guides/richtext.md index 7f5f0af6893fc..8abf81688b0b2 100644 --- a/docs/reference-guides/richtext.md +++ b/docs/reference-guides/richtext.md @@ -26,9 +26,9 @@ There are a number of core blocks using the RichText component. The JavaScript e ## Example {% codetabs %} -{% ESNext %} +{% JSX %} -```js +```jsx import { registerBlockType } from '@wordpress/blocks'; import { useBlockProps, RichText } from '@wordpress/block-editor'; @@ -66,7 +66,7 @@ registerBlockType( /* ... */, { } ); ``` -{% ES5 %} +{% Plain %} ```js wp.blocks.registerBlockType( /* ... */, { @@ -112,7 +112,7 @@ While using the RichText component a number of common issues tend to appear. ### HTML Formatting Tags Display in the Content -If the HTML tags from text formatting such as `` or `` are being escaped and displayed on the frontend of the site, this is likely due to an issue in your save function. Make sure your code looks something like `` (ESNext) within your save function instead of simply outputting the value with `

{ heading }

`. +If the HTML tags from text formatting such as `` or `` are being escaped and displayed on the frontend of the site, this is likely due to an issue in your save function. Make sure your code looks something like `` (JSX) within your save function instead of simply outputting the value with `

{ heading }

`. ### Unwanted Formatting Options Still Display