Updates to the HTML API in 6.6

WordPress 6.6 includes a helpful maintenance release to the HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. 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.. Included in this work are a few new features and a major improvement to the usability of the HTML Processor. This continues paced development since WordPress 6.5.

Table of Contents

  1. A spec-compliant text decoder.
    1. An idealized view of an HTML document.
    2. An optimized class for looking up string tokens and their associated mappings.
  2. Features
  3. Bug Fixes

A spec-compliant text decoder.

This may be surprising, but PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher leaves us hanging if we want to properly read the text content of an HTML document. The html_entity_decode() and htmlspecialchars_decode() functions work somewhat well for pure XML documents, but HTML contains more complicated rules for decoding, rules which change depending on whether the text is found inside an attribute value or normal text. These functions default to XML and HTML4 parsing rules and require manually setting the ENT_HTML5 flag on every invocation (for example, HTML5 redefined two of HTML4’s character references), but are still wrong in many cases.

Luckily you shouldn’t need to know about or call the new decoder, developed in Core-61072. It fits into get_modified_text(), further improving the HTML API’s implementation without requiring you to change any of your existing code. With WordPress 6.6 your existing code becomes more reliable for free.

One part of this change you might want to know about is WP_HTML_Decoder::attribute_starts_with(). This new method takes a plaintext prefix and a raw attribute value and indicates if the decoded value starts with the given prefix. This can be invaluable for efficiently detecting strings at the start of an attribute, as some attributes can be extremely large, and if not careful, naive parsers can overlook content hidden behind long slides of zeros.

$html = 'bob&#x00000000000000000003a,';

'bob&#x00000000000000000003a,' === html_entity_decode( $html, ENT_HTML5 );
'bob:,' === WP_Text_Decoder::decode_attribute( $html );
true    === WP_Text_Decoder::attribute_starts_with( $html, 'bob:' );

In the case of extremely long attribute values (for example, when pasting content from cloud document editors which send images as data URIs), the attribute_starts_with() can avoid megabytes of memory overhead and return much quicker than when calling functions which entirely decode the attribute value.

The new text decoder will mostly help ensure that the HTML API remains safe and reliable. There are complicated rules in parsing HTML, so as always, it’s best to leave the low-level work to the HTML API, preferring to call functions like get_attribute() and get_modified_text() directly instead of parsing raw text segments.

An idealized view of an HTML document.

The Tag Processor was initially designed to jump from 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.) to tag, then it was refactored to allow scanning every kind of syntax token in an HTML document. Likewise, the HTML Processor was initially designed to jump from tag to tag, all the while also acknowledging the complex HTML parsing rules. These rules largely exist in the form of a stack machine that tracks which elements are currently open. While the HTML Processor has always maintained this stack, it has never exposed it to calling code.

In WordPress 6.6 the HTML Processor underwent a major internal refactor to report those stack events (when an element opens and when an element closes) rather than when it finds raw text that represents things like tag openers and tag closers. This is a really big change for calling code! Previously, the HTML Processor would track all elements, but only return when a tag or token appeared in an HTML document. For instance, it always knew that <p><p> represents two sibling P elements, but it only presented each opening P tag to calling code. Now, the HTML processor is going to present not only the tags and tokens that exist in the raw HTML text, but also the “virtual nodes” that are implied but not textually present.

$processor = WP_HTML_Processor::create_fragment( '<h1>One</h3><h2>Two<p>Three<p>Four<h3>Five' );
while ( $processor->next_token() ) {
	$depth = $processor->get_current_depth();
    $slash = $processor->is_tag_closer() ? '/' : '';
	echo "{$depth}: {$slash}{$processor->get_token_name()}: {$processor->get_modifiable_text()}\n";
}

Let’s compare the output in WordPress 6.5 against the output in WordPress 6.6.

HTML Processor in WordPress 6.5

H1:
#text: One
/H3:
H2:
#text: Two
P:
#text: Three
P:
#text: Four
H3:
#text: Five

HTML Processor in WordPress 6.6

3: H1:
4: #text: One
2: /H1:
3: H2:
4: #text: Two
4: P:
5: #text: Three
4: /P:
4: P:
5: #text: Four
3: /P:
3: /H2:
3: H3:
4: #text: Five
0: /H3:

With the HTML API in WordPress 6.6, it’s possible to treat an HTML document in the idealized way we often think about it: where every tag has an appropriate corresponding closing tag in the right place, and no tags overlap. In WordPress 6.5, only the opening tags which appeared in the document return from next_tag(), and the </h3> closing tag appears as an H3 closing tag, even though the HTML specification indicates that it closes the already-open H1 element. In WordPress 6.6, every opening tag gets its closer, and the </h3> appears as if it were an </h1>. This is because the HTML Processor is exposing the document structure instead of the raw text.

Two new methods make working with HTML even easier:

  • WP_HTML_Processor->get_current_depth() returns the depth into the HTML structure where the current node is found.
  • WP_HTML_Processor->expects_closer() indicates if the opened node expects a closing tag or if it will close automatically when proceeding to the next token in the document. For example, text nodes and HTML comments and void elements never expect a closer.

