Fixes to Text widget and introduction of Custom HTML widget in 4.8.1

The 4.8 release caused issues for many sites that had custom HTML in Text widgets, which until now had been common practice. So we’ve been working hard on fixes in the 4.8.1 release which aim to simultaneously serve the needs of novice users and advanced users alike: the rich Text widget (introduced in 4.8), a legacy mode for the Text widget, and a Custom HTML widget.

For more background on the changes in 4.8, see Addition of TinyMCE to the Text Widget. To review, the Text widget in 4.8 includes TinyMCE—the same visual editor used for writing post content—and it looks like:

Text Widget Legacy Mode

The issues with the introduction of TinyMCE to the Text widget revolve around the ways that TinyMCE attempts to clean up HTML code by deleting empty elements (such as those for dashicons) and dropping attributes it may not recognize (such as HTML5 Microdata attributes). Also with the 4.8’s removal of the “automatically add paragraphs” checkbox, there were also issues related to paragraphs and line breaks being added incorrectly.

Note that the Text widget was already designed to preserve the old behavior of the widget until it was modified and thus upgraded, so there are many instances of Text widgets in the wild today that could very well begin to break upon being modified. For this reason the issues were not reported right away and instead started to trickle in steadily after the release.

There were various solutions that were considered, but the one that had the consensus among contributors was:

[Check if the Text widget] was previously saved from an older version of WordPress before TinyMCE was added to the Text widget. If it is such a pre-existing Text widget instance, then use heuristics to detect if TinyMCE would negatively impact the contents of the widget, including the auto-p checkbox being unchecked, whether there are empty tags, and whether there are spandivscript, or style tags. When the Text widget is in this legacy mode, it can have a notice that informs users of the new HTML Code widget and that it should be used going forward. Likewise, in the new mode when TinyMCE is present, when the Text (HTML) tab is selected, there can be a note (perhaps an admin pointer) that encourages users to use the HTML Code widget instead. By implementing this, novice users with basic content in their widgets win, and advanced users with custom HTML content in their widgets will cease from being negatively impacted.

The Text widget in legacy mode looks the same as the Text widget before 4.8, but with the addition of a new notice:

The legacy mode will only be presented for widgets created prior to 4.8.0 that have instance data which match the logic in the WP_Widget_Text::is_legacy_instance() method. The legacy mode will not be presented to newly created Text widgets. Once a Text widget is opened and saved in legacy mode, it will permanently stay in legacy mode. There is a new instance property called “visual” which will be set to false when a widget is saved in legacy mode. When a new Text widget is created, it is opened in the default visual mode and the new instance will get saved with visual=true.

Text Widget Filters

There is a change in how the filter instance property was used in 4.8.0: in that release, when a Text widget was modified, the fact that it had been upgraded was stored by overloading the filter boolean property to also have the value of "content", indicating that the widget gets content filters applied like a post does. Since this string is a truthy value, I reasoned it would normally work the same in filters that check ! empty( $instance['filter'] ), but it would fail in cases where a plugin tried true === $instance['filter']. So 4.8.1 reverts the overloading of the filter property to again be a boolean, and this should improve compatibility for widget_text filters. Whenever a Text widget is modified with the default visual mode (with TinyMCE) it will get both visual=true and filter=true saved in its instance. When a Text widget is modified in the legacy mode, it will always get visual=false and its filter property will reflect the checked state of the auto-paragraph checkbox.

Another note on filters: special consideration was made for shortcodes in the Text widget given the frequency of plugins and themes adding shortcode support (since the widget does not recognized them by default in core). Plugins and themes have done add_filter( 'widget_text', 'do_shortcode' ) to add support. Since the widget_text filter applies before the new widget_text_content filter (as of 4.8), it will apply before wpautop will have applied, resulting in the possibility of extra line breaks being added undesirably if the shortcode output has new line characters. So to help prevent that from happening, the Text widget will temporarily move the do_shortcode handler from widget_text to widget_text_content just in time while the filters are being applied. See the relevant logic.

Help Pointers

For users who are accustomed to pasting HTML into the Text widget, when an attempt is made to paste markup into the visual editor a pointer will be displayed informing them that they should paste it into the Text tab instead, or to alternatively use the new Custom HTML widget (see section below):

Likewise, when a user opens the Text tab, it will also open a pointer to inform them of the Custom HTML widget:

While pointers are normally displayed on upgrades, these pointers will be displayed even on new installs since they reflect changes to long-standing behavior for the Text widget that users have become accustomed to. Any tutorials that instruct users to use the Text widget for pasting in arbitrary HTML should be updated to instruct the users to select the Custom HTML widget instead.

Custom HTML Widget

For advanced users or for any use case where arbitrary HTML needs to be displayed in a widget (such as a signup form or a 3rd party JavaScript widget), there is now a dedicated “Custom HTML” widget that is specifically for this purpose. It looks very similar to the classic Text widget, except it has a monospace font and it lacks the auto-paragraph checkbox:

