Defining Content–Block Areas

One of the major projects from this year’s focuses is to expand the block editor beyond the content area and into other parts of the site. This included, so far, explorations to bring blocks into other screens within the dashboard as well as converting existing widgets into blocks. One of the remaining things to figure out is the specification of content areas themselves. In this post I’d like to start discussing what content areas are and present an example of how it can tie several concepts of phase two of Gutenberg together.

What Are Content Areas?

In its simplest form, content areas represent parts of a site where blocks can be added and manipulated. Since content has a very specific meaning in WordPress already, we can also refer to these as block areas more generally to avoid opaqueness. Block areas would include headers, footers, sidebars, and any other meaningful template part outside of the post content that contains blocks.

The concept of block areas helps provide a way to meaningfully organize blocks within a full page, but is also a way to differentiate between global elements (navigation, site title, and so on) and local elements (the main content of a post, page, or custom post type).

This proposition groups the general Gutenberg roadmap into the following three ideas — how blocks are organized within the main content area, how block areas are organized within the page, and how pages are organized within the site.

Phase one focused, for the most part, on the first idea. The following video tries to illustrate aspects of the second formulation.

Showing how block areas can be organized within the page, with some blocks from the Kioken library making an appearance.

Let’s dissect what is going on a bit more in detail — this will be a fairly technical overview.

Block Areas

Displaying a "header" block area as a single editor view.

Technically, block areas are defined as individual entries in a wp_template custom post type. These structural units can hold any number of blocks and have loose semantics. Also within wp_template are special root templates that can aggregate various block areas. Areas are equivalent to the general use of template parts in themes for this scenario.

wp:area { id: "header" }
    wp:site-title
    wp:navigation
    wp:paragraph { content: "Hello, world!" }
wp:area { id: "post" }
    wp:post-title
    wp:post-date
    wp:post-content

They exist as their own retrievable entries (from `wp_template`) and can be combined within larger template units, providing both conceptual separation and a potentially unified editing flow at the same time. The editor application is capable of saving the different elements to the right places.

Areas can contain general blocks or context-specific blocks (like “post title”, “post date”, and “post content”), making it possible to have more complex theme layouts and designs. In this context, any block offered by WordPress can be a widget in that it could be added to global areas of a site.

Block areas can only be used directly within templates and are not accessible in regular editing sessions. (These are equivalent to theme-editor responsibilities.) The content of block areas, however, becomes easy to edit in a familiar block-editing environment. It is important, then, to distinguish the ability to modify what block areas contain and the ability to insert and define block areas themselves.

It is worth noting that block areas are initially indifferent to where data is sourced and have a non-dependant relationship with editor providers. That means they can define the structure of a theme or layout but don’t deal with granular data allocation; only the blocks used within determine where specific data is allocated. (For example, a Site Title block would be saving its content to the relevant site option regardless of whether it is inserted in a header block area or a footer block area.)

The block navigator can identify different template parts and their contents.

An editor view that understands block areas would be able to display a site design either entirely or in parts. While being able to display areas together is crucial for a faithful representation of the design, the system is still able to separate and orchestrate how data is saved, keeping clear boundaries between local and global content, and allowing flexibility in representing dynamic content. Since block areas are internally blocks defining an inner blocks group they can be exposed through the regular block navigator and identified by display name.

It’s not the most important right at this time to dwell on the implementation details of how a template is defined by a theme declaration, as this could be established through a PHP structure or JSON objects (internationalization is a good subject to keep in mind here) while the anatomy of block areas remains equivalent.

// Example of a root template using various block areas.
{
  "slug": "single",
  "content": [
     [ 'theme/header' ],
     [ 'core/paragraph', { content: "Some content..." } ],
     [ 'core/post' , {}, [
         [ 'core/post-title' ],
         [ 'core/post-content' ],
     ] ]
     [ 'theme/footer' ],
  ]
}

In the example above the `theme/footer` is not a real block but something that gets swapped with a `core/template-part` referencing the corresponding block area.

With this specification, the full layout and design of a given page can be represented through blocks and block areas.