With the help of these methods it’s possible to trivially detect when an element opens and closes, because the HTML Processor guarantees a “perfect” view of the structure.

$processor = WP_HTML_Processor( $block_html );
if ( ! $processor->next_tag( 'DIV' ) ) {
	return $block_html;
}

$depth = $processor->get_current_depth();
while ( $processor->get_current_depth() > $depth && $processor->next_token() ) {
	// Everything inside of here is inside the open DIV.
}
if ( ! isset( $processor->get_last_error() ) ) {
	// This is where the DIV closed.
}

An optimized class for looking up string tokens and their associated mappings.

As part of the text decoder work the WP_Token_Map was introduced. This is a handy and efficient utility class for mapping between keys or tokens and their replacements. It’s also handy for efficient set membership; for example, to determine if a given username is found within a set of known usernames.

Read more in the Token Map announcement.

Features

  • The HTML Processor will now return the depth of the current node in the stack of open elements with get_current_depth(). [58191]
  • The HTML Processor now includes expects_closer() to indicate the currently-matched node expect a closing token. For example, no HTML void element expects a closer, no text node expects a closer, and none of the elements treated specially in the HTML API as atomic elements (such as SCRIPT, STYLE, TITLE, or TEXTAREA) expect a closer. [58192]
  • The WP_HTML_Decoder class can take a raw HTML attribute or text value and decode it, assuming that the source and destination are UTF-8. The HTML API now uses this instead of html_entity_decode() for more reliable parsing of HTML text content. [58281]
  • The HTML Processor now visits all real and virtual nodes, not only those which are also present in the text of the HTML, but those which are implied by what’s there or not there. [58304]

Bug Fixes

  • Funky-comments whose contents are only a single character are now properly recognized. Previously the parser would get off track in these situations, consuming text until the next > after the funky comment. [58040]
  • The HTML Processor now respects the class_name argument if passed to next_tag(). Formerly it was overlooking this constraint. [58190]
  • The Tag Processor was incorrectly tracking the position of the last character in some tokens, internally and when bookmarking. While this 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. did not affect the operation of the Tag Processor, it has been fixed so that future code which might rely upon it will work properly. [58233]
  • When subclassing WP_HTML_Processor the ::create_fragment() method will return the subclass instance instead of a WP_HTML_Processor instance. [58365]

Props to @gziolo, @jonsurrell, @juanmaguitar, and @westonruter for reviewing this post and providing helpful feedback.

#6-6, #dev-note, #dev-notes, #dev-notes-6-6, #html-api

Introducing the Token Map

There’s a new data structure coming in WordPress 6.6: the WP_Token_Map, but what is it? The ongoing work in the HTML API required the ability to find named character references like &hellip; in an HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. document, but given that there are 2,231 names this is no easy task. The WP_Token_Map is a purpose-built class designed to take a large set of static string tokens with static string replacements, and then be used as a lookup and replacement mechanism. That’s all very technical, so let’s see it in action and consider how it might be useful to you.

As an important note: you probably don’t need this because it’s an optimized data structure built for lookup with a very large set of tokens. The examples are unrealistically short but are meant only to illustrate the class usage in a readable form. If working with small datasets it’s possibly faster for most purposes to stick with familiar tools like in_array() or associative arrays.

The Token Map, in short, is a new semantic utility meant to answer one simple question: given a string and a byte offset into that string, does the next sequence of bytes match one of a known set of tokens, and if so, what is the replacement for that token? It’s designed as a low-level utility for use in combination with other string parsing logic.

Continue reading

#6-6, #dev-note, #dev-notes, #dev-notes-6-6

Miscellaneous Editor changes in WordPress 6.6

In this post, you will find dev notesdev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. for smaller changes to the editor in WordPress 6.6.


Table of contents

  1. Added wp-block-list class to the list block
  2. New Interactivity API directives
  3. Allow view access of the template REST API endpoint to anyone with the edit_post capability
  4. Unified split logic for writing flow
  5. BlockPopover Component is now public
  6. Add filter to modify the list of post content block types
  7. Global Styles: Filter out color and typography variations
  8. Add custom Aspect Ratio presets through theme.json
  9. Root padding style updates
  10. Added Text alignment block support

Added wp-block-list class to the list 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.

Styling a list block using the Site Editor or theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. also applied the style to other lists, partially or in full. This caused styling conflicts with blocks that use lists internally and with lists in the editor interface.

The problem has been fixed by adding the CSSCSS Cascading Style Sheets. class wp-block-list to the <ul> and <ol> elements of the list block, and only applying the styling to lists with this class name.

If you have relied on the list block styles to style generic lists, you may need to update your CSS.

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/ pull request: #56469

Props to @poena for writing the dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase..

New Interactivity 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. directives

WordPress 6.6 includes three new directives aimed at improving performance:

  • data-wp-on-async
  • data-wp-on-async-document
  • data-wp-on-async-window

These async directives optimize event callbacks by first yielding to the main thread. That way, complex interactions won’t contribute to long tasks, improving the Interaction to Next Paint (INP). You can read more about this approach in Optimize Interaction to Next Paint.

