Merge Proposal: Dark Mode

Dark Mode

Dark Mode has become a rapidly popular feature to many online tools and services in recent years and it’s about time WordPress joins in on this trend as well. Many websites such as Twitter, YouTube, Reddit and even macOS Mojave, Apple’s newest operating system have adopted this feature as one to help user’s who are looking at screens for long periods of time. Traditionally we’re use to seeing light backgrounds and dark text in a high contrast environment which can be damaging for the eyes.

If you have ever found yourself working on something late at night and having to make adjustments so the bright light doesn’t hurt your eyes so much, you’re in for a treat!

Say good evening to… Dark Mode

Dark Mode transforms the colours of the WordPress dashboard from bright white and grey colours to dark grey and black instead. This means you no longer need to squint or turn down your brightness setting trying to avoid things like headaches and eyestrain.

Whilst Dark Mode is a great way to personalise your setup, there’s a few things that it’s not. These include but is not limited to:

  • It is not a high contrast mode for accessibility needs
  • It is not a new admin colour scheme for WordPress
  • It is not a tool to aid in any health issues you may have (poor vision etc)

Your Questions Answered

1. What is Dark Mode?
Dark Mode is a new option available for each individual user of your WordPress website to change the dashboard style to a darker design, steering away from the classic white and grey design we’re all use to.

2. Why should this be in Core?
WordPress has always made use of lighter colours within the dashboard. Whilst this may be fine for many, some users may find it harder to read text on the page and it gives people the opportunity to experience their settings in a much nicer, and more comfortable design.

3. How would this be maintained in Core?
As this affects the entire WordPress experience in the dashboard, it would require at least a small group of people to actively maintain it as a component and would need continuous input between developers and designers when new features are rolled out.

4. Will this support Gutenberg?
No, Dark Mode supports TinyMCE (not the theme editable areas) but will not support Gutenberg right now. This is something that should be worked on in tandem with the Gutenberg core team. It’s been decided that a merge proposal with Gutenberg support is the most beneficial way forward at the moment. This is partly due to the nature of rapid weekly updates and changes that Gutenberg is facing which would make it difficult to properly maintain at the moment.

5. Which plugins will be supported? / How can plugins support Dark Mode?
Please refer to the plugin compatibility guide on the GitHub repository for more information on this. For most plugins, this will be a case of using an action hook to include the third party plugin’s Dark Mode stylesheet which is triggered when the current user has confirmed they’d like to use Dark Mode.

Currently, the only plugin which is natively supported by the Dark Mode plugin is Gutenberg. This is because Gutenberg is a feature plugin which will become part of the WordPress core and must be supported by default. No other plugins are to be supported at this time. Plugin developers wishing to save themselves time should try to use the default WordPress UI elements as much as possible.

And for the most important and most asked question of all…

6. Why isn’t this a colour scheme?
Admin Colour Schemes, since being added in WordPress 3.x change the colour of the admin toolbar and the side menu within the dashboard. Colour schemes, generally (and should only) change these two elements and nothing else. Dark Mode doesn’t affect either of these two elements. In fact, the sole purpose of Dark Mode is to change the style of the main content area in the dashboard. This means you can have a custom admin colour scheme enabled alongside Dark Mode if you really wanted to.

Testing & Merging

Dark Mode has already been thoroughly tested but should have further testing before merging to ensure that every element is styled just right. As it currently stands, Dark Mode has been designed in a class model which enables it to be placed within core very easily with the use of hooks.

Whilst there may be some changes required to port it over into the core stack, the current files required for it to actually work are only 2. The PHP code to check the user preference and the CSS file containing the styles meaning the task of actually merging could be relatively quick.

If you do find any issues, please report them by opening a new issue on GitHub.

Thank You!

I would like to give a big thank you to everyone who has helped get Dark Mode to where it is today. The development of the the plugin started on the 3rd October 2017. Since then, the plugin has seen contributors of various levels assist in testing, coding and designing the product we have now. Yay for open source communities!

“Try Gutenberg” Callout in WordPress 4.9.8

WordPress 4.9.8 will contain the “Try Gutenberg” callout, encouraging site owners to install the Gutenberg plugin, to test how their existing content and plugins works with the block editor. It also presents the option of installing the Classic Editor plugin, should they feel that they need more time to prepare for switching over to the block editor.