Open questions:

  • Looking further into the future, should wp_templates reflect the current template hierarchy? Example: an entry with an archive slug would map to how archive.php operates today and so on. What would this unlock for users that was harder to do before? (Easy customizations for specific category pages, for example.)
  • How should declaration work from a theme perspective? What would be the most idiomatic in the current paradigm? What would offer most convenience for the future?
  • How can we incorporate more granular add_theme_support into the areas so that color palettes, content widths, etc, are more refined and contextual?
  • Is it worth establishing common semantic areas for added portability? Current templates can be validated and there could also be transformation tools (same as block to block, block area to block area).

Relevant Issues:

Full-Page Editing

The “selector” presentation in the header of the demo is merely a convenient prototype tool and not an implementation proposal.

While block areas provide the structure to handle global elements, the editor also needs to understand how to work with them. There are largely two possibilities: a single editor that could handle all block areas together —providing a comprehensive full view of the site— or multiple editor views for each specific area.

Since each block area is effectively a post-entry, it is already easy to edit them in a regular Gutenberg session. However, as shown in the video, we can also augment the editor so that it can combine all the block area definitions from a template together in a single editing session, providing a comprehensive view of the full page.

Modes allow to explore various configurations and aspects of the editing session, such as focusing on certain areas (the post and its content, the header, sidebar, or footer in this example) and tailor tools to each task at hand. They can also control what is editable and what is locked down, providing the most convenient tools and interactions for each context. We could imagine a site-building mode that exposes more advanced theme tools, or a design mode that helps with alignment issues, balance, and document semantics.

Editing modes can also take into account the currently available block areas to expose specific modes centered around each of these template parts. These views can potentially take over many of the dedicated appearance menus.

While in “writing” mode, only the post properties are saved, whereas full-site editing orchestrates saving not just the content but also each individual template part plus the container template together.

Modes could also be extended by plugins to cover other editorial needs, like toggling between member / non-member states, ads / no-ads, and could also help as a presentational foundation for multi-language in the near future.

Open questions:

  • How should saving work from a UX perspective when there are multiple blocks with global data?
  • Should modes be toggleable within an editing session or should they be isolated to full page views (like the customizer)? (Full-site editing, design mode, etc, could all be part of a specific admin section like the customizer is now.)
  • Implicit relationships between modes and user roles.

Relevant Issues:

  • Selection Tools –17088.
  • Expanding editor beyond post_content –16281.
  • [Explore] Template mode and declarative post blocks: –17263.

Entities & Sources

With block areas handling global elements there is a need to access and manipulate site-wide data from individual blocks and for the editor application to centrally orchestrate its saving mechanisms. The goal is to eliminate the need for block authors to have to handle update mechanisms for non-HTML data.

For this purpose, the current data entities system would absorb more responsibilities and allow blocks to have bindings with data sourced from multiple places in WordPress including sourcing and updating. The block can then consume it as any regular attribute and doesn’t have to handle requests or saving operations. This stays true to the fact that blocks define primarily an interaction model, not a data model.

The architecture of entities has been iterated multiple times already and is meant to be low level so we can do all these optimizations and streamline block declaration.

This mechanism is used in the demo to create a “Site Title” block which operates like any other block in the page, yet doesn’t save to the document HTML source but to the proper site option. These attributes are synchronized from the entity value, so if the block appears multiple times (like showing the title both in the header and the footer of the site) they are kept in sync and reflect all edits within the session. The goal is arriving at a declarative API for custom entity blocks that allows the editor to handle saving the block harmoniously in the same saving flow as everything else.

Relevant Issues:

  • Updating the store to use Core Data entities –16932.
  • Implementing EntityProvider and using it to refactor custom sources –17153. (This work also provides a considerable performance boost.)
  • Add a Site Title block and required functionality –17207.

If you’d like to help with any of these three efforts, join the conversations on GitHub or in Slack at #core-editor!

#gutenberg

Gutenberg Local Environment Rewrite

With the introduction of the WordPress Local Environment, the next step was to make this shiny new development environment available for Gutenberg to use.

tl;dr: If you currently run ./bin/setup-local-env.sh to use the Gutenberg environment, switch to running npm run env install, instead.

