Dev Chat Agenda for May 24th (4.8 week 4)

This is the agenda for the weekly dev meeting on May 24, 2017 at 20:00 UTC:

If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

#4-8, #agenda, #dev-chat

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.

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.

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:

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

What’s New in Gutenberg? (May 22nd)

We’ll start making weekly posts here in the name of making the ongoing editor updates more visible outside of the Slack channel and the GitHub development stream. At the moment there are 13 blocks implemented in the project, and a few more being worked on by the team and contributors.


In Progress

We welcome all your feedback and contributions on the project repository, or ping us in #core-editor.

#core-editor, #editor, #gutenberg

Enhanced Settings API: Where we’re at

As outlined in a recent post on the accessibility team blog, enhancing the Settings API is currently a high priority for the team. We have been working on this project for a couple months now, discussing goals and approach in a biweekly meeting on Mondays at 16:00 UTC. The main objectives have been to improve accessibility of the pages generated with the Settings API as well as making it easier to use and more flexible for developers. Over the time we have identified the following list of areas to work on:

  • The HTML table layout that has been present for most admin pages should be replaced with a modern, semantically more accurate markup. As the entire table markup is created by the Settings API, we should be able to change it without major backward-compatibility concerns.
  • We’d like to investigate moving from the current two-column layout to a one-column layout, as we agreed on that it would provide a more streamlined experience and overview. Furthermore the two-column layout makes it hard if not impossible to use fieldset (and legend) to group elements properly.
  • For common fields used in Core and plugins, such as a simple text field, textarea, dropdown, radio or checkbox, default callbacks should be provided so that developers do not need to write every callback for such simple UI components themselves. These callbacks should be flexible and accept a standardized set of arguments that can be passed to add_settings_field(). Furthermore each callback should provide accessible markup out-of-the-box, so that even plugin settings pages can be made accessible easily.
  • Eventually all settings pages that Core creates should be using the enhanced Settings API instead of rendering their markup manually. This ensures a more structured output and allows developers to modify the Core fields as well.
  • It should be a high priority to create a set of standardized patterns for class names, markup and design. Elements that need to be targeted in JavaScript must have classes used explicitly for that purpose only.
  • All markup we create should be generalized enough to not be specific to only the Settings API pages. Several other pages in the admin, for example the user profile or term editing pages could benefit from the improvements as well once they are polished.

This list may possibly be extended at some point, as there were some discussions about further developer-centric improvements, but for now we would like to focus on producing a clean and accessible markup with a better DUX being a side product of these efforts.

Prototype for WCEU

After starting development through patches on #39441, we soon realized that this project would be better off as a separate plugin. Therefore we created a GitHub repository for the project, where all development happens now. The plugin uses prefixed functions to not interfere with Core’s own Settings API, so it can safely be tested. While working on the layout, we identified the need for thorough user tests of the changes, and we set the upcoming WordCamp Europe as our target to get a first testable version of the plugin ready. While we still need more time to get to the point where we can propose it as an actual feature plugin, we would like to get feedback sooner than later to uncover eventual pain points.

We will be starting next week to discuss what needs to happen to get that prototype finished in time. If you’re interested, please attend the meeting, which will take place on Monday 16:00 UTC on Slack in the #core channel, or leave a comment on this post if you cannot make it.

cc @afercia, @rianrietveld, @joedolson, @karmatosed, @johnbillion@sc0ttkclark

#accessibility, #settings

JavaScript Chat Agenda for May 23rd

Please join us for our weekly JavaScript Chat on May 23, 2017 at 13:00 UTC, where we will discuss:

  • Introducing a module pattern for WordPress JavaScript, see #40834.
  • A framework for future WordPress JavaScript. What are the goals and criteria for making a decision, and what do we hope to get out of it? To specific frameworks, which options are we considering, and who can share their experiences in implementing them in the context of WordPress? Finally, how do we make decisions about ongoing development and maintenance of existing Backbone-based features? Note: this discussion item may take more than one meeting.
  • Open floor

If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

#agenda, #javascript

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

Preferred Languages: The Prototype

A bit over six months ago I set the foundation for the Preferred Languages feature project. After highlighting the problems many WordPress users around the world are facing, some time was spent on researching popular platforms and other systems to see how they handle the issue of setting multiple preferred languages. However, this didn’t really help to move one step forward and the project became dormant — until now.

Personally, I’ve been experiencing the same problems with so-called language fallbacks over and over again. During WordCamp Bilbao I decided to revive the Preferred Languages project. In order to do this I used the previously mentioned GitHub repository to build a super-simple proof-of-concept plugin to have a new basis for discussion. As originally envisioned, this repository can be used as a playground for discussions, prototypes, and eventually a working solution.

This new plugin lets you select multiple preferred languages in your settings. WordPress then tries to load the translations for the first language that’s available, falling back to the next language in your list.

A sneak peek of an early version quickly made the rounds on Twitter:

After some very positive feedback I worked a bit more on it and wanted to share the latest version here with a larger group of people. Here’s what it currently looks like on both the settings screen and when editing your profile:

Without much further ado, please check out the plugin on GitHub, test it on your local WordPress site, and leave some feedback!

#feature-projects, #i18n, #preferred-languages

Editor API changes in 4.8

A new editor API was added in #35760. It makes it possible to dynamically instantiate the editor from JS. There are two parts to it:

  • All editor related scripts and stylesheets have to be enqueued from PHP by using wp_enqueue_editor().
  • Initialization is left for the script that is adding the editor instance. It requires the textarea that will become the Text editor tab to be already created and not hidden in the DOM. Filtering of the settings is done on adding the editor instance from JS.

There are three new methods added to the wp.editor namespace:

  • wp.editor.initialize()
  • wp.editor.remove()
  • wp.editor.getContent()

(See wp-admin/js/editor.js for more info.)

The default WordPress settings are passed to the initialize() method automatically, and can be overridden by passing a settings object on initialization, similarly to using wp_editor() in PHP.

In addition there are several custom jQuery events that are fired at different stages during initialization:

  • wp-before-tinymce-init is fired before initialization and can be used to set or change any editor setting. It passes the settings object.
  • tinymce-editor-setup is fired after initialization has started but before the UI is constructed. It passes the editor instance object.
  • tinymce-editor-init is fired when the TinyMCE instance is ready (same as the init event in TinyMCE).

Here’s an example of how to add few of the default TinyMCE buttons to the toolbar:

jQuery( document ).on( 'tinymce-editor-setup', function( event, editor ) {
	editor.settings.toolbar1 += ',alignleft,aligncenter,alignright';
});

Here is another example of how to add a custom button:

jQuery( document ).on( 'tinymce-editor-setup', function( event, editor ) {
	editor.settings.toolbar1 += ',mybutton';

	editor.addButton( 'mybutton', {
		text: 'My button2',
		icon: false,
		onclick: function () {
			editor.insertContent("It's my button!");
		}
	});
});

For more information please see the TinyMCE documentation.

#4-8, #editor, #tinymce

Increased Concurrent Jobs on Travis CI Builds

https://travis-ci.org/WordPress now has 15 concurrent jobs instead of the default 5 available to all open-source projects.

This covers all projects under https://github.com/WordPress, so it will help with daily development of Gutenberg, build times for our official wordpress-develop build (especially during releases), and ensuring that builds for these two projects don’t interfere with each other.