Improvements to the Customize JS API in 4.9

There are many user-facing Customizer improvements in 4.9, including: drafting/scheduling of changesets, autosave revisions, changeset post locking, frontend public previews, a new experience for browsing and installing themes, updated nav menu creation UX, and the code editing improvements for the Custom HTML widget and Additional CSS. But in addition to all of these, there are also many improvements for developers which will make extending the Customizer much more pleasant.

Something important to remember about the Customizer is that it is a single page application that is powered by JavaScript. Many developers may only interact with the PHP API for registering controls, settings, sections, panels, and partials. But controls, sections, and panels do not need to be registered in PHP at all. The PHP API for registration is essentially a wrapper for the underlying JS API. When you load the Customizer all of the params for the PHP-registered constructs are exported to the client for the JavaScript API to instantiate and initially add to the UI, but this JS API can dynamically instantiate additional constructs at any time thereafter in a Customizer session. This is how new widgets, nav menus, and nav menu items are added without requiring the entire Customizer to reload. You can also avoid statically registering settings and partials in PHP by instead adding filters to dynamically recognize settings and partials, allowing them to be registered on demand. All of this allows the Customizer application to scale out to be able to customize and preview an unlimited number of things on a site (e.g. any post or page with their postmeta in the Customize Posts feature plugin). The point here is that in order for the Customizer to scale, the JavaScript API must be used directly. So this is why the Customizer JS API improvements in 4.9 are important as they fix many longstanding annoyances and shortcomings with the JS API.

This dev note contains the following sections:

Continue reading

#4-9, #customize, #dev-notes

MediaElement upgrades in WordPress 4.9