Gutenberg’s Local Environment was originally an experiment in making it easy to setup a local development environment. It was a success in some ways, in that it was easier than other methods, but it was by no means easy overall, particularly for non-developer contributors. Over time, it grew into a complex set of shell scripts, with surprising interdependencies and side effects. Being written in Bash made the scripts harder to maintain, and limited the potential audience to those who had a Bash-compatible terminal installed.

Basing Gutenberg’s Local Environment on Core’s has several immediate advantages:

  • It’s cross-platform, only requiring Docker to be installed and running. It also works with Docker Toolbox, allowing all Windows users (not just those with Windows 10 Pro) to use it.
  • The WordPress environment uses Docker images that we maintain for the purpose of Core development, which allows us to to customise them as we need.
  • It ensures that tests for Core and Gutenberg run in the same environment.
  • It’s a single environment, which helps avoid the naming clashes we’ve occasionally seen between the Core and Gutenberg environments.

More broadly for WordPress in the long term, tying the development processes of Core and Gutenberg a little closer together helps pave the way for the processes to merge over time.

Architectural Decisions

Removing the Docker config from Gutenberg entirely (barring a minimal template to hook into the Core environment), and requiring wordpress-develop to run on top of gives us significantly more future flexibility with the development environment.

Additionally, this continues to lay the groundwork for an environment that works as easily as possible for non-developer contributors. In particular, this environment is intended to be usable by all feature plugins, allowing them to easily enable new contributions in a familiar environment. (Or, an environment that will become familiar, at least. 😉)

There are several reasons for putting the main Docker config in Core, and extending it in Gutenberg:

  • Having a single docker-compose.yml file in Core, as opposed to having one in Core, one in Gutenberg, and many more in other feature plugins that will be able to use this, means that there’s only set of Docker containers running. Docker has been observed getting a little weird when trying to run containers with the same names, which mount volumes with the same names.
  • Having multiple docker-compose.yml files doesn’t lend itself to testing plugins together: each plugin ends up with its own environment which can’t talk to others.
  • Managing how plugins can mount older versions of WordPress becomes exponentially more difficult if the docker-compose.yml config needs to work for every WordPress branch (this is a requirement, so that auto updates can be worked on in old branches), rather than being able to tweak the config for each branch.
  • Ideally, feature plugins shouldn’t need to do much customisation of the Docker environment, beyond mounting their particular volumes. Exposing the entire docker-compose.yml file is overkill.

That said, not every Gutenberg contributor will have a WordPress source clone, or want to manage one. So, there’s also a helper which will download and install a copy of the WordPress source repo, when needed.

Much like the WordPress environment, however, the Gutenberg environment doesn’t automate everything. As we found with the original Gutenberg environment, too much automation tended to make it difficult (particularly for more advanced contributors) to customise or debug their environment. For example, the scripts no longer install NVM, switch your Node version, or run npm install.

Using the Gutenberg Local Environment

If you don’t have a WordPress repo to work with, just run npm run env install, that’ll take care of downloading WordPress, building it, and connecting Gutenberg into it.

If you prefer to hook into your own WordPress source checkout (particularly useful for fixing issues that span Core and Gutenberg), set the WP_DEVELOP_DIR environment variable to your WordPress source directory, and run npm run env connect. This will write a docker-compose.override.yml file to the WordPress source directory, and restart the Docker containers. The Docker override file contains the appropriate volume settings for mounting Gutenberg within the WordPress environment.

Running npm run env will give you a complete list of the available commands, and what they’re for.

The WordPress Local Environment configuration options are also available for configuring the Gutenberg environment.

Adding the Local Environment to another feature plugin

The @wordpress/scripts documentation includes information about including and configuring the local environment.

There currently isn’t a clean method for sharing a managed WordPress checkout (ie, one installed by npm run env install) between plugins. Let’s figure out how that could work!

Also, this process is still mostly untested, so please ping me earlier rather than later if you run into problems. 🙂

Developing Plugins/Themes with the Local Environment

At this stage, the Local Environment is intended for developing Core, and Feature Plugins: it doesn’t have the config options that the wider plugin/theme ecosystem needs, and the base Docker images are built for Core purposes.

Of course, I know y’all will try to use it, anyway. 😉 Testing and feedback is welcome, but please be aware that fixes and features will prioritise Core/Gutenberg requirements for the foreseeable future. Patches and PRs which recognise and allow for this are the best way for additional changes to land. 💖

