Proposal for JS Standards Revision: Removing Array/Function Whitespace Exceptions

Coding standards have been a recurring topic in the JavaScript Weekly Chat over the past few months. One rule in particular which has been the focus of much discussion are the exceptions for whitespace in arrays and function calls, which reads:

Always include extra spaces around elements and arguments:

[…]

Exceptions:

  • […] do not include a space around string literals or integers used as key values in array notation
  • Function with a callback, object, or array as the sole argument: No space on either side of the argument
  • Function with a callback, object, or array as the first argument: No space before the first argument
  • Function with a callback, object, or array as the last argument: No space after after the last argument

In the course of our chats, there has been some consensus around removing this “Exceptions” section entirely, though we considered to seek broader feedback on the decision, particularly in how it impacts overlapping PHP standards and existing code.

Why should this exception be removed?

The purpose of a coding standard should be to impose sensible rules for the sake of consistency and readability. In the case of consistency, a developer should be at ease both in writing and reading code.

The very existence of an exception is at odds with these ideals, harming consistency in that:

  • A code reader may not think to expect it if they are not familiar with the exception
  • A code writer may not know to apply it if they are not familiar with the exception. Or worse yet, one familiar with the rule may not know how to apply it.

The arrays and functions exception is notably egregious for being difficult to apply. Take, for example, the following snippet of code:

( function( wp ) {
	wp.foo = foo( 5, {});
	wp.bar(function() {
		console.log( 'Done' );
	});
	wp.baz( x, x + 5 );
	wp.baz(x => x + 5);
} )( window.wp = window.wp || {} );

This code is valid in its use of whitespace, but took considerable effort on the part of a developer well-versed in the standards to understand precisely where the exceptions do and do not apply.

Generally, exceptions increase the barrier to entry for new developers by imposing another prerequisite to becoming productive, increase overhead for existing contributors by requiring careful consideration of their application, and are anti-productive in the review hours wasted enforcing their inevitable mis-use.

Why should this exception not be removed?

All of the above notwithstanding, the exceptions concerning array or object keys at least have some basis in overlap with equivalent rules in the PHP Coding Standards. While I would argue that most all exceptions should be avoided, the focus of the first section is aimed primarily at function arguments, which tends to cause most uncertainty. It may be an agreeable compromise to remove only the exceptions impacting function arguments, leaving still the array and object key exceptions.

Standards changes should be carefully considered, as it has a large impact on existing code which applies the current standard, and on knowledge of developers who have already become familiar with the standards. However, my experience is that these exceptions aren’t particularly well-understood, and in-fact that eliminating them would be more in spirit with how whitespace is otherwise applied (“When in doubt, space it out.”).

What happens next if these exceptions are removed?