Screenshot of the “Try Gutenberg” callout in place on the Dashboard.

In WordPress 4.9.8, the callout will be shown to the following users:

  • If Gutenberg is not installed or activated, the callout will be shown to Admin users on single sites, and Super Admin users on multisites. (Based on the install_plugins capability.)
  • If Gutenberg is installed and activated, the callout will be shown to Contributor users and above. (Based on the edit_posts capability.)
  • If the Classic Editor plugin is installed and activated, the callout will be hidden for all users.

Actions and Filters

The callout is attached to the try_gutenberg_panel action. If you would like to remove it on sites that you administer, you can do so with this snippet:

remove_action( 'try_gutenberg_panel', 'wp_try_gutenberg_panel' );

The “Learn more about Gutenberg” link currently directs to https://wordpress.org/gutenberg (or your localised version). However, particularly for hosts, you may have special instructions for your customers to install Gutenberg. In that case, the try_gutenberg_learn_more_link filter allows you to change this link, like so:

function my_host_learn_more_link( $link ) {
    return '<a href="https://support.my.host/gutenberg">Learn more about Gutenberg at My Host</a>';
}

add_filter( 'try_gutenberg_learn_more_link', 'my_host_learn_more_link' ); 

#core-editor, #editor, #gutenberg

What’s New in Gutenberg? (21st June)

Coming back from a great WCEU, it was cool to see a lot of examples of what people are already building with Gutenberg and the overall sense of shared enthusiasm.

This release includes a new system for walking a new user through the interface via tips. There’s also a new iteration of the block sibling inserter that continues the effort to consolidate all the multiple interactions that are possible while reducing UI weight.

Previewing and auto-saves has also gotten a lot of work, improving the auto-save mechanism and allowing to preview changes to already published posts. There’s also a lot of bug fixes, details, improvements, and tightening of components and APIs. For example, creating a shared block from an HTML block now defaults to be in preview mode when a user inserts it.

3.1 🥦

#core-editor, #editor, #gutenberg

What’s new in Gutenberg (4th October)

1.3 🦍:

Other changes:

We welcome all your feedback and contributions on the project repository, or ping us in #core-editor. Follow the “gutenberg” tag for past updates.

#core-editor, #editor, #gutenberg

What’s new in Gutenberg 27th September

1.2 (and 1.2.1) 🦄:

Other changes:

We welcome all your feedback and contributions on the project repository, or ping us in #core-editor. Follow the “gutenberg” tag for past updates.

#core-editor, #editor, #gutenberg

Enhanced Settings API: Where we’re at

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

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

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

Prototype for WCEU

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

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

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

#accessibility, #settings

Preferred Languages: The Prototype

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

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

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

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

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

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

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

Nearby WordPress Events

In an effort to grow awareness of WordPress community events like WordCamps and meetups, a group of us have been working to upgrade the WordPress News widget, adding WordCamps and meetups, as Matt mentioned in his recent post. We’ve created a plugin (background) called Nearby WordPress Events for testing and iteration. It turns the existing News widget on the Dashboard into WordPress Events and News, with a short list of upcoming nearby events above the usual news items.

WordPress Events and News widget

Why?

The community that has been created around WordPress is one of its best features, and one of the primary reasons for its success, but many users are still unaware that it exists, and aren’t taking advantage of all of the resources that it makes available to them.

Inviting more people to join the community will help to increase its overall health, diversity, and effectiveness, which in turn helps to ensure that WordPress will continue to thrive in the years to come.

We think that wp-admin is the perfect place to display these events, because that’s the place where almost all WordPress users are visiting already. Instead of expecting them to come to us, we can bring the relevant information directly to them.

How does it work?

In order to display events that are “nearby”, the plugin uses a determined location for the current user. If a site has multiple users, each one will be shown the events that are close to their individual location. The widget tries to automatically detect a user’s location, but they’ll also be able to enter any city they like.

The WordCamp and meetup event data for the plugin is provided by a new api.wordpress.org endpoint [source, documentation].

Feedback

We’ve solicited the Community team for testing and feedback and have made several improvements. Now we’d like to take it to the next level and get feedback from the Core team, in preparation for a proposal to merge it into Core, perhaps for WordPress 4.8.

