06 Conventions for examples

Specific conventions have been established for the examples in this repository to ensure the repository as a whole is scalable and maintainable. This guide details those conventions, and you can check out this diagram for a visual representation.

Each example is unique

The most important thing about each example is that they are unique. As more and more examples are added over time, some may have similar names. Therefore, uniqueness is enforced using a hexcode that acts as the example's ID, which will be referred to as <unique-code> in this guide.

Furthermore, when you see <slug> mentioned in this guide, it refers to <plugin-slug>-<unique-code>. For example, a plugin that might normally have the slug my-example-plugin would become something like my-example-plugin-64756b.

Example conventions

General setup

• All examples are plugins and they are placed in this repository's plugins folder.
• Each plugin example must have its own <unique-code>. You can generate this code by running npm run get:hexcode from the root of the project.
• The plugin folder name (<plugin-folder>) should be the <slug>. For example, my-example-plugin-64756b.

package.json

Start by ensuring the example's package.json file adheres to the following conventions.

• name: should follow the convention @wp-block-development-examples/<slug>. For example, "name": "@wp-block-development-examples/my-example-plugin-64756b".
• files: This property should be set to *. For example, "files": [ "*" ].
• scripts: It should have, at least, the following scripts defined:

        "scripts": {
            "build": "wp-scripts build",
            "plugin-zip": "wp-scripts plugin-zip",
            "start": "wp-scripts start"
        }

• devDependencies: It should have, at least, @wordpress/scripts as a dependency for development:

        "devDependencies": {
            "@wordpress/scripts": "^27.8.0"
        }

index.php (or main plugin file)

If you use the automated methods of scaffolding an example, the main plugin file will be index.php. However, you can modify this file name as needed.

In the plugin header comment, the Plugin Name: value should follow the convention: Block Development Examples - <example-name> <unique-code>. For example, Plugin Name: Block Development Examples - My Example Plugin 64756b.

block.json

• name: This property should follow the convention block-development-examples/<slug>. Make sure the block registered at index.js uses the same name. For example:
  • block.json: "name": "block-development-examples/my-example-plugin-64756b"
  • index.js: registerBlockType( 'block-development-examples/my-example-plugin-64756b',...
• textdomain: If an example includes the textdomain property, it should be set to block-development-examples.
• keywords: This property should at least include the <unique-code>, which allows users to easily search for blocks in the Inserter by the unique ID. For example, "keywords": [ "64756b"].

Block styles (CSS)

Block CSS classes should follow the convention .wp-block-block-development-examples-<slug>. For example, .wp-block-block-development-examples-my-example-plugin-64756b

Repository-specific conventions

After a new example has been added to the plugins folder, you need to ensure it works and displays properly in this repository.

• .wp-env.json: The local path of each example plugin (starting from root) should be included in the array "plugins" in the .wp-env.json file. For example, "./plugins/my-example-plugin-64756b".
• _data/example.json: Each example needs to be added to the example.json file in the _data folder. Examples are represented as objects with the following properties: slug, description, tags. The tags property should contain an array of tags from the available list in _data/tags.json. Here's an example:

{
    "slug": "my-example-plugin-64756b",
    "description": "My Example Block",
    "tags": [
      "minimal",
      "no-build"
    ]
  }

• README.md: After a new example is added, you need to add a new row with the plugin/example information. You can do so by running npm run table:update.

After ensuring all of these conventions have been applied, reinstall dependencies and generate a fresh build from the root of the project.

pnpm i
npm run build