Changes to block editor components and blocks

URLInput component

In previous versions the URLInput component available on the @wordpress/components package and script had the autoFocus prop set to true by default. The main reason for this was that the component was used as the first input in different modals/popovers (link, inserter) but most third-party usage had to explicitly disable that behavior (in blocks for instance). In WordPress 5.6, that prop is false by default. It’s a better choice for most use-cases as auto-focus is often an accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) 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., but consider checking your components if you previously relied on this behavior.

Written by @youknowriad.

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. supports

Following the initial work done for WordPress 5.6 to automatically support style properties for blocks and expose UIUI User interface controls for users, in WordPress 5.7 this mechanism has been expanded to new blocks. Themes may want to review if their styles need to adjust their specificity to accommodate the user choices.

User have now the ability to update the font size of the following blocks via the inspector panel:  core/codecore/listcore/preformattedcore/verse.

Written by @nosolosw.

Empty paragraph changes

In #27995 the default behavior of a published empty paragraph (<p></p>) changed. Before, the 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.) would collapse to zero width and zero height, and be inconsistent with what users saw in the editor. Now an invisible space character is output in empty paragraphs, ensuring linebreaks in the editor correspond to linebreaks on the frontend.
There is a chance of empty paragraphs accidentally published, which will now take up space. If that is the case, it is easily fixed by deleting the empty paragraphs.

Written by @joen.

Cover Block

As of #25171, the cover block now uses an img element instead of using CSSCSS Cascading Style Sheets. background-image for images that are not using fixed or repeated backgrounds. This means that, when rendering the post, a srcset attribute will be applied with the various generated image sizes, saving bandwidth by loading smaller images when possible.

Written by @ajlende.

Button block

The buttons block now provides justification options for its inner button blocks (Justify items left, Justify items center, Justify items right, Space between items).

To implement this feature, the block’s <div> element is now a flexbox container (display: flex)—previously it was display: block. It’s recommended that theme developers check that the buttons block still displays correctly for users for the various alignment and justification options it now provides.

The left and right alignment options for the buttons block have now been deprecated. Users can achieve the same results using a combination of a full alignment and left or right justification. Any buttons blocks that were already added to posts with left and right alignment will be migrated (via the block deprecation system) to use justification in this way when a post is loaded—users should see no change in the visual appearance of buttons.

Written by @talldanwp.

#5-7, #block-editor, #dev-notes

WordPress 5.7 Field Guide

WordPress 5.7 brings you the best features and enhancements to help start 2021 on a positive note! A small and experienced release squad lead the development of new features and resolved defects that benefit users and developers alike.

As a user, you’ll see a refined 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 UIUI User interface, lazy-loading iframes, streamlined migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. from HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. to HTTPSHTTPS HTTPS is an acronym for Hyper Text Transfer Protocol Secure. HTTPS is the secure version of HTTP, the protocol over which data is sent between your browser and the website that you are connected to. The 'S' at the end of HTTPS stands for 'Secure'. It means all communications between your browser and the website are encrypted. This is especially helpful for protecting sensitive data like banking information., standardized colors in WP Adminadmin (and super admin) to a single palette, and a new Robots 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 media search engine visibility setting. As a developer, you’ll see 66 enhancements and feature requests, 127 bug fixes, and more! Of particular interest for developers will be the ongoing cleanup after the update to jQuery 3.5.1 as step 3 on our upgrade process of eventually removing jQuery Migrate.

In this Field GuideField guide The field guide is a type of blogpost published on Make/Core during the release candidate phase of the WordPress release cycle. The field guide generally lists all the dev notes published during the beta cycle. This guide is linked in the about page of the corresponding version of WordPress, in the release post and in the HelpHub version page., you’ll notice what’s relevant to you and your users among the many improvements coming in 5.7.

Administration

Block Editor

The block editor continues its rapid iteration. 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/ version 9.9 is bundled with WordPress 5.7; that’s seven Gutenberg releases (versions 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, and 9.9) all bundled into this release (and as noted in the related Gutenberg handbook page)! Bug fixes and performance improvements from Gutenberg versions 10.0 and 10.1 are also part of 5.7.

The WordPress 5.7 Beta 1 post highlights many new features and improvements to the block editor. There is drag and drop from the inserter into the post canvas, full height alignment for blocks to fill the entire viewport, block variations shown in the block inspector, enhancements to the usability and stability of reusable blocks, vertical alignments and width percentages for buttons block, ability to change size of icons in the Social Icons block, and ability to change the font size in the List and Code blocks.

Included below are details on the new dynamic hook (render_block_{$this->name}) to 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. the content of a single block,

Import/Export

Media

Users

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/.

Robots API

Security

Other Developer Updates

