Dev Chat Summary, August 5th, 2020

This post summarizes the weekly devchat meeting from August 5th, 2020 hosted by @whyisjake (Agenda / Slack Archive).

Recent Dev-Notes

The group didn’t discuss these, but @whyisjake added them to the announcements. Have an opinion? Add your thoughts to the comments:

Upcoming Releases

  • jQuery Migrate Status
    • @whyisjake opened the chat with a conversation about the planned changes related to jQuery Migrate in 5.5. @azaozz has published working roadmap document about it.
    • Currently, the plan is to release WordPress 5.5 as is with the first step in the roadmap in place (disabling jQuery Migrate by default for all installs).
    • @clorith has been working on a plugin, now in development, that will re-enable jQuery Migrate and make any notices thrown more visible to site owners so that they can open support tickets with the appropriate 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.

Component check-in and status updates

Open Floor

The next CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. dev chat will be held on Wednesday, August 9, 2020 @ 20:00 UTC.

These meetings are held in the #core channel in the Making WordPress Core Slack instance.

Props @marybaum and @desrosj for review.

#5-5, #dev-chat

Allow post boxes and metaboxes to be reordered by using the keyboard

Before WordPress 5.5, it was possible to rearrange widgets on the Dashboard and metaboxes on post editing pages (with GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ disabled) using only a pointing device, such as the mouse. This was causing 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) issues, since it was not possible to perform the same actions with the keyboard. It was also challenging to perform these actions on touch screens.

WordPress 5.5 solves this by adding new controls and functionalities to allow reordering the boxes with the keyboard. There are also improvements to facilitate reordering of boxes on touch screens.

Before WordPress 5.5: There were no controls to move and reorder Dashboard widgets
Before WordPress 5.5: There were no controls to move and reorder boxes
WordPress 5.5 adds "up" and "down" controls to reorder boxes easily with mouse, touch screens and keyboard
WordPress 5.5 added “up” and “down” controls to reorder boxes easily with mouse, touch screens and keyboard
Reordering boxes with keyboard in WordPress 5.5

In addition to this, sound messages are sent to the live region of the administration ARIA to inform screen reader users of the result of the rearrangement action.

For 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

If you develop plugins that modify the “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.” of the post boxes, you will need to make sure you adjust your code accordingly.

Here is an example:

In WooCommerce “Edit order” pages, some WooCommerce CSSCSS Cascading Style Sheets. hide the header and the handlediv button of some metaboxes using display: none. No feature is broken and the metaboxMetabox A post metabox is a draggable box shown on the post editing screen. Its purpose is to allow the user to select or enter information in addition to the main post content. This information should be related to the post in some way. is sortable as expected because it lives in an element with the CSS class meta-box-sortables.

Plugins can customize the basic metaboxes in this way, but they should also be prepared to adjust their customizations if necessary.

Related ticketticket Created for both bug reports and feature development on the bug tracker. on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.: #39074.

Props to @afercia for technical review and @audrasjb for proofread.

#5-5, #accessibility, #dev-notes

More support for JavaScript i18n in WordPress 5.5

In WordPress 5.5, several legacy 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/. localization variables have been removed in wp-admin in favor of using the modern form wp.i18n.__().

The i18n package was introduced with WordPress 5.0 to facilitate JavaScript and dynamic UIs translationtranslation The process (or result) of changing text, words, and display formatting to support another language. Also see localization, internationalization.. It was therefore possible to use it instead of other functions used for localization as wp_localize_script().

Several interfaces in wp-adminadmin (and super admin) already use the functions and utilities provided by 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. for translatable strings. With WordPress 5.5, many others are now adopting this new approach.

Here are the related tickets for these changes on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.: #50235, #50525, #50526, #50527, #50535, #50553, #50576, #50577, #50578, #50579, #50596, #50597, #50599, #50601, #50602, #50603, #50604, #50605.

For developers

If you develop WordPress themes or extensions some previously globally accessible localization variables could stop working and cause breaks in your code.