These directives are recommended over the sync ones (data-wp-ondata-wp-on-document, and data-wp-on-window), but you can use them only when you don’t need synchronous access to the event object, specifically if you need to call event.preventDefault()event.stopPropagation(), or event.stopImmediatePropagation(). The directives in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks have been updated to use async where available.

When you must resort to using the non-async directives, the @wordpress/interactivity package now exports a splitTask function which can be used to manually split yield an action to the main thread after calling the synchronous event API. Please see the documentation on async actions for how to implement this.

GitHub pull requests: #61885 and #62665

Props to @cbravobernal and @westonruter for writing the dev note.

Allow view access of the template 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/. endpoint to anyone with the edit_post capability

Before WordPress 6.6 the templates and template-parts REST API endpoints were restricted to only be viewed/edited by anyone with the edit_theme_options capability (Administrators). WordPress 6.6 changes the permission checks to allow any user role with the edit_post capability to view these endpoints. Editing is still restricted to the edit_theme_options capability.

This change is because the post editor now includes the ability to preview a post’s template while editing the post. In WordPress 6.5, this option was limited to administrators only. However, WordPress 6.6 now supports previewing the template for all user roles.

GitHub pull request: #60317

Props to @fabiankaegy for writing the dev note.

Unified split logic for writing flow

RichText’s optional onSplit prop was deprecated and replaced with a block.json support key called splitting. The onSplit prop was only used by a few core blocks (paragraph, heading, list item, and button), so it’s not expected that this affects a lot of third-party blocks.

In any case, when the onSplit is used, splitting will still work but can’t be controlled as granularly as before: the callback won’t be called, and the block will split in a generic way.

GitHub pull request: #54543

Props to @ellatrix for writing the dev note.

BlockPopover Component is now public

The BlockPopover component is now publicly accessible. For more details, you can check the README.

GitHub pull request: #61529

Props to @gigitux for writing the dev note.

Add filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. to modify the list of post content block types

When WordPress renders a post/page’s template at the same time as the content, most template blocks are disabled/locked. However, some blocks, like the Post Title, Post Content, and Post 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., still allow users to edit the content within them. They get rendered in the contentOnly rendering mode.

WordPress 6.6 now adds a filter to modify this list of blocks that should get the contentOnly rendering mode applied when rendered as part of the template preview.

import { addFilter } from '@wordpress/hooks';

function addCustomPostContentBlockTypes( blockTypes ) {
    return [ ...blockTypes, 'namespace/hello-world' ];
}

addFilter(
    'editor.postContentBlockTypes',
    'namespace/add-custom-post-content-block-types',
    addCustomPostContentBlockTypes
);

It is important that only settings that store their data in custom ways are exposed when rendered in this contentOnly mode. An example is a block that stores a subtitle in post metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.. Anything that gets stored to the standard block attributes won’t persist.

GitHub pull request: #60068

Props to @fabiankaegy for writing the dev note.

Global Styles: Filter out color and typography variations

In addition to style variations, WordPress 6.6 adds the ability for themes to create color and typography presets. These are subsets of style variations and give users the ability to replace the color or typography of a site without all the other changes that come in a style variation.

To add color and typography presets to a theme, developers follow the same process as adding style variations, except that each variation must contain only color or typography rules. Any style variations that contain only these rules will be treated as presets and will appear under Global Styles > Typography or Global Styles > Colors > Palette.

Style variations that already conform to this requirement, i.e. they contain only color or typography rules, will automatically be treated in this way. That means these style variations will no longer appear under Global Styles > Browse styles, but instead in the relevant section for either colors or typography.

GitHub pull request: #60220

Props to @scruffian for writing the dev note.

Add custom Aspect Ratio presets through theme.json

WordPress 6.6 adds a new two new properties to the settings.dimensions object in theme.json. settings.dimensions.aspectRatios allows defining your own custom Aspect Ratio presets. These presets will be used by any block that uses the aspectRatio block support. In core that means the Image, Featured Image, and Cover block.

{
    "version": 2,
    "settings": {
        "dimensions": {
            "aspectRatios": [
                {
                     "name": "Square - 1:1",
                     "slug": "square",
                     "ratio": "1"
                 },
                 {
                     "name": "Standard - 4:3",
                     "slug": "4-3",
                     "ratio": "4/3"
                 },
            ]
        }
    }
}

Additionally the settings.dimensions.defaultAspectRatios key allows you to disable the list of core aspect ratio presets.

{
    "version": 2,
    "settings": {
        "dimensions": {
            "defaultAspectRatios": false
        }
    }
}

GitHub pull request: #47271

Props to @fabiankaegy for writing the dev note.

Root padding style updates

Root padding styles have been updated to address inconsistencies in pattern display and make the application of padding more predictable across different sets of markup. It’s now expected that:

  • Padding is applied to the outermost block with constrained layout (this is the layout enabled when “Inner blocks use content width” is set).
  • Padding is applied to all blocks with constrained layout that are full width or wide width.
  • Padding is applied to all blocks with constrained layout inside a full width flow layout (this is the layout enabled when “Inner blocks use content width” is unset) block.
  • Nested full width blocks will always be full width: a full width block inside another full width block will extend to the edges of the viewport.

