{"id":3062,"date":"2019-10-28T07:15:21","date_gmt":"2019-10-28T11:15:21","guid":{"rendered":"https:\/\/cindypotvin.com\/?p=3062"},"modified":"2019-10-26T19:28:59","modified_gmt":"2019-10-26T23:28:59","slug":"create-a-minimal-custom-gutenberg-block-in-wordpress","status":"publish","type":"post","link":"https:\/\/cindypotvin.com\/create-a-minimal-custom-gutenberg-block-in-wordpress\/","title":{"rendered":"Create a Minimal Custom Gutenberg Block in WordPress"},"content":{"rendered":"\n<p>I&#8217;ve started playing with the new Gutenberg editor in WordPress, and the experience is a lot more modern than the old TinyMCE editor that&#8217;s been around for a good 15 years (and I&#8217;ve had blogs for almost that long!). <\/p>\n\n\n\n<div class=\"wp-block-image\"><figure class=\"alignright is-resized\"><img loading=\"lazy\" decoding=\"async\" src=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/GutenbergBlockCover-1-1024x1024.png\" alt=\"\" class=\"wp-image-3097\" width=\"276\" height=\"276\" srcset=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/GutenbergBlockCover-1-1024x1024.png 1024w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/GutenbergBlockCover-1-150x150.png 150w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/GutenbergBlockCover-1-300x300.png 300w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/GutenbergBlockCover-1-768x768.png 768w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/GutenbergBlockCover-1-700x700.png 700w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/GutenbergBlockCover-1.png 1200w\" sizes=\"(max-width: 276px) 100vw, 276px\" \/><\/figure><\/div>\n\n\n\n<p>Instead of editing all the content of the post at once, the Gutenberg editor works with blocks of content that can be reordered, with a clean look similar to the Medium editor. <\/p>\n\n\n\n<p>WordPress comes with many blocks by default for standard elements such as list, button or image galleries (see <a href=\"https:\/\/gogutenberg.com\/blocks\/\">https:\/\/gogutenberg.com\/blocks\/<\/a> for all the blocks that comes built-in). You can also save blocks you&#8217;ve used in a post to reuse them in other posts.<\/p>\n\n\n\n<p>For a really effective blogging workflow, you&#8217;ll need to build  new blocks to extent the functionalities of the editor. For another blog I own (<a href=\"https:\/\/robotsbench.com\/\">https:\/\/robotsbench.com\/<\/a>), I wanted to use the HTML <aside> tag that&#8217;s not available in the default blocks so I could give it a specific style in my theme.<\/p>\n\n\n\n<p>It involved more code than I expected and there are many steps. A good surprise still, the majority of the code the plugin is in React (JavaScript) instead of the PHP scripts used for standard plugins. You&#8217;ll still need a tiny bit of PHP to package it as a WordPress plugin, but it&#8217;s mostly boilerplate that can be generated.<\/p>\n\n\n\n<p>This tutorial will walk you through the creation of plugin to use the <aside> tag. We&#8217;ll see how to:<\/p>\n\n\n\n<ul><li>Setting up the right tools to get started.<\/li><li>Create the boilerplate for the plugin.<\/li><li>Add a rich text field to add content to the block.<\/li><li>Add CSS styles to the block.<\/li><\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Setting up the Environment<\/h2>\n\n\n\n<p>Before we get started creating the plugin template, you&#8217;ll need to install the following on your computer to follow along. <\/p>\n\n\n\n<p>You&#8217;ll already have all of this if you&#8217;re already developing in JavaScript and own a blog, but here is it for completeness\u2019 sake:<\/p>\n\n\n\n<ul><li>A <strong>code editor <\/strong>to edit PHP, JavaScript and CSS files. Right now, my favorite is Visual Studio Code at <a href=\"https:\/\/code.visualstudio.com\/\">https:\/\/code.visualstudio.com\/<\/a>. <\/li><li><strong>npm version 5.3 or more <\/strong>to create the template, get the required dependencies and package the plugin at <a href=\"https:\/\/www.npmjs.com\/get-npm\">https:\/\/www.npmjs.com\/get-npm<\/a>.<\/li><li>A <strong>live or local installation of WordPress with the Gutenberg editor <\/strong>to test the plugin. The Gutenberg editor now comes enabled by default in WordPress. I used Local by Flywheel to do this.<\/li><\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Generate an Empty Plugin Template <\/h2>\n\n\n\n<p>We are going to use a tool called <em>create-guten-block<\/em> (<a href=\"https:\/\/github.com\/ahmadawais\/create-guten-block\">https:\/\/github.com\/ahmadawais\/create-guten-block<\/a>) to create a template for our new plugin and upload it to your blog to test the whole process first. It will only contain a single block in this tutorial, but you could add all your custom blocks in a single plugin.<\/p>\n\n\n\n<p>In the command line, use the following command to generate a plugin named  <em>cp-aside-gutenberg-block<\/em>. <\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: plain; title: ; notranslate\" title=\"\">\nnpx create-guten-block cp-aside-gutenberg-block\n<\/pre><\/div>\n\n\n<p>Your newly created plugin will be in a <em>cp-aside-gutenberg-block<\/em> subfolder of the current folder. To prepare your plugin to upload on your WordPress installation, navigate to the plugin folder and build it.<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: plain; title: ; notranslate\" title=\"\">\ncd cp-aside-gutenberg-block\nnpm run build\n<\/pre><\/div>\n\n\n<p>To deploy the plugin, add the following files in the <em>cp-aside-gutenberg-block<\/em>  folder to a .zip file:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: plain; title: ; notranslate\" title=\"\">\n\\dist \n\\src\nplugin.php\n<\/pre><\/div>\n\n\n<p>You could include all the other files for the sake of having the complete source code of your plugin on your blog, but they won&#8217;t be used by WordPress. If you do include them, ignore the <em>\\node_modules<\/em> folder: it&#8217;s a pretty big folder and you can always download the content again using the <em>npm install <\/em>command if you need to recreate it.<\/p>\n\n\n\n<p>Deploy it like you would deploy any other plugin, using the <em>Plugins\/Add new <\/em>menu in WordPress and clicking the <em>Upload Plugin<\/em> button to select the .zip file you just created. Activate it and it should now be shown as active in your list of plugins. <\/p>\n\n\n\n<figure class=\"wp-block-image\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"66\" src=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/installed-1024x66.png\" alt=\"\" class=\"wp-image-3132\" srcset=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/installed-1024x66.png 1024w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/installed-300x19.png 300w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/installed-768x50.png 768w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/installed-700x45.png 700w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/installed.png 1113w\" sizes=\"(max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p>From there on, the new block will appear in the list of blocks when you edit a post.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img loading=\"lazy\" decoding=\"async\" width=\"357\" height=\"406\" src=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/blocklist.png\" alt=\"\" class=\"wp-image-3133\" srcset=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/blocklist.png 357w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/blocklist-264x300.png 264w\" sizes=\"(max-width: 357px) 100vw, 357px\" \/><\/figure>\n\n\n\n<p>The block can be rendered differently in the editor and in the final blog post. With the boilerplate, it will show up in the editor as the following:<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img loading=\"lazy\" decoding=\"async\" width=\"793\" height=\"255\" src=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/backend.png\" alt=\"\" class=\"wp-image-3134\" srcset=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/backend.png 793w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/backend-300x96.png 300w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/backend-768x247.png 768w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/backend-700x225.png 700w\" sizes=\"(max-width: 793px) 100vw, 793px\" \/><\/figure>\n\n\n\n<p>And in the real post (or in the post preview):<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img loading=\"lazy\" decoding=\"async\" width=\"746\" height=\"241\" src=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/frontend.png\" alt=\"\" class=\"wp-image-3135\" srcset=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/frontend.png 746w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/frontend-300x97.png 300w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/frontend-700x226.png 700w\" sizes=\"(max-width: 746px) 100vw, 746px\" \/><\/figure>\n\n\n\n<h2 class=\"wp-block-heading\">What&#8217;s in the Boilerplate?<\/h2>\n\n\n\n<p>The template has generated many files for the plugin. Here is what&#8217;s included in the plugin we just tried out from the generated template:<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img loading=\"lazy\" decoding=\"async\" width=\"192\" height=\"460\" src=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/09\/GenTemp-Files.png\" alt=\"\" class=\"wp-image-3067\" srcset=\"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/09\/GenTemp-Files.png 192w, https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/09\/GenTemp-Files-125x300.png 125w\" sizes=\"(max-width: 192px) 100vw, 192px\" \/><\/figure>\n\n\n\n<p>Many things here will be familiar to you if you&#8217;ve worked on a React application before. Here are the most interesting parts:<\/p>\n\n\n\n<ul><li><strong>\/dist:<\/strong> The frontend files that we built with the<em> npm run build <\/em>command and that need to be deployed.<\/li><li><strong>\/src: <\/strong>Contains all the source code of the plugin (both the frontend in JavaScript and backend in PHP).<\/li><li><strong>package.json:<\/strong> Describes the various dependencies required and commands that can be run. You&#8217;ll only need to edit it if you need additional JavaScript dependencies. By default, it only depends on the <em>cgb-script <\/em>library that pulls everything else.<\/li><li><strong>plugin.php: <\/strong>The standard file needed for a WordPress plugin.<\/li><\/ul>\n\n\n\n<p>The most interesting part is the <em>src\/block\/block.js<\/em> file that contains the JavaScript for the plugin:<\/p>\n\n\n\n<pre>import &#039;.\/style.scss&#039;;\nimport &#039;.\/editor.scss&#039;;\n\nconst { __ } = wp.i18n;\nconst { registerBlockType } = wp.blocks;\n\nregisterBlockType(&#039;cgb\/block-cp-aside-gutenberg-block&#039;, {\n   title: __(&#039;cp-aside-gutenberg-block&#039;),\n   icon: &#039;shield&#039;, \/\/ Icon used for the block from Dashicons\n   category: &#039;common&#039;,\n   edit: function(props) {\n      return (\n         <div className={ props.className }>Hello from the backend.<\/div>\n         );\n   },\n   save: function(props) {\n      return (<div>Hello from the frontend.<\/div>);\n   },\n} );<\/pre>\n\n\n\n<p>The Gutenberg Block API used to extend the editor makes the <em>registerBlockType <\/em>method available to add your own blocks. The <em>registerBlockType <\/em>method describes the block and what happens when displaying for the editor or from a post. <\/p>\n\n\n\n<p>It includes metadata about the block such as its <em>title<\/em>, <em>icon <\/em>and <em>category <\/em>in the editor. It also includes the following two functions where most of the logic of the block lives:<\/p>\n\n\n\n<ul><li><strong>edit<\/strong>: The fields that are shown in the Gutenberg editor to modify the content of the block.<\/li><li><strong>save<\/strong>: The components that describe how to render the block in the post.  The rendered markup is serialized and saved with the rest of  the post so React is not needed when displaying the post.<\/li><\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Adding a Rich Text Field<\/h2>\n\n\n\n<p>Now that a basic block is available, let&#8217;s modify it to display content as an <aside> HTML tag. At the same time, we&#8217;ll also add an editable rich text field so we can add this content from the editor.<\/p>\n\n\n\n<p>To add the editable field, the block must now store a value in the block since it needs to render it. In the Block API, values are registered as a list of attributes in the <em>registerBlockType <\/em>method.<\/p>\n\n\n\n<p>Attributes behave similarly to the state in React, but they contain some extra information so they can be managed by the Block API. The definition of the attribute specifies how to map the rendered content saved into the block to the content. <\/p>\n\n\n\n<p>This block will have only one attribute named <em>content<\/em>. This attribute will look for the children inside the element described by the <em>.cp-aside-gutenberg-block-content <\/em>selector. The type of the content is an array because the block will contain many paragraphs (<p>) created by the rich text editor.<\/p>\n\n\n\n<pre>\nattributes: {\n    content: {\n        type: &#039;array&#039;,\n        source: &#039;children&#039;,\n        selector: &#039;.cp-aside-gutenberg-block-content&#039;\n    }\n},\n<\/pre>\n\n\n\n<p>The following documentation includes all the data type supported by the <em>attributes<\/em> property : <a href=\"https:\/\/developer.wordpress.org\/block-editor\/developers\/block-api\/block-attributes\/\">https:\/\/developer.wordpress.org\/block-editor\/developers\/block-api\/block-attributes\/<\/a>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Editing the Content of the Block<\/h3>\n\n\n\n<p>When editing the post in Gutenberg, the <em>edit <\/em>method will receive the current value of the <em>attributes <\/em>as a parameter so it can show the controls needed to edit them. It also receives a <em>setAttributes <\/em>to update the current value of the attributes when the control is edited. <\/p>\n\n\n\n<pre>\nedit: ({ attributes, setAttributes }) => {\n    const updateContent = (value) => {\n        setAttributes({content: value})\n        }\n\n    return (\n        <RichText tagName=\"aside\" \n                  multiline=\"p\" \n                  value={attributes.content} \n                  className=\"cp-aside-gutenberg-block-content\" \n                  onChange={updateContent} \/>\n    );\n}\n<\/pre>\n\n\n\n<p>Those values will be used to initialize the <em>RichText <\/em>control already available with Gutenberg (see the complete example at the bottom of the post to see how to import it in your block) . <\/p>\n\n\n\n<p>Since it&#8217;s a React control, the name of the attribute for CSS class of the control is <em>className <\/em>instead of <em>class <\/em>in HTML. You can also specify which tag type is the parent of the control, so in that case we&#8217;ll use <aside> to get the result we wish.  <\/p>\n\n\n\n<p>When the content of the editor change, the method specified in the <em>onChange <\/em>attribute of the <em>RichText <\/em>control is called and the current value is updated.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"> Saving the Content of the Block <\/h3>\n\n\n\n<p>When the <em>save <\/em>method is called to render the control and save the result,  it also receives the current value of the <em>attributes <\/em>as a parameter (but not the <em>setAttributes <\/em>method since it won&#8217;t change the current value).<\/p>\n\n\n\n<pre>\nsave: (props) => {\n    return (\n        <RichText.Content tagName=\"aside\" \n                          value={props.attributes.content} \n                          className=\"cp-aside-gutenberg-block-content\" \/>\n    );\n}\n<\/pre>\n\n\n\n<p>It then uses the <em>RichText.Content <\/em>control to render the value correctly as rich text so it can be displayed later, so the parameters are similar to the <em>RichText <\/em>editor control.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">CSS for the Block<\/h3>\n\n\n\n<p>To complete the plugin, let&#8217;s add this little bit of CSS in <em>src\\block\\style.scss<\/em> to show a small border around the aside block. I&#8217;ve kept it simple since it will be most likely edited at the theme level. <\/p>\n\n\n\n<p>This style is applied in the editor and in the post preview; there is also a <em>src\\block\\editor.scss<\/em> file already created for styles specific to the editor.<\/p>\n\n\n\n<pre>\n.cp-aside-gutenberg-block-content {\n  border:3px dashed #160c28;\n  margin: 1.5em 3em 1.5em 3em;\n  padding: 1em;\n  background-color: #e1efe6;\n}\n<\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">Final Version of the Block<\/h3>\n\n\n\n<p>Here is the complete plugin. Notice the import to be able to use the <em>RichText <\/em>control that I mentioned earlier.<\/p>\n\n\n\n<pre>\nimport &#039;.\/style.scss&#039;;\nimport &#039;.\/editor.scss&#039;;\n\nconst { __ } = wp.i18n; \/\/ Import __() from wp.i18n\nconst { registerBlockType } = wp.blocks;\nconst { RichText } = wp.editor;\n\nregisterBlockType(&#039;com-cindypotvin\/cp-aside-gutenberg-block&#039;, {\n    title: &#039;Aside Box&#039;,\n    description: &#039;Block showing a <aside> HTML element.&#039;,\n    icon: &#039;editor-justify&#039;,\n    category: &#039;formatting&#039;,\n    attributes: {\n      content: {\n          type: &#039;array&#039;,\n          source: &#039;children&#039;,\n          selector: &#039;.cp-aside-gutenberg-block-content&#039;}\n    },\n    edit: ({ attributes, setAttributes }) => {\n        const updateContent = (value) => {\n            setAttributes({content: value})\n            }\n        return (\n            <RichText tagName=\"aside\" \n                      multiline=\"p\" \n                      value={attributes.content} \n                      className=\"cp-aside-gutenberg-block-content\" \n                      onChange={updateContent} \/>\n        );\n    },\n    save: (props) => {\n        return (\n            <RichText.Content tagName=\"aside\" \n                              value={props.attributes.content} \n                              className=\"cp-aside-gutenberg-block-content\" \/>\n        );\n    }\n});\n<\/pre>\n\n\n\n<p>Here is a GitHub repository with the full code of the plugin and more comments: <a href=\"https:\/\/github.com\/CindyPotvin\/cp-aside-gutenberg-block\">https:\/\/github.com\/CindyPotvin\/cp-aside-gutenberg-block<\/a>.<\/p>\n<iframe loading=\"lazy\" src=\"https:\/\/newsletter.cindypotvin.com\/embed\" width=\"100%\" height=\"320\" frameborder=\"0\" scrolling=\"no\"><\/iframe><!--themify_builder_content-->\n<div id=\"themify_builder_content-3062\" data-postid=\"3062\" class=\"themify_builder_content themify_builder_content-3062 themify_builder tf_clear\">\n    <\/div>\n<!--\/themify_builder_content-->\n","protected":false},"excerpt":{"rendered":"<p>I&#8217;ve started playing with the new Gutenberg editor in WordPress, and the experience is a lot more modern than the old TinyMCE editor that&#8217;s been around for a good 15 years (and I&#8217;ve had blogs for almost that long!). Instead of editing all the content of the post at once, the Gutenberg editor works with [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":3096,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[62,4,110,111],"tags":[113,61,116,114,115,112],"jetpack_featured_media_url":"https:\/\/cindypotvin.com\/wp-content\/uploads\/2019\/10\/GutenbergBlockCover.png","jetpack-related-posts":[],"jetpack_sharing_enabled":true,"builder_content":"","_links":{"self":[{"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/posts\/3062"}],"collection":[{"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/comments?post=3062"}],"version-history":[{"count":34,"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/posts\/3062\/revisions"}],"predecessor-version":[{"id":3136,"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/posts\/3062\/revisions\/3136"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/media\/3096"}],"wp:attachment":[{"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/media?parent=3062"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/categories?post=3062"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/cindypotvin.com\/wp-json\/wp\/v2\/tags?post=3062"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}