You can see how to use the functions and utilities of i18n package in this p2 post.

Props to @loicblascos for raising this note topic and @francina and @johnbillion for review.

#5-5, #dev-notes, #i18n

New editor preview options

You can now preview editor content in different screen sizes. Replacing the old preview button there is now a dropdown with “Desktop”, “Tablet” and “Mobile” sizes, as well as the previous front end preview option.

The new preview options currently only work on medium to large screens (>= 600px). In the future, there may be a way to preview large screens on a phone.

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

If you’re a block developer and would like to have responsive styles for your blocks in the editor, use the #start-resizable-editor-section and#end-resizable-editor-section markers to define responsive styles. Styles between these markers will be picked up by the editor and render correctly when it is resized. As an example, this is what your styles would look like:

#start-resizable-editor-section {
    display: none;
}

/* add all responsive styles here */

#end-resizable-editor-section {
    display: none;
}

Currently, we aren’t able to manipulate theme editor styles because they are loaded inline in a <style> 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.), instead of a separate stylesheet.

Related pull request on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can 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/ for this feature: https://github.com/WordPress/gutenberg/pull/19082.

#5-5, #dev-notes, #editor, #gutenberg

Registering default values for meta data

With WordPress 5.5, the register_meta() functions ( including register_post_meta() ) now support registering default values. Previously it was only possible to register default values for 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/. schema like this:

register_meta(
     'post',
     'greeting',
     array(
         'single'       => true,
         'type'         => 'string',
         'show_in_rest' => array(
             'schema' => array(
                 'type'  => 'string',
                 'default' => 'hello',
             ),
         ),
     )
 );

However, this would only be applied to calls made from within the REST API – calls to get_post_meta() would not use this default value. Now it is possible to pass in a default value that will be applied to all calls to any of the 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. functions, like this:

register_meta(
     'post',
     'greeting',
     array(
         'single'       => true,
         'type'         => 'string',
         'default'      => 'hello',
         'show_in_rest' => array(
             'schema' => array(
                 'type'  => 'string',
             ),
         ),
     )
 );

This brings register_meta() inline with register_setting() where it has been possible to register default values for options since WordPress 4.7.

Default values can also be paired with object sub types (introduced in WordPress 4.9.8) to limit the scope of a default value. An example of this might be if 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 registers a custom post typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. of product. A developer could register a default value that would only apply to the post of type product.

register_post_meta(
     'product',
     'price',
     array(
         'single'       => true,
         'type'         => 'string',
         'default'      => '0.00',
     )
 );

It is worth noting that registering a default value to a custom post type like this may have some performance overhead. To determine which post type the current post ID is, it has to load that object. See get_object_subtype for more detail. In most cases, the meta and main objects are loaded at the same time (like when using WP_Query) but if your code is doing something other than just loading meta data, it may now load the main object type too.

Non-Single Metadata

It is also possible to register not-single default values like this:

register_post_meta(
     'product',
     'price',
     array(
         'single'       => false,
         'type'         => 'string',
         'default'      => '0.00',
     )
 );

When requesting multiple values, like this:

$result = get_post_meta( 123, 'price', false );

The above code will return a numeric array with 0.00, as the first value.

Validation

When registering a default meta value the data must match the type provided. The following example will trigger a _doing_it_wrong notice as hello is not an integer.

register_meta(
     'post',
     'greeting',
     array(
         'single'       => true,
         'type'         => 'integer',
         'default'      => 'hello',
     )
 );

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

If you desire to do some really custom with default meta values, there is now a filter:

$value = apply_filters( "default_{$meta_type}_metadata", $value, $object_id, $meta_key, $single, $meta_type );

This is a dynamic filter, requiring you to add the meta type. This is an example of it’s use:

function add_my_meta_value( $value, $object_id, $meta_key, $single ){
	if( 'price' === $meta_key ) {
		if ( ! $single ) {
	   		$value = array( '0.99' );
		} else {
			$value = '0.99';
		}
	}
}
add_filter( 'default_post_metadata', 'add_my_meta_value', 10, 4 );