GitHub pull request: #60715

Props to @isabel_brison for writing the dev note.

Added Text alignment block support

WordPress 6.6 adds new block support for setting the horizontal alignment of text.

This support is controlled by settings.typography.textAlign in theme.json, which defaults to true. To opt-in to this support for a block, add the supports.typography.textAlign field in block.json. For example:

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "gutenpride/my-block",
    "title": "My Block",
    "supports": {
        "typography": {
            "textAlign": true
        }
    }
}

Currently, core blocks do not support textAlign and the Text Alignment UIUI User interface is implemented separately without this block support. In the future, it is planned to gradually migrate core blocks to this support as well, and progress will be tracked in this Github issue: #60763.

The default horizontal alignment style can also be defined via theme.json. For example:

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "styles": {
        "blocks": {
            "core/heading": {
                "typography": {
                    "textAlign": "center"
                }
            }
        }
    }
}

GitHub pull request: #59531

Props to @wildworks for writing the dev note.


Props to @juanmaguitar for review.

#6-6, #dev-note, #dev-notes, #dev-notes-6-6

Internationalization improvements in 6.6

Various internationalization (i18n) improvements are in WordPress 6.6, and this developers note focuses on these.

Enhanced support for only using PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher translationtranslation The process (or result) of changing text, words, and display formatting to support another language. Also see localization, internationalization. files

WordPress 6.5 shipped with a completely new localization system with improved performance, which uses .l10n.php files in addition to .po and .mo files. This system was slightly enhanced in 6.6 to better support scenarios where only these PHP translation files exist, but not the others. This specifically applies to wp_get_installed_translations(), which is used to check which translations are installed, and the Language_Pack_Upgrader for updating translations.

See #60554 for more details.

New lang_dir_for_domain filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.

A new lang_dir_for_domain filter has been added to WP_Textdomain_Registry, allowing plugins to override the determined languages folder when using just-in-time translation loading. This is mostly useful for multilingual plugins.

See #61206 for more details.

Additional context for the load_translation_file filter

The load_translation_file filter was introduced in WordPress 6.5 to support changing the file path when loading translation files, regardless if it’s a PHP or an MO translation file. In 6.6, the localeLocale A locale is a combination of language and regional dialect. Usually locales correspond to countries, as is the case with Portuguese (Portugal) and Portuguese (Brazil). Other examples of locales include Canadian English and U.S. English. is passed as an additional argument to this filter, bringing it more in line with similar i18ni18n Internationalization, or the act of writing and preparing code to be fully translatable into other languages. Also see localization. Often written with a lowercase i so it is not confused with a lowercase L or the numeral 1. Often an acquired skill. filters.

See #61108 for more details.

Props to @audrasjb and @juanmaguitar for review.

#6-6, #dev-note, #dev-notes, #dev-notes-6-6, #i18n

Section Styles

In WordPress 6.6, Section Styles simplify the process of styling individual sections of a webpage by offering users a one-click application of curated styles, eliminating the need for repetitive manual configuration.

Table of Contents

  1. What’s Changed?
  2. Usage
    1. Registration of Block Style Variations
    2. Defining Block Style Variations
      1. Theme.json Partial Files
      2. Programmatically
      3. Via Theme Style Variations (Not Recommended)
  3. Backwards Compatibility
  4. Limitations
  5. What’s Next?
  6. Useful Links

What’s Changed?

Section-based styling has been enabled by extending the existing Block Styles feature (aka 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. style variations) to support styling inner elements and blocks. These enhanced block style variations can even be applied in a nested fashion due to uniform CSS specificity (0-1-0) for Global Styles introduced in WP 6.6.

In addition block style variations can now be:

  • registered across multiple block types at the same time
  • defined via multiple methods; primarily through theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. partials, or by passing a theme.json shaped object in the style’s data given to existing block style registration functions
  • customized via Global Styles (see also current limitations)

Usage

Registration of Block Style Variations

The block style variations that can be defined and manipulated through Global Styles are limited to those that have been registered with the WP_Block_Styles_Registry or via a block type’s styles property, such as Outline for the Button block. If a block style variation has not been registered, any theme.json or global styles data for it will be stripped out.

Any unregistered block style variation defined within a theme.json partial with be automatically registered.

Outlined below are three approaches to registering extended block style variations. The approaches leveraging theme.json definitions will automatically register the block style variation with the WP_Block_Styles_Registry.

Defining Block Style Variations

Outlined below are recommended approaches to registering extended block style variations.

Theme.json Partial Files

With the extension of block style variations to support inner element and block type styles, they essentially are their own theme.json file much like theme style variations. As such, block style variations also reside under a theme’s /styles directory. They are differentiated from theme style variations however by the introduction of a new top-level property called blockTypes. The blockTypes property is an array of block types the block style variation can be applied to.

