PMC Plugins: PMC Gutenberg

All additional documentation can be found in the pmc-gutenberg's /docs directory or in the PMC Docs (opens in a new tab).

What is PMC Gutenberg?

PMC Gutenberg is the name of our Core Tech and standards for the WordPress Block Editor, Gutenberg. Code for any feature in the block-editor on any PMC website is stored in pmc-plugins/pmc-gutenberg and built with our standards (todo: add link to standards).

NOTE: There should never, under any circumstance, be block-editor code added to a theme.

Even if a block or sidebar is developed for a specific theme, it should still be contributed to this plugin and enabled via configuration added to the theme (todo: when it exists, link to configuration pathways documentation).

Block-editor-related code includes the JavaScript for a feature in the editor, specific styling for the editor UI, server-side adjustments for classic editor compatibility (e.g. de-registering a metabox), and more.

Understand the Block Editor

The first recommendation is to check out the Block Editor Handbook (opens in a new tab) which breaks down the parts of the block editor and has several how-to guides (opens in a new tab) to walk through things like creating blocks (the WordPress way), extending core blocks and UI, and handling meta and frontend output.

Second, get familiarize wth the reference guides (opens in a new tab) that has resources on every part of the available Block API, custom hooks, and slotfill references as well as a few other breakdowns and explanations.

This is where we depart from the "WordPress Way" and will talk more deeply about the "PMC Way" which provides additional helpers, support, and ways of building block features that may differ from the what WordPress may expected so that we can easily built at scale for multiple brands. Those will be noted as they come up.

Everything going forward will assume you have at least a cursory understanding of Gutenberg (opens in a new tab), the Block Editor (opens in a new tab), and React (opens in a new tab).

Nomenclature

• Block Editor: refers to the editor experience built into WordPress Core (opens in a new tab).
• Gutenberg: refers to the [repository]((https://github.com/wordpress/gutenberg (opens in a new tab)) that powers the new Block Editor experience.

The "Block Editor" and "Gutenberg" may be used synonymously throughout the company, but speaking technically we should specify that there is a difference.>

JSON Schema

JSON Schema for use within custom JSON configs can be added or read from the /src/config/schema directory. Any time we add configurations via JSON we should ensure that we use a pre-made JSON schema, one that we've created in the schema directory or add a new one.

It is recommended that we use the draft-07 (opens in a new tab) version.

WordPress Schema

• theme.json (opens in a new tab)
• block.json (opens in a new tab)

PMC Schema

• theme.json (opens in a new tab) This is used for our custom theme.json implementation, but relies on the WordPress theme.json above.
• config.json (opens in a new tab)
• block.json (opens in a new tab)
• meta.json (opens in a new tab)

Information on adding a new JSON schema can be found here (opens in a new tab).

Code Standards

Make sure to check out the Code Standards while building Block Editor features.

Development Setup

• nvm use to ensure your node and npm versions are correct.
• npm install to install dependencies.
• npm run update to keep dependencies up to date.

During Development

• npm run build: formats, lints, and builds for production, note that the posttest scripts runs after tests to perform the production build.
• npm run prod: runs just the build process for production.
• npm run start: starts the dev server; page reload required (for now), no hot reload.
• npm run format runs css and js/json configs formatting scripts. Alternatively npm run format:style or npm run format:js to run them individually.
• npm run lint runs css and js/json configs linting scripts. Alternatively npm run lint:style or npm run lint:js to run them individually.
• npm run scaffold to scaffold a new block.
• npm run test to run tests. Alternatively npm run test:watch to watch tests. npm run test:update can be run to update snapshot testings for blocks. npm run test:dev will avoid the production build used by the GitHub pipeline for diff checks. Recommend using this locally.
• npm run update which updates WordPress packages.
• postinstall the postinstall script runs to install scripts at the root pmc-plugins directory to allow for these above scripts to function. Running npm i in this plugin will run this script automatically.

Block API Versions

Wordpress 6.3 introduced the new block API, version 3. To leverage the latest code, the block must be setup to use the v3 API. This has been added to the scaffolder already.

V3 is also backwards compatible to version 2 which was introduced in WordPress 5.6.

For context see the block api docs here (opens in a new tab) and here (opens in a new tab).

This effectively adds support for using useBlockProps without parent container duplication. Important for maintaining clean editor markup and semantic HTML among other things.