Adding Inspector Controls

Let’s go step by step through the Caterpillar Block. You might not need every technique used in this example, but it covers a lot of common features you may need in developing your own blocks.

Setup/Assumptions

You are working in a repo cloned from responsive-child-starter-3x-block-editor and are using npm 20
You are familiar with the command line
You’ve read and understand Block Architecture and Dynamic vs Static
Screenshots will depict VS Code
This is what the final code will look like: https://github.com/bu-ist/block-sandbox/tree/sandbox/src/blocks/caterpillar

Step 1: Create a New Block Using Create-Block Template

In the command terminal, from the root of your project run npm run new-id-block.

This will start a series of prompts. Here’s what was used to make this block:

The template variant to use for this block: theme
The block slug used for identification (also the output folder name): demo
The internal namespace for the block name (something unique for your products): block-sandbox
The display title for your block: demo
The short description for your block (optional): demo
The dashicon to make it easier to identify your block (optional): ellipsis
The category name to help users browse and discover your block: text
The text domain used to make strings translatable in the block (optional): block-sandbox

When this is done there will be a new block in the folder /src/blocks/caterpillar.

You can learn more about what is happening in this step here.

Step 2: Update Bundled Styles

In your IDE, navigate to /src/blocks
Open blocks-bundled.scss
Scroll down to the section // Import Block Styles
Add a new line: @import 'caterpillar/block-base';

This ensures the styles for your new block will be bundled with the other block styles when the theme serves the bundled style file.

Now it’s time to start work on the block itself.

Step 3: Updating the Files

Check out Block Architecture page for an overview of all the files in this directory. Otherwise, get ready to get your feet wet!

`block.json`

Simplifies the process of defining and registering a block by using the same block’s definition in JSON format to register the block on both the server and the client.

We defined most things here through the command line create-block command, but there are a few things we need to add.

example

Below the description key, let’s add example data for the block. This data is used to construct a preview for the block to be shown in the Inspector Help Panel when the user mouses over the block.

"example": {
        "attributes": {
            "message": "hungry hungry"
        }
    }

supports

Block Supports is the API that allows a block to declare support for certain features.

link to docs…

Right below the example we just added, let’s add support for HTML:

"supports": {
		"html": true
	},

attributes

Block attributes provide information about the data stored by a block. For example, rich content, a list of image URLs, a background color, or a button title.

link to docs…

"attributes": {
		"textField": {
			"type": "string"
		}
	},

viewScript

We want to run some JS in the frontend, so we will need to add that here

"viewScript": "file:./view.js"

See block.json

Styles

These files are all optional and will not be used in this tutorial. Feel free to play around with them though!

You can put whatever you want here. I’ve added a few just to visually confirm that the file is loading as intended.

`block-base.scss`

SCSS partial that contains all of the base (structural) styles for this block. These are compiled both individually and in a bundle.

@todo more about this…

https://github.com/bu-ist/block-sandbox/blob/sandbox/src/blocks/caterpillar/block-base.scss

`editor.scss` (block.json: editorStyle)

Styles that are applied inside the editor only.

If you are not using this, remove the editorStyle entry from block.json.

https://github.com/bu-ist/block-sandbox/blob/sandbox/src/blocks/caterpillar/editor.scss

See Editor Styling

`modules/inspector-editor.scss`

Basically the same as the editor.scss above, but specific to the editor-partials code.

It is included @todo

`style.scss` (block.json: style)

Styles that are applied both on the front of your site and in the editor. Our block template @imports some common tools and the block-base.scss in order to stay DRY.

If you are not using this, remove the style entry from block.json.

See Frontend Styling

Scripts

`edit.js` (block.json: editorScript)

Contains the React component responsible for rendering the block’s editing user interface, allowing users to interact with and customize the block’s content and settings in the Block Editor. This component gets passed to the edit property of the registerBlockType function in the index.js file.

If you are not using this, remove the ??? entry from block.json.

See @todo

`index.js`

The entry point file for JavaScript that should only get loaded in the Block Editor. It’s responsible for calling the registerBlockType function to register the block on the client and typically imports the edit.js and save.js files to get the functions required for block registration.

`modules/inspector.js`

`view.js` (block.json: viewScript)

Use this file for JavaScript code that you want to run in the front-end on posts/pages that contain this block.

If you are not using this, remove the viewScript entry from block.json.

See Frontend JS

PHP

`render.php` (block.json: render)

PHP file to use when rendering the block type on the server to show on the front end. See Render Template

update each file…
1. modify components
2. Importing Components
3. useBlockProps
4. Inner Blocks
linting
1. Testing the Block
building
Deprecating a Block

if we make the repo public we can embed gists using https://emgithub.com/

todo: find a good tutorial style and mimic it… maybe https://web.dev/articles/building/a-dialog-component or https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog

include: wp support; php/css support; accessibility; known issues; author (so they can be contacted with questions or bugs)

Adding Inspector Controls

Setup/Assumptions

Step 1: Create a New Block Using Create-Block Template

Step 2: Update Bundled Styles

Step 3: Updating the Files

block.json

example

supports

attributes

viewScript

Styles

block-base.scss

editor.scss (block.json: editorStyle)

modules/inspector-editor.scss

style.scss (block.json: style)

Scripts

edit.js (block.json: editorScript)

index.js

modules/inspector.js

view.js (block.json: viewScript)

PHP

render.php (block.json: render)