Block Scaffolding for WordPress

Notes from Ian Register

Assumptions

Need to ensure strings are translateable but not provide actual pot file / translation directories etc.

Not including title block in count.

Why did I restructure to include multiple blocks / mutiple files per block

Introduce least amount of boilerplate and not have to set up tests on every block for registerBlockType. Each block exports a name string and settings configuration object exactly as consumed by registerBlockType.

Multiple files per block easier to find, understand etc - but mainly as named exports show up better in devtools rather than showing as anonymous

Why did I restructure the plugin

Mostly to understand fully how it works.

Moved images and php directories into resources as those images would relate to the plugin whereas any images for the blocks would be in either the blocks directory or the individual block directories

The scripts I would consider renaming config so there's no confusion with thinking that it contains JS logic for the block or plugins (of course it contains JS in the webpack but that's not the point!)

Also means that I get all the linters and coding standards properly working - this was something I've come across before - global vs local vs VM

Why did I add HMR

When properly configured HMR allows developers to make changes to a component file, save, and see that component update instantly on our webpage without disrupting any other application state, dramatically speeding up prototyping work and code iteration.

From here abbreviated note form, to be edited.

Testing

Programmatic with jest/enzyme/phpunit but also user interactions add/remove blocks Test for have 0 blocks and then multiples Compatibility with older gutenberg or use of deprecations Transforms (currently resets ordernumber to false transforming -> paragraph) Test what happens with innerblocks Installed WordPress coding standards locally not before realising they're autoloaded BUT wpcs path is not getting picked up so leaving as is - will solve another day Updated path for phpcs to vendor/bin/ or set bin-dir to ./ to put binaries in project root.

Bugs

Running composer lint works but npm run lint:php does not work Perhaps need to use npx to run npm-run-all

Notes

Explain - I would update to use wp-scripts - Want add typescript - Use an asset file name thing - During an actual project or tasking would stick to the brief and time / effort estimate - Hmr because I’m a ui developer - Allowing multiple blocks as that’s generally how i’ve needed to set up for a UI build - working through the GB examples from core, and paragraph from Block library to learn from first principles - have refactored js directory to blocks directory as it contains styles and js - I would probably spend some time deciding whether to call the output directory dist or build, leaning towards dist as it would be built, commited and distributed vs if it is built via a CI process - would add a config.json (uncomitted) and a config.json.example comitted with settings picked up by webpack for hostnames/directory paths etc - test what sort of cache busting needed (note as components are cached in memory and re-register if they’re updated), and needs a means to loading on front end. - would create/update an .env variable or file so that php could pick up whether development mode was in just static/built local or running hmr - rename scripts to config so it doesn’t get confused with js - tried named and default exports for the save/edit - check function names show up in dev tools (ie from module exports ) - not testedd agaaint teh deprecated functions of p block- added exit if accessed directly but generally have that disabled in nginx at server level- would look at the enqued vs register front / editor assets - experimenting with the styles hence the different css selectors targeting styles, really need more of a UI - errors if not running webpack in dev mode ie localhost webpack dev server in memory serving blocks/dist/* need to run webpack build to see front end updates and there may be invalidation of the block due to this, perhaps can fix with better management of when localhost vs actual hostname is used - icon is a bit large, would also like to test svgr to see if it converts svg to js component appropriately - use function names with upper or lower case ParagraphExtendAttributes etc - haven't done - do I need wp-data, wp-hooks in enqueue script? - where would an admin page to plugin go - i prefer putting stylelint, eslint settings in package.json to have less files in directory but am quite ambivalent because it's also nice have settings file if needing to modify tho i'd prefer all in json - would hope that PHP>7 not 56 could be supported min - not happy with the asset_url modification but it's a quick hack to get it working - test for only updating when clicking out perhaps need a react component lifecycle method for updating count - note stylelint v9 installed but all other stylelint packages wanting >v11 - torn between separate config files like stylelintrc.js or in package.

Was trying to debug an error but it's present with all plugins disabled perhaps test if it's there when React not in development mode

Main issue is to integrate my webpack config with wp-scripts

prettier is set up to run linting across js/css and to run phpcbf - was initially some conflict and I have it setup globally for phpcsfixer not phpcbf but have that set now am pretty much fully migrated to VSCode from Atom though I like to keep an eye on how the alternatives run (except vim) Web/PhpStorm and Atom and curious about the new commerical offering from Panic called Took me a while to realise that Prettier for PHP is using PHP CS Fixer which is only PSR which suited the project which is in PSR4, then finding a VSCode extension for phpcbf that produced the same result as running ./vendor/bin/phpcbf Added prettier integration to VScode but don't think it's configured properly for npm run lint:js so need to add this package https://github.com/prettier/prettier-eslint or otherwise integrate eslint with prettier (or vice versa)

Requirements

• WordPress 5.0+ or the Gutenberg Plugin.
• PHP 7.2 or later, Composer and Node.js for dependency management.
• Docker or Vagrant with VirtualBox for a local development environment.

We suggest using a software package manager for installing the development dependencies such as Homebrew on MacOS:

brew install php composer node docker docker-compose

or Chocolatey for Windows:

choco install php composer node nodejs docker-compose

Development

1. Clone the plugin repository.

2. Setup the development environment and tools using Node.js and Composer:

   npm install

   Note that both Node.js and PHP 7.2 or later are required on your computer for running the npm scripts. Use npm run docker -- npm install to run the installer inside a Docker container if you don't have the required version of PHP installed locally.

Development Environment

This repository includes a WordPress development environment based on Docker that can be run on your computer or inside a Vagrant and VirtualBox wrapper for network isolation and simple .local domain names.

Using Vagrant

To use the Vagrant based environment, run:

vagrant up

which will make it available at block-scaffolding-wp.local.

Use the included wrapper command for running scripts inside the Docker container running inside Vagrant:

npm run vagrant -- npm run test:php

where npm run test:php is any of the scripts you would like to run.

Visit block-scaffolding-wp.local:8025 to check all emails sent by WordPress.

Using Native Docker

To use the Docker based environment with the Docker engine running on your host, run:

docker-compose up -d

which will make it available at localhost. Ensure that no other Docker containers or services are using port 80 on your machine.

Use the included wrapper command for running scripts inside the Docker container:

npm run docker -- npm run test:php

where npm run test:php is any of the scripts you would like to run.

Visit localhost:8025 to check all emails sent by WordPress.

Scripts

We use npm as the canonical task runner for the project. Some of the PHP related scripts are defined in composer.json.

All of these commands can be run inside the Docker or Vagrant environments by prefixing the scripts with npm run docker -- for Docker or with npm run vagrant -- for Vagrant.

• npm run build to build the plugin JS and CSS assets. Use npm run dev to watch and re-build as you work.

• npm run lint:js to lint JavaScript files with eslint.

• npm run lint:php to lint PHP files with phpcs.

• npm run test:php to run PHPUnit tests without generating a coverage report.

• npm run test:php:coverage to run PHPUnit tests and generate a coverage report in both XML Clover and HTML format.