Core Editor Improvement: Curated experiences with locking APIs & theme.json

These “CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Editor Improvement…” posts (labeled with the #core-editor-improvement 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.)) are a series dedicated to highlighting various new features, improvements, and more from Core Editor related projects. 

A new API was released in WordPress 5.9 that offers more control for locking blocks to build on the current foundation of locking. When combined with the existing template locking 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. and newer tools like theme.json, it will be able to closely curate the editing experience. This post seeks to explore some practical ways you can perhaps apply these locking options to your individual projects to both provide some guardrails and still allow users to make things their own. Keep in mind you could always take this further in either direction, by limiting options more or opening options up!

Let presets and limitations guide the experience

Sometimes you want to allow users to be able to make some choices without getting overwhelmed or getting too far away from the overall design of a site. This might be a situation where you’ve agreed on a color scheme! In this case, you can lean on the various granular options provided by theme.json to limit choice in a way that guides someone in their decision-making while still providing a solid user experience. 

In the quick video below, you’ll see an example where both the options to customize are removed and some presets remain. Specifically, the Post Title 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 Post Date block don’t have options for custom font sizes, line height, font-weight, and colors. They both do still provide a few default options for font sizes and the ability to edit the blocks in other ways, like alignment. Color options are paired down to offer a few simple options in duotone, with the option to set custom colors removed.

Post Title and Post Date blocks with custom presets and limited design options. Here’s a copy of the theme.json used inside a very basic theme generated from these steps.

Protect the important pieces while unleashing creativity 

Since locking can apply to templates and blocks now, you can easily combine those abilities to lock down what you need while still leaving room for customization. For this demonstration, you’ll see a locked template in a custom post typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. that has a “related posts” section. This section is powered by a Query LoopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. block that doesn’t allow users to remove the Post Title and Featured ImageFeatured image A featured image is the main image used on your blog archive page and is pulled when the post or page is shared on social media. The image can be used to display in widget areas on your site or in a summary list of posts. blocks. Within the entire template too, only a few blocks can be removed and moved around within the Query Loop block to allow for some customization while also ensuring someone doesn’t delete the important pieces: the content and key parts of the Query Loop block. The outcome is a customized posts section that enables users to highlight what they want at the bottom of their post, whether it’s their latest posts or posts from a specific categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. (or more).

Locked template preventing Post Title and Featured Image blocks from being removed from a Query Loop. Check out @welcher’s repo to use his plugin that powered this experience.

Preserving patterns without losing too many options

With certain custom patterns, you are sometimes going to have key elements that you don’t want moved or removed, since it might break the integrity of the design. Inspired by this pattern in the Pattern Directory, the following video shows how you can maintain the integrity of a pattern design with specific blocks locked (header and button blocks) using the block locking API introduced in 5.9. Keep in mind that you could also curate the experience even more using the same approaches shown above, both locking patterns and customizing its blocks’ presets and available design options at the same time! Note that even though the experience is locked down in a few ways, it doesn’t hamper the ability to make the pattern your own.

HeaderHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. and Button blocks locked inside a pattern. Here’s a copy of the pattern used to create the above video. 

Take advantage of theme.json while limiting template editor access

If you’re looking for a way to use theme.json in a Classic Theme in some of the ways described above but don’t want to allow access to the template editor, just add remove_theme_support( `block-templates`); to your functions.php file. This is one of the many ways you can have the best of both worlds – presets and supports powered by theme.json without opening up too much access.

Additionally, when you add theme.json to your Classic Theme, some controls for color and typography are enabled by default. This can be managed by using this theme.json setup that disables all features to allow you to opt-in to the ones your theme uses.

What have you tried? How have you approached allowing the right amount of access for different situations?

These are just a few examples of many. Share below what you’ve tried so we can all learn together and so we can help shape the documentation on each of these features around possible real-world applications. On the flip side, if there’s something you’re itching to see possible, share too! Feature requests are always welcome.

Expect more to come in the future, especially when collaborative editing work gets underway for phase 3, and follow along in the meantime in the next iteration of this work in this broader issue.

Props to @welcher for collaborating on this post and @talldanwp for feedback.

#core-editor, #core-editor-improvement