A new slug property was also added to provide consistency between the different sources that may define block style variations and to decouple the slug from the translatable title property.

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "Variation A",
	"slug": "variation-a",
	"blockTypes": [ "core/group", "core/columns", "core/media-text" ],
	"styles": {
		"color": {
			"background": "#eed8d3",
			"text": "#201819"
		},
		"elements": {
			"heading": {
				"color": {
					"text": "#201819"
				}
			}
		},
		"blocks": {
			"core/group": {
				"color": {
					"background": "#825f58",
					"text": "#eed8d3"
				},
				"elements": {
					"heading": {
						"color": {
							"text": "#eed8d3"
						}
					}
				}
			}
		}
	}
}

Programmatically

Within a theme’s functions.php or 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, a call can be made to register_block_style, passing it an array of block types the variation can be used with as well as a theme.json shaped style object defining the variation’s styles. The style object provided here will be absorbed into the theme’s theme.json data.

register_block_style(
	array( 'core/group', 'core/columns' ),
	array(
		'name'       => 'green',
		'label'      => __( 'Green' ),
		'style_data' => array(
			'color'    => array(
				'background' => '#4f6f52',
				'text'       => '#d2e3c8',
			),
			'blocks'   => array(
				'core/group' => array(
					'color' => array(
						'background' => '#739072',
						'text'       => '#e3eedd',
					),
				),
			),
			'elements' => array(
				'link'   => array(
					'color'  => array(
						'text' => '#ead196',
					),
					':hover' => array(
						'color' => array(
							'text' => '#ebd9b4',
						),
					),
				),
			),
		),
	)
)

This approach has been enabled as a temporary means to facilitate ergonomic definitions of shared block style variations through theme style variations. It is being flagged here for transparency however it will likely be deprecated soon as the Global Styles architecture is updated to address growing complexity and simplify its mental model.

More details on what’s ahead for Global Styles can be found in this issue.

Shared block style variations can be defined via styles.variations. Style data defined under styles.variations will be copied to, and merged with, variation data stored at the block type level for all block types that have a matching variation registered for it.

Additionally, a new translatable title property has been added here to mirror the capabilities of the theme.json partial files outlined above.

The key for the variation correlates to the slug property for theme.json partials. In the example below, this would be variation-a.

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "Theme Style Variation",
	"styles": {
		"variations": {
			"variation-a": {
				"color": {
					"background": "#eed8d3",
					"text": "#201819"
				},
				"elements": {
					"heading": {
						"color": {
							"text": "#201819"
						}
					},
				},
				"blocks": {
					"core/group": {
						"color": {
							"background": "#825f58",
							"text": "#eed8d3"
						},
						"elements": {
							"heading": {
								"color": {
									"text": "#eed8d3"
								}
							}
						}
					}
				}
			},
		}
	}
}

Backwards Compatibility

As the Section Styles feature was implemented via extensions to block style variations rather than as a replacement, existing block style variations will continue to work as before.

Limitations

The following limitations for block style variations in WordPress 6.6 should be noted:

  1. Only root styles, i.e. those that apply directly to the block type the block style variation belongs to, can be configured via Global Styles.
  2. Block style variations cannot redefine or customize inner block style variations.
  3. Block style variations do not support their own custom settings values (yet).
  4. Custom block style variations cannot be applied and previewed within the Style Book.

What’s Next?

The Global Styles UIUI User interface for block style variations will be updated to facilitate the customization of all available styles for inner elements and block types. This includes potentially enhancing the Style Book to support block style variations.

Another future enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. is the possible support for settings per block style variations.

Props to @bph, @oandregal and @juanmaguitar for review

#6-6, #core-editor, #dev-note, #dev-notes, #dev-notes-6-6, #gutenberg

WordPress 6.6 CSS Specificity

One of the goals of WordPress 6.6 is to simplify the process for theme authors to override coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. styles while also maintaining support for Global Styles.

Historically, high CSSCSS Cascading Style Sheets. specificity in core styles has made customization challenging and unpredictable, often requiring complex CSS rules to achieve desired outcomes. Development of the new section styles feature also highlighted a need for uniform CSS specificity to support nesting such styles, facilitating the creation of sophisticated, layered designs.

Uniform 0-1-0 Specificity

WordPress 6.6 introduces several changes aimed at broadly reducing CSS specificity and making it more uniform. These changes generally fall into two categories:

  1. Core 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. Styles
  2. Theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. / Global Styles:

Where adjustments to CSS specificity were required, they were achieved by wrapping the existing selector within :root :where(...).

Core Block Styles

The choice of 0-1-0 specificity greatly reduced the changes required to existing core block styles as blocks targeting their default .wp-block- class already have the desired specificity.

Any blocks with Global Styles support using higher specificity selectors had those selectors wrapped in :root :where(...). This also applied to Block Styles (aka block style variations) and their default styles e.g., .wp-block-image.is-style-rounded img was updated to :root :where(.wp-block-image.is-style-rounded img).

Theme.json / Global Styles:

