Building a Basic Dynamic Block

Let’s go step by step to create a simple Dynamic 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

  1. You are working in a theme repo cloned from responsive-child-starter-3x-block-editor and are using npm 20. I am using labs-theme-blocks.
  2. You are familiar with the command line and are running npm start to rebuild files on save.
  3. You’ve read and understand Block Architecture and Dynamic vs Static.
  4. Screenshots will depict VS Code.
  5. This is what the final code will look like: https://github.com/bu-ist/labs-theme-blocks/tree/sandbox/src/blocks/theme

Final Product

This is what we will build by the end of this tutorial:

▼▼▼


hello world

▲▲▲

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: tutorial-1
  • The block slug used for identification (also the output folder name): tutorial-1
  • The internal namespace for the block name (something unique for your products): labs-theme-blocks
  • The display title for your block: Tutorial 1 Block
  • The short description for your block (optional): My first block!
  • The dashicon to make it easier to identify your block (optional): block-default
  • The category name to help users browse and discover your block: widgets
  • The text domain used to make strings translatable in the block (optional): labs-theme-blocks

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

Check out Using Create-Block Template page to learn more about what is happening in this step here and an overview of all the files in this directory. Otherwise, get ready to get your feet wet!

@todo After adding the block we should give instructions how to start compiling the block and check first that it appears in the admin before starting to modify it. That way they see it working before adding attributes.

Step 2: Updating the Files

Now it’s time to start work on the block itself. In your IDE, navigate to /src/blocks/theme to begin.

Core Block Files

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 everything we need for this tutorial through the command line create-block command, but it’s worth looking at.

In this tutorial, we will be adding 2 fields to the block, so we will be want to add 2 attributes here. The key should be named something that clearly references what the field will store, and the type should define what kind of value is being stored. See lines 36-43.

For the attributes step, suggest adding a link to: https://developer.bu.edu/gutenberg/handbook/wp-core/block-architecture/attributes/10:06“All this is doing is taking the new value and saving it to the block attribute.”Let’s change this to:
“All this is doing is taking the new value and storing it to the block attribute. When the post is saved, the stored attribute will be saved to the post’s content in the database.”10:09After the reader adds the attributes, we should have a step before render.php that says something like:Compile, and check the editor. If you insert your new block you should see a Title field and Excerpt field with the placeholder values you set in the RichText Component.Set a value for each and save the post. Then reload and verify your saved values are shown in the block.

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.

edit.js

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.

This will be the biggest edit of the day. The attributes we just defined in index.js? Time to set them up in the editor.

First, we need to import the RichText component from WordPress.See line 14.

Now lets define the attributes we will be using. Go to line 36 and destructure each from the attributes object.

Now let’s add these to the Editor. Jump down to line 49. First we will add a RichText component for the Title, defining the various properties and constraints we want it to have. value will be the attribute we defined, and onChange will be how we update this value. in the next step.

Jump up to line 38. We are going to write a simple function that is called when the RichText component we just made is changed. All this is doing is taking the new value and saving it to the block attribute.

Excellent, do the same for the excerpt and we are done here. See lines 57-68 and 42-44.

make a note about <> fragment

PHP

render.php

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

Let’s setup how this block is going to appear in the front end. You can use any php and WordPress methods you want here. In this example, we simply check to see if an attribute is defined, and if it is, render it to the page. See lines 18-24.

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.

The theme starter has the option to bundle all block styles into a single css file. Out of the box, your new block style is not included in the bundle. You will need to import it in blocks-bundled.scss (located in the parent directory).

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.

block-decorative.scss

SCSS partial that contains all of the decorative (opinionated) styles for this block. These are compiled in a bundle.

Note: this file is only generated if you select the plugin template variant.

Out of the box, this file will not get enqueued. You will need to import it in blocks-decorative.scss (located in the parent directory).

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

editor.scss

Styles that are applied inside the editor only.

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

Note, this file is generated from within edit.js.

style.scss

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.

Scripts

This file is optional and will not be used in this tutorial. Feel free to play around with it though! You can put whatever you want here. In the example, I added a console.log statement just to ensure the script was loading.

script.js

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 script entry from block.json.

Bringing it all Together

Wow, we should have the workings of a basic block now! One last thing to do – build it:

  • Make sure you are in the root of your repo.
  • In the command line, run npm run build (you could also run npm start to watch changes as you work)
  • Make sure everything is pushed up to the server.
  • Go to a page and see if you block is there!

Uh oh, not working? Reach out to Tim King, he wrote this…

Next Steps

There are many examples in the r3-id-documentation repo that will show you how to add InspectorControls, split code into modules, and more!