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

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” and then it will apply a new widget_text_content filter which then apply the above functions to the widget text.

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.

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