All block styles, including block style variation styles, output by theme.json and Global Styles are now limited to 0-1-0 specificity. Layout styles, e.g., constrained, flex, flow` etc., have also been limited however depending on the specific layout type and definition the final specificity varies slightly from 0-1-0 so they apply correctly.

Usage

The alignment of 0-1-0 specificity for Global Styles to default block selectors, e.g. .wp-block-, greatly reduces the need for updates. It’s recommended for theme and block authors to double-check their designs if they rely on custom CSS using more complex selectors.

Custom blocks

Authors of custom blocks that opt into global styles and apply default styling via a selector with greater than 0-1-0 specificity, should update those selectors wrapping them in :root :where().

An example could be a custom list block that opts into padding block support but defines default padding via:

ul.wp-block-custom-list {
    padding: 0;
}

Without adjusting the specificity of this rule, any customizations of the block type’s padding in Global Styles would be overridden. Wrapping the selector in :root :where() here would allow the style load order to determine which rule takes precedence.

// Block's stylesheet
:root :where(ul.wp-block-custom-list) { // This is a contrived example and could simply be `.wp-block-custom-list`
    padding: 0;
}

// Global Styles - Loaded after the block styles
:root :where(.wp-block-custom-list) {
    padding: 1em;
}

Block Styles (aka Block Style Variations)

Theme authors customizing Block Styles for a core block will need to limit their style’s specificity, so the block style continues to be configurable via Global Styles.

For example, take a theme that tweaks the border radius for the Image block’s rounded block style:

.wp-block-image.is-style-rounded img {
    border-radius: 2em;
}

Without adjustment, this style would override any customizations made to the Rounded block style within Global Styles.

In this case, the theme can tweak its rounded image style to the following:

//. Theme style
:root :where(.wp-block-image.is-style-rounded img) {
    border-radius: 2em;
}

// Global Styles - Loaded after the block styles
:root :where(.wp-block-image.is-style-rounded img) {
    border-radius: 4px;
}

Zero-Specificity, CSS Layers, and the future

Reducing all core styles to zero specificity was explored before settling on 0-1-0 specificity. Zero specificity unfortunately wasn’t robust in the face of common reset stylesheets and required more widespread changes.

CSS Layers were also evaluated but fell short due to not being able to enforce all styles belonged to a layer. This will change in the future at which point a combination of CSS Layers and zero-specificity can be revisited to further the benefits gained in this initial reduction of CSS specificity.

More history and context can be found in this detailed discussion.

Useful Links

Props to @bph and @juanmaguitar for review

#6-6, #core-editor, #dev-note, #dev-notes, #dev-notes-6-6, #gutenberg

Roster of design tools per block (WordPress 6.6 edition)

Below you find a table that lists all coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks available in the inserter marks in the grid the feature they support in the 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. editor. It’s a basic lookup table that helps developers to find the information quickly.

While this post is released as part of 6.6, the content summarizes changes between 6.1 and 6.6. This is an update of the post published for the 6.1 release and provides a cumulative list of design supports added with the last five WordPress releases.

The features covered are:

  • Align
  • Typography,
  • Color,
  • Dimension,
  • Border,
  • Layout,
  • Gradient,
  • Duotone,
  • Shadow,
  • Background image*
  • Pattern overrides / Block Bindings (PO/BB)

*Note: In WordPress 6.6, the background image tools are only available for Group, Pull quote, Site Logo blocks and as side-wide feature. For Quote, Verse and Post content blocks, it’s only in 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 18.6 and slated for WordPress 6.7.

This post might move to a site that won’t create a horizontal scrollbar.

Props to @annezazu and @juanmaguitar for review.

#6-6, #dev-notes, #dev-notes-6-6, #editor

Site-wide background images in WordPress 6.6

In WordPress 6.6 you can define site-wide background images in theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. and the Site Editor.

A “site-wide” background image is one whose value is set on the body element using the background-image CSSCSS Cascading Style Sheets. property, and, therefore, appears on every page of a site.

An example might be a photo that stretches with the window size, or a repeating pattern background.

To customize how background images appear, WordPress 6.6 supports the following background style properties:

  • background position
  • background size
  • background repeat

Usage

In theme.json

In theme.json, site-wide background images and their properties are defined under "styles.background".

For example, as a single image URI in styles.background.backgroundImage.url:

{
	"styles": {
		"background": {
			"backgroundImage": {
				"url": "<a href="http://path.to/some/image.png">http://path.to/some/image.png</a>"
			},
			"backgroundSize": "cover"
		}
	}
}

For the above, WordPress will automatically wrap the image in the CSS url() function.

styles.background.backgroundImage also accepts string values, which can be any valid CSS value for background-image :

{
	"styles": {
		"background": {
			"backgroundImage": "url(<a href="http://path.to/some/image.png">http://path.to/some/image.png</a>)",
			"backgroundPosition": "center"
		}
	}
}

The above examples use absolute paths to image files. Such files would need to be hosted and maintained.

Most likely, theme developers will want to define background images using paths to a theme’s own assets. This ensures that the theme is self-contained and portable.

Relative paths to theme assets are defined using the file:./ prefix:

{
	"styles": {
		"background": {
			"backgroundImage": {
				"url": "file:./assets/my-theme-background.jpg"
			},
			"backgroundSize": "cover"
		}
	}
}

Paths are resolved on the backend using get_theme_file_uri.

Paths defined this way must be relative to the theme root, regardless of where the theme.json sits in your theme’s directory. This follows an existing pattern for web fonts.

Despite the dot in file:./, the special symbols dot (.) and double dot (..) for directory navigation are not supported in theme.json relative paths. This means, for example, that theme style variation files, which reside under the style/ directory, would use the same path as the theme’s main theme.json.

An issue exists to make the syntax more consistent.

In the Site Editor

Background images can be also be uploaded, and their properties tweaked through the Site Editor’s styles panel.

In WordPress 6.6, background image controls are located under Styles > Layout.

The styles panel navigation is undergoing review however, so in upcoming versions the location may change.

As well as setting new background images, it’s possible to “remove” a theme’s default background image in the Site Editor.

Relative paths to any images in theme.json are resolved on the backend, and are sent in the _links array of Global Styles REST responses. The Editor uses the resolved values to generate theme CSS in the client.

Limitations

In WordPress 6.6, the ability to define background images in theme.json exists only for top-level styles. Top-level styles apply to the body element. An open PR aims to also enable the feature at the 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. level in the next WordPress release.

Work is also underway to:

  • add support for fixed images, using the background-attachment CSS property.
  • avoid conflicts between gradient backgrounds, whose values are currently set to the background property, and background-image. The proposal is that gradient backgrounds will also be set to background-image, and, where both an image and a gradient are defined, their values are merged .

Backwards compatibility

WordPress already has support for custom site-wide background images in the Customizer. The theme.json variant will not affect themes that have enabled this feature.

Background images added in the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. take precedence over those set in theme.json or in the Site Editor.

An ongoing discussion seeks to harmonize the two features.

What’s next

Progress on upcoming work is tracked on Background Image block support follow-up tasks.

Props to @andrewserong and @juanmaguitar for review

#6-6, #core-editor, #dev-note, #dev-notes, #dev-notes-6-6, #gutenberg

Theme.json version 3

The theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. version is incremented whenever a breaking change would need to be made to the 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.. This allows consumers to opt-in to the breaking change by updating the version. Older theme.json versions will always be supported in the latest versions of WordPress.

Upgrading to version 3 is recommended when your minimum supported WordPress version reaches 6.6. See the theme.json reference for more info on migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies..

Why does my code editor tell me to update to version 3?

This is probably because you are using the wrong version of the theme.json schema. The theme.json schema has different versions that correspond to WordPress releases and a trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. version that includes all the latest changes 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/ 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.

The WordPress release versions of the schema follow the pattern: http://schemas.wp.org/wp/x.x/theme.json. Use the version that matches your minimum supported WordPress version. For example, use https://schemas.wp.org/wp/6.5/theme.json if the minimum supported WordPress version for your theme is WordPress 6.5.

If you update the schema reference in your theme.json file to match the version that you are using, then the code editor will be able to tell you which version of theme.json you should be using as well as the features that are available in that version of WordPress.

Breaking changes in version 3

Starting with theme.json version 3 the default behavior for using the same slugs as the default fontSizes and spacingSizes presets has been changed to match how other theme.json presets work: from always overriding the default presets to requiring defaultFontSizes or defaultSpacingSizes to be false in order to override the default presets.

Default font sizes

settings.typography.defaultFontSizes is a new option in theme.json v3. It controls whether the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. provided default settings.typography.fontSizes presets are shown and used.

The default fontSizes presets’ slugs are: small, medium, large, x-large, and xx-large.

  • When defaultFontSizes is true it will show the default font sizes in the editor and prevent the theme from creating presets using the default slugs.
  • When defaultFontSizes is false it will hide the default font sizes in the editor and allow the theme to use the default slugs.

For 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. themes defaultFontSizes is true by default. This is consistent with how other default* options work such as settings.color.defaultPalette.

For classic themes there is a new theme support default-font-sizes which is also true by default. However, unlike block themes, it is set to false when editor-font-sizes theme support is defined.

In theme.json v2, the default font sizes were only shown when theme sizes were not defined. A theme providing font sizes with the same slugs as the defaults would always override the defaults.

To keep behavior similar to v2 with a v3 theme.json:

  • If you do not have any fontSizes defined, defaultFontSizes can be left out or set to true.
  • If you have some fontSizes defined, set defaultFontSizes to false.
--- theme.json v2
+++ theme.json v3
@@ -1,24 +1,25 @@
 {
-	"version": 2,
+	"version": 3,
 	"settings": {
 		"typography": {
+			"defaultFontSizes": false,
 			"fontSizes": [
 				{
 					"name": "Small",
 					"slug": "small",
 					"size": "10px"
 				},
 				{
 					"name": "Medium",
 					"slug": "medium",
 					"size": "14px"
 				},
 				{
 					"name": "Large",
 					"slug": "large",
 					"size": "20px"
 				}
 			]
 		}
 	}
 }

Default spacing sizes

settings.spacing.defaultSpacingSizes is a new option in theme.json v3. It controls whether the core provided default settings.spacing.spacingSizes presets are shown and used.

The default spacingSizes presets’ slugs are: 20, 30, 40, 50, 60, 70, and 80.

  • When defaultSpacingSizes is true it will show the default spacing sizes in the editor and prevent the theme from creating presets using the default slugs.
  • When defaultSpacingSizes is false it will hide the default spacing sizes in the editor and allow the theme to use the default slugs.

defaultSpacingSizes is true by default. This is consistent with how other default* options work such as settings.color.defaultPalette.

For classic themes there is a new theme support default-spacing-sizes which is also true by default. However, unlike block themes, it is set to false when editor-spacing-sizes theme support is defined.

In theme.json v2, the default spacing sizes were only shown when theme sizes were not defined. A theme providing spacing sizes with the same slugs as the defaults would always override the defaults.

Furthermore, there are two settings that can be used to set theme level spacing sizes: spacingSizes and spacingScale. With theme.json v3, presets from both will be merged together and sorted numerically by slug. Presets defined in spacingSizes will override those generated by spacingScale if the slugs match.

In theme.json v2, setting both spacingSizes and spacingScale would only use the values from spacingSizes.

To keep behavior similar to v2 with a v3 theme.json:

  • If you do not have any spacingSizes presets or spacingScale config defined, defaultSpacingSizes can be left out or set to true.
  • If you disabled default spacing sizes by setting spacingScale to { "steps": 0 }, remove the spacingScale config and set defaultSpacingSizes to false.
  • If you defined only one of either spacingScale or spacingSizes for your presets, set defaultSpacingSizes to false.
  • If you defined both spacingScale and spacingSizes, remove the spacingSizes config and set defaultSpacingSizes to false.
--- theme.json v2
+++ theme.json v3
@@ -1,27 +1,25 @@
 {
-	"version": 2,
+	"version": 3,
 	"settings": {
 		"spacing": {
-			"spacingScale": {
-				"steps": 0
-			},
+			"defaultSpacingSizes": false,
 			"spacingSizes": [
 				{
 					"name": "Small",
 					"slug": "40",
 					"size": "1rem"
 				},
 				{
 					"name": "Medium",
 					"slug": "50",
 					"size": "1.5rem"
 				},
 				{
 					"name": "Large",
 					"slug": "60",
 					"size": "2rem"
 				}
 			]
 		}
 	}
 }

Props to @scruffian and @juanmaguitar for assistance with writing and reviewing this post.

#6-6, #dev-note, #dev-notes, #dev-notes-6-6

Social Links block changes in WordPress 6.6

WordPress 6.6 includes some changes affecting both the social link and social links blocks.

HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. changes when using a social links 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. inside a Navigation Block

As of WordPress 6.6, the social links block will be wrapped in a list item (li 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.)) when used in the navigation block. This change fixed an issue where the navigation block produced invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. HTML (the social links block’s ul was nested directly under the navigation block’s ul).

This may affect some themes that depend on the exact nesting of the HTML elements, for example using a selector like .wp-block-navigation__container > .wp-block-social-links.

Here are some examples of how the HTML has changed:

Example of navigation block and social links markup before WordPress 6.6

<ul class="wp-block-navigation__container wp-block-navigation">
  <ul class="wp-block-social-links is-layout-flex wp-block-social-links-is-layout-flex">
  </ul>
</ul>

Example of navigation block and social links markup after WordPress 6.6

<ul class="wp-block-navigation__container wp-block-navigation">
  <li class="wp-block-navigation-item">
    <ul class="wp-block-social-links is-layout-flex wp-block-social-links-is-layout-flex">
    </ul>
  </li>
</ul>

Class name changes to the social link block

As of WordPress 6.6, the social link block will no longer output the components-button class name on its button element within the block editor.

Themes targeting this class name for editor styles should use the existing wp-block-social-link-anchor class instead.

It’s expected that most themes will be doing this already, so for most no change will be required.

Why was this class name present?

The class name was a side-effect of using the Button ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. component from the @wordpress/components package (which can also be referenced as wp.components.Button) within the social link block’s implementation.

Why is this being changed?

  • The components from @wordpress/components are intended for use in the editor’s general interface and have a lot of opinionated CSSCSS Cascading Style Sheets., while the on-canvas part of a block is intended to be styled by a theme and should have minimal CSS.
  • Updates made to styles in the @wordpress/components can have unintended side-effects for the block’s appearance, and can also raise or lower the specificity of the styles above or below what a theme implementer might expect. The change to the block’s implementation leads to more stable and predictable css specificity.
  • There’s no guarantee the styles from @wordpress/components will continue to work in the iframed editor canvas, some CSS variable references in the styles were already not working as expected.
  • The styles that were previously added to the social link block contravene the CSS guidelines used by developers on the WordPress project.

Props to @ramonopoly and @juanmaguitar for review

#6-6, #dev-note, #dev-notes, #dev-notes-6-6