New functions

To make this functionality possible there are two new functions added to WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.:

  • get_metadata_raw()
  • get_metadata_default()

Now the get_metadata() function calls get_metadata_raw() and if the value is null, calls get_metadata_default(). So calling get_metadata() no longer gets the raw value, that is what get_metadata_raw() is now intended for.

More detail of the history of this change can be found in the original tracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. #43941.

Props @timothyblynjacobs, @jjj and @justinahinon for reviewing prior to publish.

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

Dev Chat Summary, July 29th, 2020

@whyisjake hosted this agenda and @marybaum and @audrasjb edited.

Recent Dev-Notes

The group didn’t discuss these, but @whyisjake added them to the announcements. Have an opinion? Add your thoughts to the comments:

Upcoming Releases

  • WordPress 5.5 RC was released July 28th
    • @whyisjake mentioned that work is underway to only show the auto-update UIUI User interface for themes that support updates.
    • Testing changeset [48688] will determine whether it lands in 5.5.
    • @pbiron confirmed there will be a 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. on these changes.
  • WordPress 5.5 RC 2 scheduled for August 4th
    • An extra RC is possible if the UI changes much for themes.
  • @desrosj and @justinahinon completed a docs scrub on July 29th
  • Tickets and issues of concern:
    • @Carike seeks feedback on how to streamline 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/ dev updates with any ticketticket Created for both bug reports and feature development on the bug tracker. on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress..
    • @pbiron added a new patch to ticket #48507 for 5.5 RC 1.
    • @jeffpaul shared process on patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. reviews of release candidates

Component check-in and status updates

Open Floor

Props @jeffpaul for proofreading.

#5-5, #dev-chat

WordPress 5.5 Field Guide


Update on 08 August 2020: Added “CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Editor 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) Improvements” and “New editor preview options”

Update on 06 August 2020: Added the “Registering default values for 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. data” section.


WordPress 5.5 is shaping up to be “the best version of WordPress ever“!

As a user, you’ll see automatic updates for plugins and themes, a 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. directory, XML sitemaps, lazy-loading images, and the latest and greatest featured in the block editor. As a developer, you’ll see 157 enhancements and feature requests, 307 bug fixes, and more! Of course, all those improvements mean code changes, which could in turn require you to make updates to your site, 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, or theme.

So take a look through 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., and see what’s relevant to you and your users, among the many improvements coming in 5.5…

Accessibility

Of the 34 various accessibility updates, Theme developers are highly encouraged to utilize the opt-in navigation-widgets feature to improve the semantics and accessibility of widgets with lists of links in themes. When support is declared, all default widgets included in WordPress Core that produce lists of links will be output wrapped in the <nav> element and an aria-label attribute is automatically generated based on the widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user.’s title field and added to the nav element. Read the following 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. to learn which widgets are affected, how to declare support, and other details behind this update.

Auto-updates (Security)

On the 6 security updates, the new core-auto-updates team worked on introducing a new UIUI User interface to manage Plugins and Themes automatic updates. Learn more about controlling this new UI, email notifications, site health screen, and if you’re a plugin developer, ensure your plugin is ready for the new auto-updates system.

Customize

Of the seven updates to the Customize component, Theme developers will want to take notice of changes to how the custom logo is linked on the homepage and a new logo image attributes 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..

Block Editor

The block editor has continued its rapid iteration since WordPress 5.0. Now it has 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 8.5 bundled with WordPress 5.5; that’s ten releases all bundled into this release (versions 7.6, 7.7, 7.8, 7.9, 8.0, 8.1, 8.2, 8.3, 8.4, and 8.5)! Bug fixes and performance improvements from Gutenberg versions 8.6 and 8.7 will also be part of 5.5.

The WordPress 5.5 Beta 1 post highlights a lot of new features and improvements across these releases, though you’ll also want to note inline image editing, block patterns, device previews, block directory, among many other improvements bringing forth a better, smoother editing experience.