What’s Next?

Please try out the new Gutenberg Local Environment, and report any issues you run into over on the Gutenberg repository.

If you have thoughts about making this aspect of contributing to Core/Gutenberg easier, I’d love to hear about them!

#block-editor, #gutenberg

What’s new in Gutenberg? (28 August)

With the date of the WordPress 5.3 beta release approaching, testing Gutenberg is increasingly more critical. Any help testing the plugin is much appreciated as it may avoid bugs in a future WordPress beta release.

The Gutenberg 6.4 release brings some interesting highlights.

The Cover block got two new significant functionalities: the ability to be resized and the ability to use a solid color as a background instead of a video or an image.

Recently we added an API that allows themes and plugin developers to create block styles using just PHP calls. In this release, we continued the improvements to the block styles and added the ability for the users to select their preferred default style per block. Each time the user inserts a block, the preferred style is automatically applied.

Another relevant improvement in this release is the introduction of the “Typewriter experience“. We hope this makes writing more “fun” and overall more comfortable, especially on mobile.

6.4 🇫🇷

Features

Enhancements

Experiments

New APIs

Bug Fixes

Various

Documentation

Mobile

Performance Benchmark

The following benchmark compares performance for a particularly sizeable post (~ 36000 words, ~ 1000 blocks) over the last releases. Such a large post isn’t representative of the average editing experience but is adequate for spotting variations in performance.

Version Loading Time KeyPress event (typing)
Gutenberg 6.4 5.6s 66.36ms
Gutenberg 6.3 5.4s 66.87ms
Gutenberg 5.3 (WordPress 5.2) 6.0s 75.79ms

#core-editor, #editor, #gutenberg

APAC Triage and Bug Scrub Sessions

Living in APAC timezones can be difficult. From waking up at 3am for meetings, to flying 20+ for WCUS or WCEU (WCAsia is coming to fix that!), to hearing “what’s it like living in the future?” jokes for the millionth time. One thing that shouldn’t be hard is contributing to WordPress, and it’s time to make that even easier, with APAC-friendly triage and bug scrub sessions.

You may have already seen Gutenberg meetings happening every second week for the last few months, but starting Thursday at UTC 0600, we’ll alternate each week between working on WordPress Core, and Gutenberg! This week, join in the fun in the #core Slack channel for a WordPress Core bug scrub. Next week, the party will be in the #core-editor Slack channel, for a Gutenberg bug scrub. 🎉

The meeting lead will pick a report to work through, but if there are particular issues you’d like to get more eyes on, or you have a patch/PR that you’d like reviewed, this is the place to bring it up!

#apac, #bug-scrub, #core, #core-editor, #gutenberg, #triage

Editor chat summary: 14 August 2019

This post summarizes for the weekly editor chat meeting on Wednesday, August 14, 2019 at 1300 UTC held in Slack.

The agenda can be found here.

Gutenberg 6.3 

  • @riad noted that this release is a very important release in terms of Accessibility because it introduces the Navigation Mode

Priorities for next week

Please don’t hesitate to help there. Provide a11y and design feedback. Help with tests… Let’s move these forward.

Task Coordination

Based on the links in Task Coordination, Riad extracted a list of PRs where feedback is needed:

Open Floor

There was a discussion about new core blocks being developed. The central idea is that some ideas, while good, are low priority, for example the gists block or the multi select dropdown.

Riad explained that the ideas for the blocks themselves are good but “we added components as we needed them in Core and Core blocks. Doesn’t mean we can’t add components for third-party authors if they prove to be useful for a lot of persons but we’d need contributors to champion these”

There is also a list of new blocks that are high priority and considered “blessed tasks” and the list includes: icons, menu, social icons, divider and other Full site editing related blocks (site title, post title, post categories).


Note: Anyone reading this summary outside of the meeting, please drop a comment if you can/want to help with something.

The agenda for the next meeting, 21 August 2019 13:00 UTC is here, please add anything you want to discuss.

#core-editor, #core-restapi, #editor, #gutenberg, #meeting-notes

What’s new in Gutenberg? (14 August)

The Gutenberg 6.3 release is an important milestone in terms of accessibility of the editor.