Since users are prompted (per the pointers above) to try using the Custom HTML widget instead of the Text widget for some use cases, it is important that the widget content be able to be freely copied between the Text widget and the Custom HTML widget. For this reason, the Custom HTML widget retains the application of the widget_text filters like the Text widget does. The type of widget for which the filter is applying can be determined by looking at the type of the WP_Widget instance being passed as the last filter argument. When the widget_text filter is applied, it will pass the second $instance parameter in the same format as the Text widget, with title, text (instead of content), and filter and visual properties that are always both set to false (as if the instance was in legacy non-visual mode). In addition to re-applying the widget_text filter, the Custom HTML widget has a dedicated widget_custom_html_content filter whereas the the Text widget has a dedicated widget_text_content filter.

In addition to filter compatibility, the Custom HTML widget also tries to retain theme styling compatibility by using the same widget_text CSS class name on the outer widget wrapper and textwidget on the inner wrapper around the content itself. For any themes that wish to style the Custom HTML widget alone, there are the widget_custom_html and custom-html-widget class names used on the outer and inner wrapper elements respectively. For themes that wish to style the Text widget alone and exclude the Custom HTML widget, the :not() pseudo selector can be used, for example .widget_text:not(.widget_custom_html) and .textwidget:not(.custom-html-widget) for the outer and inner wrappers, respectively.

The markup generated by a Custom HTML widget on the frontend will look like:

<section id="custom_html-6" class="widget_text widget widget_custom_html">
  <h2 class="widget-title">My Title</h2>
  <div class="textwidget custom-html-widget">My Content</div>
</section>

This same Custom HTML widget’s instance data will look like:

{
  "title": "My Title",
  "content": "My Content"
}

For more specifics on the Custom HTML widget, refer to the subclass: WP_Widget_Custom_HTML.

Here is a list of tickets related to the Text widget and Custom HTML widget which are closed in the 4.8.1 release:

  • #40907: Introduce widget dedicated for HTML code
  • #40951: New Text Widget – Switching Between Visual/Text Editor Strips Out Code
  • #40960: Set `’filter’ => ‘content’` on starter content “business info” widget
  • #40960: Widgets: The Text widget should respect the “Disable the visual editor when writing” setting
  • #40972: TinyMCE editor in Text widget does not have RTL contents
  • #40974: Updated text widget do not save text (when using paste)
  • #40986: Widgets: text widget and media widgets cannot be edited in accessibility mode
  • #41021: Text widget does not show Title field or TinyMCE editor
  • #41158:  Increase tinymce panel z-index
  • #41361: Text widget can raise JS error if customize-base is enqueued on widgets admin screen
  • #41386: Text Widget – Wording – Legacy Mode 4.8.1 beta
  • #41392: Theme styles for Text widget do not apply to Custom HTML widget
  • #41394: Text widget: Rename legacy mode to visual mode and improve back-compat for widget_text filters

 

#4-8-1, #dev-notes, #tinymce, #widgets

WordPress 4.8 Field Guide

WordPress 4.8 is officially the best WordPress 2017 has seen!  Users will receive new and refined features focused on Editing and Customizing their sites while developers will be able to take advantage of 109 enhancements and features added.  Let’s look at the many improvements coming in 4.8…

 

Media Widgets

Not one, not two, but three new media widgets make their way into core. It’s like the AV crew just showed up and now the party can really begin. You get an audio widget. You get an image widget. You get a video widget. Check under your seat, media widgets for everyone!

Media Widgets for Images, Video, and Audio

 

Fabulously Rich Text Widget

Robin Hood has come to town and is handing out rich text editing to all the text widgets. No more having to manually type out your HTML in text widgets like it’s 2016.

Addition of TinyMCE to the Text Widget

 

Simpler Link Editing, Streamlined Browser Support, and Editor Instantiation via JS

Editing just got a lot easier, you can thank us later. But trust us that adding and managing links within the editor is now easier than ever. If you don’t trust us, then just try navigating in and out of links with your arrow keys. Pretty cool, huh? That’s the new TinyMCE inline element / link boundaries. As for the reduced browser support, let’s just say IE 8, 9, and 10 have been thanked for their service but can feel free to enjoy their retirement. Also, if bootstrapping the TinyMCE content editor dynamically via JS is your thing, then boy are you going to be excited!

Editor changes in 4.8

Editor API changes in 4.8

 

WMV and WMA get retirement packages

Remember Silverlight? Many browsers these days don’t. So the file formats which require the presence of the Silverlight plugin are being removed from core support. Files will still display as a download link, but will no longer be embedded automatically.

Removal of core embedding support for WMV and WMA file formats

 

Resizing the Customizer sidebar

If you have used the Customizer on a high-resolution screen, then you may have noticed that the Customizer sidebar is… suboptimally narrow. The sidebar is now variable width based on screen size to help you receive the best editing experience possible.