Below you’ll find details on updates to various Block APIs, how to register a block pattern, how themes can opt-out from core bundled block patterns, image editing via 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/. and how edited images are saved as a new attachment, custom line heights and custom units as new block tools, changes to the BlockPreview, URLInput, and Popover ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. components, and how to add your block plugin directly to the Block Directory.

Media

There are 26 updates to the Media component, including the core merge of the Lazy Loading featured plugin that now sees images lazy-loaded by default. Read on to learn more about reduced layout shifting as a prerequisite, how to customize lazy-loading, and browser compatibility.

REST API

36 updates to the REST API with particular interest pointed to new and modified endpoints, parameter and 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 changes, discoverable REST resource links, new 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. functions, CORS changes, the new register_theme_feature() function and its arguments, and other miscellaneous updates.

Options, Meta APIs

Sitemaps

The new Sitemaps component and its 13 items in WordPress 5.5 comes from the XML sitemaps feature project merge. Read on to learn more about adding custom sitemaps, removing certain sitemaps, adding additional tags to sitemap entries, excluding a single post from the sitemap, completely disabling sitemaps functionality, and the new classes, functions, 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., and filters.

Themes

This release sees the introduction of a Theme Field Guide! You’ll find a few theme related changes that were not large enough for their own developer note included here, as well as links to the other 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. above that are theme related.

Other Developer Updates

There are even more goodies in 5.5! Here are a few:

  • Update a plugin or theme by uploading a ZIP file
  • Default categories for custom post types
  • Support for default terms in custom taxonomies
  • Enforcing a default comment_type value
  • Updates to the PHPMailer, SimplePie, Twemoji, Masonry, imagesLoaded, getID3, Moment.js, and clipboard.js external libraries
  • Template loading functions now allow additional arguments to be passed through to the matched template file using a new $args parameter
  • WordPress now attempts to invalidate PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 files when Core, Plugins, or Themes are updated via wp_opcache_invalidate()
  • How theme authors can filter archive page headings
  • The new createInterpolateElement and wp_get_environment_type() functions
  • Better control of the redirect_guess_404_permalink() function
  • New CSSCSS Cascading Style Sheets. styles for buttons with disabled state
  • The final update to the Dashicons icon font as focus now shifts to the new Icon component
  • Various PHP-related improvements and changes
  • So much much more!

Read through the dev notes below to see details on all these changes coming in 5.5.

But Wait, There is More!