MediaElement has been upgraded to 4.2.6 (see #39686), which includes many bug fixes as well as:

  • Removal of all dependencies to jQuery in code to make it more portable
  • Updated UI, using flexbox
  • Improved accessibility for player controls
  • Dropped support for older browsers (supports IE11+, Chrome, FF, Safari, Android 4+ and iOS 8+), keep in mind that ME.js applies to the front end and not just WP Admin
  • Upgraded YouTube and Vimeo renderers to use new APIs (for Vimeo, it uses now https://player.vimeo.com/api/player.js, since Froogaloop is deprecated)
  • Added support for iOS 10 and Mac OS on websites using HTTPS

With this upgrade, a couple of things must be considered:

  1. In order to create themes compatible with it, it is required to add the classPrefix: mejs- in the player configuration, since latest version of MEJS switched to BEM naming convention, so make sure it is set correctly.
  2. player.options.mode has been removed completely.
  3. Although jQuery was removed from the core package, a MediaElement migration file has been included to provide full backward compatibility between themes and development of new features.

A full list of changes in MediaElement.js is available in the project’s GitHub repository.

Props to @rafa8626 for helping write this Dev Note.

#4-9, #dev-notes, #mediaelement

Dev Chat Summary: October 25th (4.9 week 13)

This post summarizes the dev chat meeting from October 25th (agendaSlack archive).

4.9 schedule

  • Beta 4 dropped late last night / early this morning, please do help test. RC is scheduled to go out on Monday, October 30th and that entails soft string freeze.
  • For all @committers, please let @melchoyce @westonruter know if you are able to help with commits during RC as we’ll need two committers to approve a patch before merging.
  • Bug Scrubs are scheduled on Monday’s and Thursday’s. If you have availability to help run a scrub, please let @jbpau17 know. Any help would be greatly appreciated, thanks!
  • Currently nine tickets that show as needs-dev-note
  • Three Dev Notes coming from @westonruter and one from @rafa8626 (#39686); all could use proofreading
  • If anyone can help draft the Field Guide, please let @jbpaul17 know especially for things around New Action Hooks, New Filter Hooks, Modified Filter Hooks, and External Library Updates.
  • If anyone can help populating the “Developer Happiness” section of the About page, please let @melchoyce know or add notes to #42087

Editor / Gutenberg update

  • Gutenberg v1.5 includes metabox support and likely has advanced cases where the plugin will benefit from feedback and iteration.
  • You can report via GitHub, the feedback form within the Gutenberg plugin, or in #core-editor.

General announcements

  • @johnbillion: The last PHP 7.2 issue, #41526, needs some eyes and can still make it into 4.9 if another patch comes along. The original patch causes some warnings.
  • @paaljoachim: looking for comments on #42324

#4-9, #core, #dev-chat, #gutenberg, #summary

Improvements in REST API request parameter regular expressions

With WordPress 4.9, a bug has been fixed which would cause unexpected numeric results to be included in the parsed URL parameters for a REST API request. Prior to this change, calling WP_REST_Request::get_params() for a request like /wp/v2/users/(?P<id>[\d]+) with an ID of 10 would return array( 'id' => 10, 1 => '10' ), where the latter numeric key is unnecessary and a result of PCRE matching against a named subpattern (see preg_match() documentation). The fix ensures that the above request now only returns array( 'id' => 10 ) instead. This helps for example to verify that a request does not include more than a few specific parameters.

The WP REST API docs have always been using named URL parameters, using regular (numeric) matches was never recommended. With this bug fix in place, using named parameters is now effectively required, for example /my-namespace/my-endpoint/(?P<numeric_param>[\d]+) must be used instead of /my-namespace/my-endpoint/(\d+). For background discussion on these changes, see #40704.

#4-9, #dev-notes, #rest-api

Dev Chat Agenda for October 25th (4.9 week 13)

This is the agenda for the weekly dev meeting on October 25, 2017 at 20:00 UTC / October 25, 2017 at 20:00 UTC:

  • 4.9 schedule
  • Editor / Gutenberg update
  • General announcements

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-9, #agenda, #dev-chat

Widget Improvements in WordPress 4.9

On the heels of adding TinyMCE rich editing to the Text widget and the media widgets in 4.8, there are another round of improvements coming to the Text widget and Video widget in 4.9, among other improvements to widgets.

Shortcodes in Text Widget

One very longstanding request—for over 8 years—has been to support shortcodes in the Text widget (#10457). This is finally implemented in WordPress 4.9. It is no longer required to have plugins and themes do add_filter( 'widget_text', 'do_shortcode' ). Core now will do_shortcode() at the widget_text_content filter (added in 4.8) in the same way it is applied in the_content at priority 11, after wpautop() and shortcode_unautop(). If a plugin has added do_shortcode() to widget_text then this filter will be suspended while the widget runs to prevent shortcodes from being applied twice. If a Text widget is in legacy mode then it will manually do_shortcode() as well.

One reason for the long delay with adding shortcode support in Text widgets was due to many shortcodes looking for a global $post when they run. Since the global $post varies depending on whatever the main query is, the shortcodes in a Text widget could render wildly different on different templates of a site. The solution worked out was to temporarily nullify the global $post before doing the shortcodes so that they will consistently have the same global state, with this global $post then restored after the shortcodes are done. So if you have shortcodes that depend on a global $post—or call get_post()—then you should make sure that they short-circuit when $post is null in order for them to behave properly if used in the Text widget.

As of [42185] this nullification of $post is only done for archive (non-singular) queries; for singular queries, the $post will instead be set to be the current main queried post via get_queried_object(). This ensures that the global $post is consistent and explicit. This setting of the $post global while applying filters (and shortcodes) is also now implemented for the Custom HTML widget. Additionally, to ensure that gallery shortcodes that lack ids do not end up listing out every attachment in the media library, a shortcode_atts_gallery filter has been added which makes sure the shortcode’s id attribute is set to -1 when the widget is rendered on archive templates. This allows you to embed the gallery for any currently queried post in the sidebar. You should make sure such a Text widget is not displayed on an archive template by either adding it exclusively to a sidebar that appears on singular templates, or by using a feature like Jetpack’s Widget Visibility to hide the widget on non-singular templates.

Media in Text Widget

One reason why shortcode support in the Text widget was needed in this release is because 4.9 also allows media to be embedded in the Text widget (#40854). There is now the same “Add Media” button in the rich Text widget as on the post editor, allowing you to add images, galleries, videos, audio, and other media. To support these, core also needed to support shortcodes like captionaudiovideo, and gallery. Note there are also dedicated widgets (Image, Audio, Video, and Gallery) for these media types as well.

Having separate media-specific widgets helps with discovery and allows us to provide streamlined interfaces for each media type. For example, the Image widget now has a field specifically for supplying the link URL (see #41274), and the Video widget now provides more guidance to users when supplying external URLs (#42039). The media-specific widgets are closely aligned with blocks in Gutenberg; the existence of media inside the Text widget will align with eventual nested blocks in Gutenberg, and would be treated as Classic Text blocks in any future migration from widgets to blocks.

Embeds in Text Widget and Video Widget

One shortcode not mentioned above is embed. This one was more difficult to support because oEmbeds have not been supported anywhere other than post content. This was because there were dependencies on having a post as context for the sake of caching, as the responses to oEmbed requests get stored in postmeta. However, as of #34115 if there is no post as context the oEmbeds will now get cached in an oembed_cache custom post type instead. Since a Text widget will explicitly nullify the global $post while shortcodes are processed, this means oEmbeds will get cached in this custom post type. Similarly to how do_shortcode() now applies in the widget_text_content filter like it applies on the_content, so too now WP_Embed::autoembed() and WP_Embed::run_shortcode() both also now run on widget_text_content.

In WordPress 4.8 the Video widget was introduced with support for displaying an uploaded video file, a YouTube video, or a video from Vimeo. Each of these were displayed using MediaElement.js. Just as oEmbeds are now able to be displayed in the Text widget, so too now the Video widget has been expanded to support any oEmbed provider for video. See #42039.

Theme Styling Changes

As with the previously-introduced media widgets (#32417) and the new Gallery widget (#41914), some themes will need to be updated to ensure the proper styling is applied to media and embeds that appear in the widget area context, since previously they would only appear in post content. Please follow #42203 and #41969 for style changes that are made to the core bundled themes, as you may need to make similar changes to your themes.

Improved Theme Switching

A longstanding difficulty with widgets has been where they end up when switching from one theme to another. With #39693 this experience is improved in 4.9 by having logic that is able to better map widgets between the themes’ widget areas. As noted by @obenland in [41555], there are three levels of mapping:

  1. If both themes have only one sidebar, they gets mapped.
  2. If both themes have sidebars with the same slug (e.g. sidebar-1), they get mapped.
  3. Sidebars that (even partially) match slugs from a similar kind of sidebar will get mapped. For example, if one theme as a widget area called “Primary” and another theme has “Main” then the widgets will be mapped between these widget areas. Similarly, widgets would get mapped from “Bottom” to “Footer”.

The names for the widget areas used for the mapping groups were obtained by gathering statistics from all the themes on WordPress.org.

Widget Saved State on Admin Screen

With #23120 there is now an indication for whether or not changes to a given widget has been saved on the widgets admin screen. (Widgets in the Customizer already had a saved state by virtue of being registered as regular settings.) When first opening a widget, the button will say “Saved” and appear disabled. Once a change is made to the widget (e.g. a change event triggered), then the button will become enabled and say “Save”. If you try leaving the admin screen at this point, an “Are you sure?” message will appear alerting that if you leave your changes will be lost. If you cancel, then the first widget with unsaved changes will be scrolled into view, expanded, and focused. Upon hitting “Save” the spinner will appear and then upon a successful save it will switch to “Saved” and become disabled. The “Close” link has been changed to “Done” and it only appears when the changes have been saved. Note that the HTML5 checkValidity method will now be called on the widget form prior to attempting to submit, and submitting will be blocked if it returns false. If you have JavaScript-based fields in the widget, make sure that you trigger change events whenever changes are written into any hidden inputs; this was already a requirement for widgets in the Customizer.

Related Tickets

  • #10457: Parse shortcodes in text widgets by default
  • #23120: There should be indication that widget settings have been saved
  • #34115: oEmbed not working on author page without posts
  • #38017: Add widget instance to remaining widget argument filters
  • #39693: Fix missing assignment of widgets on theme switch
  • #40442: Widgets: Rename “Custom Menu” widget to “Menu”
  • #40854: Allow media to be embedded in Text widget
  • #41274: Improve discoverability of link URL in Image widget.
  • #41610: Widgets: Change “close” to “done?”
  • #41914: Widgets: Add gallery widget
  • #41969: Ensure Gallery widget is styled properly across widget areas in bundled themes
  • #42039: Widgets: Enable oEmbed support for Video widget
  • #42203: Ensure media & embeds in Text widget are styled properly across widget areas in bundled themes

See full list of tickets in the Widgets component with the 4.9 milestone.

#4-9, #dev-notes, #feature-oembed, #media, #media-widgets, #widgets

A New Themes Experience in the Customizer

WordPress 4.9 introduces a new experience for discovering, installing, and previewing themes in the customizer. Building on efforts during WordPress 4.7 development, this project prioritizes user flow, extensibility, and performance improvements.

A theme is the most fundamental aspect of customizing a site. This project seeks to unify the theme-browsing and theme-customization experiences by introducing a comprehensive theme browser and installer directly in the customizer.

The new flow seamlessly integrates theme management into the customization experience by bringing a new theme browsing framework into the customization interface along with the ability to install and live-preview a theme in a single click.

Screencast demonstrating the new themes experience in the customizer. Open the theme browser, search and browse installed and WordPress.org themes, and then install and preview in a single click.

The new theme browser is designed for extensibility. Third-party theme directories are encouraged to integrate with the core experience via plugins. Because the new browser is built on the core customize API, extending it is similar to extending any other part of the customization experience. As with every aspect of the customizer, this project approaches extensibiity modularly and in terms of both user and developer experience. The end of this post includes a technical overview of the new API.

Since WordPress 4.2, the customizer has loaded information about every installed theme every time the customizer loaded. In 4.9, theme data will only be loaded when a user visits the themes panel. The resulting performance improvement on every customizer load may be substantial on sites with a large number of installed themes, particularly on multisite networks.

For more information on the history and goals of this project, check out the original feature proposal from last year:

Feature Proposal: A New Experience for Discovering, Installing, and Previewing Themes in the Customizer

Theme Browsing Improvements

The changes since the previous merge proposal center around the experience of browsing themes. The customize sidebar now serves as the global index of theme sources (installed, WordPress.org, upload, and any additional sources added by plugins). In the customize preview area, a filter bar controls navigation within each of those sections.

Installed themes feature an instant search filter and a count of the results. WordPress.org themes also feature a search bar, in addition to the feature filter found in wp-admin and on WordPress.org. Rather than mimicking the existing WordPress.org and wp-admin theme browsers, the customizer features a simplified filter-oriented approach. The popular, favorites, and (randomized) featured sections are excluded in favor of a single, filter-driven section that defaults to showing the latest themes.

Over time, the customization team hopes to work with the theme review and meta teams to broadly evaluate the process of finding a theme. This future project will be driven by research into other product discovery experiences, as well as the experiences that third-party plugins build within the customizer for browsing themes from other sources. Ultimately, the goal is to bring an improved and unified theme browsing experience to WordPress.org, wp-admin, and the customizer, complete with new tags and other taxonomies. For now, the WordPress.org theme browser within the customizer is a starting point for a user-driven theme discovery experience.

Customize Themes API

The remainder of this post is dedicated to the technical implementation of the new themes experience, with three objectives: providing an example implementation of the customize API, documenting the feature to assist in future iterations, and introducing the API for extending the experience.

Customize Object Structure

The context for the themes experience is contained with a custom customize panel object, WP_Customize_Themes_Panel in PHP and wp.customize.ThemesPanel in JS. This panel is responsible for:

  • The overall theme browser UI layout
  • Installing themes (via wp.updates)
  • Loading theme previews
  • Updating installed themes from WordPress.org (via wp.updates)
  • Deleting installed themes (via wp.updates)

The custom themes panel object joins WP_Customize_Widgets_Panel and WP_Customize_Menus_Panel as core examples of the intended use for panels – as contexts for distinct features, rather than as generic containers for sections. It should generally not be necessary to modify the core panel object when extending the themes experience.

Theme browsing is done within custom customize section objects, which are instances of WP_Customize_Themes_Section in PHP and wp.customize.ThemesSection in JS. In 4.9, core provides two sections for browsing themes: Installed Themes and WordPress.org Themes. An additional section to Upload Themes will be added in a future release. Themes Sections handle the following:

  • Searching and filtering
  • Loading themes (from wp_prepare_themes_for_js() and WordPress.org), as theme control objects
  • Rendering screenshots for theme controls as they become visible (rather than loading all screenshots as soon as the theme data is loaded, for improved performance)
  • Opening and navigating the theme details modal

The themes section was initially introduced in WordPress 4.2. In 4.9, it has been completely reworked, most notably with the addition of built-in support for loading theme data from WordPress.org.

Each theme within the browser is represented with a customize control object, instances of WP_Customize_Theme_Control in PHP and wp.customize.ThemeControl in JS. Theme controls:

  • Display information about a single theme
  • Provide contextual buttons to install, preview, or install and preview themes depending on whether the theme is already installed
  • Contain an internal filter (and sorting) method in JS, which can be used for searching and filtering all theme controls within a section

While the theme control object was also initially introduced in WordPress 4.2, its 4.9 update completely refactors the control to use JS templates for rendering. This facilitates the updated themes section’s ability to quickly load data for large numbers of themes within a fully JS-driven experience. Hundreds of individual theme controls are dynamically created and deleted as users navigate the theme browsing interface, leveraging the customize API’s ability to scale by building on functionality initially introduced in WordPress 4.3 for the menus interface.

Extending the Core Experience

The modular structure of the customize API allows any aspect of the new themes experience to be modified or extended. In most cases, extensions will modify the themes section object, or create custom themes section instances or subclasses.

There are two types of WP_Customize_Themes_Sections: those that load all themes at once and search/filter theme locally (like the core installed section), and those that search and filter themes remotely, replacing every theme control object each time a search or filter changes. This distinction is managed with the filter_type parameter. When this set to local, all themes are assumed to be loaded from Ajax when the section is first loaded, and subsequent searching/filtering is applied to the loaded collection of themes within the section. This is how the core “Installed” section behaves – third-party sources with limited numbers of themes may consider leveraging this implementation. When filter_type is set to remote, searching and filtering always triggers a new remote query via Ajax. The core “WordPress.org” section uses this approach, as it has over 5000 themes to search.

With this parameter, it is theoretically possible to create a plugin that adds an instance of WP_Customize_Themes_Section that browses themes from a third-party source (using a custom action parameter). The customize_load_themes filter facilitates loading themes from third-party sources (or modifying the results of the core sections) within an Ajax call triggered by a themes section. In practice, it may be desirable to create a custom themes section object (subclassing WP_Customize_Themes_Section) to further customize the experience of browsing third-party themes within the customizer.

Additional Information & Next Steps

Most of the work for 4.9 was completed in #37661, with several follow up tickets to polish the feature. In addition to iterating on the WordPress.org theme browsing experience, there are a few improvements that are already planned for future releases:

  • #40278 – Introduce theme uploading in the customizer
  • #42046 – Clarify active and previewed themes
  • #42140 – Improve plurality of the themes count string

Here is the complete design flow for the new theme browser within the customizer, courtesy of @folletto:

Mockups of the user flow through the customize themes experience in 4.9, with additional elements for future releases

Please test the new themes experience in the 4.9 betas and share any feedback or bugs that you find on trac and in the comments.

#4-9, #customize, #dev-notes, #themes

4.9 Beta 4 postponed until October 24th

Due to travel and illnesses, we're pushing the Beta 4 release to October 24, 2017 at 22:00 CDT / October 25, 2017 at 3:00 UTC.

Note that we still intend to release RC as currently planned on the 4.9 release schedule next Monday, October 30th.

#4-9

Changes to the screen-reader-text CSS class in WordPress 4.9

The screen-reader-text CSS class is a small bit of CSS used in WordPress to visually hide text and make it still available to assistive technologies, screen readers, and any other software reading a page.

For a number of years, this CSS class has used an incorrect syntax for the clip property to deal with old Internet Explorer versions. WordPress 4.8 officially dropped support for Internet Explorer versions 8, 9, and 10. This is a good opportunity to update screen-reader-text to a modern, correct syntax and standardize it across the codebase. Furthermore, the clip property is deprecated: some browsers may still support it, but it is in the process of being dropped and it may cease to work at any time.

Worth noting this change applies only to the CSS class used in the WordPress admin pages.

Here’s how the old CSS class looks like:

.screen-reader-text {
	position: absolute;
	margin: -1px;
	padding: 0;
	height: 1px;
	width: 1px;
	overflow: hidden;
	clip: rect(0 0 0 0);
	border: 0;
	word-wrap: normal !important;
}

And here’s how the new CSS class looks like in WordPress 4.9:

.screen-reader-text {
	border: 0;
	clip: rect(1px, 1px, 1px, 1px);
	-webkit-clip-path: inset(50%);
	clip-path: inset(50%);
	height: 1px;
	margin: -1px;
	overflow: hidden;
	padding: 0;
	position: absolute;
	width: 1px;
	word-wrap: normal !important;
}

The only changes are the clip property value new syntax and the introduction of clip-path.

In the vast majority of cases this small change shouldn’t require any update to plugins and themes. There’s only one case to be aware of and that’s when the screen-reader-text CSS class is used to dynamically reveal some text. In a very few cases, WordPress itself reveals some visually hidden text. For example, when there’s no JavaScript support or on small screens, screen-reader-text gets reset to make the visually hidden text visible again:

.no-js .some-element .screen-reader-text {
	position: static;
	-webkit-clip-path: none;
	clip-path: none;
	width: auto;
	height: auto;
	margin: 0;
}

If you’re using a similar CSS technique in your plugin or theme admin pages, don’t forget to reset the new clip-path property too.

For more details, see the related changeset and Trac ticket.

#4-9, #dev-notes

Code Editing Improvements in WordPress 4.9

The themes outlined for WordPress 4.9 are “editing code, managing plugins and themes, a user-centric way to customize a site, and polishing some recently added features over this last year.” Within the themes of editing code and polishing recent features, we’re improving the code editing functionality in the Customizer’s Additional CSS feature, the Custom HTML widget, and the Plugin and Theme file editors. We included these improvements to code editing among the 4.9 goals and this release is packed with them.

CodeMirror: Syntax Highlighting, Linting, and Auto-completion

The most visible and drastic improvement to code editing in 4.9 is that there is now an actual code editing control rather than just a textarea input. If you’ve been using WordPress for a long time (over 8 years), this may sound like déjà vu. Syntax highlighting for the theme and plugin editors was originally introduced in WordPress 2.8 (#9173) but it was removed shortly after in 2.8.1 due to browser compatibility problems with the “CodePress” library (no relation to WordPress). So in the 8 years since the feature was re-proposed in #12423, after considering a slew of code editor libraries, we decided on incorporating CodeMirror:

CodeMirror is a versatile text editor implemented in JavaScript for the browser. It is specialized for editing code, and comes with a number of language modes and add-ons that implement more advanced editing functionality. ¶ A rich programming API and a CSS theming system are available for customizing CodeMirror to fit your application, and extending it with new functionality.

You have probably already used this CodeMirror library a lot online, since it powers the editors in many familiar products and services including Brackets.io, Bitbucket, Chrome’s DevTools, Codepen, Firefox Developer Tools, GitHub, and JSFiddle, among many others. In the WordPress world specifically CodeMirror is also very familiar. Jetpack switched from ACE to CodeMirror in 2013 for its Custom CSS module, and there are close to 100 search results for CodeMirror on the plugin directory. Many of them should be updated to re-use CodeMirror as bundled with core as well. See below for some details on how to do that.

The syntax highlighting abilities of CodeMirror can help authors catch many mistakes visually while writing code, as the color coding can quickly clue in that something isn’t right. In addition to color coding, WordPress also enables by default the add-ons which will auto-close brackets and tags, and then also highlight matching braces and tags which have already been written.

CodeMirror also supports linting to actually add explicit error checking beyond just stylistic helps. WordPress is initially bundling the following linters: CSSLint, JSHintHTMLHint, and JSONLint. See #41873 for adding a PHP linter as well, though as described below, the theme and plugin editors have a more robust means of checking for PHP errors by running the code on the server itself. The linters will report either errors or warnings with your code:

When a linter finds an error in your code (CSS, HTML, JS, or JSON) the code editor in WordPress will prompt you to fix the error before allowing you to proceed with saving. The nature of this error notice varies by whether the code editor is in Custom CSS control, Custom HTML widget, or the file editor.

Another feature of CodeMirror which reduces mistakes is auto-completion (or hinting). As you start typing out a CSS property, JavaScript DOM object, or HTML tag, an autocomplete dropdown will appear which you can use your keyboard to select an option:

 

There is still room for improvement with auto-completion (see #42213), but the feature does help suggest possibilities when you generally have an idea of what you’re wanting to enter.

Theme and Language Modes

For the CodeMirror library now bundled in core, we decided to not include any of the alternate themes, so the default theme is used with some styles added to bring it in line with core. Additionally we also did not include all of the language modes, as many would be very unlikely to be relevant in the WordPress context (e.g. Fortran). The WordPress-relevant modes we are including with the core bundle are: clikecss, diff, htmlmixed, http, javascript, jsx, markdown, gfm, nginx, php, sass, shellsql, xml, and yaml. If a plugin wants to use a mode that is not bundled with core, they may bundle and enqueue the mode script separately (e.g. fortran.js); a plugin may also bundle and enqueue a custom theme if desired.

Accessibility and User Preference

One of the biggest challenges when exploring the incorporation of a code editor library into WordPress was the concerns raised regarding accessibility. For users of screen readers, a plain textarea is just going to be easier to navigate and use. CodeMirror does have an inputStyle option which:

Selects the way CodeMirror handles input and focus. The core library defines the "textarea" and "contenteditable" input models. On mobile browsers, the default is "contenteditable". On desktop browsers, the default is "textarea". Support for IME and screen readers is better in the "contenteditable" model. The intention is to make it the default on modern desktop browsers in the future.

The code editor in WordPress goes ahead and explicitly defines contenteditable as being the default for both desktop and mobile due to better accessibility. Nevertheless, since there are still accessibility concerns we decided to not yet integrate CodeMirror in the post editor’s Text tab; as CodeMirror is enabled by default it could impede users of screen readers from performing the primary writing workflow upon upgrading to 4.9. Additionally, it doesn’t make sense to work on integrating CodeMirror in the post editor since it is being heavily revamped right now in Gutenberg; we should instead focus on integrating CodeMirror into Gutenberg itself.

Lastly, if a user still does not want the CodeMirror library to be used when they edit code then there is now a user preference to turn it off. It is available on one’s user profile and it is called “Syntax Highlighting”. Again, it is enabled by default:

Additional CSS Integration

When the Additional CSS feature was introduced in 4.7, it used a plain textarea to edit the CSS code in the Customizer. For several years prior, Jetpack had already featured a Custom CSS module but it allowed CSS to be edited via a CodeMirror editor on an Edit CSS admin screen. After 4.7 was released, Jetpack was updated to use Additional CSS in the Customizer instead, but enhanced it with the CodeMirror editor it had used on its Edit CSS admin screen. So now in WordPress 4.9, core is following suit and integrating CodeMirror into the Additional CSS feature as well (#38707), and there’s now an issue for Jetpack to newly re-use CodeMirror as bundled in core.

One key improvement from the initial implementation of Additional CSS is in regards to the detection of syntax errors. In 4.7 the error detection logic merely checked to make sure that the number of braces, brackets, and parentheses were balanced. This was not ideal because there were false positives when a balancing character was present in a comment (e.g. #39198). The goal was to eventually harden validation of CSS syntax validity by utilizing a tokenizer/parser (#39218). Instead of having to implement this logic in PHP, however, we now rely on client-side logic via CodeMirror and CSSLint to check for CSS errors and the unreliable server-side validation has been removed.

Code Editor Customizer Control

As when the Additional CSS feature was first introduced as being extensible, the updates feature new extensibility as well. When the feature was under development in 4.7 we debated whether or not to add a reusable code editor control for the Customizer. At that time we decided to opt for a regular textarea control with some enhancements since there wasn’t enough unique about the code editor to justify a separate control at that time. With the availability of CodeMirror, however, there is now justification for a reusable code editor Customizer control (#41897). This control is what is used to power the Additional CSS editor.

The code editor control may be registered in PHP via instantiating the WP_Customize_Code_Editor_Control class as can be seen in core. It allows you to pass a code_type param to indicate the file type being edited. Alternatively, an editor_settings array param may be passed which is the same format the new wp_enqueue_code_editor() function accepts (described below).

As with any Customizer control, the code editor control may also be added dynamically with just JavaScript. One example of this can be seen in the Customize Posts CSS plugin. Another example would be to add a second code editor control for Additional CSS to show up in the Colors section of the Customizer:

wp.customize.control.add( new wp.customize.CodeEditorControl( 'custom_colors', {
	section: 'colors',
	priority: 100,
	label: 'Custom CSS',
	editor_settings: {
		codemirror: {
			mode: 'css'
		}
	},
	setting: 'custom_css[' + wp.customize.settings.theme.stylesheet + ']'
} ) );

The code editor control registered for Additional CSS can itself also be extended. Either the registered custom_css control can be swapped out for a subclass of wp.customize.CodeEditorControl in JS (as seen in Jetpack PR), or the existing control can be modified at runtime. For example, in keeping with 4.7’s Custom SCSS Demo plugin, here is how you can dynamically change the Additional CSS control to use SCSS instead of plain CSS:

wp.customize.control( 'custom_css', function( control ) {

	/*
	 * CodeMirror gets initialized once the control's containing
	 * section is expanded. Note that if the Syntax Highlighting
	 * user preference is disabled, then the deferred will be
	 * rejected.
	 */
	control.deferred.codemirror.done( function() {
		var scssOptions = {
			mode: 'text/x-scss',
			lint: false, // CSSLint doesn't like SCSS.
			// The lint-marker gutter is automatically
			// toggled when lint option changes. 
		}
		_.each( scssOptions, function( value, option ) {
			control.editor.codemirror.setOption( option, value );
		} );
	} );
} );

And similarly, here is how you can change the default from CSS to SCSS via PHP:

add_action( 'customize_register', function( $wp_customize ) {
	$control = $wp_customize->get_control( 'custom_css' );
	if ( $control instanceof WP_Customize_Code_Editor_Control ) {
		$options = array();
		if ( isset( $control->editor_settings['codemirror'] ) ) {
			$options = isset( $control->editor_settings['codemirror'] );
		}
		$control->editor_settings['codemirror'] = array_merge(
			$options,
			array(
				'mode' => 'text/x-scss',
				'lint' => false,
				'gutters' => array(),
			)
		);
	}
}, 11 );

Custom HTML Widget Improvements

In WordPress 4.8.1 a dedicated Custom HTML widget was introduced in order to take over the role the Text widget had for adding arbitrary markup to sidebars, as the Text widget in 4.8 featured the TinyMCE visual editor. This new Custom HTML widget was introduced as essentially a clone of the old Text widget, aside from the absence of the “automatically add paragraphs” checkbox. Well now in WordPress 4.9 the Custom HTML widget comes into its own as it also now incorporates CodeMirror to provide users with syntax highlighting, auto-completion, and error checking. As with the Additional CSS feature, if you make a coding error in the Custom HTML widget, you will be blocked from saving until you fix the error. This guards against a misplaced div tag from breaking your site’s entire layout.

On multisite installs or any site on which an admin user lacks the unfiltered_html capability, there are restrictions for what HTML a user can provide in post content, Text widgets, and Custom HTML widgets alike. In 4.8.1 we resorted to listing out some common tags that would be illegal when a user cannot do unfiltered_html. With CodeMirror, however, this is greatly improved due to its integration with HTMLHint and because it is extensible to allow custom rules to be added. There is now a custom kses rule for HTMLHint (htmlhint-kses.js) which checks HTML for any tags or attributes that are not returned by wp_kses_allowed_html( 'post' ). This means that we don’t need to tell users what they can’t do if they have no intention of doing it in the first place, and HTMLHint provides contextual inline error reporting when they do provide something invalid. Plus, since saving is blocked when there are errors, a user’s illegal HTML will not be silently stripped from them when they attempt to save (as wp_kses_post() is still applied on the content when saving on the server).

The CodeMirror component in the Custom HTML widget is integrated in a similar way to TinyMCE being integrated into the Text widget, adopting the same approach for integrating dynamic JavaScript-initialized fields. See custom-html-widgets.js which exports a wp.customHtmlWidgets object to JS.

Just as CodeMirror has been integrated into the Custom HTML widget, once 4.9 is released a logical next step would then be to integrate CodeMirror into Gutenberg’s Custom HTML block, as per PR comment. Similarly, once CodeMirror is available in core it can then be explored for use in Gutenberg’s Text view (see issue).

Theme and Plugin File Editors

Now, about those theme and plugin editors. The file editor in WordPress has been the subject of much debate and skepticism over the years. This may be also why hasn’t received a lot of love in terms of improvements. For reasons why the file editor is still a valuable part of WordPress in its mission to democratize publishing, please see @melchoyce‘s post “From No Code to Pro Code”. She goes on to outline a few ways that the file editor can be improved and in WordPress 4.9 almost all of them have been implemented and beyond.

Nevertheless, when a user first visits the theme or plugin editor, they will be presented with the new warnings as follows:

Notice how the theme editor has a link directing a user to the Additional CSS feature in the Customizer. It is the hope that CodeMirror will be primarily used in Additional CSS and the Custom HTML widget, but for users who do need to make theme and plugin changes the editors have been vastly improved.

The file editors now also feature the same CodeMirror-powered syntax highlighting, auto-completion, and error checking. The allowed file extensions in the file editors can edit have been expanded to include formats which CodeMirror has modes for: conf, css, diff, patch, html, htm, http, js, json, jsx, less, md, php, phtml, php3, php4, php5, php7, phps, scss, sass, sh, bash, sql, svg, xml, yml, yaml, txt. In addition to increasing the number of editable file types, the file editors also now allow you to edit files deeper than two directories deep. And now given that the file list can be much longer than before, the files and their directories are now presented in an scrollable expandable tree like most editors provide:

When editing CSS, JS, HTML, and JSON files there is the same error checking powered by client side linters. As with Additional CSS and the Custom HTML widget, if a linter detects an error it will display an error and block you from saving the change. Here there is also a way for a user to override the error to proceed with saving anyway:

When editing PHP files, however, client-side linting is not enough (though it would be a nice enhancement, see #41873). If attempting to call an undefined function this will not be a syntax error, but it will cause a fatal error and whitescreen your site. The plugin editor did previously have some basic safeguards for this by temporarily deactivating the plugin and then re-activating it in a sandbox to check for fatal errors, though it was not very reliable (see #39766). And even when it was able to check for errors, a fatal error would result in the plugin being deactivated, a plugin which could be critical to a site to function properly. For themes on the other hand, there was no such ability to temporarily deactivate the theme and do a sandboxed check for fatal errors since a theme cannot be deactivated like a plugin can.

Ultimately what was worked out in #21622 was a new sandboxed method for making PHP file changes in both plugins and themes. When attempting to save a PHP file edit for a plugin or theme, during the user’s save request WordPress will write the file to disk after first copying the old file’s contents into a variable. Then immediately after writing the change it will do a loopback request back to the file editor screen with the user’s same cookies to check to see if the PHP file edit would lock them out of the editor. If that loopback request generates a PHP fatal error, then the original PHP file is restored. Otherwise, if there is no fatal error then WordPress will open another loopback request to the homepage of the site to check if there is a fatal error generated there. If so, again, the PHP file edit is undone with the old version of the file restored. At that point, an error message is shown to the user informing them of what specifically the error was and prompting them to fix it. The user’s modifications to the PHP file remain in the editor for them to fix (also these save requests now happen over Ajax so the user never leaves the page). If they try leaving the page without fixing the error and successfully re-saving, they’ll get an “Are you sure?” dialog informing them they would lose their changes, in the same way as leaving the Customizer or the Add New Post screen. If the loopback requests aren’t able to complete, the file edits will also be reverted and the user will be prompted to use SFTP to edit the file.

The JavaScript powering the new updated interface for the theme and plugin editors is located in theme-plugin-editor.js, which exports a wp.themePluginEditor object.

Code Editor APIs

The Customizer code editor control, Custom HTML widget, and file editor all make use of an underlying “code editor” API that provides an abstraction on top of CodeMirror. In PHP there is the wp_enqueue_code_editor() function which is named and functionally similar to wp_enqueue_editor() for TinyMCE. The wp_enqueue_code_editor() function takes an array of args, including the ability to specify the file type that you intend to edit, or else the file name itself. Alternatively, you can pass a codemirror array arg that has the same structure as what you would pass when initializing CodeMirror in JS. Then depending on the language mode that is either explicitly provided via codemirror arg or which is deduced from the file or type args, the function will specify various defaults depending on the selected mode. For example, if editing CSS then it will enable linting and if editing HTML it will enable the auto-closing of tags. Once the settings array is fully assembled it is then passed into a wp_code_editor_settings filter to give plugins a chance to further modify the settings. If this filter returns false or if the user had previously disabled the syntax highlighting preference, then the function will return false and no scripts will be enqueued. Otherwise, the function will proceed to then enqueue the code-editor script and style along with the wp-codemirror script/style dependencies and then any supporting linter scripts.

The wp_enqueue_code_editor() function will exported its settings array to wp.codeEditor.defaultSettings in JS while also returning it to that a feature can directly pass it into the wp.codeEditor.initialize() API. This initialize method is modeled after CodeMirror.fromTextArea() in that it takes a textarea object or ID as its first argument and then the settings as its second. In addition to the settings exported from wp_qneueue_code_editor() the settings passed into the initialize method can also include several callbacks including onChangeLintingErrors, onUpdateErrorNotice, onTabPrevious, onTabNext. These callbacks are what the various integrations rely on to manage the displaying of linting errors as well as ensuring keyboard navigation.

Here is a simple example of turning the user’s bio into a CodeMirror HTML editor on their profile screen:

add_action( 'admin_enqueue_scripts', function() {
	if ( 'profile' !== get_current_screen()->id ) {
		return;
	}

	// Enqueue code editor and settings for manipulating HTML.
	$settings = wp_enqueue_code_editor( array( 'type' => 'text/html' ) );

	// Bail if user disabled CodeMirror.
	if ( false === $settings ) {
		return;
	}

	wp_add_inline_script(
		'code-editor',
		sprintf(
			'jQuery( function() { wp.codeEditor.initialize( "description", %s ); } );',
			wp_json_encode( $settings )
		)
	);
} );

As noted above, CodeMirror and its bundled modes and add-ons are registered in a wp-codemirror script handle. Also important to note here that this script does not define a global CodeMirror object but rather a wp.CodeMirror one. This ensures that other plugins that may be including other CodeMirror bundles won’t have conflicts. This also means that if you do want to include fortran.js from CodeMirror, that you’ll need to bundle it to call wp.CodeMirror.defineMode() instead of CodeMirror.defineMode(). A workaround for having to do this would be the following, but be aware of potential conflicts:

wp_add_inline_script( 
	'wp-codemirror', 
	'window.CodeMirror = wp.CodeMirror;'
);

Development History

The integration of CodeMirror into core was initially worked on in the Better Code Editing feature plugin on GitHub. A full development history can be found there in the issues, pull requests, and commit log.

The principal contributors to code editing in this release were @afercia, @helen, @georgestephanis, @obenland, @melchoyce, @westonruter, and @WraithKenny.

The key tickets related to code editor improvements in 4.9 are:

  • #6531: Recursively search for files in theme and plugin editors
  • #12423: Include default code editor
  • #21622: Validate or sandbox theme file edits before saving them (as is done for plugins)
  • #24048: Code Editors: Increase the usability of Code Editor’s files list
  • #31779: Warn users before using a built-in file editor for the first time
  • #38707: Customizer: Additional CSS highlight, revisions, selection, per-page, pop-out (partially completed for this release)
  • #39218: Customize: Harden validation of CSS syntax validity by utilizing tokenizer
  • #39766: Plugin does not gracefully fail when editing active plugin causes fatal error
  • #39892: Default value in Additional CSS
  • #41073: Linting code changes: prevent saving, or add confirm message
  • #41872: Code Editor: Minor accessibility improvements to the CodeMirror editing areas
  • #41887: Code Editor: Error disables the Update File button.
  • #41897: Code Editor: Add reusable code editor Customizer control

#4-9, #codemirror, #dev-notes