Specifically, we’d like to get testing and feedback about:

  • UX: What is the user experience like? Is it easy to find a local event near you? Do you have trouble changing your location? Have we built the widget in an accessible way? (cc +make.wordpress.org/design)
  • Location detection: Does the widget accurately detect your location? If not, be sure to report your approximate location at the time you started using the plugin/widget.
  • City search: Does it find the city nearest to you with the name you searched? How well does it work when searching in languages other than English? Character sets other than Latin? (cc +make.wordpress.org/polyglots)

The best place to file issues is the GitHub repo.

 

Kudos to everyone who worked to make this a reality: @andreamiddleton, @azaozz, @camikaos, @coreymckrill, @chanthaboune, @courtneypk, @dd32, @iandunn, @iseulde, @mapk, @obenland, @pento, @samuelsidler, @stephdau, @tellyworth

#nearby-wordpress-events

Image Widget Merge Proposal


As part of this year’s Customization Focus, @westonruter, @obenland, @adamsilverstein, @timmydcrawford, @gonom9, and I have been working on creating an image widget for core. This new widget lets you quickly and easily add an image to your site’s widget areas.

You may have previously seen this come up as a media widget on Trac, before we decided to split the widget up into individual media-focused widgets. Having single widgets makes them more discoverable, and eases the way forward for similar blocks in the Editor. The image widget is the first in a series of media-focused widgets we’ll be introducing to core.

You can check out the widget on GitHub, install the plugin from WordPress.org, or check out the Trac ticket.

Why make an image widget?

People want to add images to their widget areas. Visit any subject blog across the internet and you’ll likely find images in the sidebars. People add photos of themselves along with bio blurbs, link to their books, promote upcoming events with graphics, partner with other blogs and exchange ads, and add call-to-actions using images.

