Getting Started with Gutenberg Development
•Download as PPTX, PDF•
0 likes•396 views
A basic introduction to developing blocks for the new WordPress Gutenberg Editor. Presented at WordCamp St. Louis 2018
Recommended
More Related Content
What's hot
What's hot (20)
Similar to Getting Started with Gutenberg Development
Similar to Getting Started with Gutenberg Development (20)
More from Jason Yingling
More from Jason Yingling (14)
Recently uploaded
Recently uploaded (12)
Getting Started with Gutenberg Development
- 1. GETTING STARTED WITH GUTENBERG DEVELOPMENTJason Yingling (@jason_yingling) jasonyingling.me
- 2. GUTENBERG TODAY Active development - Github Feature Plugin on WordPress.org Coming in WordPress 5.0 Release date: TBD 2018 🤞
- 3. TABLE OF CONTENTS What are Blocks Best Practices Enqueueing Scripts JavaScript for Gutenberg The Block API Where to Learn More
- 4. GUTENBERG BLOCKS “ ” The way in which themes and plugins can add their own functionality to expand on the post editor.
- 6. BLOCKS IN THE FRONT END
- 7. BLOCK OBJECT TREE While editing a post with the Gutenberg editor, block information is stored in memory in a “tree of objects”.
- 8. BLOCKS IN THE DATABASE HTML comments are used to denote blocks in the post markup for conversion back to editable blocks in the Gutenberg editor.
- 10. WIDE AND FULL IMAGE ALIGNMENTS Gutenberg adds two new image alignments alignwide and alignfull. Themes must declare theme support to enable them.
- 11. STYLING THE ALIGNMENTS METHOD 1 Breaking alignfull and alignwide out of a limited width parent.
- 12. STYLING THE ALIGNMENTS METHOD 2 alignfull and alignwide inside a full-width parent.
- 13. DEFAULT COLOR PALETTE The color palette allows theme developers to set a collection of preset colors to choose from in the block editor.
- 15. INCLUDING BLOCKS PLUGINS OR THEMES “ ” The general rule of thumb for including functionality in plugins or themes is to keep themes to the presentation of content and use plugins for functionality.
- 16. BEST PRACTICES: FILE STRUCTURE File structures can vary and this particular structure is not a requirement.
- 17. BEST PRACTICES: NAMING BLOCKS Blocks require the name to be structured as namespace/block-name. namespace will be your plugin name. block-name can only use lowercase alphanumeric characters, dashes, and must begin with a letter.
- 18. BEST PRACTICES: TRANSLATION Strings in JavaScript can be made translatable with similar functions as used in PHP translations.
- 20. ENQUEUEING SCRIPTS HOOKS enqueue_block_editor_assets Hook for enqueueing scripts and styles in the admin editor only. enqueue_block_assets Hook for enqueueing scripts and styles in both the admin editor and the frontend. Use with wp_enqueue_script and wp_enqueue_style
- 21. WHAT TO ENQUEUE EDITOR ONLY Main JavaScript for registering and editing blocks Styles that are only relevant in the context of the editor. enqueue_block_editor_assets
- 22. WHAT TO ENQUEUE EDITOR ONLYenqueue_block_editor_assets
- 23. WHAT TO ENQUEUE EDITOR AND FRONTEND JavaScript needed to function on the frontend Main styles for final output of the block enqueue_block_assets
- 24. WHAT TO ENQUEUE EDITOR AND FRONTENDenqueue_block_assets
- 25. AN ALTERNATE METHOD FOR ENQUEUEING A slightly different approach to enqueueing
- 26. A NOTE ON DEPENDENCIES Gutenberg comes with several JavaScript libraries that can kick-start your block building. At minimum when enqueueing your scripts you should list wp-blocks and wp-element as dependencies wp-components and wp-i18n are optional but very useful libraries
- 28. JAVASCRIPT LIBRARIES WP.ELEMENT Abstraction layer atop React Used for creating elements Protects the WordPress Way Access to createElement and render functions Handle: wp-element
- 29. JAVASCRIPT LIBRARIES WP.BLOCKS Gives access to components and functions used for building blocks registerBlockType lives here BlockControls and RichText components are made available Handle: wp-blocks
- 30. JAVASCRIPT LIBRARIES WP.EDITOR BlockControls and RichText components are made available As of 3.1.0 5 days ago Handle: wp-editor
- 31. JAVASCRIPT LIBRARIES WP.COMPONENTS Additional components that can be used in block creation tooltips, popovers, and spinners are a few components that can be found Full List on Github Handle: wp-components
- 32. JAVASCRIPT LIBRARIES WP.I18N Contains internationalization functions for JavaScript Similar to the PHP __() internationalization function Handle: wp-i18n
- 34. WHAT IS MODERN JS ES6+ (ECMASCRIPT) ES5 - 2009 ( Standard JS ) ES6+ - 2015 ( Modern JS / Yearly ) ES7 - 2016 ES8 - 2017 ES Next - The next version
- 35. WHAT IS MODERN JS JSX A syntax for writing HTML like markup in JavaScript
- 36. WHAT IS MODERN JS REACT A JavaScript framework for building user interfaces using components. Components are essentially custom HTML elements with their own functionality.
- 37. USING MODERN JS BUILD TOOLS Tools for taking modern JS and outputting browser compatible JS. Babel, webpack, etc. Babel
- 39. BLOCK API INDEX.JS Import dependencies Make functionality from JavaScript libraries available to your block Register your block
- 40. BLOCK API REGISTER BLOCK TYPE The function for registering a block. Takes two arguments: block name and a block configuration object edit and save functions are where the magic happens
- 41. BLOCK CONFIG TITLE The title for your block shown to the user when inserting a block
- 42. BLOCK CONFIG DESCRIPTION (OPTIONAL) Short description for your block
- 43. BLOCK CONFIG CATEGORY Helps users discover and browse blocks. Core categories are common, formatting, layout, widgets, and embed
- 44. BLOCK CONFIG ICON (OPTIONAL) A Dashicon or custom SVG used to identify your block in the editor
- 45. BLOCK CONFIG KEYWORDS (OPTIONAL) Additional keywords (up to 3) used for discovering blocks
- 46. BLOCK CONFIG ATTRIBUTES (OPTIONAL) Allow for extracting values from saved post content for use in the JavaScript representation of a block
- 47. BLOCK CONFIG EDIT The edit function handles how your block is displayed in the context of the editor. It receives the attributes, className, and isSelected properties.
- 48. BLOCK CONFIG SAVE The save function handles how the attributes of your block are combined into the final markup.
- 49. BLOCK CONFIG RICHTEXT API A component for rendering a rich contenteditable input for blocks. Provides users the option to add emphasis or links to content. Properties Available
- 50. BLOCK CONFIG DYNAMIC BLOCKS For blocks that need to pull information from the database you’ll use a PHP callback. For the editor display Gutenberg exposes the RestAPI with withAPIData.
- 52. STEPS TO GET STARTED Setup a plugin Enqueue assets Setup a compiler Write the code Run a build process
- 54. GUTENBERG DEVELOPMENT RESOURCES Gutenberg.courses Gutenberg.news Create Guten Block Gutenberg Handbook Gutenberg Repository Make.WordPress.org
- 55. GUTENBERG DEVELOPMENT QUESTIONS Twitter: @jason_yingling Email: jason@jasonyingling.me
Editor's Notes
- The idea behind Gutenberg - tie the front end and the editor together. better user experience.
- Takes functionality that was previously done with shortcodes and makes it more visual within the editor. Drag and droppable. Save blocks to reuse across posts. Define blocks available to post types through templates.
- Better tie between visual on frontend and backend
- The tree of objects describes the blocks that compose a post in the editor view each item represents a block and the attributes within it that can be edited
- Once a block is saved in the editor it is saved into the database with an HTML comment In order to allow the saved content to be converted back into the “tree of objects” used by the editor the data is serialized into the HTML comment Were the “tree of objects” and output stored separately there would be the risk of data becoming out of sync
- Most blocks within Gutenberg will provide their own styles which can then be added to or overwritten by a theme Some features however require themes to opt-in for support as it is difficult for the block to supply styles to work with all themes as they can be handled multiple ways The wide and full image alignments are good examples Note: neither of these will work very well with sidebars
- Breaking out of a limited width parent. Pretty common to have a layout when the entire post content is wrapped in a fix width parent. Rather than recode there are ways to break outside the limits of the parent.
- The nicer way. No limit on the parent width, but you take all direct children and give them a max-width then overwrite the max-width as needed
- I tend to think of it this way: if I were to switch themes would losing the definition of a block effect content? It most likely would especially if there are any dynamic blocks. So blocks should be built in a plugin that can stay with a site through theme changes.
- Gutenberg introduces two new hooks for enqueuing scripts and styles for gutenber.
- The bulk of your block JS will be included in the enqueue_block_editor_assets Styles could be things like a focus state on an input in the editor. Whereas the front-end would only display the final value that was input.
- JS might be the JS needed for a slider to function. The bulk of your styles will be here.
- There is another way. Currently the method shown in the Gutenberg Handbook. Connected to the ‘init’ hook and passed as an argument Use ‘editor_script’, ’editor_style’, and ‘style’ I like the other hooks as it give more control and is similar to the current method of enqueueing scripts and styles
- Having an abstraction layer on top of react give WordPress protection against changes to React and leaves open doors for switching to other frameworks Basically if the need were to arise to switch off React an abstraction layer helps protect against the change effecting plugins and themes using the existing framework The wp.element library gives access to react’s createElement and render functions createElement Create and return a new React element tag name string (like div or span) or a React component In React you don’t typically need to call createElement directly if you’re writing in JSX. render Is the function used by React to render an element in the DOM
- BlockControls provides a toolbar of icons buttons to be used in the block editor. RichText provides an easy way to include a contenteditable interface in your block
- Allows for easily adding existing components to your own blocks allowing to keep the look and feel of block editing the same. Also gives a good head start to creating your own blocks.
- Allows you to easily make strings in your JavaScript translatable A .pot file can be generated using a custom Babel plugin to scan JS
- Gutenberg is built with modern JavaScript. What does that mean?
- ES6+ refers to any JS after ES6. JavaScript switched to a yearly release schedule with ES6 in 2015. ES Next refers to the next version of JS from the current release ES6 doesn’t replace ES5 it builds upon it Gutenberg can be fully built with ES5
- JSX is a syntax for writing HTML like markup within JavaScript Makes it much easier to read and write markup within your JavaScript Example shows a div, h2, and custom React component of RichText being written in JSX Note “className” is used as “class” is reserved in JS
- React is the framework used by Gutenberg for building user interfaces in JavaScript This is done by building components which are essentially custom HTML elements with their own functionality. Like the <RichText> element from the previous slide
- In order to use Modern JS in browser you’ll want a build tool that takes modern JS and JSX and outputs it into browser compatible JavaScript Babel is used to convert modern JS to browser compatible JS webpack is a build tool for watching and compiling files automatically
- The Block API consists of the functions WordPress exposes for adding functionality to the gutenberg editor
- importing styles is a pattern from React that is used in core development. It allows for scoping styles to blocks. define the functions you want to use from dependencies so you can call it independently.
- block name is the namespace/block-name discussed previously block configuration object is an object containing the attributes and functionality of your block the edit and save functions of the block configuration object define how the block works in the editor and frontend
- First let’s look at a handful of the available attributes
- Alias like an Image block using “Photo” Limited to 3 keywords per block
- Attributes are the data within the block. Attributes allow for extracting the value from a saved post for use in an editable block This example shows how you would be able to manipulate the src attribute from an img element.
- This is a simple (un-editable) example. This block would display a div with a paragraph in it in the editor. This example shows accessing the className by passing in props to the function
- The alternate save function of this simple block. This is what the block would output to the database a div wrapping a paragraph
- Some of the properties made available in the RichText component include: value: which is a string of what is entered in the input onChange: a callback handler fired when the value changes passing the new value placeholder: a string for placeholder text in the input multiline: a tag name that should be used when enter is pressed for example if set to li it would wrap each line in a li tagName the editable element. In the example we have a H2
- The edit function still shows a representation of the block in the editor’s context (this could be very different from the rendered version, it’s up to the block’s author) The save function just returns null because the rendering is performed server-side. The server-side rendering is a function taking the block attributes as an argument and returning the markup (quite similar to shortcodes)
- Ok so to recap. We need to <read list> … That’s a lot to handle and figure out
- Luckily there are several tools out there for speeding up this process create-guten-block is maybe the fastest setup I’ve come across Ot comes with JSX and ES6 syntax support Webpack build process for dev and production CSS prefixing To get started you’ll need Node.JS and npm installed Then you’ll globally install create-guten-block Then from the plugins folder of a local development site you can run “create-guten-block block-name” and it’ll spin up a full plugin ready for you to start building blocks with modern JS!