There are even more goodies in 5.7! Read through the 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 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. below to see details on additional changes coming in 5.7 within Login and Registration, and Post Types.

But Wait, There is More!

5.7 offers so much more! Over 127 bugs, 66 enhancements and feature requests, and 29 blessed tasks have been marked as fixed in WordPress 5.7. Here are a few that haven’t been highlighted in the dev notes above:

  • Editor: Support filtering arguments in block type registration from metadata (#52138).
  • Menus: Add sticky footer to avoid duplicate save buttons (#51631).
  • Upgrade/Install: Display version number in update-core.php Re-install Now button (#51774).
  • Upgrade/Install: Add development as accepted value for WP_AUTO_UPDATE_CORE (#51978).

Please, test your code. Fixing issues that your code has with WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. helps you and millions of WordPress sites.

Props to @audrasjb, @jeffpaul for contributing to this guide.

#5-7, #dev-notes, #field-guide

New i18n filters & createI18n() changes

New 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

The JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. i18n functions (__()_x()_n() and _nx()) provide translations of strings for use in your code. The values returned by these functions are now filterable if you need to override them, using the following filters:

  • i18n.gettext
  • i18n.gettext_with_context
  • i18n.ngettext
  • i18n.ngettext_with_context

Note: Text domain-specific versions of these filters are also available, see below for more details.

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. Arguments

The filters are passed the following arguments, in line with their PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher equivalents.

i18n.gettext

function i18nGettextCallback( translation, text, domain ) {
	return translation;
}

i18n.gettext_with_context

function i18nGettextWithContextCallback( translation, text, context, domain ) {
	return translation;
}

i18n.ngettext

function i18nNgettextCallback( translation, single, plural, number, domain ) {
	return translation;
}

i18n.ngettext_with_context

function i18nNgettextWithContextCallback(
	translation,
	single,
	plural,
	number,
	context,
	domain
) {
	return translation;
}

Basic Example

Here is a simple example, using the i18n.gettext filter to override a specific translationtranslation The process (or result) of changing text, words, and display formatting to support another language. Also see localization, internationalization..

// Define our filter callback.
function myPluginGettextFilter( translation, text, domain ) {
	if ( text === 'Add to Reusable blocks' ) {
		return 'Save to MyOrg block library';
	}
	return translation;
}

// Adding the filter
wp.hooks.addFilter(
    'i18n.gettext',
    'my-plugin/override-add-to-reusable-blocks-label',
    myPluginGettextFilter
);

Using ‘text domain’-specific filters

Filters that are specific to the text domain you’re operating on are generally preferred for performance reasons (since your callback will only be run for strings in the relevant text domain).

To attach to a text domain-specific filter append an underscore and the text-domain to the standard filter name. For example, if filtering a string where the text domain is “woocommerce”, you would use one of the following filters:

  • i18n.gettext_woocommerce
  • i18n.gettext_with_context_woocommerce
  • i18n.ngettext_woocommerce
  • i18n.ngettext_with_context_woocommerce

For example:

// Define our filter callback.
function myPluginGettextFilter( translation, text, domain ) {
	if ( text === "You’ve fulfilled all your orders" ) {
		return 'All packed up and ready to go. Good job!';
	}
	return translation;
}

// Adding the filter
wp.hooks.addFilter(
	'i18n.gettext_woocommerce',
	'my-plugin/override-fulfilled-all-orders-text',
	myPluginGettextFilter
);

To apply a filter where the text-domain is undefined (for example WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. strings), then use “default” to construct the filter name.

  • i18n.gettext_default
  • i18n.gettext_with_context_default
  • i18n.ngettext_default
  • i18n.ngettext_with_context_default

Changes to createI18n()

In order to support the filtering of translated strings, the createI18n() method that creates an i18n instance now allows a @wordpress/hooks instance to be passed in.

If you are directly creating an i18n instance yourself by calling createi18n() and you wish to take advantage of filtering, then you will need to update your code to supply a suitable third argument.

Note: If you are using the existing translation functions provided by @wordpress/i18n then you do not need to do anything, the default i18n instance is already set up correctly.

Use standard wp.hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. instance when creating an i18n Instance

import { createI18n } from "@wordpress/i18n";
import "@wordpress/hooks";

const myI18n = createI18n( initialData, initialDomain, wp.hooks );

Use separate hooks instance when creating an i18n Instance

import { createI18n } from "@wordpress/i18n";
import { createHooks } from "@wordpress/hooks";

const myHooks = createHooks();
const myI18n  = createI18n( initialData, initialDomain, myHooks );

This 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 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. was written by @leewillis77.

#5-7, #block-editor, #dev-notes

REST API Changes in WordPress 5.7

The following is a snapshot of some of the changes to the 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/. in WordPress 5.7. For more details, see the full list of closed tickets.

Endpoint Changes

Posts Collection Tax Query Accepts include_children

Introduced in 50157, the REST API posts collection endpoints have been updated to allow a more complex syntax for specifying the tax_query used when querying posts. Each taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies.’s query parameters can now both accept a list of term ids or an object with a terms property. 

Hierarchical taxonomies support an include_children property alongside terms. By default it’s disabled, but if set to true the flag is enabled for the generated tax_query to enable searching for posts that have the given terms or terms that are children of the given terms.

import { addQueryArgs } from '@wordpress/url';
import apiFetch from '@wordpress/api-fetch';

const query = {
	categories: {
		terms: [ 3, 5, 7 ],
		include_children: true,
	},
};
apiFetch( { path: addQueryArgs( '/wp/v2/posts', query ) } );

See #39494 for more details.

Support modified_before and modified_after Query Parameters

Introduced in 50024 the REST API posts collection endpoints now accept modified_before and modified_after query parameters to query posts based on the post modified date instead of the post published date.

import { addQueryArgs } from '@wordpress/url';
import apiFetch from '@wordpress/api-fetch';

const query = {
	modified_after: '2020-12-01T00:00:00Z',
	modified_before: '2020-12-31T23:59:59Z',
};
apiFetch( { path: addQueryArgs( '/wp/v2/posts', query ) } );

As a result of this change, the posts controller now uses a date_query with a separate clause for each date related query parameter instead of a single clause with the before and after flags set.

See #50617 for more details.

Multiple 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. Values for a Key Can Be Deleted by Sending an Empty Array

Previously, to remove all values for a specific meta key, passing null as the value for that meta key was required. After 49966 an empty array can be passed instead.

register_post_meta( 'post', 'my_meta_key', array( 
	'type' => 'string',
	'show_in_rest' => true,
) );
import apiFetch from '@wordpress/api-fetch';

const data = {
	meta: {
		my_meta_key: [],
	}
};
apiFetch( { data, method: 'PUT', path: '/wp/v2/posts/1' } );

See #50790 for more details.

All Themes are Returned via the Themes Controller

As of 49925, the themes endpoint now returns all themes installed on the site, not just the active theme. By default, the endpoint returns both active and inactive themes, but the status query parameter can be used to limit the list to themes with the desired status.

Note, the theme_supports value is only exposed for the active theme. The field is omitted for inactive themes since declaring the supported theme features requires calls to add_theme_support which can only be done if the theme is active.

When querying solely for active themes, the only permission required is to be able to edit posts of any show_in_rest post type. However when querying for inactive themes the switch_themes or manage_network_themes capability is required.

In addition to the changes to the collection endpoint, a new single theme endpoint is available. For example, /wp/v2/themes/twentytwentyone will return information about Twenty Twenty One. For convenience, a link is also added to the currently active theme in the REST API Index if the current user has the requisite permissions. This is the recommended way for applications to discover the currently active theme.

{
  "name": "WordPress Develop",
  "_links": {
    "help": [
      {
        "href": "http://v2.wp-api.org/"
      }
    ],
    "wp:active-theme": [
      {
        "href": "https://wordpress.test/wp-json/wp/v2/themes/twentytwentyone"
      }
    ],
    "curies": [
      {
        "name": "wp",
        "href": "https://api.w.org/{rel}",
        "templated": true
      }
    ]
  }
}

Lastly, the pageper_pagesearch and context query parameters are no longer exposed in the index as they are not supported by this endpoint.

See #50152 for more details.

Image Editor Accepts a List of Modifiers

The /wp/v2/media/<id>/edit endpoint introduced in WordPress 5.5 came with a limited 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. that accepted top-level rotation and crop declarations. In 50124 this API was made more powerful and flexible by accepting an array of modifications in the new modifiers request parameter.

import apiFetch from '@wordpress/api-fetch';

const data = {
	modifiers: [
		{
			type: 'crop',
			args: {
				left  : 0,
				top   : 0,
				width : 80,
				height: 80
			}
		},
		{
			type: 'rotate',
			args: {
				angle: 90
			}
		}
	]
};
apiFetch( { data, method: 'POST', path: '/wp/v2/media/5/edit' } );

The previous query parameters have been marked as deprecated, but will continue to function as normal and do not currently issue deprecation warnings. Clients are encouraged to switch to the new syntax.

To alleviate server resources, whenever possible, clients should simplify redundant modifications before sending the request.

See #52192 for more details.

Parameter Validation

Non-String Enums

In 50010 support for type coercion was added to the enum 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. Schema keyword. Previously, the enum keyword was validated by perform a strict equality check. For string types this is generally ok, but it prevented using alternative types like number when rich type support isn’t available.

Now the same level of type coercion/sanitization is applied when validating enum as all other validation checks. This means that a value of "1" will be accepted for an enum of [ 0, 1 ]. Additionally, object types now properly ignore key order when checking for equality.

See #51911 for more details.

Validation Error Codes

As of 50007, the rest_validate_value_from_schema function now returns specific error codes for each validation failure instead of the generic rest_invalid_param. For instance, if more array items are given than allowed by maxItems, the rest_too_many_itemserror code will be returned.

See #52317 for more details.

Return Detailed Error Information from Request Validation

Previously when a parameter failed validation only the first error message specified in the WP_Error instance was returned to the user. Since 50150 the REST API will now return detailed error information as part of the details error data key.

{
  "code": "rest_invalid_param",
  "message": "Invalid parameter(s): enum_a, enum_b",
  "data": {
    "status": 400,
    "params": {
      "enum_a": "enum_a is not one of a, b, c.",
      "enum_b": "enum_b is not one of d, e, f."
    },
    "details": {
      "enum_a": {
        "code": "rest_not_in_enum",
        "message": "enum_a is not one of a, b, c.",
        "data": {
          "enum": ["a", "b", "c"]
        }
      },
      "enum_b": {
        "code": "rest_not_in_enum",
        "message": "enum_b is not one of d, e, f.",
        "data": {
          "enum": ["d", "e", "f"]
        }
      }
    }
  }
}

See #50617 for more details.

Application Passwords

Fine Grained Capabilities

When the Application Passwords REST API controllers were introduced, the edit_user meta capability was used for all permission checks. As of 50114, the REST API now uses specific meta capabilities for each action type.

  • create_app_password
  • list_app_passwords
  • read_app_password
  • edit_app_password
  • delete_app_password
  • delete_app_passwords

By default, these capabilities all map to edit_user however they can now be customized by using the map_meta_cap 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..

See #51703 for more details.

Introspection Endpoint

50065 introduces a new Application Passwords endpoint for introspecting the app password being currently used for authentication. This endpoint is accessible via /wp/v2/users/me/application-passwords/introspect and will return the same information as the other endpoints. This allows for an application to disambiguate between multiple installations of their application which would all share the same app_id.

Clients can use this information to provide UIUI User interface hints about how the user is authenticated, for instance by displaying the App Passwords’s label. Or when their application is uninstalled by the user, they can automatically clean up after themselves by deleting their App Password.

See #52275 for more details.

Unique Application Names

As of 50030 the Application Passwords API enforces that each App Password has a unique name that cannot consist solely of whitespace characters. Additionally, 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. characters are stripped from the provided application name.

See #51941 for more details.

Props to @flixos90, @desrosj for proofreading.

#5-7, #dev-notes, #rest-api

Inner Blocks API Changes

The majority of 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. authors prefer to keep the focus on the parent block upon insertion in the editor rather than move it to one of the child blocks. Prior to WordPress 5.7, the default behaviour is the latter. In WordPress 5.7, the default behaviour has been changed to be the former.

This simplifies 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. and means that the behaviour of the following APIs has changed:

  • InnerBlock component
  • useInnerBlocksProps hook
  • replaceInnerBlocks action

InnerBlock component and useInnerBlocksProps hook

Both handle the focus on the blocks with templateInsertUpdatesSelection property. If you want to keep the focus on the parent you can omit this property.

If you want to move the focus to the first child block you have to set this property to true.

Example:

<InnerBlocks template={ [ [ 'core/heading' ] ] } templateInsertUpdatesSelection />

const innerBlocksProps = useInnerBlocksProps(
	{ className: 'wp-block-cover__inner-container' },
	{
		template: [ [ 'core/heading' ] ],
		templateInsertUpdatesSelection: true,
	}
);

replaceInnerBlocks action

Reference: https://developer.wordpress.org/block-editor/data/data-core-block-editor/#replaceInnerBlocks

This action handles focus with the third argument updateSelection. If you want to keep the focus on the parent you can skip this argument when calling replaceInnerBlocks.

If you want to move the focus to the first child block you have to pass this argument with true value. Examples:

replaceInnerBlocks( rootClientId, blocks, true )

This 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 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. was written by @ntsekouras and edited by @noisysocks.

#5-7, #block-editor, #dev-notes

Introducing script attributes related functions in WordPress 5.7

WordPress 5.7 adds a handful of new functions that enables passing attributes, such as async or nonce, to both regular and inline script 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.) attributes. This creates a path forward for enabling a Content-Security-Policy (or CSP) in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., plugins, and themes.

These new functions are:

  • wp_get_script_tag() – Formats <script> loader tags and automatically injects a type attribute (if needed).
  • wp_print_script_tag() – Prints a formatted <script> loader tag.
  • wp_print_inline_script_tag() – Prints inline JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. wrapped in a <script> tag.
  • wp_get_inline_script_tag() – Wraps inline JavaScript in a <script> tag.

All of these functions automatically inject the type attribute if the theme has not declared support for HTML5 script tags. Reminder: to declare HTML5 support for script tags, theme authors should use the following declaration in their functions.php file:

add_theme_supports( 'html5', 'script' );

Examples

wp_get_inline_script_tag()

wp_get_inline_script_tag(
	'document.createElement("video");',
	array(
		'id'    => 'create-video-js',
		'async' => true,
	)
);

Returns:

<script id="create-video-js" async>document.createElement("video");</script>

wp_print_inline_script_tag()

Directly prints the value returned by wp_get_inline_script_tag().

wp_get_script_tag()

Setting the attributed value to true just add the attribute without any value. For example:

wp_get_script_tag(
	array(
		'src'      => 'RELATIVE_PATH/FILE.js',
		'nomodule' => true,
	)
);

Returns:

<script src="RELATIVE_PATH/FILE.js" nomodule></script>

Attributes values are automatically escaped using esc_attr but URLs have to be manually escaped using esc_url. For example:

wp_get_script_tag(
     array(
         'id'        => 'jquery-"js"-2.3.4',
         'integrity' => 'sha384-long_hash',
         'src'       => esc_url( 'https://domain.tld/jquery-2.3.4.min.js' ),
     )
 );

Returns:

<script id="jquery-"js"-2.3.4" integrity="sha384-long_hash" src="https://domain.tld/jquery-2.3.4.min.js"></script>

wp_print_script_tag()

Directly prints the value returned by wp_get_script_tag().

Plugins/Themes should not overwrite the nonce attribute of script tags if not specifically responsible for implementing CSP integration.

Filtering script tag attributes in WP 5.7

The wp_script_attributes hook can be used to 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. the attributes to be added in script tags. Attributes are provided in an array containing key-value pairs representing <script> tag attributes.

Please note that only the attribute name is added to the <script> tag for entries with a boolean value, if the value is true.

Attributes are sanitized by the new wp_sanitize_script_attributes function before being printed in the script tag.

Example of use

Adds a nonce attribute to every script tag generated by either wp_get_script_tag or wp_get_inline_script_tag:

function wporg_my_wp_script_attributes( $attr ) {
	if ( ! isset( $attr['nonce'] ) ) {
		$attr['nonce'] = get_my_custom_nonce(); // Random custom function
	}
	return $attr;
);
add_filter( 'wp_script_attributes', 'wporg_my_wp_script_attributes' );

What’s next?

This creates a path forward for enabling a Content-Security-Policy (or CSP) 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. in Core, plugins, and themes.

The next steps to get wp-admin to Strict CSP mode are:

  • Add nonces to all <script> elements. With strict CSP, every <script> element must have a nonce attribute which matches the value specified in the policy. Work started in ticketticket Created for both bug reports and feature development on the bug tracker. #39941.
  • Refactor inline event handlers and javascript: URIs. Inline event handlers (onclick="...", onerror="...") and <a href="javascript:..."> links can be used to run scripts, so an attacker who finds an XSS 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. could inject such HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. and execute malicious JavaScript. CSP requires refactoring those patterns into safer alternatives. Work started in ticket #51407.
  • Refactor calls to JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. APIs incompatible with CSP – includes things like document.write() used to load additional scripts and uses of eval().
  • Serve the Content-Security-Policy 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.. This final step will be the reward at the end of the process, turning on Strict CSP.

A complete post will be published by @adamsilverstein and @enricocarraro on Make/Core to explain these next steps in details.


For reference, see ticket #39941.

Props @johnbillion, @adamsilverstein, @enricocarraro, and @desrosj for proofreading.

#5-7, #dev-notes

Standardization of WP-Admin colors in WordPress 5.7

This is the first part of a larger project in cleaning up WordPress adminadmin (and super admin) CSSCSS Cascading Style Sheets.. In WordPress 5.7, all colors used in the CSS is collapsed to one of 12 blues, greens, reds, and yellows, 13 grays, pure black, and pure white.

This new streamlined color palette collapses all the colors that used to be in the WordPress source code down to seven coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. colors and a range of 56 shades that meet the WCAG 2.0 AA recommended contrast ratio against white or black.

The colors are perceptually uniform from light to dark in each range, which means they start at white and get darker by the same amount with each step. Half the range has a 4.5 or higher contrast ratio against black, and the other half maintains the same contrast against white.

Standardizing on this set of colors will help contributors make consistent, accessible design decisions. Themes and 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 developers are encouraged to use this new color palette, for better consistency between their products and WordPress Core.

Plugin authors that use the existing CSS Core classes should be all set up with the new color palette, as every Core class was updated accordingly.

The full color palette is also available on this CodePen, courtesy of @ryelle.

A PostCSS tool to help plugin authors to switch to the new WP-Admin color palette

@ryelle also published a PostCSS tool which can be used on any CSS file to either replace or create a second CSS file with the 5.7 colors – this is essentially the same process that ran over core, so it should make the same matches in plugin CSS.

This tool uses PostCSS and postcss-palettize-colors to automatically convert any colors in your CSS to the new color palette in WordPress admin. It uses a basic color difference algorithm to convert any color to the closest color in the palette.

To use it, follow the usage guide from PostCSS for your setup. Follow the postcss.config.js in this gist to add the postcss-palettize-colors to your process. Make sure to define the palette colors using paletteOptions.

If you’re not using PostCSS or a build process yet, you can use this tool via the following steps:

  1. Install the dependencies:
    npm i postcss postcss-cli https://github.com/ryelle/postcss-palettize-colors.git
  2. Configure PostCSS – download the postcss.config.js in this gist. This includes the full color palette for wp-admin.
  3. Run PostCSS via command line:
    postcss style.css --replace
  4. Swap out style.css for the path to your CSS file. Note, this will overwrite your CSS file with the new color values.

Alternately, if you need to match colors in both 5.7 and older WordPress: you could use this command to create a separate 5.7-specific stylesheet, and check the version of WordPress to enqueue the correct CSS for each version:

postcss style.css -o style-57.css

See also postcss-cli for more configuration options.

Now that the color palette has been reduced, the next step will be to switch to CSS variables for a better maintainability of WordPress Admin CSS colors.


For reference, see ticketticket Created for both bug reports and feature development on the bug tracker. #49999 and the initial proposal published on Make/Core.

Props @ryelle for proofreading.

#5-7, #dev-notes

Miscellaneous developer focused changes in WordPress 5.7

In WordPress 5.7, a large handful of developer-focused changes were made that deserve to be called out. Let’s take a look!

Post statuses when counting term posts

The _update_post_term_count() function is responsible for querying the database for the number of objects belonging to a given term and updating the count property for that term in the database. However, the publish post status has been hard coded in the database query ever since it was introduced in [5556] (except for when counting attachments, which always use the inherit status).

If a site wants to include posts with a different status in a term’s count, the current solution is to use the edited_term_taxonomy action hook that immediately follows the code updating the term’s count in the database. This can be used to run an additional query to calculate the desired count, and a second query to update the term’s count in the database to reflect this. This works, but results in unnecessary database queries.

Starting in WordPress 5.7, the update_post_term_count_statuses 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. can be used to adjust the list of post statuses used when counting posts for a term.

Example

The following example uses the update_post_term_count_statuses filter to include posts with the future status when counting posts for a category taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. term.

<?php
/**
 * Include posts with the future status in term counts.
 *
 * @param string[]    $post_statuses List of post statuses to include in the count. Default is 'publish'.
 * @param WP_Taxonomy $taxonomy      Current taxonomy object.
 *
 * @return List of post statuses to include in the count.
 */
function myplugin_custom_statuses_in_term_counts( $post_statuses, $taxonomy ) {
	if ( 'category' !== $taxonomy->name ) {
		return $post_statuses;
	}

	if ( ! in_array( 'future', $post_statuses, true ) ) {
		$post_statuses[] = 'future';
	}

	return $post_statuses;
}
add_filter( 'update_post_term_count_statuses', 'myplugin_custom_statuses_in_term_counts', 10, 2 );

For more information on this change, see #38843 on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress..

Overriding the behavior of wp_mail()

The wp_mail() function is one of roughly 40 functions in WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. that are “pluggable”. Pluggable functions are ones that can be completely replaced simply by being defined elsewhere. WordPress wraps its own version of these functions in an if ( ! function_exists( 'function_name' ) ) check, allowing other versions of the function to take precedent without causing a PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher fatal error.

While this approach is sometimes handy, it’s often using a sledgehammer to crack a nut, as most of the desired adjustments are very minor. There are also a lot of problems with defining custom versions of pluggable functions:

  • Unless you are monitoring changes to these functions in each new version of WordPress and merging in changes, the custom versions of a function will not receive bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes, improvements, or compatibility enhancements.
  • Pluggable functions can only be overridden once, and there’s no reliable way to control which custom version of the function is used (whichever is loaded first wins).
  • No assumptions can be made about the code found within a custom versions of pluggable functions. If an action or filter hook is added to WordPress, there’s no guarantee the custom version will ever be updated to include that filter.

In WordPress 5.7, a new filter has been introduced to allow the wp_mail() function to be short-circuited without having to define a custom version of the entire function. When a non-null value is returned to the new pre_wp_mail filter, wp_mail() will assume the email is being processed elsewhere and will return early.

This makes it easier for emails to be handled differently in various environment types (staging, local, etc.), placed in some type of queue system, etc., and prevents unnecessary processing.

For more information on this change, see #35069 on Trac.

Better error handling in the Cron 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.

Since WordPress 5.1, the various WP-Cron related functions (wp_schedule_event(), etc.) now return meaningful return values, but the underlying reason for failure is still not surfaced.

To solve this, a new $wp_error parameter has been added to all functions writing to the cron array. This allows more descriptive and meaningful errors can be returned instead of just false. The functions affected are:

  • wp_schedule_single_event()
  • wp_schedule_event()
  • wp_reschedule_event()
  • wp_unschedule_event()
  • _set_cron_array() (meant for internal use only)

The related filters have also been updated to pass and receive a WP_Error object. The filters affected are:

  • pre_schedule_event
  • pre_reschedule_event
  • pre_unschedule_event

For more information on this change, see #49961 on Trac.

Additional developer treats

  • Two new functions have been introduced to determine whether a post status or post should be viewable more easily: is_post_status_viewable() and is_post_publicly_viewable() (see #49380).
  • Embeds will now work for all posts with public post statuses, even custom ones. Previously, only posts with the publish status could be embedded (see #47574).
  • When WP_DEBUG is set to true, PHP error suppression flags will no longer be applied when calling getimagesize(). This will help identify scenarios where errors occur with the goal of removing all error suppression in the future. In PHP 8.0, the @ operator was updated and no longer suppresses fatal errors. These calls have also been wrapped in the new wp_getimagesize() function to minimize code repetition (see #49889.
  • The redirect_canonical() function has been updated to ensure that users are only redirected to private posts if they are authenticated. All other users will be shown a 404 page at the originally requested URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. This removes the ability to use ID enumeration to discover the slugs of private posts (see #5272).
  • The new wp_image_src_get_dimensions filter has been added to the wp_image_src_get_dimensions() function to allow the dimensions for a file to be corrected whenever WordPress is not able to correctly retrieve them from attachment metadata (see #51865).
  • get_post_status() has been improved to prevent false from being returned for the attachment post type when the parent post has been deleted (see #52326).
  • The bulk edit checkboxes in post list tables are currently tied to the edit_post capability. However, it is sometimes desirable to show or hide these checkboxes in certain scenarios. The new wp_list_table_show_post_checkbox filter added in 5.7 will allow more control over when these checkboxes are visible (see #51291).
  • The Quick/Bulk Edit dropdown fields at the top and bottom of post list tables will no longer produce unexpected behavior. Previously, some list tables ignored the bottom dropdown value entirely, always applying the value selected in the field at the top, and selecting a new value in one dropdown did not synchronize to the other (see #46872).
  • The WP_MEMORY_LIMIT constant has been added to the debug info in Site Health (see #51680).
  • In WordPress 5.7, A new string, filter_by_date, is accepted in the labels array passed to register_post_type(). This label is output for the date filter in list tables and defaults to Filter by date (see #42421).
  • Also in 5.7, a new string, filter_by_item, is accepted in the labels array passed to register_taxonomy(). This label is used for the related filter displayed at the top of list tables, but only for hierarchical taxonomies. The default value is Filter by category (see #42421).
  • sort and args are now officially declared as properties within the WP_Taxonomy class. These have been in use since WordPress 2.5 and 2.6 but were never declared as class properties (see #52142).
  • The PHPMailer library has been updated to the latest version, 6.3.0 (see #52577).

Props for @audrasjb for contributing and @cbringmann, @metalandcoffee for reviewing.

#5-7, #dev-notes

Enhancements to the Import/Export feature in WordPress 5.7

In WordPress 5.7, two main changes affected the WordPress built-in import/export feature.

A new export specific 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. for post title

WP 5.7 introduces creates an export-specific filter for post titles.

Since WordPress 2.5 and 2.6, post_content and post_excerpt have both had export-specific filters: the_content_export, and the_excerpt_export, respectively. post_title, however, has used the_title_rss, which behaves differently in two important ways:

  • It strips HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. tags from the string
  • It HTML-encodes the title string

These behaviors are not ideal for exports, since it changes the post title, resulting in data loss in export files, and incorrect post duplicate matching on import. This changes replaces the usage of the_title_rss with a new filter, the_title_export. The new filter is intended to be used in the same as the_content_export and the_excerpt_export.

Usage example: add a prefix to exported posts titles:

function wporg_edit_exported_title( $post_title ) {
	$post_title = sprintf(
		/* Translators: the post title. */
		__( '[IMPORTED] %s', 'text-domain' ),
		$post_title
	);
	return $post_title;
}
add_filter( 'the_title_export', 'wporg_edit_exported_title', 10 );

For reference, see ticketticket Created for both bug reports and feature development on the bug tracker. #52250.

Add the date each post was last modified in export files

WP 5.7 introduces post_modified and post_modified_gmt fields to the generated WXR export file.

This allows for more flexibility when determining which version of a post is the latest one, and makes it possible to implement import logic involving updating and adding revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. to existing posts or pages.

Here is a sample of the new structure of RSS feeds:

<item>
	<title><?php echo $title; ?></title>
	<link><?php the_permalink_rss(); ?></link>
	<pubDate><?php echo mysql2date( 'D, d M Y H:i:s +0000', get_post_time( 'Y-m-d H:i:s', true ), false ); ?></pubDate>
	<dc:creator><?php echo wxr_cdata( get_the_author_meta( 'login' ) ); ?></dc:creator>
	<guid isPermaLink="false"><?php the_guid(); ?></guid>
	<description></description>
	<content:encoded><?php echo $content; ?></content:encoded>
	<excerpt:encoded><?php echo $excerpt; ?></excerpt:encoded>
	<wp:post_id><?php echo (int) $post->ID; ?></wp:post_id>
	<wp:post_date><?php echo wxr_cdata( $post->post_date ); ?></wp:post_date>
	<wp:post_date_gmt><?php echo wxr_cdata( $post->post_date_gmt ); ?></wp:post_date_gmt>
	<wp:post_modified><?php echo wxr_cdata( $post->post_modified ); ?></wp:post_modified>
	<wp:post_modified_gmt><?php echo wxr_cdata( $post->post_modified_gmt ); ?></wp:post_modified_gmt>
	<wp:comment_status><?php echo wxr_cdata( $post->comment_status ); ?></wp:comment_status>
	<wp:ping_status><?php echo wxr_cdata( $post->ping_status ); ?></wp:ping_status>
	<wp:post_name><?php echo wxr_cdata( $post->post_name ); ?></wp:post_name>
	<wp:status><?php echo wxr_cdata( $post->post_status ); ?></wp:status>
	<wp:post_parent><?php echo (int) $post->post_parent; ?></wp:post_parent>
	<wp:menu_order><?php echo (int) $post->menu_order; ?></wp:menu_order>
	<wp:post_type><?php echo wxr_cdata( $post->post_type ); ?></wp:post_type>
	<wp:post_password><?php echo wxr_cdata( $post->post_password ); ?></wp:post_password>
	<wp:is_sticky><?php echo (int) $is_sticky; ?></wp:is_sticky>
</item>

For reference, see ticket #52180.

Better performance for menu items imports

The wp_update_nav_menu_item() function now makes use of wp_resolve_post_date() when updating menu items. This allows a menu item’s post_date to be set to a specific value instead of just “now”. This allows the WordPress Importer to perform faster, more accurate duplicate checks.

For reference, see #52189.


Props @desrosj and @chaton666 for proofreading.

#5-7, #dev-notes

Changes in @wordpress/data API

As of #26655, it is now possible to pass a store definition instead of the string when referencing a given store registered with @wordpress/data 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 change impacts mostly 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/ project. It is fully backward compatible, so 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 and theme authors can continue using hardcoded names when referencing data stores.

The store registration has now two new methods register that takes the store definition as a param to register a store. There is also a new helper method createReduxStore that creates a data store definition for the provided Redux store options containing properties describing reducer, actions, selectors, controls, and resolvers.

Example of the store usage before this change:

registerStore( 'my-store', {
    reducer: ( state = 'OK' ) => state,
    selectors: {
        getValue: ( state ) => state,
    },
} );
import { select } from '@wordpress/data';

const blockTypes = select( 'my-store' ).getBlockTypes();

Example of the new recommended usage:

import { createReduxStore } from '@wordpress/data';

export const store = createReduxStore( 'my-store', {
    reducer: ( state = 'OK' ) => state,
    selectors: {
        getValue: ( state ) => state,
    },
} );

register( store ); 
import { select } from '@wordpress/data';
import { store as myStore } from './store';

const blockTypes = select( myStore ). getValue();

This new capability enables additional static analysis in the Gutenberg project that improve code quality. We can ensure now that all stores used in a given module are always properly defined as dependencies. In effect, it provides the correct loading order of JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. files. It also opens possibilities for new store implementations that share the same high-level API.

Finally, there is a new optional ESLint rule @wordpress/data-no-store-string-literals available in @wordpress/eslint-plugin package. It ensures that string literals aren’t used for accessing @wordpress/data stores when using API methods. The store definition is promoted as the preferred way of referencing registered stores.

This 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 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. was written by @gziolo.

#5-7, #block-editor, #dev-notes