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.<\/p>\n\n\n\n
npm start<\/code> to rebuild files on save.<\/li>- You’ve read and understand Block Architecture<\/a> and Dynamic vs Static<\/a>.<\/li>
- Screenshots will depict VS Code.<\/li>
- This is what the final code will look like: https:\/\/github.com\/bu-ist\/labs-theme-blocks\/tree\/sandbox\/src\/blocks\/theme<\/a><\/li><\/ol>\n\n\n\n
Final Product<\/h2>\n\n\n\n
This is what we will build by the end of this tutorial:<\/p>\n\n\n\n
\u25bc\u25bc\u25bc<\/p>\n\n\n
hello world
<\/p>\n
<\/p>\n
\u25b2\u25b2\u25b2<\/p>\n
<\/p>\n
<\/p>\n
Step 1: Create a New Block Using Create-Block Template<\/h2>\n
<\/p>\n
<\/p>\n
In the command terminal, from the root of your project run npm run new-id-block<\/code>.<\/p>\n<\/p>\n
<\/p>\n
This will start a series of prompts. Here’s what was used to make this block:<\/p>\n
<\/p>\n
<\/p>\n
\n- The template variant to use for this block: tutorial-1<\/strong><\/li>\n
- The block slug used for identification (also the output folder name): tutorial-1<\/strong><\/li>\n
- The internal namespace for the block name (something unique for your products): labs-theme-blocks<\/strong><\/li>\n
- The display title for your block: Tutorial 1 Block<\/strong><\/li>\n
- The short description for your block (optional): My first block!<\/strong><\/li>\n
- The dashicon to make it easier to identify your block (optional): block-default<\/strong><\/li>\n
- The category name to help users browse and discover your block: widgets<\/strong><\/li>\n
- The text domain used to make strings translatable in the block (optional): labs-theme-blocks<\/strong><\/li>\n<\/ul>\n
<\/p>\n
<\/p>\n
When this is done there will be a new block in the folder \/src\/blocks\/theme<\/code>.<\/p>\n<\/p>\n
<\/p>\n
Check out Using Create-Block Template<\/a><\/strong> 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!<\/p>\n<\/p>\n
<\/p>\n
@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.<\/p>\n
<\/p>\n
<\/p>\n
Step 2: Updating the Files<\/h2>\n
<\/p>\n
<\/p>\n
Now it’s time to start work on the block itself. In your IDE, navigate to \/src\/blocks\/theme<\/code>\u00a0to begin.<\/p>\n<\/p>\n
<\/p>\n
Core Block Files<\/h3>\n
<\/p>\n
<\/p>\n
block.json <\/code><\/h4>\n<\/p>\n
<\/p>\n
Simplifies the process of defining and registering a block by using the same block\u2019s definition in JSON format to register the block on both the server and the client.<\/p>\n
<\/p>\n
<\/p>\n
We defined everything we need for this tutorial through the command line create-block command, but it’s worth looking at.<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
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.<\/p>\n
<\/p>\n
<\/p>\n
For the attributes step, suggest adding a link to:\u00a0https:\/\/developer.bu.edu\/gutenberg\/handbook\/wp-core\/block-architecture\/attributes\/<\/a>10:06<\/a>“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:09<\/a>After 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.<\/p>\n<\/p>\n
<\/p>\n
\n- See block.json<\/a> for more information.<\/li>\n<\/ul>\n
<\/p>\n
<\/p>\n
\n<\/p>\n
<\/p>\n
index.js<\/code><\/h4>\n<\/p>\n
<\/p>\n
The entry point file for JavaScript that should only get loaded in the Block Editor. It\u2019s 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.<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
\n<\/p>\n
<\/p>\n
edit.js<\/code><\/h4>\n<\/p>\n
<\/p>\n
Contains the React component responsible for rendering the block\u2019s editing user interface, allowing users to interact with and customize the block\u2019s content and settings in the Block Editor. This component gets passed to the edit property of the registerBlockType function in the index.js<\/code> file.<\/p>\n<\/p>\n
<\/p>\n
<\/p>\n
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.<\/p>\n
<\/p>\n
<\/p>\n
First, we need to import the RichText component from WordPress.See line 14.<\/p>\n
<\/p>\n
<\/p>\n
Now lets define the attributes we will be using. Go to line 36 and destructure each from the attributes object.<\/p>\n
<\/p>\n
<\/p>\n
Now let’s add these to the Editor. Jump down to line 49. First we will add a RichText component<\/a> for the Title, defining the various properties and constraints we want it to have. value<\/code>\u00a0will be the attribute we defined, and onChange<\/code>\u00a0will be how we update this value. in the next step.<\/p>\n<\/p>\n
<\/p>\n
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.<\/p>\n
<\/p>\n
<\/p>\n
Excellent, do the same for the excerpt<\/code>\u00a0and we are done here. See lines 57-68 and 42-44.<\/p>\n<\/p>\n
<\/p>\n
make a note about <> fragment<\/p>\n
<\/p>\n
<\/p>\n
\n<\/p>\n
<\/p>\n
PHP<\/h3>\n
<\/p>\n
<\/p>\n
render.php<\/code><\/h4>\n<\/p>\n
<\/p>\n
PHP file to use when rendering the block type on the server to show on the front end.<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
Let’s setup how this block is going to appear in the front end. You can use any php<\/code>\u00a0and 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.<\/p>\n<\/p>\n
<\/p>\n
<\/p>\n
\n- See Render Template<\/a> for more information.<\/li>\n<\/ul>\n
<\/p>\n
<\/p>\n
\n<\/p>\n
<\/p>\n
Styles<\/h3>\n
<\/p>\n
<\/p>\n
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.<\/em><\/p>\n<\/p>\n
<\/p>\n
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<\/code> (located in the parent directory).<\/p>\n<\/p>\n
<\/p>\n
\n- In\u00a0
blocks-bundled.scss<\/a><\/code>\u00a0add a new line:<\/li>\n<\/ul>\n<\/p>\n
<\/p>\n
<\/p>\n
\n<\/p>\n
<\/p>\n
block-base.scss<\/code><\/h4>\n<\/p>\n
<\/p>\n
SCSS partial that contains all of the base (structural) styles for this block. These are compiled both individually and in a bundle.<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
\n<\/p>\n
<\/p>\n
block-decorative.scss<\/code><\/h4>\n<\/p>\n
<\/p>\n
SCSS partial that contains all of the decorative (opinionated) styles for this block. These are compiled in a bundle.<\/p>\n
<\/p>\n
<\/p>\n
Note: this file is only generated if you select the plugin<\/em> template variant.<\/strong><\/p>\n<\/p>\n
<\/p>\n
<\/p>\n
Out of the box, this file will not get enqueued. You will need to import it in blocks-decorative.scss<\/code> (located in the parent directory).<\/p>\n<\/p>\n
<\/p>\n
\n- In
blocks-decorative.scss<\/a><\/code>\u00a0add a new line:<\/li>\n<\/ul>\n<\/p>\n
<\/p>\n
<\/p>\n
This ensures the styles for your new block will be bundled with the other block styles when the theme serves the bundled style file.<\/p>\n
<\/p>\n
<\/p>\n
\n<\/p>\n
<\/p>\n
editor.scss<\/code><\/h4>\n<\/p>\n
<\/p>\n
Styles that are applied inside the editor only.<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
If you are not using this, remove the editorStyle<\/code> entry from block.json<\/code>.<\/p>\n<\/p>\n
<\/p>\n
<\/p>\n
\n- See Editor Styling<\/a> for more information.<\/li>\n<\/ul>\n
<\/p>\n
<\/p>\n
Note, this file is generated from within edit.js<\/code><\/em>.<\/p>\n<\/p>\n
<\/p>\n
<\/p>\n
\n<\/p>\n
<\/p>\n
style.scss<\/code><\/h4>\n<\/p>\n
<\/p>\n
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<\/code> in order to stay DRY.<\/p>\n<\/p>\n
<\/p>\n
<\/p>\n
If you are not using this, remove the style<\/code> entry from block.json<\/code>.<\/p>\n<\/p>\n
<\/p>\n
<\/p>\n
\n- See Frontend Styling<\/a><\/li>\n<\/ul>\n
<\/p>\n
<\/p>\n
\n<\/p>\n
<\/p>\n
Scripts<\/h3>\n
<\/p>\n
<\/p>\n
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.<\/em><\/p>\n<\/p>\n
<\/p>\n
script.js<\/code><\/h3>\n<\/p>\n
<\/p>\n
Use this file for JavaScript code that you want to run in the front-end on posts\/pages that contain this block.<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
If you are not using this, remove the script<\/code> entry from block.json<\/code>.<\/p>\n<\/p>\n
<\/p>\n
<\/p>\n