Over 307 bugs, 157 enhancements and feature requests, and 31 blessed tasks have been marked as fixed in WordPress 5.5. Some additional ones to highlight include:

  • Comments: The proper comment counts and page numbers for unapproved comments are now calculated correctly. (#8973)
  • Comments: get_comment_count() now returns integers for all counts of all statuses returned (#48093)
  • Customize: 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. UI is now themed correctly based on the selected adminadmin (and super admin) theme (#50547)
  • Internationalization: Domain-specific 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. filter hooks have been added. (#49518)
  • Media: sanitize_file_name() now correctly sanitizes filenames, removing accents (#22363)
  • Menus: Menu Settings are now provided when creating a new menu (#44286)
  • Menus: Empty 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. terms now show up in searches when adding items to menus (#45298)
  • Widgets: Widgets with custom image sizes now correctly display captions (#50160)

Please, test your code. Fixing issues helps you and helps millions of WordPress sites.

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

#5-5, #field-guide

Recommended usage of the Updates API to support the auto-updates UI for Plugins and Themes in WordPress 5.5

This is an addendum to Controlling Plugin and Theme auto-updates UI in WordPress 5.5.

Edit 8/05/2020: An error in the example of populating no_updates for plugins has been corrected: in site_transient_update_plugins the value of response and no_update are arrays of objects; whereas in site_transient_update_themes, they are arrays of arrays. props @afragen. @pbiron

By default, the enable and disable auto-updates action links for plugins (detailed in the previous developer note) will only appear when the WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Updates 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. (available since version 3.7.0) is supported.

All plugins that are hosted in the WordPress Plugin Directory and themes that are hosted in the WordPress Theme Directory already fully support the Updates API and require no changes.

Plugins and themes that are hosted elsewhere (such as premium or “private” plugins) can also support the Updates API with a little bit of code.

Though there is currently no one “official” way for such plugins to support the Updates API, this note offers recommendations for how developers can provide enough support for the auto-updates UIUI User interface to work for their plugins.

Filtering the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party update transient

The responses received from querying the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ Updates API are stored in the update_plugins site transient. There are several existing filters that developers can use to add information about the availability or lack of available updates for a specific plugin that is not hosted in the WordPress Plugin Directory to that transient. The most common are:

Using pre_set_site_transient_update_plugins, for example, developers can do:

<?php
function myplugin_pre_set_site_transient_update_plugins( $transient ) {
	// Query premium/private repo for updates.
	$update = myplugin_check_for_updates( 'my-plugin' );
	if ( $update ) {
		// Update is available.
		// $update should be an array containing all of the fields in $item below.
		$transient->response['my-plugin/my-plugin.php'] = $update;
	} else {
		// No update is available.
		$item = (object) array(
			'id'            => 'my-plugin/my-plugin.php',
			'slug'          => 'my-plugin',
			'plugin'        => 'my-plugin/my-plugin.php',
			'new_version'   => $myplugin_current_version,
			'url'           => '',
			'package'       => '',
			'icons'         => array(),
			'banners'       => array(),
			'banners_rtl'   => array(),
			'tested'        => '',
			'requires_php'  => '',
			'compatibility' => new stdClass(),
		);
		// Adding the "mock" item to the `no_update` property is required
		// for the enable/disable auto-updates links to correctly appear in UI.
		$transient->no_update['my-plugin/my-plugin.php'] = $item;
	}

	return $transient;
}

add_filter( 'pre_set_site_transient_update_plugins', 'myplugin_pre_set_site_transient_update_plugins' );

Developers that have already been using the Updates API to offer updates for their plugins that are not hosted in the WordPress Plugins Directory have already been populating the response property for their plugin.

The no_update property is a requirement for the auto-update UI to work correctly for externally hosted plugins.

Some are already populating the no_update for their plugin. Any that are not should update their code accordingly for the best user experience.

Filtering the theme update transient

For themes, the responses received from querying the WordPress.org Updates API are stored in the update_themes site transient. The filters used to modify the values of these transients are similar to the ones used for plugins but slightly different:

Using pre_set_site_transient_update_themes, for example, developers of a theme hosted in a different location can do:

<?php
function mytheme_pre_set_site_transient_update_themes( $transient ) {
	// Query premium/private repo for updates.
	$update = mytheme_check_for_updates( 'my-theme' );
	if ( $update ) {
		// Update is available.
		// $update should be an array containing all of the fields in $item below.
		$transient->response['my-theme'] = $update;
	} else {
		// No update is available.
		$item = array(
			'theme'        => 'my-theme',
			'new_version'  => $mytheme_current_version,
			'url'          => '',
			'package'      => '',
			'requires'     => '',
			'requires_php' => '',
		);
		// Adding the "mock" item to the `no_update` property is required
		// for the enable/disable auto-updates links to correctly appear in UI.
		$transient->no_update['my-theme'] = $item;
	}

	return $transient;
}

add_filter( 'pre_set_site_transient_update_themes', 'mytheme_pre_set_site_transient_update_themes' );

The no_update property was only recently added to API responses for theme update queries, and like plugins, the no_update property is a requirement for the auto-update UI to work correctly for externally hosted themes.

Props @desrosj and @audrasjb for review prior to publishing.

#5-5, #auto-update, #auto-updates, #dev-notes, #feature-autoupdates

Themes field guide: WordPress 5.5

WordPress 5.5 will contain several changes to existing features that will directly impact themes. This theme specific 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. details a few changes and also links several that were previously published separately.

Theme compatibility checks

In WordPress 5.4, support was added to the style.css file for the RequiresWP (Requires at least) and RequiresPHP (Requires PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20) file headers (see #44592). These headers allow theme authors to define the minimum versions of WordPress and PHP required to reliably run their themes. Though support was added for these headers, they were not yet used in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

In 5.5, the values provided by these headers will now be respected. Users will be unable to install, activate, or preview themes when a site does not meet the specified requirements.

Please ensure your theme contains these headers, and that the values are up to date and accurate.

For more information, check out the related tickets on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. (#48491, #48507, #49334, #49653).

Adding icons in Twenty Twenty

The Twenty Twenty default theme includes a feature that displays SVG icons to a page from a defined list if available icons. Additionally, there is an array that maps icon names to specific social website URLs. When a menu is assigned to the social menu location, the link text is automatically replaced with logo icons for each link (should one match the predefined list of supported icons).

Continuing to add requested icons (there are a small handful every few months) is not sustainable. Because of this, no new requests for icons will be considered for the Twenty Twenty theme. However, filters have been added in the theme to allow additional icons to be added as desired.

  • The twentytwenty_svg_icons_{$group} 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. allows new SVG icon tags to be added to a group’s list of icons. The default groups are ui (twentytwenty_svg_icons_ui), and social (twentytwenty_svg_icons_social). Custom groups could be added if needed.
  • The twentytwenty_social_icons_map filter allows new services to be added to the list of site links that are automatically replaced with icons in a menu assigned to the social menu location.
  • And finally, the new twentytwenty_svg_icon_color filter allows the color of the icon being displayed to be changed.

For example, say you wish to replace the calendar icon provided by default with your own.

<?php
function mychildtheme_twentytwenty_svg_icons_ui( $icons ) {
	$icons['calendar'] = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path fill-rule="evenodd" d="M6.75 0a.75.75 0 01.75.75V3h9V.75a.75.75 0 011.5 0V3h2.75c.966 0 1.75.784 1.75 1.75v16a1.75 1.75 0 01-1.75 1.75H3.25a1.75 1.75 0 01-1.75-1.75v-16C1.5 3.784 2.284 3 3.25 3H6V.75A.75.75 0 016.75 0zm-3.5 4.5a.25.25 0 00-.25.25V8h18V4.75a.25.25 0 00-.25-.25H3.25zM21 9.5H3v11.25c0 .138.112.25.25.25h17.5a.25.25 0 00.25-.25V9.5z"></path></svg>';

	return $icons;
}
add_filter( 'twentytwenty_svg_icons_ui', 'mychildtheme_twentytwenty_svg_icons_ui' );

As a second example, say you have a separate photography blogblog (versus network, site) and would like to add a link in your social navigation.

<?php
function mychildtheme_twentytwenty_social_icons_map( $icons ) {
	$icons['myphotoblog'] = array(
		'myphotoblogdomain.com',
		'asecondphotoblogdomain.com',
	);

	return $icons;
}
add_filter( 'twentytwenty_social_icons_map', 'mychildtheme_twentytwenty_social_icons_map' );

function mychildtheme_twentytwenty_svg_icons_social( $icons ) {
	$icons['myphotoblog'] = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path fill-rule="evenodd" d="M2.25 4a.25.25 0 00-.25.25v15.5c0 .138.112.25.25.25h3.178L14 10.977a1.75 1.75 0 012.506-.032L22 16.44V4.25a.25.25 0 00-.25-.25H2.25zm3.496 17.5H21.75a1.75 1.75 0 001.75-1.75V4.25a1.75 1.75 0 00-1.75-1.75H2.25A1.75 1.75 0 00.5 4.25v15.5c0 .966.784 1.75 1.75 1.75h3.496zM22 19.75v-1.19l-6.555-6.554a.25.25 0 00-.358.004L7.497 20H21.75a.25.25 0 00.25-.25zM9 9.25a1.75 1.75 0 11-3.5 0 1.75 1.75 0 013.5 0zm1.5 0a3.25 3.25 0 11-6.5 0 3.25 3.25 0 016.5 0z"></path></svg>';

	return $icons;
}
add_filter( 'twentytwenty_svg_icons_social', 'mychildtheme_twentytwenty_svg_icons_social' );

For more information on this change, check out #48713 on Trac.

The icons in the examples above courtesy of Octicons.

Other theme related updates

There are several other changes affecting themes that were published as separate developer notes. You can find them below for easy reference.

For a full list of developer notes associated with WordPress 5.5 (including those documenting new features), please read the full WordPress 5.5 field guide.

Props @audrasjb for reviewing prior to publish.

#5-5, #dev-notes

Controlling Plugin and Theme auto-update email notifications and Site Health infos in WP 5.5

This is the second part of the plugins and themes auto-updates 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. for WordPress 5.5. The first part was dedicated to Controlling Plugins and Themes auto-updates user interface.

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 auto-update email notifications

As of WordPress 5.5, email notifications will be sent after each attempt to auto-update a plugin or theme regardless of outcome (success or failure).

Here’s what you need to know about these emails.

Filtering the emails

Using the auto_plugin_theme_update_email hook, the recipient, subject, headers, and email content can be filtered to adjust a site’s needs.

Example of use:

<?php
function myplugin_auto_plugin_theme_update_email( $email, $type, $successful_updates, $failed_updates ) {
	// Change the email recipient.
	$email['to'] = 'admin@example.com';
	// Change the email subject when updates failed
	if ( 'fail' === $type ) {
		$email['subject'] = __( 'ATTN: IT Department – SOME AUTO-UPDATES WENT WRONG!', 'my-plugin' );
	}

	return $email;
}
add_filter( 'auto_plugin_theme_update_email', 'myplugin_auto_plugin_theme_update_email', 10, 4 );

Repeated failures email notifications prevention

Sometimes, a specific update may fail multiple times. When this happens, a notification email will be sent for only the first failure. A failure is considered a repeat when attempting to update to the same version.

For example, if version 1.0.1 fails and then 1.0.2 is released and fails, that is not a repeat failure.

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

Disabling email notifications

Email notifications can be disabled using two filters:

  • auto_plugin_update_send_email
  • auto_theme_update_send_email

Emails are enabled by default (true). Returning false to either 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. will disable email notifications for that auto-update type.

The following snippet can be used to disable email notifications for themes and/or plugins auto-updates.

<?php
// Disable auto-update email notifications for plugins.
add_filter( 'auto_plugin_update_send_email', '__return_false' );

// Disable auto-update email notifications for themes.
add_filter( 'auto_theme_update_send_email', '__return_false' );

Auto-updates information in Site Health

Each plugin and theme’s auto-update status is also surfaced on the Site Health “Info” tab.

This text can be adjusted using the plugin_auto_update_debug_string and theme_auto_update_debug_string filters.

The following example replaces the text for the status of auto-updates for plugins:

<?php
function myplugin_plugin_auto_update_debug_string( $text, $plugin, $enabled ) {
	if ( false === $enabled ) {
		return __( 'Please consider turning on auto-updates!', 'my-plugin' );
	} else {
		return __( 'Thanks for enabling auto-updates!', 'my-plugin' );
	}
}
add_filter( 'plugin_auto_update_debug_string', 'myplugin_plugin_auto_update_debug_string', 10, 3 )

The following example replaces the text for the status of auto-updates for themes:

<?php
function mytheme_theme_auto_update_debug_string( $text, $active_theme, $enabled ) {
	if ( false === $enabled ) {
		return __( 'Please consider turning on auto-updates!', 'my-theme' );
	} else {
		return __( 'Thanks for enabling auto-updates!', 'my-theme' );
	}
}
add_filter( 'theme_auto_update_debug_string', 'mytheme_theme_auto_update_debug_string', 10, 3 )

Please note: Site Health support was introduced in the Feature Plugin, so there is no Changelog/Trac ticketticket Created for both bug reports and feature development on the bug tracker. to link.

Reviewed by @pbiron and @desrosj

#5-5, #dev-notes