Riad Benguella 12:21 am on October 3, 2018
Tags: core-js ( 131 )

Technical overview of Gutenberg integration

To better understand how we can integrate GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ into WordPress, it’s crucial to know how the Gutenberg pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party is organized.

JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. Packages

The Gutenberg plugin is mostly a JavaScript application composed of several packages. Each one of these packages is:

Generic and available as an npm package.
The Gutenberg Plugin registers each package as a WordPress script.
The Gutenberg Plugin makes the public APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. of each package available in the wp global variable.
If a package is dependent on another one, it consumes it as a global variable and adds it as a dependency of the WordPress registered script.
A package can have one or multiple CSSCSS Cascading Style Sheets. stylesheets.

For example:

A @wordpress/components npm package is registered in the plugin as a wp-components WordPress script; its API is available in the wp.components global variable; and depends on @wordpress/element.

In turn, @wordpress/element‘s script is wp-element and is consumed by @wordpress/components in the bundled script as wp.element.

Bootstraping the editor’s page

To display the editor’s page we call wp.editPost.initializeEditor from the higher-level wp-edit-post package. This function takes as arguments the post to be edited and some editor settings.

This call is made when loading the edit.php page localizing the required arguments and enqueuing the wp-edit-post script.

REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. endpoints

Once the editor’s page rendered, all the communication with WordPress happens using REST API calls. In addition to the regular REST API endpoints to fetch, update and delete taxonomies, posts, etc., Gutenberg adds new REST API endpoints that include:

Autosaving endpoint.
Reusable Blocks endpoint.
Root endpoint for site settings.

Many other tweaks have been necessary in existing endpoints (taxonomies, embeds, permalinks, post search, etc) and most of these have been merged in the previous 4.9.* releases.

MetaBoxes

To support MetaBoxes, Gutenberg hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. initially render the content of the MetaBoxes in a hidden DOM node rendered using a PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher script. We also hook into the post.php call to persist the MetaBoxes save call.

Summary

So, as a high-level picture, the Gutenberg plugin is composed of:

JavaScript scripts and styles.
A PHP file to bootstrap the editor in edit.php.
REST API endpoints.
PHP utilities to parse, register and render blocks on the front-end.
PHP script to inject the MetaBoxes into the page and hooks to save the MetaBoxes.

Integration Process

In previous JavaScript meetings, we discussed the packages integration approach:

Since the JavaScript scripts are built as reusable npm packages, we’ll consume them in WordPress like any other npm package:

Adding a dependency in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’s package.json.
Exporting the wp.* globals in enqueue scripts inside WordPress Core.
- Example: wp.components = require( '@wordpress/components' );
Moving the script registration corresponding to each package into wp-includes/script-loader.php.

Scripts like wp.shortcode, wp.a11y.speak, wp.utils.WordCount can be replaced by their corresponding npm packages. This has already been proposed for the shortcode package and should continue for other packages.

The work being done in #core-js meetings to align the JavaScript guidelines (code style) between Gutenberg and Core would result in a formal @wordpress/eslint-preset package that should be used as a replacement for the current JSHint config.

The REST endpoints should be moved to the regular REST endpoints location in WordPress Core wp-includes/rest-api/endpoints.

The PHP utilities and classes should be moved to wp-includes.

Some minor tasks are also left to do in the Gutenberg repository:

Drop the Gutenberg name from all the PHP APIs still using it.
Finalize the block-library and edit-post packages:
- HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. and Freeform block to be moved to the npm packages.
- The creation of the edit-post package.

Test Suite

The e2e tests are crucial to avoid regressionregression A software bug that breaks or degrades something that previously worked. Regressions are often treated as critical bugs or blockers. Recent regressions may be given higher priorities. A "3.6 regression" would be a bug in 3.6 that worked as intended in 3.5. when making updates to WP-Adminadmin (and super admin). The e2e test infrastructure and the tests themselves should be moved to WordPress Core and their stability can be considered a metric for the success of the integration process.

Unit tests, in general, live next the code being tested. For packages, these will stay in the Gutenberg repository and, for the files moved to Core, the tests will follow.

What about the Gutenberg Plugin?

After WordPress 5.0 is released, the Gutenberg plugin will continue to exist. Its purpose will be changed to the development and the maintenance of the WordPress npm packages, including the editor itself, and will also serve to develop the second phase (site customization) of the Gutenberg project. Plugin updates will continue to be released during the 5.0 cycle.

The PHP part of the plugin won’t be needed anymore, as the plugin will just register new versions of the scripts of the packages to replace the ones already registered by Core.

davidshq 1:46 am on October 3, 2018