The current process for adding an image to your widget areas is quite painful. You need to:

  1. Upload or select an image in your media library.
  2. Copy the image URL.
  3. Go to the widgets admin screen, or the widgets panel in the Customizer.
  4. Create a new Text widget.
  5. Add the image to the Text widget using HTML, which is often a barrier for new or non-technical site maintainers. (See #35243 for work to add a visual mode to Text widget.)

This is a huge barrier to what should be a relatively simple task. This new image widget makes it much easier to add an image to your widget areas by natively integrating with core’s media library.

How is it implemented?

There hasn’t been any new widget types added to core in a long time; the Custom Menu widget was the last widget added in WordPress 3.0—almost 7 years ago! (The core themes Twenty Eleven and Twenty Fourteen did include their Ephemera widgets since then.) Since widgets are a very old part of WordPress, widgets in core have been very much entirely built using PHP with some Ajax sprinkled on top. In the time since WP_Widget was introduced in 2.8, WordPress has made dramatic shifts toward developing interfaces in JavaScript, including with the Customizer in 3.4 and the Media Library in 3.5, and more recently with the focus on the REST API.

Given that the media widgets are naturally interfacing with the media library JS, it is necessary that the media widgets make use of JavaScript to construct their UI instead of relying on PHP. Initial groundwork for shimming JavaScript into widgets was added in 3.9 via the widget-added and widget-updated events. A more recent proposal for making JavaScript more of a first class citizen can be found in #33507 and the media widgets incorporate some of its patterns that were also prototyped in the JS Widgets plugin. The media widgets make use of a Backbone View to manage the widget control’s UI and a Backbone Model for reading and manipulating the widget instance data.

Another unique aspect of how the media widgets work is how instance data is sanitized. Normally widgets write procedural code to sanitize instances via a subclassed WP_Widget::update() method. The media widgets, however, make use of a REST API schema returned from WP_Widget_Media::get_instance_schema() to sanitize instances declaratively. The WP_Widget_Media::update() method iterates over the schema and uses it to sanitize and validate the instance properties. Adding schemas to the base WP_Widget class is also proposed in #35574.

Please test

Please test the image widget. For now, you can grab the latest version of the widget on GitHub. You can either check it out locally using Git, or download a zip by clicking “Clone or download” → “Download ZIP.” Alternately, you can download the nightly version of the plugin from the WordPress.org plugin directory.

#image-widget, #media-widgets

Nextgen Bootstrap/Load Feature Project

The bootstrapping process of WordPress Core (affectionately called the “Bootstrap/Load” component around here) is a critical piece of the system, and everything else depends on it being reliable and performant. However, developers and system administrators also need it to be flexible enough to adapt to the requirements of their differing projects or environments. Large-scale WordPress installations often require substantial customizations to adjust for scalability and redundancy.

Considering the importance of this component, the documentation is not adequate, and very few people actually know what the exact flow is. More importantly, there isn’t a wide understanding of why specific decisions had been taken, and how later code depends on the bootstrap process.

This proposal aims to launch a feature project to work on the next iteration of the bootstrap component with a set of specific goals in mind.

Goals

To be able to guide the design process and have measurable success metrics, clear goals need to be defined.

Here’s an overview of what specific goals the project should aim for:

  1. The component has proper documentation for every step of the process.
    Documentation will include both clear comments in the source as well as an external documentation space that includes reference material, execution flow diagrams, best practices and examples of usage.
  2. The component models a modernized flow which still provides same sane defaults, but enables advanced use cases in a supported way.
    Customizing high-volume sites or specialized applications should be less “hacky”, and all of the major subsystems should provide reliable means of configuration/extension.
  3. The component adapts to differing contexts to optimize both performance and memory consumption where possible.
    The system should be able to intelligently load only the parts of the code that are strictly necessary for the current requests, through means of conditional execution flows, smart routing, proxy objects and autoloading. Special consideration should be given to the WP REST API endpoints to make them as fast and efficient as possible.
  4. The component offers a coherent way of supporting all versions of multisite (networks), reducing some of the idiosyncrasies that currently exist.
    The difference between single sites, networks of sites and networks of networks should be kept as small as possible so that less care needs to be taken to have the code work reliably with all of them.
  5. The component considers both backward compatibility as well as forward compatibility.
    It is of paramount importance that existing sites do not break due to the changes that will be proposed with this project. However, forward compatibility needs to be taken into account just as well, to create a next version of the bootstrap component that can easily grow with future requirements in a controlled way.

Project Phases

The project will have four different phases: Discovery, Design, Execution and Merge Proposal.

1. Discovery

The Discovery Phase aims to properly research and document the status quo. It will be a thorough analysis of source code, trac tickets and contributor discussions to decipher the reasoning behind the current implementation and what the requirements, strengths and weaknesses are. Documentation will be written in parallel, logging all findings and producing a better onboarding process for this component. Characterization tests will be written to be able to detect regressions when making changes in phase 3 later on.

2. Design

The Design phase will examine all the findings from phase one to design a new version of the bootstrap component that meets all the requirements and strengths while reducing some or all of the weaknesses and improving reliability, flexibility and performance.

We want to avoid having yet another component update that just grows organically. There should be strong principles in place that make sure that the new version is not only backward compatible but also forward compatible.

3. Execution

The Execution phase will create a modified fork/branch of WordPress Core, to allow for collaborative work on this new iteration of the bootstrap component.

Through automated tests, refactoring will be guided to implement the design from phase 2. The characterization tests from phase 1 will make sure that compatibility remains a given, even for “compatibility-enforced bugs”. Optional mechanisms to get saner results in such cases will be discussed on a case-by-case basis.

4. Merge Proposal

The Merge Proposal phase will be the final phase of the project, identifying a clean merge process and a proper migration path to merge the new version of the component into Core.

Metrics will need to be defined to have measurable and achievable goals that can objectively tell whether the Component is ready to be merged.

Contributions

During the initial Discovery Phase, contributions in the following areas will prove to be useful:

Advanced Use Cases

We need lots of data about the types of customizations that people use for their projects: bootstrap modifications (WP-CLI), complex network hierarchies, folder rearrangements, specialized caches, etc.

Problems With Current Code

We need to know about all and any challenges and limitations that you have been experiencing with the current bootstrapping flow: setups that were difficult or impossible to achieve, settings that didn’t yield the expected results, etc.

Documentation

Documentation will not only need to be written for the way the current code works, but also for all deprecated functionality, buggy behavior and unexpected side-effects. We are going for completeness, not ease-of-use here. Documentation should also cover best practices for modifying the bootstrap process.

Join us in #core-bootstrap to start contributing!

Thanks to Helen Hou-Sandì (@helen), Jeremy Felt (@jeremyfelt) and Aaron Jorbin (@jorbin) for their help in shaping this proposal.

#bootstrap-load, #core