This repository contains a series of examples to demonstrate various aspects of coding Gutenberg blocks.
There is an alphabetical list of the examples below, as well as a suggested order.
The example files, which are written in JSX, are in the src/ folder. When using the examples, they are transpiled into a WordPress plugin, located in the start/.
Running these examples on your computer requires a development environment, so that, a WordPress test site can be hosted locally.
Using these examples requires WordPress' development environment:
-
Node.js--needed for everything else to run.
-
@wordpress/env--needed to get a locally hosted test site running on you computer.- Requires Docker (installed separately)
-
@wordpress/scripts--needed to build (transpile) the examples into a WordPress plugin.- Requires Webpack (installed automatically when
@wordpress/scriptsis installed)
- Requires Webpack (installed automatically when
WordPress' development environment quick start guide can be found in the Gutenberg Handbook.
When wp-scripts is started, the examples are built into a WP plugin, located in the /start folder.
Using this environment, when files within the src folder are changed and saved, the plugin within the start folder will automatically be updated.
Other methods of running a WP test site can be use. However, the you must be able to copy the start folder to the wp-content/plugins/ folder of a WP installation. Using code editors, such as VS Code, it is also possible to connect the start folder to a remotely hosted WP site via an FPT/SFTP plugin.
Once the development environment is up and running, the examples can be installed .
Clone this repository into the folder you wish to work from on your computer@#[]. For example, gutenberg-block-examples.
In the terminal, from the examples' root folder, enter:
~/gutenberg-block-examples$ npm install
This will create a node_modules folder, and install all the npm dependencies listed in the package.json file.
With a WP site running (terminal: wp-env start):
-
Open
src/build-list.json. -
On the examples you want to test, set
includetotrue. -
In the terminal, enter:
~/gutenberg-block-examples/$ npm run start
wp-scripts will now create the start/ folder, and the plugin files will be placed into it. The chosen examples should now be available in the test site.
The folder structure after build process has started.
The plugin is in the start folder.
Each time you wish to change which examples are included in the plugin, you must stop wp-scripts (ctrl + c in the terminal where wp-scripts is running), edit src/build-list.json, and restart wp-scripts.
When working on multiple examples at once, it is confusing to have several files open in the code editor, all called index.js etc. To avoid this, in the src folder, most files are prefaced with the name of the example. When the examples are built to the start folder, all of the JS files are transpiled to start/example-name/index.js; the other files in the example are copied to start/example-name/, and in some cases renamed as well.
Example files
-
All JS files transpiled from
src/example-name/*.js, tostart/example-name/index.js -
src/example-name/example-name.phpcopied & renamed tostart/example-name/index.php -
src/example-name/example-name.block.jsoncopied & renamed tostart/example-name/block.json -
src/example-name/example-name.style.csscopied & renamed tostart/example-name/style.css -
src/example-name/example-name.style.scsstranspiled tostart/example-name/style.css -
src/example-name/extra-block.block.jsoncopied tosrc/example-name/extra-block.block.json†
† Some examples build more than one block. In which case, the primary block's JSON file becomes block.json, and the secondary block's JSON filename remains unchanged. Try the block-json example to see this in action.
Plugin files
-
scr/plugin.phpcopied tostart/plugin,php -
src/build-list.jsoncopied tosrc/build-list.json††
††Note, build-list.json is needed for the serverside code, as well as the Webpack build process.
The build process also adds the following files to root folder of each example:
-
index.assets.php--contains the WP@wordpressdependencies for the example. The dependencies are generated from theimportstatements of@wordpresspackages in the example's JS source files. ††† -
style.css.map--allows Devtools to quote filenames and line numbers in the source style code (css, orscss), rather than the transpiled code. -
index.js.map--allows Devtools to quote filenames and line numbers in the source JS code, rather than the transpiled code.
††† Note, normally Webpack will include the code for the dependencies into the transpiled file. However, Webpack can be instructed that certain packages will be available in the JS environment (in this case the Gutenberg editor, in a WordPress website), and don't need to be included. These packages are called "externals". @wordpress/scripts includes all @wordpress packages, and several other 3rd party packages as externals. See the documentation on GitHub for more details.
The start folder, after two examples have been built to it.
Links to files
The PHP file uses the transpiled names, whereas, the src JS files uses the file names as they are before transpiling. This is because the PHP files are only used once the plugin is built, while the src JS files are transpiled to index.js by Webpack during the build process.
richtext-transforms-multiblock