Very helpful overview Riad, thanks for putting this together!
Drew Jaynes 4:24 am on October 3, 2018

Great writeup. It seems that the one major piece still missing is the plan for how documentation will be managed and maintained going forward. I’m aware there is currently a Gutenberg handbook already living within .org’s infrastructure, though I’m particularly interested in more information on how governance and continued maintenance of that documentation will proceed following the merge.

Corollary to maintenance of the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ handbook, there is the inevitable problem of sharding the code documentation into multiple locations by virtue of integrating any code (particularly the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher parts, like the REST endpoints) into coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and the docs associated with that code landing in the Code Reference. What, if any, are your plans for tying docs in the Code Reference back into the handbook, and who will be responsible for broadly maintaining that handbook?

Side note: It looks like there’s some content in the handbook that will need to be adjusted to present tense following the merge, stuff like “The editor will endeavour” should become “The editor endeavors” etc.
- Riad Benguella 1:49 pm on October 3, 2018
  
  That’s a good question, documentation is very important for the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ integration.
  
  As a start, we will probably continue updating the documentation in the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party while making it clear in the Handbook which version you’re looking at:
  
  – Is it the integrated version into CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. (the default)?
  – Is it the handbook for the updates coming to Core (The current version in the plugin)?
  – A version selector could also be integrated.
  
  It’s also important to note that the setup itself is subject to change over time.
  
  As you mentioned, the handbook needs adjustments and we’re are already improving its content. If you want to be involved in that feel free to take a look at the “docs” folder of the repository and make updates to the markdown files.
Jb Audras 7:15 am on October 3, 2018

Thanks @youknowriad for this recap!

My only concerns is about updating GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ as a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party: in my opinion Gutenberg plugin should never be updated without a coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. update too. Like other bundled plugins, the “as a plugin” version should always follow the bundled version 😉
- Riad Benguella 1:40 pm on October 3, 2018
  
  The idea here is to see GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ as the “development” version for the upcoming changes into CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. These changes will always make their way into Core.
  
  Gutenberg PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party will server as a development plugin (or featured plugin) for the changes post 5.0.
  
  – Site Customization.
  – Enhancements to the Gutenberg editor.
  
  The user flow needs to be polished to match something like that:
  
  – When you install 5.0, the Gutenberg plugin is disabled automatically with a notice.
  – If you want to continue opting-in to the development version of Gutenberg, you’ll have to reactive the plugin again.
  - noisysocks 9:08 pm on October 3, 2018
    
    I’m wondering, how will we backportbackport A port is when code from one branch (or trunk) is merged into another branch or trunk. Some changes in WordPress point releases are the result of backporting code from trunk to the release branch. urgent bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes to old versions of a package if a newer version is being developed in the packages repository? For example, say that WordPress uses @wordpress/components v1.0.0, @wordpress/components v2.0.0 is what is currently in the package repository’s master branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch"., and that there’s an urgent bug that necessitates a v1.0.1 release.
    - gziolo 7:07 am on October 15, 2018
      
      The good part about the approach we took is that we tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) every release through Lerna so technically speaking you can check out older version locally, apply changes by cherry picking commits and publish a new version to npm when necessary. This would be similar to what we did in the past with GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party release candidates. I’m sure we will figure out something as soon as such issue pops up 🙂
  - Riad Benguella 10:13 pm on October 3, 2018
    
    That’s a good question @noisysocks and part of the workflow we need to polish for post 5.0.
    
    – One way to approach this is to use branches
    – Another way is to use feature flags where the new features are hidden unless you opt-in (pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party).
Justin Kopepasah 7:34 am on October 11, 2018

@youknowriad if the plan is to continue development from the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ repository after merging into coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and releasing WordPress 5.0, then what types of Core JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. development will reside under the official WordPress Develop repository (i.e. git://develop.git.wordpress.org/)?

Are we to consider these two separate pieces of WordPress in the foreseeable future?
- Riad Benguella 7:54 am on October 11, 2018
  
  For the time being, we should consider these as two separate repositories that constitute WordPress when assembled.
  
  A secondary goal of GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ is to be CMS agnostic and even backend agnostic, using a separate repository allows us to avoid “shortcuts” which would harm those secondary goals. Also, keeping the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party in GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ allows us to keep the rapid pace of development for the next phases.
  
  This means the JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. that leaves in the develop repository will be mainly what I call “Glue JavaScript”: making sure the generic packages fit together and provide the necessary configs from the WordPress backend.
  
  Keeping these repositories separate should be seen as a pragmatic solution for the moment, it doesn’t mean we can change that in the future.
  - Justin Kopepasah 8:17 am on October 11, 2018
    
    Thanks for the clarification. 🙂