Gutenberg comes with a lot of features by default, each block can be manipulated with custom controls in its toolbar and inspector panel, block movers, a drag handle. The block UI also includes the content of the block itself which can be complex from block to another. This makes it very challenging for screen reader users to navigate the content of their posts.

To address that issue, we’re introducing the Navigation Mode. By default the editor is loaded in this mode, it allows you to move from block to block using a single Tab press. You can also use the arrow keys to navigate between blocks. Once you reach the block you want to edit, you can enter the Edit Mode by hitting the Enter key. The Escape key allows you to move back to the Navigation Mode.

It’s very important for us to make the editing experience as enjoyable as possible for all the users with different accessibility needs. This feature is very early, please help us test it and we’re looking forward to taking your feedback into consideration.

This feature includes dozens of improvements and bug fixes including:

  • support for text alignments in table block columns.
  • Border color support for the separator block.

For developers, new APIs are available such as the BlockPreview component that allows you to render and preview blocks in any context.

6.3

Features

Enhancements

Experiments

New APIs

Bug Fixes

Various

Documentation

Mobile

Performance Benchmark

The following benchmark compares performance for a particularly sizeable post (~ 36000 words, ~ 1000 blocks) over the last releases. Such a large post isn’t representative of the average editing experience but is adequate for spotting variations in performance.

Version Loading Time KeyPress event (typing)
Gutenberg 6.3.0 4.8s 53.5ms
Gutenberg 6.2.0 4.5s 49.7ms
Gutenberg 5.3 (WordPress 5.2) 5.6s 60.1ms

👏 Kudos to all the contributors. Thank you.

#core-editor, #editor, #gutenberg

Editor chat summary: 7 August 2019

This post summarizes for the weekly editor chat meeting on Wednesday, August 7, 2019 at 1300 UTC held in Slack.

The agenda can be found here.

Task Coordination

Open Floor

@karmatosed and @chrisvanpatten brought up the need for leadership in user focused documentation for Gutenberg.

Graphics requested for Gutenberg documentation can be found on the Design team’s board.

@paaljoachim offered to reach out to the docs team for assistance in moving forward. If you’re interested in helping with user-focused docs for Gutenberg, please reach out in the comments here or in the #core-editor channel!

@kadamwhite mentioned that the REST API team is working on catching up with requests for feedback on tickets and invited folks to the the #core-restapi channel to connect.


Note: Anyone reading this summary outside of the meeting, please drop a comment if you can/want to help with something.

The agenda for the next meeting, 14 August 2019 13:00 UTC is here, please add anything you want to discuss.

#editor, #gutenberg, #meeting-notes

What’s new in Gutenberg? (31 July)

The number of Gutenberg contributors is growing significantly and it’s a pleasure to see how people from all around the world come together to build and improve the software. I’d like to take this opportunity to thank the 48 contributors that participated in this release.

Among the improvements of Gutenberg 6.2, a feature that might seem small but which a lot of people were waiting for: the possibility to customize the target of the Button block (open the link in a new tab).

We also had a lot of people asking for the possibility to use all kinds of block types in the Cover and Media & Text blocks, so we’ve removed their nested block restrictions.

From a Developer Experience perspective, this release introduces a new PHP API to simplify the registration of block styles variations.

// Registering a style variation using a registered WP style.
register_block_style(
	'core/quote',
	array(
		'name'         => 'fancy-quote',
		'label'        => 'Fancy Quote',
		'style_handle' => 'myguten-style',
	)
);

// Registering a style variation using an inline style.
register_block_style(
	'core/quote',
	array(
		'name'         => 'not-fancy-quote',
		'label'        => 'Not Fancy Quote',
		'inline_style' => '.wp-block-quote.is-style-not-fancy-quote { color: blue; }',
	)
);

6.2

Enhancements

New APIs

Bug Fixes

Documentation

Divers

Mobile

Performance Benchmark

The following benchmark compares performance for a particularly sizeable post (~ 36000 words, ~ 1000 blocks) over the last releases. Such a large post isn’t representative of the average editing experience but is adequate for spotting variations in performance.

Version Loading Time KeyPress event (typing)
Gutenberg 6.2.0 4.8s 67.2ms
Gutenberg 6.1.0 5.9s 67.2ms
Gutenberg 5.3 (WordPress 5.2) 7.6s 80.13ms