If consensus is reached, the following actions should be taken:

  • Our standards documentation are updated to remove the exception language
  • Our ESLint rules are updated to remove the exception
  • All new commits to WordPress core follow the new standards
  • Old code will only be refactored as part of a larger, codebase wide refactoring effort (see related effort at #41057)

What are your thoughts? Please share in the comments below.

#javascript, #standards

Converting Dashicons to SVG

Currently, WordPress uses a font to render all the icons. The goal is to convert to SVG. We’ve started the process, but there’s a lot more work to be done to make sure the SVGs are rendered properly.

Read more about the project’s purpose in a previous post by @melchoyce:

https://make.wordpress.org/core/2015/06/11/moving-dashicons-from-an-icon-font-to-svg/

Since that post, progress has been made on a new GitHub repo at github.com/ryelle/WordPress/ (the ones listed in the previous post are no longer being used). Issues and instructions on how to get started can be found there.

So far, the font code has been replaced with SVG code wherever possible. For the most part, the SVGs are displaying properly. Issues are being posted on the GitHub repo.

To summarize:

  • There are several places where the SVG is still not showing up. The code used to display the font is inconsistent, e.g. in the TinyMCE bar above the visual content editor.
  • There are likely many places that haven’t been discovered that need icons. For the most part, if you see a square, it’s a missing icon. I’ve gone through and noted everywhere that I’ve seen this, but that’s just one person.
  • The CSS styling of the SVGs is fundamentally different that what’s being used to style the font. We need people to style the SVGs so they look and behave the way the font currently does.
  • We need to clean out the old CSS (and HTML) code being used to display and style the font.
  • We need to QA test on a variety of devices and browsers.

Get started by joining the #design-dashicons channel on Slack. Meetings are held there every Friday at 7pm UTC. The next one is on Friday at 19:00 UTC.

#dashicons

Twenty Seventeen: Merge Proposal for 4.7

A note from @helen: Before we get into the proposal itself, I’d like to officially introduce its author, @davidakennedy, as a committer for bundled themes. We really should have done this ages ago, but now he’ll get to make a big splash with Twenty Seventeen. Congrats, David! 🎉


twenty-seventeen

The team behind Twenty Seventeen has reached that point that we’re ready to propose Twenty Seventeen as the new default theme for WordPress in 4.7. It’s an ambitious theme that focuses on a creative home page and an easy site setup experience for users.

Like last year, with Twenty Sixteen, the development process happened on GitHub. The theme will be merged into WordPress from the beta period on, and development will move to Trac. Some remaining tickets will move over to Trac at that time.

Features of Twenty Seventeen

Created with the feedback on previous default themes in mind, and the desire to reach a new audience, Twenty Seventeen was designed for business websites. It offers:

  • multiple sections on the front page, selected in the Customizer.
  • a striking asymmetrical grid.
  • custom color schemes, built on top of a monochromatic foundation, and adjustable via a hue picker.
  • different headline placement for pages, changeable in the Customizer, via theme options.
  • a great experience in many languages, thanks to language-specific font stacks.
  • SVG icons (a first for a default theme).
  • support for custom logo, custom header image and many post formats.
  • the use of new functions in Core for making child theming easier.

Contributions

As usual, a default theme couldn’t happen without the community. This year, Twenty Seventeen has benefited from 57 amazing contributors so far (up from 38 at this point last year). They have helped with:

  • triaging issues.
  • providing code reviews.
  • testing and recommending language specific font stacks.
  • improving the theme’s accessibility.
  • browser and device testing.
  • numerous bug fixes, code tidying and countless improvements.

Testing, Feedback and Next Steps

While contributors have tested Twenty Seventeen on various devices and browsers throughout the development process, edge cases still exist. Please test Twenty Seventeen in as many different environments as you can.

Until the merge deadline, contributors to Twenty Seventeen will work on the Core Merge milestone in GitHub, knocking out as many issues as possible.

A big thank you to everyone that has helped make Twenty Seventeen come to life.

#4-7, #bundled-theme, #twenty-seventeen

Feature Proposal: Better theme customizations via custom CSS with live previews

When people ask “why WordPress?”, some of the most common answers center around flexibility for users of all kinds, whether they’re building their sites primarily through code or UI. Let’s take the story of a user who does a little of both – we’ll call her Becky.

Becky is a pretty savvy user. She knows that you’re supposed to make child themes instead of hacking on a theme directly, because updates can wipe out your changes. She found that out the hard way when she first started using WordPress – she hardly knew what CSS or PHP were, but she knew there was a theme editor in the admin and that she could make tweaks to colors or remove the author byline pretty easily without having to figure out this FTP stuff. Later on, most colors could be changed with the customizer so having a child theme just to remove an author byline seemed like overkill, but it was certainly better than having it reappear every time her site updated, especially with auto updates turned on.

After a couple years with the same theme on her personal site, Becky felt it was time to change things up. She was pleasantly surprised to find some new features that made getting a theme set up a lot easier, especially when live previewing them. Still, though, that pesky author byline remained, and since her last child theme copied a template to get rid of the byline, she would have to set up a whole new one to do it again. Then Becky found an “Edit CSS” option and realized she could hide things using CSS without having to go through the entire child theme process. Now, it turns out that those CSS tweaks didn’t come with live previewing, and that functionality was provided by a certain plugin, but Becky got what she needed to get done a lot faster than she would have otherwise, and ended up with the site she wanted.

This isn’t one specific story, but it is a combination of user stories many have heard, witnessed, or even personally experienced. You could replace Becky with @helen and it would be 100% accurate. The theme editor is a dangerous but useful entry point to more deeply customizing your site – rather than outright removing it and cutting off that introduction not just to WordPress code but to the concept of web development at large, why not provide a far safer and more user-friendly alternative? This post will explain why custom CSS with live previewing is valuable for WordPress and propose an implementation for inclusion in 4.7.

Proposed solution: Custom CSS with live preview

When bridging the gap between advanced user and beginning developer, desired changes are typically visual tweaks, such as changing a font size or hiding something, that are theme-specific. These sorts of changes should not require that users take risks editing live files that might white screen their sites or jump immediately into developer-facing tasks such as using FTP. Therefore, the scope of this feature has been defined as a custom CSS editor that leverages the customizer for a user-friendly live preview experience. This live preview allows for users to try various tweaks to a theme before saving and setting their changes live.

There are hundreds of thousands (if not millions) of users making use of custom CSS plugins or other themes/plugins that have custom CSS capabilities, and the frequent suggestion of CSS fixes in support forums justify a core need for this functionality. When plugins and themes interact in unexpected ways, CSS snippets are often an efficient solution to fixing the particular problem on particular sites.

The CSS editor takes inspiration from the many plugins offering similar solutions, but with an updated approach that offers instant live previewing in the customizer. The proposal for 4.7 looks like this:

custom-css-proposal-demo

Notably, previewing CSS in the customizer allows the site to be navigated and previewed on different sized devices by leveraging existing core features, allowing users to visualize the impact of their changes across their site. Error messages are shown for common syntax mistakes to help users ensure that their CSS is formatted properly before saving.

In future releases, the interface can be iterated on to further improve usability. The long-term design vision provides functionality such as revisions, syntax highlighting, and in-preview selector helpers, and can be implemented iteratively over time (click through for the full version):

customizer-css-i2

CSS would be stored in a custom post type (without admin UI), with a post stored for each theme. The editor would be used to supplement and override theme styles rather than editing them directly, as users have long been advised that directly editing files may lead to lost changes during updates. Instead, custom CSS safely stays available through updating and switching themes, starting fresh for each new theme. Projects such as customize changesets (#30937) and revisions for customizer settings (#31089) would bring future enhancements to this feature and further leverage the opportunities that come with storing the data in post objects.

This is proposed as core functionality rather than remaining as plugin territory because it is designed as the first step toward a next generation of the existing theme editor in core, with a more refined feature set and safer, more user-oriented focus. The theme editor is not proposed to be removed at this time, though with the introduction of this feature it likely makes sense to introduce more friction before accessing the editor (#31779).

Documentation

To improve the user experience further, it is critical that a link to documentation and resources for learning CSS be included with useful help text. This could initially be the “CSS” codex page but would ideally live on a user or developer handbook of some sort eventually (perhaps the theme developer handbook?). This help text must be much more succinct than the help tab on the existing theme editor, conveying what CSS is, where to learn about specific rules, and explaining that it’s specific to each theme in only a few lines.

Help is needed to create a resource for using custom CSS in WordPress, and locate it on WordPress.org. There are some related resources on make/training and WordPress.com has a good introductory page that they may be willing to contribute. Translated versions will eventually be needed as well. If anyone is interested in improving this aspect of the feature, which will presumably live on WordPress.org, please comment on this post.

Security, Capabilities, and Multisite

While the proposal includes basic validation, it is not possible to fully sanitize CSS. For this reason, a new meta capability will be introduced for managing css, unfiltered_css. By default, this is mapped to the unfiltered_html capability.

Site administrators on multisite networks do not have the unfiltered_html capability by default. A plugin that remaps unfiltered_css to a different capability can be created to provide this access on multisite, where custom CSS is especially useful given the need to restrict the number of themes and child themes in the network. This is an area of potential evolution over time.

Related Customize API Improvements

There are a couple of customizer API improvements introduced as part of the implementation of custom CSS in the customizer. A new “Code Editor” customizer control (WP_Customize_Code_Editor_Control) is used for the CSS editor and can also be utilized in plugins and elsewhere in the future. It currently handles line numbers and basic code styling, and will eventually add enhancements such as syntax highlighting.

Additionally, the WP_Customize_Section class has a new “description_hidden” parameter, which locates the section description in the section header behind the help icon toggle (“?”), functioning in the same manner as the customizer panel descriptions.

Contributors

@johnregan3 is leading development of this project, based on initial work by myself (@celloexpressions). @folletto is leading design efforts, with a focus on the long-term growth of the feature for maximum usability.

The implementation takes inspiration from many of the numerous plugins and services that implement custom CSS, specifically including:

  • Simple Custom CSS (@johnregan3)
  • Modular Custom CSS (@celloexpressions)
  • WordPress.com Custom CSS in the design upgrade (Automattic)
  • Jetpack (Automattic)

Testing, Feedback, and Next Steps

Your help is needed in giving feedback on this proposal and testing the feature! To test, please apply the patch either via Trac or the PR (helpful reminder: grunt patch handles both) and try some custom CSS in the customizer using various themes.

Pending approval of this proposal, the next steps will be to finalize and commit the patch on #35395. Code review is ongoing in the GitHub PR linked on the ticket. Feedback on the feature in general and the specific implementation is encouraged via the comments on this post, with any more technical implementation discussion happening on the Trac ticket or GitHub PR.

#4-7, #css, #customize, #proposal, #themes

REST API Merge Proposal, Part 2: Content API

Hi everyone, it’s your friendly REST API team here with our second merge proposal for WordPress core. (WordPress 4.4 included the REST API Infrastructure, if you’d like to check out our previous merge proposal.) Even if you’re familiar with the REST API right now, we’ve made some changes to how the project is organised, so it’s worth reading everything here.

(If you haven’t done so already, now would be a great time to install the REST API and OAuth plugins from WordPress.org.)

A brief history of the REST API

The REST API was created as a proof-of-concept by Ryan McCue (hey, that’s me!) at the WordPress Contributor Summit in 2012, but the project kicked off during the 2013 Google Summer of Code. The end result was Version 1.0, which grew into a community supported initiative that saw adoption and provided for a solid learning platform. The team used Version 1 to test out the fundamental ideas behind the API, and then iterated with Version 2, which made some major breaking changes, including explicit versioning, the introduction of namespacing for forwards compatibility, and a restructure of the internals. Version 2 also led to the infrastructure of the REST API being committed to WordPress core in 4.4.

This infrastructure is the core of the REST API, and provides the external interface to send and receive RESTful HTTP requests. Since shipping in 4.4, the infrastructure is now used by WordPress Core for oEmbed responses, and by plugins like WooCommerce and Jetpack, enabling anyone to create their own REST API endpoints.

The team has also been hard at work on the API endpoints. This has included core changes to WordPress to support the API, including deeper changes to both settings and meta.

Today the REST API team is proposing the inclusion of a collection of endpoints that we term the “Content API” into WordPress Core.

Proposals for Merge

Content Endpoints

For WordPress 4.7 the API team proposes to merge API endpoints for WordPress content types. These endpoints provide machine-readable external access to your WordPress site with a clear, standards-driven interface, allowing new and innovative apps for interacting with your site. These endpoints support all of the following:

  • Content:
    • Posts: Read and write access to all post data, for all types of post-based data, including pages and media.
    • Comments: Read and write access to all comment data. This includes pingbacks and trackbacks.
    • Terms: Read and write access to all term data.
    • Users: Read and write access to all user data. This includes public access to some data for post authors.
    • Meta: Read and write access to metadata for posts, comments, terms, and users, on an opt-in basis from plugins.
  • Management:
    • Settings: Read and write access to settings, on an opt-in basis from plugins and core. This enables API management of key site content values that are technically stored in options, such as site title and byline.

This merge proposal represents a complete and functional Content API, providing the necessary endpoints for mobile apps and frontends, and lays the groundwork for future releases focused on providing a Management API interface for full site administration.

Content API endpoints support both public and authenticated access. Authenticated access allows both read and write access to anything your user has access to, including post meta and settings. Public access is available for any already-public data, such as posts, terms, and limited user data for published post authors. To avoid potential privacy issues we’ve taken pains to ensure that everything we’re exposing is already public, and the API uses WordPress’ capability system extensively to ensure that all data is properly secured.

Just like the rest of WordPress, the Content API is fully extensible, supporting custom post meta, as well as allowing more complex data to be added via register_rest_field. The API is built around standard parts of WordPress, including the capability system and filters, so extending the API in plugins should feel as familiar to developers as extending any other part of WordPress.

This Content API is targeted at a few primary use cases, including enhancing themes with interactivity, creating powerful plugin interfaces, building mobile and desktop applications, and providing alternative authoring experiences. We’ve been working on first-party examples of these, including a mobile app using React Native and a liveblogging web app, as well as getting feedback from others, including WIRED, the New York Times, and The Times of London. Based on experience building on the API, we’ve polished the endpoints and expanded to support settings endpoints, which are included as the first part of the Management API.

Authentication

The API Infrastructure already in WordPress core includes support for regular cookie-based authentication. This is useful for plugins and themes that want to use the API, but requires access to cookies and nonces, and is hence only useful for internal usage.

To complement the Content Endpoints, for WordPress 4.7 the API team also proposes merging the REST API OAuth 1 server plugin into WordPress Core. This plugin provides remote authentication via the OAuth 1 protocol, allowing remote servers and applications to interact securely with the WordPress API.

OAuth is a standardised system for delegated authorisation. With OAuth, rather than providing your password to a third-party app, you can authorise it to operate on your behalf. Apps are also required to be registered with the site beforehand, which gives site administrators control over third-party access. Access to these apps can be revoked by the user if they are no longer using the app, or by a site administrator. This also allows apps with known vulnerabilities to have compromised credentials revoked to protect users.

We’ve chosen OAuth 1 over the newer OAuth 2 protocol because OAuth 1 includes a complex system for request signing to ensure credentials remain secure even over unsecured HTTP, while OAuth 2 requires HTTPS with a modern version of TLS. While it is strongly encouraged for sites to use HTTPS whenever possible (Let’s Encrypt makes it easier than ever to do so), WordPress itself does not require HTTPS and we do not believe WordPress should make HTTPS a requirement for using the API. The additional complexity that OAuth 1 adds can be easily supported by a library, and many such libraries already exist in most programming languages. OAuth 1 remains supported around the web, including for the Twitter API, and we also provide extensive documentation on using it.

Authentication Beyond 4.7

One issue with OAuth over direct username and password authentication is that it requires applications to be registered on the site. For centralized OAuth servers this wouldn’t be a problem, but the distributed nature of WordPress installations makes this tough to handle: your application must be independently registered with every WordPress site it connects to. If you’ve ever had to create a Twitter or Facebook app just to use an existing plugin on your site, you’ll know this can be a less-than-optimal experience for users.

To solve this distribution problem, we’ve created a solution called brokered authentication. This allows a centralised server (called the “broker”) to handle app registration and to vouch for these apps to individual sites. It simplifies app registration by allowing app developers to register once for all sites, and improves security by allowing the broker to vet applications and revoke them across the entire network. The system is designed to allow multiple brokers; while the main broker is run at apps.wp-api.org, organisations can run their own broker for internal usage, and developers can run a broker locally for testing.

While the broker system has been running live at apps.wp-api.org for months, we want to stay conservative in our approach to the API, especially where security is concerned. We are therefore proposing brokered authentication for WordPress 4.8 to ensure we have further time to continue testing and refining the broker system. In addition, this will require an installation of the broker on a centralised server to act as the canonical broker for out-of-the-box WordPress. While apps.wp-api.org is currently acting in this role, this is currently hosted by a third-party (Human Made) on behalf of the API team. For long-term usage the broker should instead be hosted on WordPress.org, alongside the existing plugin and theme repositories. This migration will take time but we remain committed to continuing to develop and support the broker.

After Merge

After merging the REST API, the team plans to continue developing the API as before. We expect that integrating the REST API into WordPress core will bring additional feedback, and we plan on incorporating this feedback through the rest of the 4.7 cycle.

During the remaining parts of this release cycle and through into the 4.8 cycle, additional work will go into other parts of the API. This includes further work and refinement on the broker authentication system, including work on WordPress.org infrastructure. Additionally, we plan to continue working on the Management API endpoints, including theme and appearance endpoints to support the Customiser team. Both of these components will be maintained as separate feature projects on GitHub until they’re ready for merge into core.

The team remains committed to supporting the API in core, and the Content API will switch from GitHub to Trac for project management and contributions. This same process occurred for the API Infrastructure in WordPress 4.4.

Reviews and Feedback

With this merge proposal, we’re looking for feedback and review of the project. In particular, we’re focussing on feedback on the security of the API and OAuth projects, and are also reaching out to specific people for reviews. (We take the security of the API seriously, and bug reports are welcomed on HackerOne at any time.) Design and accessibility reviews for the OAuth authorisation UI are also welcomed to ensure we maintain the high standards of WordPress core.

Both the REST API plugin and the OAuth plugin are available on WordPress.org, and issues can be reported to the GitHub tracker for the API and the OAuth plugin respectively. We have released a final beta (Beta 15 “International Drainage Commission”) which includes the meta and settings endpoints.

With Love from Us

As always, this is a merge proposal, and is not final until 4.7 is released. We’re eager to hear your thoughts and feedback; the comments below are a perfect place for that, or you can pop along to one of our regular meetings. We’re also always available in the #core-restapi room on Slack.

We’d like to thank every single one of our contributors, including 88 contributors to the main repository and 23 contributors to the OAuth repository. Particular thanks goes to my (@rmccue) wonderful co-lead Rachel Baker (@rachelbaker), our 2.0 release leads Daniel Bachhuber (@danielbachuber) and Joe Hoyle (@joehoyle), and our key contributors for the 4.7 cycle: Adam Silverstein (@adamsilverstein), Brian Krogsgard (@krogsgard), David Remer (@websupporter), Edwin Cromley (@chopinbach), and K. Adam White (@kadamwhite). Thanks also to the core committers helping us out through the 4.7 cycle, including Aaron D. Campbell (@aaroncampbell) and Aaron Jorbin (@aaronjorbin), and to the fantastic release lead, Helen Hou-Sandí (@helen).

Thanks also to everyone who has used the REST API, and to you for reading this. We built the REST API for you, and we hope you like it.

With love, The REST API Team

#feature-plugins, #json-api, #merge-proposals, #rest-api

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

This is the feature merge proposal for the new themes experience in the customizer introduced with #37661. Here’s an overview of the current proposed UI:

Customizer themes design and user flow mockup

Customizer themes design and user flow mockup by @folletto.

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.

Walkthrough of the latest patch on #37661.

Walkthrough of the latest patch on #37661.

Background & History

The customizer originated as a tool for previewing and customizing themes and as such, was closely integrated into the theme browsing experience in wp-admin when it was introduced in WordPress 3.4. The theme browser and installer were rewritten in WordPress 3.8 and 3.9, respectively, offering a fast JavaScript-based way to explore, install, and switch themes.

Eventually, as the customizer’s role grew to that of a framework for live-previewing any change to a site, it became apparent that it would benefit from a more direct way to switch themes, without entering the wp-admin context. The Customizer Theme Switcher plugin was created, and after some refinement, merged into WordPress 4.2. However, while it initially included external links to install themes in the admin, these were eventually removed due to the jarring experience of unexpectedly leaving the customizer.

Currently, there is no indication that additional themes can be installed when viewing available themes in the customizer. For new users, it may take quite a bit of time to discover the ability to install themes, via wp-admin, or they may give up on WordPress before making this discovery. This is a usability dead-end where a user’s flow is disrupted in the process of discovering, installing, previewing, and activating themes, both on initial site setup and when considering a redesign.

When the theme switcher plugin was developed, the team made preliminary plans for a theme installation interface as a second phase of the project. Specifically, it would leave the “preview” context of the customizer but retain the same identity in the user experience. @folletto helped develop this initial concept in early 2015.

Technical Constraints & Requirements

There have been several technical limitations preventing theme installation in the customizer from being addressed previously. Most notably, such an interface requires “shiny” ajax-based theme installation, updates, and deletion, so that the user flow can persistently stay in the customizer themes interface rather than jumping to separate “installing” views. This is now possible with phase 2 of “Shiny Updates” in WordPress 4.6. Additionally, expansions of the customizer JavaScript and JS-templated controls APIs to better support dynamically-registered controls were needed to support theme installation within the customizer framework, and these were fully fleshed out for the customizer menus interface introduced in WordPress 4.3. With these technical constraints eliminated, theme installation in the customizer is now possible without additional significant improvements to the underlying themes or customizer APIs.

The customizer must currently be completely reloaded from PHP to preview a different theme. To perform a theme switch without a reload, theme-defined settings, sections, and controls would need to be updated dynamically with JavaScript. While the customizer internals have been working toward making this possible for some time, significant work remains to make inline theme switches possible. Therefore, changes to this part of the theme-switching workflow are out of scope for the current project, which focuses on the user-facing flow.

The biggest usability block that this limitation causes is that unsaved changes are lost when the theme is switched. Unsaved changes are currently handled by prompting users with an are-you-sure notice in the browser before making the switch. Unfortunately, limitations in JavaScript require the loading indicator to be hidden after the user decides to stay on the page or to continue to the new theme, causing confusion. In the new interface, this is further mitigated by displaying a warning that there are unsaved changes, with an inline button to save and publish them, at the top of the interface. With customize changesets (transactions) (#)30937, a “save draft” option could also become possible in the future, allowing changes to be saved (potentially automatically) without being published between theme previews.

Previewing Themes

One of the biggest challenges with theme installation in wp-admin, and opportunities in the customizer, is previewing themes. Currently, a customizer-like frame displays a preview hosted on WordPress.org, with limited content. Rather than opening this potentially-disorienting similar but different interface, the proposed flow de-emphasizes the distinction between installed and available themes. The primary action for available themes is now “Install & Preview”, which installs the theme and live previews it in one step.

Users can now see any theme on their site with their content and play with its options in the customizer in one click. If they decide it’s the wrong theme for their site, the themes panel can be quickly reopened and another theme selected and previewed with no harm done. A secondary action allows themes to be installed without instantly previewing, so that the installed themes tab can become a personal theme library of sorts, where users can save themes that they might want to try on their site. Installed themes being a filter along with the available theme headings unifies the previously-disorienting separation of themes and add-new themes on separate screens, with confusingly-separate search and header (add new/upload theme) functionality.

Proposed Themes Interface

Due to the tight integration with the existing system, with the existing theme control and section as well as internal elements in the customizer manager and theme details template requiring moderate modifications, this project was implemented as a patch and cannot be reasonably converted into a plugin and back. The patch has been available on trac for six+ weeks, with iterations continuing to improve and polish the new experience.

The technical implementation continues adapting the concepts present in the backbone.js-based themes experience in wp-admin to leverage the customizer API. With the themes experience natively built on the customizer framework, it should be much easier for developers to improve and maintain the core experience in the future as well as extending the core experience in a structured way.

A few highlights of the proposed details:

  • Installed themes are no longer loaded every time the customizer is opened, resulting in potentially significant performance improvements by only calling wp_prepare_themes_for_js() when needed. This also allows themes in the customizer to be fully disabled with remove_panel( 'themes' ).
  • The themes experience is unchanged on the top level of the customizer, but selecting the change theme button now opens a panel that fills the entire screen, as the preview is not relevant when considering a theme change.
  • The UI diverges somewhat from what is found in the theme installer in wp-admin (which will remain), particularly around the filters.
  • The theme details view is unified between installed and available themes; clicking on a screenshot opens the details view to match the admin UI.
  • Primary buttons are used where clicking them takes you away from the current page (ie, for previews); secondary buttons are used elsewhere.
  • The loading strategy attempts to balance performance with wait time by loading theme data from Ajax in large batches (100 themes) and following up by rendering screenshots as they become visible (as the existing interface does).

Usability Testing

Four usability tests have been conducted so far. The full test screencasts are available on Make/Design, alongside key takeaways. These tests expose a lot of largely-known issues with themes and the customizer in general, but did not reveal any significant issues with the proposed new theme browser. Because the tests were conducted in-person with a limited set of volunteers, additional testing with a broader user base would be ideal.

There has been design feedback since the user testing was conducted, resulting in some significant changes. @karmatosed has volunteered to coordinate additional testing in the next week to verify that the changes haven’t introduced usability regressions, and to test with a broader audience. Check out the call for user testing on make/design to help out here.

A visual record on a phone of the revised design has been posted on make/flow.

Extensibility

Because the new interface is built entirely on the customizer API, third-party plugins should now be able to integrate much more easily. This means that other theme marketplaces (including commercial themes) could realistically be browsed (and maybe even installed) from within WordPress, while leveraging the core UI exactly.

The presentational flexibility is available via the customizer API (with custom theme sections for other theme sources, and theme controls for individual themes), but there are likely some gaps in the ability to do this seamlessly in the internals. If anyone is interested in building this sort of functionality, please evaluate whether any additional hooks are needed so that they can launch alongside the new feature.

Review and Approval

In addition to a general core approval of this proposal, the following sign-offs are required before the feature could be approved for merge, based on the applicable elements of this list:

  • Flow (and mobile) review (see also an initial post)
  • Docs review
  • Security audit
  • Polyglots/i18n review
  • Design/UX review – tentative approval has been provided from @karmatosed and @folletto (with additional input from others in last week’s design meeting) with an expectation that minor adjustments will continue to be required. General design feedback is still welcome, but major changes are unlikely to be feasible at this point.
  • Accessibility review – @afercia completed an initial review, with the issues fixed in a subsequent patch. A comprehensive final review would be a good idea as well, since there have been significant design changes.
  • Code review – to be handled by @westonruter once the patch is otherwise deemed “ready” based on review from other teams.

To test, update to latest trunk and apply the latest patch on #37661. On your test site, open the customizer and “change” the theme. Try out the various filters, browse themes, and install and preview them. Also test the inline update and deletion functionality.

To meet the feature merge deadline for 4.7 (10/19), reviews from various teams and any corresponding iterations need to be completed by October 12th, leaving a week for final code review and commit. General feedback and specific reviews and action items should be provided as comments on this post.


Update: this feature was merged in 4.9.

#4-7, #4-9, #customize, #proposal, #shiny-updates, #theme-switcher, #themes

Feature Project Proposal: Notifications API

Most of the situations where WordPress sends an outgoing email can be classified as a notification. X just happened on your website and you should be aware of it.

Back when WordPress was a youngster, the only way to reliably notify a user was via email. In 2016 we have many more options, including push notifications to mobile platforms, desktop notifications to browsers, messages to chat apps, endless services via webhooks, SMS messages, or even notifications in the WordPress admin area. The list goes on. For many users, email is no longer the optimal delivery mechanism for ephemeral notifications.

To that end, let’s think about replacing wp_mail() with a modern API that allows developers to route notifications to services other than email, allow them to better modify notifications and the way in which they’re formatted, and allow them to do so without stepping on each others’ toes.

The current lack of a notifications API (or even an email sending API) can be easily summed up:

Problem: Plugin A wants to provide HTML emails, and Plugin B wants to send emails via an email delivery service such as Mandrill. Plugin C wants to disregard emails and send Slack notifications. It’s very difficult for these to co-exist.

Notification Destinations

There are only two types of destination for a notification in WordPress. Most notifications are actually notifications to a user account that get delivered via email because it’s the only contact information available for every user account. The remaining notifications are explicitly notifications to an email address rather than a user account (or not yet attached to a user account), such as when a user signs up for a blog and needs to click a confirmation link before their user account gets created.

With this in mind, you might be able to imagine a notification class in WordPress core that defaults to delivering notifications via email, but which can be extended by a plugin on a per-user and per-notification basis to deliver notifications via any of the means listed above. WordPress core would support delivery via email and provide the API that allows plugins to implement delivery via other means.

With a well-designed API, multiple plugins can co-exist in order to deliver different notifications via different mechanisms, format email notifications as HTML, easily disable notifications, change the delivery mechanism for email notifications, or provide a UI for users to manage their notification preferences and destinations.

Planning a Notifications API

I’d like to begin work on a feature project with the intent of designing and implementing such an API. I’d like to get input from authors of existing plugins that provide functionality such as delivering notifications via a service other than email, that override the default email delivery mechanism, or that implement extra notifications (such as e-commerce sale notifications), in order that the API can be backwards compatible and that we can get some plugin implementations built during the API’s development.

I already have some technical ideas regarding how the API might look, but I’m conscious that such an API needs to be well-designed before anyone jumps into writing code. Maybe we can even try some test-driven development? Who knows.

In addition, consultation and involvement with the team that are working on the two-factor authentication feature project is important as it implements several delivery mechanisms for 2FA codes that could potentially be made simpler with a notifications API.

Get Involved

Feedback is most welcome in the comments. Would you like to help out? Yes? Great. Let’s plan a date and time for a meeting in Slack and go from there.

Finally, a reminder that feature projects are not tied to a specific release of WordPress. This won’t make 4.7. It would be great if it was mature enough for 4.8, but we won’t be aiming for a particular release just yet.

#feature-plugins, #notifications

HTTPS Working Group

In WordPress 4.4 and 4.5, various pieces of work were done to improve HTTPS support in core, but not much has been tackled since then. To address this, I’m going to re-start the weekly chats in the #core-http channel in Slack. Fridays late afternoon UTC/GMT are good for me — does this work for other people who are interested in helping with HTTPS issues?

Although the HTTPS improvements are always ongoing and not tied to a particular release, it would be great to get some improvements into 4.7.

If you run a WordPress site over HTTPS only, support is very good and there are very few issues to contend with. If you’re running a multisite network on HTTPS there are a few small issues when adding new sites. However, the main HTTPS issues in core come from:

  • Enforcing the HTTPS scheme on assets (such as embedded images in post content, and enqueued JS and CSS).
  • Enforcing the HTTPS scheme on links, redirects, and canonical URLs.
  • Migrating an existing HTTP site to HTTPS.
  • Running a site that uses a mixture of HTTP and HTTPS.

The first two points — avoiding mixed content on HTTPS sites — need to be solved via an opt-in system (either via constants or filters) because enforcing these can cause issues with sites that run proxies (for example Cloudflare’s Universal SSL). Overall though, this ought to be a fairly straight forward set of enhancements to implement.

The third point is a potentially complex one which will need a lot of discussion and some ideas putting forward. How can core make life easier for a site owner who wishes to switch their site from HTTP to HTTPS? Should it be a case of being able to change the scheme in the URL on the General Settings screen or is there too much risk of breakage? What else can be done post-migration to aid the site owner, or will the opt-in enhancements for avoiding mixed content be enough?

The last point is one that, going forward, should be generally discouraged, however it needs to continue to be supported for multisite networks that use domain mapping and can’t serve every domain over HTTPS.

There’s an https keyword on Trac which has been applied to tickets that concern HTTPS issues. We’ll start going through this list in next week’s chat.

Here’s a bunch of further considerations that need to be taken into account while working on HTTPS issues:

  • Differing schemes, domains, and ports in the siteurl and home options.
  • Domain mapping
  • force_ssl_admin() usage
  • Self signed certs
  • No public access to admin URLs
  • Different HTTPS domain on front end (!)
  • HTTP site optionally available over HTTPS

Here’s a list of items that should be considered for enforcing over HTTPS:

  • Enqueued JS and CSS.
  • Post content, images, js, CSS, iframes,srcset, oembeds, forms.
  • How about other fields such as term descriptions, user bios, etc.
  • Force https links. Links to the current site.
  • Force https link in nav menus.
  • Force https redirects and/or canonical.
  • Force HSTS. (Probably not.)
  • Force https rest api endpoint.
  • Force https XML RPC.
  • Set https-only on cookies.

Let me know in the comments if you’d like to help out and if Fridays are good for the meeting time!

#https

Feature Proposal: Content Authorship in Menus, with Live Preview

The current navigation menus system is built around a paradigm that every menu item must be associated with an existing piece of content. However, this is problematic for new users, who may find themselves with the opportunity to build a menu before creating any content. #34923 seeks to improve this experience and eliminate this usability “dead end” by adding the ability to create new post objects (most notably pages) within the menus interface in the customizer.

content-authorship-nav-menus

Purpose & Goals

While this feature is aimed primarily at new users setting up their site for the first time, it may also be useful for users that are restructuring a site, or even if they want to add a page here or there and add it to their menu before filling out its contents. It’s important to note that posts and pages added here are stubs – only their title is filled out, and the content will be added later via the post editor. For that reason, most existing sites would probably maintain their existing workflows to create new pages via the post editor, publish them, and then add them to menus. This is of course still fully supported and the new proposal seeks to provide an alternative approach that may be better for different use cases such as new sites.

Because the feature is proposed to be located in the customizer, it also fully supports live preview. The live preview component can build user trust and confidence by letting users preview and interact with their site as changes are made, before they’re published.

Technical Considerations

To allow new content to be created in the customizer, posts are created with the auto_draft status. When the user saves & publishes in the customizer, these newly-created posts are transitioned to be published. In the customizer preview, the status is modified to protected to allow the posts to be previewed.

Ideally, term creation should also be a part of the menus UI. Unfortunately, terms to not currently have a status field, and implementing that or looking at alternative approaches is something that will take more thought. Thus, this feature is being built with future support for terms in mind, but without support currently.

By default, the ability to add new content depends on the appropriate capabilities and the show_in_nav_menus parameter when registering post types. Additionally, a new filter is proposed to allow authorship in menus to be disabled on a per-post-type basis.

Testing

User testing has been requested and there are several tasks that could be tested:

  • Create a new menu for a brand new site by creating pages and adding them to a menu, assign the menu to a location and publish it.
  • On an existing site, create new pages to add to an existing menu.
  • On a complex site with multiple menus create a new page once then add it to multiple menus.
  • On sites with custom post types, create new custom posts for any of the scenarios above.

Test with the latest patch on #34923 and make sure the customize posts plugin is not activated (it has conflicts). If anyone is able to conduct user tests that would be much appreciated.

Customize Posts Plugin

Part of the inspiration for this feature comes from the Customize Posts plugin, which has the ability to live-preview posts and post meta in the customizer. Only a very small portion of the plugin would make its way into core as part of the nav menus content authorship feature. However, the proposal is currently to establish the wp.customize.Posts namespace for future expansions of post-related functionality in the customizer. The existing plugin would extend this core namespace, and other plugins could do so as well.

There are currently no plans to consider the Customize Posts plugin for full merge into core; however, stay tuned for an upcoming feature project kick-off that will seek to explore the future of live preview in WordPress at a broader level.

Feedback & Next Steps

The latest patch is currently seeking feedback for accessibility, design, code review, docs, and general comments. Please test it and leave your feedback as comments on this post or the ticket, #34923. Given current timing the ticket is likely to target the 4.7 milestone.

One remaining piece to implement is a mechanism to inform the user that their new posts have been published and provide links to edit the posts in the admin. This could take the form of a notifications area in the customizer or preview, or happen inline within the menus UI as a notice using the customizer setting validation feature that’s new in 4.6. UX feedback and ideas for the potential approach here are needed, and it could also probably work to ship without this part for now.

#customize, #menus, #proposal

Proposal: More Shiny Updates

The Bleak screen of Sadness™ 😢 that users encounter when installing/updating/deleting plugins or themes is a terrible experience WordPress users. It’s not timely anymore and doesn’t reflect the values WordPress strives to adhere to. Instead, WordPress needs a simpler and more straight forward experience when installing, updating, and deleting items.

That’s why the Shiny Updates Team is proposing a merge of the Shiny Updates plugin into WordPress 4.6 💥. We’re eager to hear feedback from WordPress core contributors and users alike.

Old plugin install process

Existing plugin install process, showing The Bleak Screen of Sadness.

Purpose & Goals

The Bleak screen of Sadness™ is disruptive to user workflows, pulling them out of the context of plugins or themes, and dropping them into a screen filled with technical details that most users don’t care about or don’t understand. Shiny Updates deals with these details behind the scenes, maintaining the context of the triggered actions and leaving users with clear actions and results.

This caters to two core principles of WordPress, designing for the majority, and striving for simplicity. Users don’t really care about the internal process of installing or updating themes and plugins. Listing out these technical steps for them is unnecessary at best.

With Shiny Updates these actions also don’t require a page reload anymore, which creates a simpler workflow without context changes and lets users achieve their goals of an enhanced WordPress experience quicker.

We also revamped the whole Dashboard -> Updates page to improve simplicity and make the process of updating translations and WordPress core shiny as well. 🎉

Project Background

Whether it was through the update mechanism available under Dashboard -> Updates or the automatic updates introduced in version 3.7, WordPress has always been encouraging users to update their sites to the newest versions.

Plugin updates have been made shiny in WordPress 4.2, but now we want to extend this to other areas as well. Shiny Updates v2 improves the update process for themes, translations and even WordPress itself, as well as install and delete workflows for plugins and themes.
As of today, the plugin has been downloaded about 8,000 times and is actively installed on over 1,000 WordPress sites. We’ve gotten input from many users and core committers through GitHub and during regular meetings in the #feature-shinyupdates.

You can read more about the shiny updates flow with various visual records on make/flow, where we also shared results of the various user tests we did. Doing multiple rounds of user testing has really shaped the whole project and helped us refine the plugin and improve the overall usability of installing updates in WordPress.

Implementation Details

Shiny Updates builds upon the shiny plugin updates feature already existing in core, which basically consists of some JavaScript and Ajax callbacks for updating plugins in the background. As such, it can easily be extended by the new JavaScript parts of Shiny Updates. All new JavaScript functionality is available under the wp.updates umbrella.

Here’s it looks like in action:

In addition to that, we propose a revamped updates overview under Dashboard -> Updates. It’s simpler, more elegant, more shiny:

Shiny Updates Table

With Shiny Updates, the Dashboard -> Updates page gets a much needed overhaul

Relevant Core Tickets

Merging Shiny Updates into core would resolve a long list of outstanding trac tickets related to updates, including #31529, #31530, #31531, #31532, #31534, #31535, #31773, #33637 and #35032. All tickets related to Shiny Updates can be found here.

Remaining Issues

There are a few remaining bugs on GitHub, which will be resolved by Friday, June 3rd. Since the revamped updates table relies on plugin icons being returned by the Plugins API, the API needs to be changed as part of the plugin directory update. The new directory will launch well before the 4.6 release, so that shouldn’t be a big deal. As a bonus, this change would also enable us to fix #30186.

Contributors and Feedback

This is a proposal and is subject to revision based on your feedback. If you haven’t already tried out the plugin, please download and install it from WordPress.org or the comfort of your WordPress admin. You can review the current code and leave feedback at the project’s GitHub repository or in #feature-shinyupdates on Slack.

Thanks a lot to everyone who has been contributing to this plugin since its inception, especially @obenland for leading this project, @adamsilverstein for his numerous contributions, @mapk for helping with testing and UX, and @ocean90 for giving valuable feedback despite being super busy with leading 4.6.

So far we’ve received positive feedback from different core teams like the accessibility and design teams, and we have reached out to @drew who will review the docs once a core patch is ready.

#4-6, #feature-plugins, #merge, #proposal, #shiny-updates