Customizer sidebar width is now variable

 

WordCamps and meetups all up in your admin dashboard

One of the best things about WordPress is its community. You can now read about WordCamps and meetups in your area right within your dashboard. No more excuses for missing the speaker or volunteer deadlines now!

Nearby WordPress Events

Showing upcoming local events in wp-admin

 

Mu will really love these multisite changes

We know you love superheroes but is_super_admin() needs to go. So while we’re replacing that with appropriate capabilities, we’re also treating you to some new hooks and a new $network_id parameter that gets wide usage across several functions.

Multisite Focused Changes in 4.8

 

Accessibility: saving the best for last

As a part of ongoing efforts to improve accessibility in WordPress, 4.8 includes some changes to headings within admin screens. This is a continuation of the work started in 4.3 on restoring the H1 (heading level 1) to the admin screens and continued in 4.4 with the introduction of a better headings hierarchy. Also improved is the Tag Cloud widget, now swapping out the title attributes in favor of aria-label attributes.

Cleaner headings in the admin screens

Tag Cloud widget changes in 4.8

 

But Wait, There is More!

Roughly 217 bugs, 108 enhancements, 1 feature request, and 16 blessed tasks have been marked as closed in WordPress 4.8. Some additional ones to highlight include:

  • REST API: orderby normalization (#38693)
  • REST API: Add supports object to /types response (#39033)
  • New filter to disable auto-focus on the login screen (#40301)
  • Screencast.com was added as an oEmbed provider (#38367)
  • HHVM removed from the test matrix on Travis (#40548)
  • Bundled Themes now support the new media and updated text widgets (#40745)
  • Popular plugins feed has been removed from the dashboard (#40702)
  • Support added for Bosnian locale (bs_BA) in remove_accents() (#39658)
  • Easily enqueue WP_Editor JavaScript files using the new wp_enqueue_editor() (#35760)

New Action Hooks

  • deleted_blog (#25584)
  • print_default_editor_scripts (#35760)

New Filter Hooks

  • file_mod_allowed replaces disallow_file_mods (#38673)
  • minimum_site_name_length (#39676)
  • nav_menu_submenu_css_class (#36163)
  • page_menu_link_attributes (#40359)
  • post_date_column_status (#39545)
  • signup_site_meta (#39223)
  • signup_user_meta (#39223)
  • wp_doing_cron (#39591)
  • widget_text_content (#40772)
  • rest_oembed_ttl (#40450)
  • widget_{$this->id_base}_instance (#32417)

Modified Filter Hooks

  • widget_text_content (#40772)
  • {$type}_template (#39525)
  • display_media_states (#39628)
  • media_library_show_audio_playlist (#31071)
  • media_library_show_video_playlist (#31071)
  • rest_pre_insert_comment (#39578)
  • wp_is_large_network (#40489)

External Library Updates

  • TinyMCE was updated from version 4.5.6 to version 4.6.2 (see: #40859).
  • Twemoji was updated from version 2.2.2 to version 2.3.0 (see: #40858).
  • zxcvbn was updated from version 1.0 to version 4.4.1 (see: #31647).

Please, test your code. That bears repeating: Please, test your code. Fixing issues now, before 4.8 is released, helps you and helps millions of WordPress sites. Please. Test. Your. Code.

#4-8, #dev-notes, #field-guide

Tag Cloud widget changes in 4.8

The Tag Cloud widget is still pretty popular and for a number of years, it has used title attributes to visually display the number of posts using a specific tag.

tag cloud in WordPress 4.7

Example of a title attribute displaying the number of items for a specific tag in WordPress 4.7

WordPress 4.8 removes these title attributes and replaces them with aria-label attributes with optional counts displayed in plain text.

Why it matters

Title attributes aren’t very accessible. Depending on the specific assistive technology and on user settings, they might be completely ignored. On touch devices, title attributes are a bit pointless.

The best option is not to rely on title attributes to convey important information to users. Information that is important enough should be available to all users.

In the last few releases, WordPress has been progressively removing many title attributes used in the admin screens (see: #24766). The same principle applies to the front end. The Tag Cloud widget is another step towards the progressive removal of title attributes in the front end where they’re used inappropriately.

What plugin or theme authors should know

There are no visual changes by default, other than the removal of the title attributes. There is a new option for developers though: tag counts can be displayed in plain text within the list of tags. Users will now find a checkbox in the widget interface, consistent with what other widgets already do (e.g., Archives and Categories widgets).

the tag cloud widget admin interface

The new option “Show tag counts” in the widget admin interface

Checking the “Show tag counts” option in the admin will make the Tag Cloud show the counts alongside each tag. The screenshot below compares the Tag Cloud with and without the counts displayed:
the Tag Cloud with and without tag counts

Themes can style the tag counts targeting the new CSS class tag-link-count. Also, note that wp_generate_tag_cloud() has a new show_count argument. Themes and plugins that filter the Tag Cloud arguments can use this new argument to force the tag counts to be displayed.

Theme authors are recommended to check how the tag counts look like in their themes and make small CSS adjustments if needed. And remember, the tag counts are not displayed by default! Users can enable and also disable them at any time.

Some technical details

The relevant changeset is [40816] and the related ticket is #35566. Behind the scenes, the tag cloud now attempts to determine whether to output the aria-label attribute, trying to respect the theme author’s intent.

By default, the Tag Cloud displays tags in different font sizes to visually represent how many times they’re used. When tags have a different font size, they visually convey important information that should also be available to assistive technologies.

Sometimes instead, theme authors set up the Tag Cloud to display all tags with the same font size. Twenty Sixteen, for example, displays all the tags with a “flat” styling. It does that by filtering the arguments passed to wp_generate_tag_cloud() and setting the smallest and largest arguments to the same value (note: this is the recommended way to output “flat” tags).

In order to always serve the same information to all users and try to respect the theme author’s intent, the aria-label that conveys the count information to assistive technologies gets printed out:

  • when tags have a different size
  • when the tag count is displayed in plain text (for example when users check the checkbox in the Tag Cloud widget), regardless of the tags font size

A quick update about title attributes

To give an idea of the progress done so far, here’s data from the WordPress codebase from version 4.0 to 4.7. Searching for occurrences of  title= (space-title-equal) only within .php files and only in the wp-admin directory:

WordPress 4.0: 157 results found in 37 files
WordPress 4.1: 156 results found in 37 files
WordPress 4.2: 146 results found in 35 files
WordPress 4.3: 101 results found in 30 files
WordPress 4.4: 97 results found in 32 files
WordPress 4.5: 21 results found in 12 files
WordPress 4.6: 19 results found in 11 files
WordPress 4.7: 17 results found in 9 files

Of the 17 title attributes in WordPress 4.7, four of them are legitimate because they’re used on <iframe> elements and most of the other ones are in files no longer used by core. Many of these occurrences were within loops so the number of title attributes actually output was higher, yet going from 157 down to a very few is wonderful progress.

As always, any comments and contribution to improving accessibility are welcome!

#4-8, #accessibility, #dev-notes

Addition of TinyMCE to the Text Widget

Note: Update: A follow-up post has been published regarding Fixes to Text widget and introduction of Custom HTML widget in 4.8.1.

In its first couple years, WordPress lacked rich/visual text editing. Before TinyMCE was incorporated in WordPress 2.0, users had to edit post content as raw HTML with some support from the Quicktags buttons. When widgets were introduced in WordPress 2.2, the Text widget was included which allowed a user to add content to their sidebar. Nevertheless, unlike the post editor, the Text widget did not incorporate TinyMCE, nor did it include Quicktags. For twelve years, since TinyMCE was added to core in 2005, users have had to hack around with HTML in their Text widgets to do things as simple as make text bold or add links. This has been featured even as recently as the 4.7 release video. Well, as of WordPress 4.8, the Text widget is finally getting the same treatment as the post editor with the introduction of TinyMCE for visual text editing, while still supporting raw HTML editing via a Text tab but now with the additional help of Quicktags:

Text widget: visual tab Text widget: text (HTML) tab

A primary reason for the long delay in incorporating TinyMCE into the Text widget was the difficulty of cleanly instantiating another copy of the WordPress visual editor dynamically after the page has loaded. Since WordPress 3.3 there has been the wp_editor() PHP function for instantiating an editor for the initial page load, but there was no facility for instantiating editors afterward, such as when adding a new Text widget to a sidebar. So in #35760 a new JS API was introduced for dynamically instantiating WP editors on the page: wp.editor.initialize(). This JS API is used for the new TinyMCE-powered Text widget; for more, please see Editor API changes in 4.8.

Note that by default the Text widget only features buttons for bold, italic, unordered list, ordered list, and link. If you want to add additional buttons to the toolbar, you may use a plugin to enqueue the following JS to add the blockquote button, for example:

jQuery( document ).on( 'tinymce-editor-setup', function( event, editor ) {
	if ( editor.settings.toolbar1 && -1 === editor.settings.toolbar1.indexOf( 'blockquote' ) ) {
		editor.settings.toolbar1 += ',blockquote';
	}
});

Likewise, a custom button can be added via code like:

jQuery( document ).on( 'tinymce-editor-setup', function( event, editor ) {
	editor.settings.toolbar1 += ',mybutton';
	editor.addButton( 'mybutton', {
		text: 'My button',
		icon: false,
		onclick: function () {
			editor.insertContent( 'Text from my button' );
		}
	});
});

A reason for why there is no “Add Media” button for the editor in the Text widget is that WordPress 4.8 also includes dedicated media widgets for adding images, video, and audio to sidebars. Another reason is a current technical limitation whereby arbitrary media embeds (oEmbeds) fail to work properly outside the context of post content (see #34115). For this reason if you try to embed a video or something else by pasting in a URL it will not currently expand into the embedded content. The same is true for shortcodes: they are not processed by default since many shortcodes presuppose a global $post as the context within which they expect to be running. Plugins may opt-in selectively to support individual shortcodes by filtering widget_text as they have had to do for many years now.

While not supporting shortcodes, the updated Text widget does have some of the same filters applying to it as the_content, in particular:

  • wpautop
  • wptexturize
  • capital_P_dangit
  • convert_smilies

The Text widget has supported a “filter” instance property which was reflected in the UI via a checkbox for whether or not to automatically add paragraphs and line break tags (wpautop). For the updated Text widget, this checkbox is removed entirely in favor of aligning its behavior with the post editor where this behavior is always enabled. These filters only apply on Text widgets that have been updated/touched after the 4.8 upgrade. When a Text widget is modified in 4.8, the filter instance prop gets set to a static string “content both the filter instance property and a new visual property will be set to true and then it will apply a new widget_text_content filter which then apply the above functions to the widget text. For Text widgets created prior to 4.8, they will be opened in a legacy mode with the old behavior when it is determined that TinyMCE could mutate the content undesirably; such legacy instances will be saved with visual=false instance property. Read more about Fixes to Text widget and introduction of Custom HTML widget in 4.8.1.

Important: When pasting HTML into the “Text” (HTML) tab of the Text widget, any extraneous line breaks should be removed or else unwanted paragraphs and line beaks may result. This is particularly important when you paste in script or style tags (as in the case of 3rd-party JavaScript embeds), since auto-inserted paragraphs will cause script errors; this will be fixed in #2833. This behavior aligns with longstanding behavior in the post editor, so it is not new, although it does differ from how the Text widget has previously behaved. As noted above, for previously-existing Text widgets that had the “auto-add paragraphs” checkbox unchecked (and thus the filter instance prop set to false), the previous behavior of not doing wpautop will be maintained: only once the widgets are modified will any extraneous line breaks need to be removed. Any such Text widgets created prior to 4.8 will be go into a legacy mode as of 4.8.1 to prevent any data loss. Going forward, arbitrary HTML should be placed into the new Custom HTML widget instead.

The incorporation of TinyMCE into the Text widget has necessitated constructing the widget’s form fields differently than how they are normally done. Widgets in core have historically utilized static HTML for their control form fields. Every time a user hits “Save” the form fields get sent in an Ajax request which passes them to the WP_Widget::update() method and then the Ajax response sends back the output of WP_Widget::form() which then replaces the entire form. (Note widgets in the Customizer behave differently since there is no Save button in the widget, as updates are synced and previewed as changes are made; read more about Live Widget Previews.) This worked for static HTML forms in the past, but TinyMCE is a JavaScript component. To avoid having to rebuild TinyMCE every time the user hits Save on the admin screen, the Text widget puts the title field and TinyMCE text field outside of the container that is “managed” by the server which gets replaced with each save. (A similar approach has also been employed by the new media widgets in 4.8.) The fields in the Text widget’s UI sync with hidden inputs which get synchronized with the server; in the Customizer, changes to the TinyMCE field will be previewed after 1 second with denouncing. The container for the Text widget’s fields is .text-widget-fields and the traditional container for a widget’s input fields as rendered by WP_Widget::form() is .widget-content:

Themes should already account for the most common HTML elements within the text widgets and provide appropriate styles for them—the addition of the editor toolbar increases the likelihood its elements will be used in the future. Most default themes needed additional styles for ordered and unordered lists within widgets, so theme authors are encouraged to double-check their themes and test them with content in the text widget that includes markup provided by the editor toolbar.

Initial groundwork for shimming JavaScript into widgets was added in 3.9 via the widget-added and widget-updated events. A more recent proposal for making JavaScript more of a first class citizen in widgets can be found in #33507 and the media widgets incorporate some of its patterns that were also prototyped in the JS Widgets plugin. The synchronization of a widget’s state (instance properties) via hidden text fields can be eliminated once a widget’s state can be fully represented in a JavaScript model.

The Text widget is implemented as a Backbone.js view which is available at wp.textWidgets.TextWidgetControl. Instances of this view are then stored in the wp.textWidgets.widgetControls object. The widget’s control JS will only instantiate for a given widget once it is first expanded, when the widget-added event fires. What’s more is that the widget will only first initialize once the container is fully expanded since TinyMCE is not able to initialize properly inside of a container that is animating. In order to capture when TinyMCE inside the Text widget is initialized, you should use a TinyMCE event like tinymce-editor-setup. Note also that due the Document Object Model, when a widget is moved to a new location in a sidebar and this the TinyMCE iframe is moved in the DOM, this dynamically-created iframe is reloaded and thus emptied out. For this reason, every time a Text widget is moved to a new location the TinyMCE editor in the widget will be removed and then re-initialized. Keep this in mind when extending.

Keep also in mind that the Text widget will likely undergo many more changes with the incorporation of the Gutenberg editor, and that widgets themselves will likely see many changes to align with Gutenberg’s editor blocks which are now being prototyped.

#4-8, #dev-notes, #editor, #widgets

Multisite Focused Changes in 4.8

Here’s an overview of the developer facing changes made in multisite for the 4.8 cycle. If you’re interested in more detail, checkout the full list of tickets.

New capabilities

As part of the goal to remove all calls to is_super_admin() in favor of capability checks, two new meta capabilities have been introduced in this release:

  • upgrade_network is used to determine whether a user can access the Network Upgrade page in the network admin. Related to this, the capability is also checked to determine whether to show the notice that a network upgrade is required. The capability is not mapped, so it is only granted to network administrators. See #39205 for background discussion.
  • setup_network is used to determine whether a user can setup multisite, i.e. access the Network Setup page. Before setting up a multisite, the capability is mapped to the manage_options capability, so that it is granted to administrators. Once multisite is setup, it is mapped to manage_network_options, so that it is granted to network administrators. See #39206 for background discussion.

Both capabilities work in a backward-compatible fashion, so no changes should be required in plugins that deal with those areas. The capabilities however allow more fine-grained control about access to their specific areas. As an additional reminder: Usage of is_super_admin(), while not throwing a notice, is discouraged. If you need to check whether a network administrator has access to specific functionality in your plugin, use one of the existing network capabilities or a custom capability. See #37616 for the ongoing task.

New Hooks

  • deleted_blog fires after a site has been deleted. See #25584
  • signup_site_meta filters site meta in wpmu_signup_blog(). See #39223
  • signup_user_meta filters user meta in wpmu_signup_user(). See #39223
  • minimum_site_name_length filters the minimum number of characters that can be used for new site signups. See #39676

Network-specific site and user count control

With WordPress 4.8, several functions related to network site and user counts now support an additional $network_id parameter that allows to read and update those counts on a different network than the current one. While this mostly increases general flexibility, the new parameter can be leveraged to fix inconsistencies, for example prior to 4.8 the creation of a new site on another network would falsely trigger a recalculation of the current network instead of the network being actually modified. See #38699 for the bug ticket and resulting task.

The functions that now support a $network_id parameter are:

  • get_blog_count(). See #37865.
  • get_user_count(). See #37866.
  • wp_update_network_site_counts(). See #37528.
  • wp_update_network_user_counts(). See #40349.
  • wp_update_network_counts(). See #40386.
  • wp_maybe_update_network_site_counts(). See #40384.
  • wp_maybe_update_network_user_counts(). See #40385.
  • wp_is_large_network(). The filter wp_is_large_network now passes the network ID as fourth parameter as well. See #40489.

#4-8, #dev-notes, #multisite

Removal of core embedding support for WMV and WMA file formats

With the introduction of the video widget (#39994) and audio widget (#39995) it was discovered that the WMV and WMA file formats are no longer supported by MediaElement.js as of v3. While core is currently shipping with MediaElement.js v2.22, these file formats only play if the Silverlight plugin is installed, something which is less and less common since the plugin is no longer supported as of Chrome 45 and as of Firefox 52. So with the planned upgrade of MediaElement.js from 2.22 to 4.x (see #39686), it is a good time with the WP 4.8 major release to remove support for the formats. This has been done in [40813] for #40819.

Plugins may continue to add embedding support for these file formats by re-adding them via the wp_video_extensions and wp_audio_extensions filters, for example:

function add_wmv_to_wp_video_extensions( $extensions ) {
    $extensions[] = 'wmv';
    return $extensions;
}
add_filter( 'wp_video_extensions', 'add_wmv_to_wp_video_extensions' );

function add_wma_to_wp_audio_extensions( $extensions ) {
    $extensions[] = 'wma';
    return $extensions;
}
add_filter( 'wp_audio_extensions', 'add_wma_to_wp_audio_extensions' );

Plugins would also need to implement fallback rendering routines via the wp_video_shortcode_override and wp_audio_shortcode_override filters, or else use a different library than MediaElement.js altogether via the wp_video_shortcode_library and wp_audio_shortcode_library filters.

Note that there is no functional difference before and after the removal of WMA and WMV support. When MediaElement.js doesn’t support a format, it displays a download link. Before and after [40813], the following is ho  the audio and video shortcodes look like with WMA and WMV files respectively:

In the admin, the functional difference is that these formats are not listed as being available for selection in the Video and Audio widgets. Additionally, when you Add Media in the post editor, there is now no option to embed the player for these formats; only a link to the media will be provided, just as when attempting to add non-media files to content.

#4-8, #core-media, #dev-notes, #mediaelement

Cleaner headings in the admin screens

One of the most common needs for accessibility is providing tools to effectively navigate through content. Users of assistive technologies use headings as the predominant mechanism for finding page information. Headings provide document structure. Assistive technologies can list all the headings in a page to help users navigate and jump to different sections, like in a table of contents. For this reason, headings should contain just the heading text.

For a number of years, the main headings in the admin screens have been used to contain extraneous content, most notably the “Add new” button. WordPress 4.8 aims to fix this.

This is a continuation of the work started in 4.3 on restoring the H1 (heading level 1) to the admin screens and continued in 4.4 with the introduction of a better headings hierarchy.

What plugin or theme authors should know

If your plugin or theme follows the previous WordPress pattern of adding extraneous content to the main heading, please update your plugin or theme to make the heading cleaner. All you need to do is move the extraneous content outside of the heading. WordPress 4.8 ships with new CSS rules to take care of the new markup structure and in most cases, no additional changes will be required.

Of course, it’s impossible to cover all edge cases. If your plugin or theme uses additional content in the area next to the admin screens main heading, please double check now and be prepared to upgrade your markup and CSS to account for the cleaner headings. The relevant area is highlighted in the screenshot below and it applies to almost all the admin screens.

example of a main heading in the admin screens

Need more details?

If you need more details about the markup and CSS changes, please do have a look at the tracking ticket #26601 and the first changeset [38983], followed by several other ones all listed in the main ticket.

Get ahead of 4.8 and update now!

The power of the Web is in its universality. Help us to make the Web a place designed to work for all people. Any feedback and thoughts are more than welcome, please let us know in the comments below.

#4-8, #accessibility, #dev-notes

Customizer sidebar width is now variable

A common request for the Customizer has been to grant more room for the controls that appear in its sidebar. Ticket #32296 was created to allow the sidebar pane to be user-resizable with a grabber just like the Dev Tools pane in Chrome can be resized. After a lot of back and forth, the scope was reduced to remove the user-resizable aspect and to instead address a more fundamental issue that the sidebar is exceedingly and unnecessarily narrow on high-resolution displays. So while 4.8 doesn’t include a user-resizable controls pane, there is still a feature plugin for possible future merge. Important to that end, the changes that have been merged begin to introduce the fundamental prerequisite for a variable-width sidebar pane: responsive controls.

As can be seen in [40511] and [40567], no longer should Customizer controls assume that their container will always be 300px wide. Given the new responsive breakpoints for high-resolution screens, the pane can now be between 300px and 600px wide depending on the screen width. And actually this has already been the case on smaller screens (e.g. mobile) where the preview and pane aren’t shown at the same time; it now also applies to very large screens where there is ample space for both the preview and a wider pane.

Custom controls in plugins and themes should utilize alternative approaches to doing layout than using pixel widths. Use of percentage-based widths or flexbox will help ensure that controls will appear properly in larger displays, while also making controls future-compatible when the sidebar width could be user-resizable.

#4-8, #customize, #dev-notes

Recent updates to the unit testing infrastructure

Several changes have made their way into WordPress’ unit test suite and its infrastructure recently. If you maintain a WordPress project (such as a plugin or website) that has its own test coverage, you may be interested in porting some of these changes to your test suite too. Here’s a round-up:

  • Tests which require Multisite to be enabled, or tests which should be excluded from running when Multisite is enabled, can now be placed into the new ms-required and ms-excluded groups to skip them automatically when the test requires Multisite to be in use, or when it requires Multisite to not be in use, respectively. In addition, the default configuration in phpunit.xml now excludes such test groups as appropriate without them being marked as skipped, which removes unwanted noise from PHPUnit’s reporting when run in verbose mode. See #40531.

Note: Please note that this usage example has been updated from a previous version of this post.

Example usage:

/**
 * @group ms-required
 */
function test_something_on_multisite() {
	// Run your Multisite-only assertions here
}

/**
 * @group ms-excluded
 */
function test_something_without_multisite() {
	// Run your single-site-only assertions here
}
  • XDebug is now disabled when running tests on Travis in order to speed up the builds. This resulted in a huge reduction in build times, up to 40% in some cases. See #39978.
  • The PHPUnit version used when running tests on Travis is now explicitly coupled to the PHP version in order to avoid incompatibilities such as the one caused when PHPUnit 6 was rolled out. See [40269] for the main change and #40100 and #40086 for more info.
  • A compatibility shim for PHPUnit 6+ has been added, which means the test suite will no longer cause fatal errors if you want to update to PHPUnit 6+ locally or, for example, you want to require it through a Composer dependency. See #39822.
  • Several tests which were previously skipped when the environment wasn’t suitable will now cause failures, for example tests which depend on constants such as DISALLOW_FILE_MODS not being set. This is to avoid hiding tests that never run and therefore never fail if the assertions contained within them would otherwise fail. If the core test suite begins failing on your local environment as a result, you should address the cause. See #40533.
  • The number of PHP versions which older branches are tested against on Travis has been significantly reduced in order to speed up build times for patch releases. This is most beneficial when security fixes are released and backported. As a general rule, branch builds except the latest branch are now only tested on the oldest supported version (5.2), the latest in the 5.x branch, and the latest in the 7.x branch. See #40407.

#dev-notes

WordPress 4.7 Field Guide

WordPress 4.7 is shaping up to be the best WordPress yet!  Users will receive new and refined features that make it easier to “Make your site, YOUR site”, and developers will be able to take advantage of 173 enhancements and feature requests added.  Let’s look at the many improvements coming in 4.7…

RESTing, RESTing: 1, 2, 3

The foundation for RESTful APIs has been in core since 4.4, and 4.7 sees the addition of Content Endpoints after a healthy discussion. We’ve defined four success metrics as part of the merge discussion and you can help by building themes and plugins on top of the API, using the API in custom development projects, and utilizing the API for a feature project, core features, or patches. So, dive in, start playing around, and let us know what you build!

https://make.wordpress.org/core/2016/10/08/rest-api-merge-proposal-part-2-content-api/

 

It don’t mean a thing, if you ain’t got a theme

No matter if you are building themes for public consumption, as a bespoke project for a major public company, or anything in between WordPress 4.7 has something to help you.

https://make.wordpress.org/core/2016/11/29/theming-with-twenty-seventeen/

https://make.wordpress.org/core/2016/11/26/video-headers-in-4-7/

https://make.wordpress.org/core/?p=20650

https://make.wordpress.org/core/2016/11/10/visible-edit-shortcuts-in-the-customizer-preview/

https://make.wordpress.org/core/2016/11/07/whitespace-changes-in-navigation-for-4-7/

https://make.wordpress.org/core/2016/11/03/post-type-templates-in-4-7/

https://make.wordpress.org/core/2016/11/03/new-post-type-labels-in-4-7/

https://make.wordpress.org/core/2016/09/09/new-functions-hooks-and-behaviour-for-theme-developers-in-wordpress-4-7/

The Voyages of USS Media

Two notable changes, enhanced PDF support in the media library and changes to the default fallbacks for image alt attributes, are explained in separate posts.

https://make.wordpress.org/core/2016/11/15/enhanced-pdf-support-4-7/

https://make.wordpress.org/core/2016/11/11/improving-accessibility-of-image-alternative-text-in-4-7/

Media also received other exciting enhancements and bug fixes you should check out.

Around the World

The way users understand the words on WordPress are important and now users will be able to select their personal preferred language.

https://make.wordpress.org/core/2016/11/07/user-admin-languages-and-locale-switching-in-4-7/

 

For Whom Customization Tolls

The customize component will now support the ability to create pages within live preview during site setup; will have a faster, smoother, and more accessible navigation; will automatically persist your changes in the background while you browse your site and switch themes; and will let you fine-tune your site with custom CSS.

https://make.wordpress.org/core/?p=20534

https://make.wordpress.org/core/2016/10/12/customize-changesets-technical-design-decisions/

https://make.wordpress.org/core/2016/09/28/changes-to-customizer-sliding-panelssections-in-wordpress-4-7/

https://make.wordpress.org/core/2016/11/26/extending-the-custom-css-editor/

 

Reading, Writing and Teriffic

Whether you’re creating content in the WordPress Admin or concerned about comment moderation, we’ve got updates that will be sure to please you.

https://make.wordpress.org/core/2016/10/28/editor-changes-in-4-7/

https://make.wordpress.org/core/2016/10/11/comment-allowed-checks-in-wordpress-4-7/

 

The Foundation of WordPress

For those who like to get “under the hood” of WordPress, we’ve got some improvements that will hopefully make your life easier.

https://make.wordpress.org/core/2016/11/07/changed-loading-order-for-current-user-in-4-7/

https://make.wordpress.org/core/2016/11/04/multisite-focused-changes-in-4-7/

https://make.wordpress.org/core/2016/11/03/attributes-for-resource-hints-in-4-7/

https://make.wordpress.org/core/2016/11/02/wp_list_sort-and-wp_list_util-in-4-7/

https://make.wordpress.org/core/2016/10/29/wp_taxonomy-in-4-7/

https://make.wordpress.org/core/2016/10/28/fine-grained-capabilities-for-taxonomy-terms-in-4-7/

https://make.wordpress.org/core/2016/09/08/wp_hook-next-generation-actions-and-filters/

https://make.wordpress.org/core/2016/10/26/registering-your-settings-in-wordpress-4-7/

 

But Wait, There is More!

Over 447 bugs, 165 enhancements, 8 feature requests, and 15 blessed tasks have been marked as fixed in WordPress 4.7. Some additional ones to highlight include:

  • Make media library searchable by file name (#22744)
  • Improved Custom Background Properties UI (#22058)
  • Hue-only Color Picker (#38263)
  • Fix Sections that .cannot-expand (#37980)
  • Allow Plugins to do Comprehensive Late Validation of Settings (#37638)

Please, test your code. Fixing issues now, before 4.7 is released, helps you and helps millions of WordPress sites.

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