{"id":28361,"date":"2019-10-31T19:40:25","date_gmt":"2019-10-31T19:40:25","guid":{"rendered":"https:\/\/futurelab.digitalmachine.co.nz\/blog\/how-to-create-your-first-gutenberg-block\/"},"modified":"2019-10-31T19:40:25","modified_gmt":"2019-10-31T19:40:25","slug":"how-to-create-your-first-gutenberg-block","status":"publish","type":"post","link":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/","title":{"rendered":"How to create your first Gutenberg block"},"content":{"rendered":"\n

This post is dedicated to a wonderful WordPress Bogota community<\/a> that invited me to speak on their meetup. I’ll summarise here what we’ve learned on that meetup.<\/p>\n\n\n\n

At this point, I assume that you know what Gutenberg is<\/a>, you know the basics of WordPress programming and a very basic understanding of React.<\/p>\n\n\n\n

You need to start with a clean and fresh WordPress\ninstallation. <\/p>\n\n\n\n

Prerequisites <\/h2>\n\n\n\n

In order to start developing React application, you will need to have Node JS installed on your computer and Composer. There are quite a few tutorials online on how to do it so I will not explain it in details. Once you have Node JS and composer, we will use a Gutenberg boilerplate in order to speed up the setup. It\u2019s a set of files and setup that everyone has to do at the beginning of the development. Of course there are different approaches to developing React application, however, this is a basic tutorial and the point of it is to understand Gutenberg structure and basic elements.<\/p>\n\n\n\n

I will be using Windows commands as an example with Git bash command line, however, on Mac and Linux the commands are identical and on Windows, you can use and shell simulating program.<\/p>\n\n\n\n

The boilerplate is called Create Guten Block<\/a> and is made by Ahmad Awais<\/a>. In order to install it go to your WordPress plugins folder and execute the following command:<\/p>\n\n\n\n

npx create-guten-block my-block<\/code><\/pre>\n\n\n\n
The third part of the command will be the name of your plugin and is editable \u2013 you can name it any way you can. The documentation has examples on how to create multiple blocks in one plugin in order to avoid a growing list of WordPress plugins.<\/p>\n\n\n\n
Once the command is executed you should see the following screen.<\/p>\n\n\n\n
\"Result<\/figure>\n\n\n\n
The next step is to compile the React application. Go to your plugin folder (which should be “my-block” and execute the command<\/p>\n\n\n\n
Npm start<\/code><\/pre>\n\n\n\n
Because we created a WordPress plugin with the first command\nline we need to go to plugins and activate the plugin. Once activated, the\nplugin should give you a basic block out of the box. To check it, create a new\npage and press the plus sign and add your block to the content.<\/p>\n\n\n\n
\"Adding
Adding the block to the content<\/figcaption><\/figure>\n\n\n\n
\"Our
This is how our first block looks like<\/figcaption><\/figure>\n\n\n\n
The structure<\/h2>\n\n\n\n
Let\u2019s take a look at our plugin\u2019s file structure. The most\nimportant files are highlighted here:<\/p>\n\n\n\n
\"WordPress
List of files in our new plugin<\/figcaption><\/figure>\n\n\n\n
To understand better how Gutenberg we have to step back a little bit and understand how any plugin works. Any WordPress plugin has a frontend and a backend. Both frontend and backend are PHP files and generate HTML based on some logic. The difference is that one generates the HTML for the admin area, the other one for the frontend website.<\/p>\n\n\n\n
React plugin is very similar, however, it has to be compatible with WordPress itself. That is why on the above image you will see \u201cinit.php\u201d that main functionality is to load React JavaScript files to WordPress and tell WordPress that there is a new block. Have a look at init.php file as it\u2019s very well documented. It will give you a good overview of what it does.<\/p>\n\n\n\n
We then have block.js file that we\u2019ll describe below and 2 Sass files. The boilerplate is configured well enough that the files are compiled automatically while the \u201cnpm start\u201d command is running in the background. The reason why we have 2 different files is the same reason why we have frontend and backend. Simply \u201ceditor.scss\u201d is responsible for styling the block in the admin area and \u201cstyle.css\u201d is responsible for styling the block on the frontend of the website. We also have a common.scss file that contains common values for both frontend and backend.<\/p>\n\n\n\n
Gutenberg structure<\/h2>\n\n\n\n
Gutenberg itself is structured in \u201cfrontend\u201d and \u201cbackend\u201d way as well. Open block.js file and have a look at the structure. The comments of the default boilerplate file are pretty good but let\u2019s focus on 3 important elements that we need to understand before any further development.<\/p>\n\n\n\n
RegisterBlockType function<\/h3>\n\n\n\n
You\u2019ll find it pretty odd that you have to call the function that is already called in PHP. However, WordPress core is still written mainly in PHP whereas Gutenberg is written in React which compiles to JavaScript. When PHP tells WordPress that the block has been registered, JavaScript (React) has to tell Gutenberg core that there is a new block as well. <\/p>\n\n\n\n
This is the part where we define the block, we can see some\nbasic descriptions of the block like the title, icon, category and keywords\n(for search). Feel free to play around with those values and see what the\neffect is on your block.<\/p>\n\n\n\n
Edit function<\/h3>\n\n\n\n
As I mentioned \u2013 the comment of the function is pretty descriptive but also pretty technical. In a nutshell, the edit function is in a way description of how we are going to process the block in the backend (WordPress admin). This is the place where we\u2019re going to add any settings, any variables and any processing.<\/p>\n\n\n\n
Save function<\/h3>\n\n\n\n
On the other side, we have a save function which in a very simplified way we can call \u201cfrontend\u201d function or how the block is displayed on the website. Here\u2019s where it gets tricky. Without digging much into React, if you ever used a bit more advanced JavaScript (even jQuery) you know that the main structure is based on DOM elements. Similarly here React reads DOM elements and analyses them the way we tell it to. So when Save function grabs the result of our work and inserts it into the database (physically it ends up just in wp_post<\/em> table the same way as any other WordPress page content), we need to make sure that \u201cedit\u201d function logic is matching \u201csave\u201d logic. Put it this way, we tell block in \u201csave\u201d function that we store our image in a div and that is how it\u2019s going to get saved in the database as <div><img><\/div>\u2026. , however, if in edit function we\u2019ll tell block that we expect an image to be in a paragraph, Gutenberg will try to find <p> before looking for an image and because it will be unable to do so, it will return an error.<\/p>\n\n\n\n
Debugging<\/h2>\n\n\n\n
Once you get a basic understanding of the structure, you can easily build your own block, based on simple HTML. You don\u2019t need to know React or advanced JavaScript. All you need is an HTML structure in edit and save function. <\/p>\n\n\n\n
However, as you\u2019ll see in lesson 2, once the things get a\nbit more complicated, you might need to debug some elements. <\/p>\n\n\n\n
We will not dig into complex React debugging, however, here\nare 3 most important things to know on how to see what\u2019s wrong with your\nGutenberg block.<\/p>\n\n\n
\n
  1. In order to speed up Gutenberg core \u2013 it\u2019s compiled and stripped of some functionality in WordPress core. That is why for any development you will need to install the Gutenberg plugin that will allow you to see your errors with details.<\/li>
  2. When you make an error in React, HTML or SCSS structure, you will see it in your system console where you run npm start<\/em> command. <\/li>
  3. Finally, a standard browser console is your go-to to check the errors on your website. On Chrome Windows press F12 and click on \u201cconsole\u201d tab to see the errors of the current page, on Mac Chrome you’ll need to right-click on the website and click “inspect” to open the console<\/li><\/ol>\n<\/div>\n\n\n
    Summary<\/h2>\n\n\n\n
    Create Guten Block boilerplate is a great starting point for developing your first Gutenberg block. Out of the box, it is very well configured and explained in comments. I encourage you to play around with default edit<\/em> and save<\/em> functions and HTML inside to see how easy it is to create a simple block.<\/p>\n\n\n\n
    In the next lesson we\u2019ll make our block editable and add a setting to it.<\/p>\n","protected":false},"excerpt":{"rendered":"
    This post is dedicated to a wonderful WordPress Bogota community that invited me to speak on their meetup. I’ll summarise here what we’ve learned on that meetup. At this point, I assume that you know what Gutenberg is, you know the basics of WordPress programming and a very basic understanding of React. You need to  Read More<\/a><\/p>\n","protected":false},"author":1,"featured_media":28363,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"content-type":""},"categories":[268,269,270,229],"tags":[271],"yoast_head":"\nHow to create a simple Gutenberg Block - Lesson 1<\/title>\n<meta name=\"description\" content=\"The new WordPress editor introduced blocks. For developers it's a completely new experience. In this tutorial I'm explaining how to create a simple block.\" \/>\n<meta name=\"robots\" content=\"noindex, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"How to create a simple Gutenberg Block - Lesson 1\" \/>\n<meta property=\"og:description\" content=\"The new WordPress editor introduced blocks. For developers it's a completely new experience. In this tutorial I'm explaining how to create a simple block.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/\" \/>\n<meta property=\"og:site_name\" content=\"futurelab\" \/>\n<meta property=\"article:published_time\" content=\"2019-10-31T19:40:25+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/futurelab.digitalmachine.co.nz\/wp-content\/uploads\/2021\/02\/wordpress_block_view.png\" \/>\n\t<meta property=\"og:image:width\" content=\"1025\" \/>\n\t<meta property=\"og:image:height\" content=\"566\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"author\" content=\"futurelab\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"futurelab\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"7 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/\",\"url\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/\",\"name\":\"How to create a simple Gutenberg Block - Lesson 1\",\"isPartOf\":{\"@id\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#website\"},\"datePublished\":\"2019-10-31T19:40:25+00:00\",\"dateModified\":\"2019-10-31T19:40:25+00:00\",\"author\":{\"@id\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#\/schema\/person\/ff10b1cf7176aa8cd97fb1681fddc3ae\"},\"description\":\"The new WordPress editor introduced blocks. For developers it's a completely new experience. In this tutorial I'm explaining how to create a simple block.\",\"breadcrumb\":{\"@id\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/#breadcrumb\"},\"inLanguage\":\"en-NZ\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"How to create your first Gutenberg block\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#website\",\"url\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/\",\"name\":\"futurelab\",\"description\":\"Digital Technology for businnesses\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-NZ\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#\/schema\/person\/ff10b1cf7176aa8cd97fb1681fddc3ae\",\"name\":\"futurelab\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-NZ\",\"@id\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/2b905414f26ba3faaacf7d9d1a2ccc9f?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/2b905414f26ba3faaacf7d9d1a2ccc9f?s=96&d=mm&r=g\",\"caption\":\"futurelab\"},\"description\":\"Biographical Info from user settings\",\"sameAs\":[\"https:\/\/futurelab.digitalmachine.co.nz\"],\"url\":\"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/author\/futurelab\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"How to create a simple Gutenberg Block - Lesson 1","description":"The new WordPress editor introduced blocks. For developers it's a completely new experience. In this tutorial I'm explaining how to create a simple block.","robots":{"index":"noindex","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"og_locale":"en_US","og_type":"article","og_title":"How to create a simple Gutenberg Block - Lesson 1","og_description":"The new WordPress editor introduced blocks. For developers it's a completely new experience. In this tutorial I'm explaining how to create a simple block.","og_url":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/","og_site_name":"futurelab","article_published_time":"2019-10-31T19:40:25+00:00","og_image":[{"width":1025,"height":566,"url":"https:\/\/futurelab.digitalmachine.co.nz\/wp-content\/uploads\/2021\/02\/wordpress_block_view.png","type":"image\/png"}],"author":"futurelab","twitter_card":"summary_large_image","twitter_misc":{"Written by":"futurelab","Est. reading time":"7 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/","url":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/","name":"How to create a simple Gutenberg Block - Lesson 1","isPartOf":{"@id":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#website"},"datePublished":"2019-10-31T19:40:25+00:00","dateModified":"2019-10-31T19:40:25+00:00","author":{"@id":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#\/schema\/person\/ff10b1cf7176aa8cd97fb1681fddc3ae"},"description":"The new WordPress editor introduced blocks. For developers it's a completely new experience. In this tutorial I'm explaining how to create a simple block.","breadcrumb":{"@id":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/#breadcrumb"},"inLanguage":"en-NZ","potentialAction":[{"@type":"ReadAction","target":["https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/how-to-create-your-first-gutenberg-block\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/"},{"@type":"ListItem","position":2,"name":"How to create your first Gutenberg block"}]},{"@type":"WebSite","@id":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#website","url":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/","name":"futurelab","description":"Digital Technology for businnesses","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-NZ"},{"@type":"Person","@id":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#\/schema\/person\/ff10b1cf7176aa8cd97fb1681fddc3ae","name":"futurelab","image":{"@type":"ImageObject","inLanguage":"en-NZ","@id":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/2b905414f26ba3faaacf7d9d1a2ccc9f?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/2b905414f26ba3faaacf7d9d1a2ccc9f?s=96&d=mm&r=g","caption":"futurelab"},"description":"Biographical Info from user settings","sameAs":["https:\/\/futurelab.digitalmachine.co.nz"],"url":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/blog\/author\/futurelab\/"}]}},"_links":{"self":[{"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/posts\/28361"}],"collection":[{"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/comments?post=28361"}],"version-history":[{"count":0,"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/posts\/28361\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/media\/28363"}],"wp:attachment":[{"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/media?parent=28361"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/categories?post=28361"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/futurelab.digitalmachine.co.nz\/nz\/wp-json\/wp\/v2\/tags?post=28361"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}