👏 Kudos to all the contributors. Thank you.

#core-editor, #editor, #gutenberg

Dev chat summary: July 17

@earnjam led the meeting. @marybaum took notes and is writing this summary.

Announcements

Gutenberg 6.1

@earnjam announced the release of Gutenberg 6.1 last week. New features include animations/motion to block reordering, improved messaging for REST API errors and more.

Check out the release post for more details: https://make.wordpress.org/core/2019/07/10/whats-new-in-gutenberg-10-july/

Look for version 6.2 RC to land next week.

PHP Coding Standards

@pento posted a followup to some proposed coding standards changes from a few months back.
See the decisions on these changes here (they might surprise you!): https://make.wordpress.org/core/2019/07/12/php-coding-standards-changes/

And keep in mind these affect only the code for WordPress Core. In your own Themes and Plugins, use the coding conventions that make sense for you.

Releases

5.2.3

With four tickets in the queue and none of them affecting functionality, it’s still not clear that they warrant a separate 5.2.3 release. Scheduling for that is still pending further info on a roadmap for 5.3, which should land in early fall.

5.3

As yet the Core team is progressing on current open tickets — there are 57 in the queue — while @chanthaboune continues gathering data from component maintainers on feature priorities for 5.3.

Component maintainer updates

Core-media

@azaozz asked for more eyes on #40439.

If you can help test, please check out the ticket or head to #core-media.

Site-health

@clorith pointed to the call for input for bumping the PHP recommendation and said that soon a Make blogpost will outline next steps—and next versions.

For now, the site-health team isn’t looking to raise the hard minimum. This will be a soft bump up to nudge users toward the minimums that will follow.

Open Floor

Triage Team

@joyously asked about progress from the Triage Team, and the responses came from several quarters.

@desrosj posted a link to his three-month summary: https://jonathandesrosiers.com/2019/06/wordpress-triage-team-3-month-reflection/ and plans to post more often on https://make.wordpress.org/updates.

@karmatosed mentioned that Design holds two triages a week, and that from where she sits, triage seems to be going gangbusters and spreading across the WordPress Project.

@azaozz pointed the group to his efforts on TinyMCE: https://core.trac.wordpress.org/query?status=accepted&status=assigned&status=new&status=reopened&status=reviewing&component=TinyMCE&order=priority

@marybaum mentioned having been in an accessibility triage last Friday.

Gutenberg Phase 2

Newcomer @Lu asked about the timing of Gutenberg Phase 2, with a particular interest in widget blocks. @earnjam answered with a summary of the release discussion earlier in the chat.

Strings

@marybaum asked the group for their thoughts on a more systematic, global approach to the copy in strings.

For now, the group agreed to have #meta add two keywords to tickets—needs-copy-review and has-copy-review.

Props to @garrett-eclipse, who opened meta#4609 and its counterpart meta#4610 on the spot.

Right at the close of the official chat, @audrasjb linked to https://make.wordpress.org/core/handbook/best-practices/post-comment-guidelines/#style-and-substance

#dev-chat, #gutenberg, #releases, #strings, #triage-team

#summary

What’s new in Gutenberg? (10 July)

A few weeks ago, Matías shared a post about using motion to express change in reactive UIs. This release is a first step in implementing those ideas. It introduces motion to block changes, creation, removal, reordering.

In addition to a number of other improvements and bug fixes, the contributors also worked on typing performance. As of this release, typing is 30% faster on long posts.

6.1

Enhancements

Experiments

Bug Fixes

Performance

Documentation

Various

Mobile

Performance Benchmark

The following benchmark compares performance for a particularly sizeable post (~ 36000 words, ~ 1000 blocks) over the last releases. Such a large post isn’t representative of the average editing experience but is adequate for spotting variations in performance.

Version Loading Time KeyPress event (typing)
Gutenberg 6.1.0 5.2s 56.89ms
Gutenberg 6.0.0 5.4s 80.2ms
Gutenberg 5.3 (WordPress 5.2) 4.9s 66ms

👏 Kudos to all the contributors. Thank you.

#core-editor, #editor, #gutenberg