Customizer Improvements in 4.7

WordPress 4.7 has been the most active release on record for the customize component, with four major feature projects merging and shipping with 4.7 and over 90 tickets closed as fixed. This post summarizes the highlights of the user and developer-facing changes.

4.7 CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. Feature Projects

Create pages within live preview during site setup

Add new pages while building menus and setting a static front pageStatic Front Page A WordPress website can have a dynamic blog-like front page, or a “static front page” which is used to show customized content. Typically this is the first page you see when you visit a site url, like wordpress.org for example.; outline your site directly in the customizer.

This project began with the ability to create posts and pages direction from the available menu items panel in the customizer, as originally proposed near the end of the 4.6 cycle:

https://make.wordpress.org/core/2016/06/16/feature-proposal-content-authorship-in-menus-with-live-preview/

Subsequent changes also added the ability to create new pages when assigning the front page and posts page in the Static Front Page section. Because this is now built into the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. dropdown-pages customizer control, themes and plugins can also allow users to create new pages for their options instead of relying on existing content. The homepage sections in Twenty Seventeen include this new allow_addition parameter. Here’s how to register a dropdown-pages control supporting new pages:

$wp_customize->add_control( 'featured_page', array(
	'label'          => __( 'Featured Page', 'mytextdomain' ),
	'section'        => 'theme_options',
	'type'           => 'dropdown-pages',
	'allow_addition' => true, // This allows users to add new pages from this dropdown-pages control.
) );

Additionally, a proposal for term statuses was developed as a first step toward expanding the menus functionality to work for creating and previewing taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. terms in a future release (see #37915).

Improvements to the Sliding Panels UIUI User interface

Customizer navigation is now faster, smoother, and more accessible.

This project tackled a series of tickets focused on improving the usability of the “sliding panels” UI in the customizer controls pane. The first step was to refactor the section and panel markup so that sections and panels are not logically nested. This is the biggest internal change to the UI and has a dedicated post going into the details:

https://make.wordpress.org/core/2016/09/28/changes-to-customizer-sliding-panelssections-in-wordpress-4-7/

This primary change resolved numerous problems with sections and panels not opening and closing properly, and eliminated situations where navigation to leave a section could become hidden. The next step was making section and panel headers “sticky” so that navigation is easier to access within long sections (such as for a menu); see #34343.

Finally, hover and focus styling for navigation in the customizer has been updated to use the blue-border approach found elsewhere in core, including for the device-preview buttons in the customizer, in #29158. This completes a refresh of the customizer controls pane’s UI design that began in WordPress 4.3 with #31336. The core UI now uses the following consistent UI patterns in the customizer:

  • White background colors are used only to indicate navigation and actionable items (such as inputs)
  • The general #eee background color provides visual contrast against the white elements
  • 1px #ddd borders separate navigational elements from background margins and from each other
  • 15px of spacing is provided between elements where visual separation is desired
  • 4px borders are used on one side of a navigation element to show hover or focus, with a color of #0073aa
  • Customizer text uses color: #555d66, with #0073aa for hover and focus states on navigation elements

Plugins and themes should follow these conventions in any custom customizer UI that they introduce, and inherit core styles wherever possible.

Any custom sections and panels, as well as customizations to the core objects in plugins and themes, should be tested extensively to ensure that they continue functioning as intended with all of these changes in 4.7. It’s particularly important to ensure that things like the use of color match the core conventions so that the user experience is seamless between functionality added by plugins and core.

Customize Changesets (formerly Transactions)

Browse your site and switch themes more seamlessly within the customizer, as your changes automatically persist in the background.

This project rewrote the internals of the customizer preview mechanism to make changes persistent. Each change made to a setting in the customizer is saved to a changeset (a new customize_changeset post type), facilitating future features such as scheduled changes, revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision., or saving and sharing drafted changes. Changesets also open the door to using the customizer to preview Ajax requests, headless sites, and REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. calls for mobile apps. In 4.7, changesets enable switching themes in the customizer without needing to decide between publishing or losing your customizations, as they’re automatically persisted in the background.

For more details on changesets, check out the two dedicated posts:

https://make.wordpress.org/core/2016/10/12/customize-changesets-formerly-transactions-merge-proposal/

https://make.wordpress.org/core/2016/10/12/customize-changesets-technical-design-decisions/

Custom CSSCSS Cascading Style Sheets.

Fine-tune your site and take your theme customizations to the next level with custom css in the customizer.

#35395 introduced a user-oriented custom CSS option in the customizer. Now that the base functionality is in place, it will be further enhanced in #38707 in future releases. Read the feature proposal for details on the implementation and why it’s important for core:

https://make.wordpress.org/core/2016/10/11/feature-proposal-better-theme-customizations-via-custom-css-with-live-previews/

There’s also a dedicated post that walks through the process of migrating existing custom CSS options in themes and plugins to the core functionality – be sure to follow those steps if your pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party or theme does custom CSS:

https://make.wordpress.org/core/2016/11/26/extending-the-custom-css-editor/

Other Changes with Dedicated Posts

4.7 features several other features deserving special attention. Read the posts for visible edit shortcuts (which expand the functionality of customizer partials), video headers (which extend the custom headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. feature), and starter content for more information:

https://make.wordpress.org/core/2016/11/10/visible-edit-shortcuts-in-the-customizer-preview/

https://make.wordpress.org/core/2016/11/26/video-headers-in-4-7/

https://make.wordpress.org/core/2016/11/30/starter-content-for-themes-in-4-7/

Additional User-facing Changes

With over 90 tickets fixed in the customize component in 4.7, we can’t cover everything here. But, here are a few more highlights:

Improved Custom Background Properties UI

#22058 introduces a more comprehensive and more usable custom background properties UI when a custom background is set up. There are now presets to control all of the detailed options at once, and the individual options are presented in a more visual way. Background size and vertical position are also now available as standalone options when using a custom preset.

Theme developers should update their add_theme_support() calls for custom-background to specify the default size, vertical position, and preset to reflect their default background image CSS. Perhaps the most significant improvement here is the ability for users to easily set up fixed full-screen backgrounds – and the ability for themes to make that behavior default if desired.

And even more…

4.7 also:

  • Loads the frontend preview iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser. more naturally, eliminating a lot of weirdness with JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. running in an unexpected location and ensuring that JS-based routing will work (#30028)
  • Allows the search results page to be previewed, and any forms that use the GET method in general can now be submitted whereas previously they would do nothing when submitted (#20714)
  • Hides edit post links in the customizer by default. Plugins, such as Customize Posts, can restore the links if they make post editing available in the customizer (#38648), although the visible edit shortcuts should generally be used instead.
  • Shows a cursor: not-allowed for mouse users when hovering over external links in the preview, as these can’t be previewed
  • Officially removes support for the customizer in Internet Explorer 8, preventing users of this outdated browser from accessing the customizer at all (#38021)

Additional Developer-oriented Changes

Hue-only Color Picker

#38263 adds a hue-only mode to the Iris color picker, wpColorPicker, and WP_Customize_Color_Control. Built for Twenty Seventeen’s custom colors functionality, the hue-only mode allows users to select a hue and saves the hue degree as a number between 0 and 359. To add a hue-color control:

$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'colorscheme_hue', array(
	'mode' => 'hue',
	'section' => 'colors',
) ) );

As demonstrated in Twenty Seventeen’s custom colors strategy, the hue-selection strategy opens up a whole new world of possibilities for custom color options in themes. Rather than introducing numerous text and background color options and requiring users to adjust them to ensure that adequate color contrast is provided, themes can consolidate their color options into one or more hue pickers. Then, the corresponding use of hsl colors in CSS allows themes to define color patterns where users customize color hues without impacting the lightness of a color option, thereby preserving the designer’s use of proper contrast between text and background colors, and any use of color lightness for visual hierarchy. Check out the implementation in Twenty Seventeen for inspiration (including instant live preview).

Fix Sections that .cannot-expand

When creating custom customizer sections that, for example, display an external link but don’t actually expand to show section contents, the cannot-expand class can be added to the section title container to prevent JS events and CSS hover/focus styles from being applied. Be sure to also remove the tabindex="0" from the container if you copy the core code since your custom section shouldn’t be focusable if it can’t expand (and any contained links or buttons would be keyboard-focusable automatically). See #37980 for details.

Allow Plugins to do Comprehensive Late Validation of Settings

To account for custom subclasses of WP_Customize_Setting that don’t apply the customize_validate_{{$setting_id}} filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., this filter now will be applied when WP_Customize_Manager::validate_setting_values() is called. This ensures that plugins can add custom validation for every setting. For more, see #37638.

Credits

Huge thanks to the 61 people (and counting) receiving props for the 120+ customize component commits in 4.7 (as of RC2): @westonruter, @celloexpressions, @afercia, @sirbrillig, @ryankienstra, @helen, @ocean90, @melchoyce, @bradyvercher, @folletto, @johnbillion, @delawski, @karmatosed, @georgestephanis, @dlh, @curdin, @valendesigns, @mattwiebe, @michaelarestad, @joemcgill, @sstoqnov, @lgedeon, @mihai2u, @coreymcollins, @stubgo, @utkarshpatel, @desrosj, @odysseygate, @johnregan3, @aaroncampbell, @mapk, @iseulde, @mrahmadawais, @vishalkakadiya, @sayedwp, @hugobaeta, @jonathanbardo, @jorbin, @tristangemus, @deltafactory, @kkoppenhaver, @seancjones, @Presskopp, @Mista-Flo, @nikeo, @adamsilverstein, @lukecavanagh, @coffee2code, @peterwilsoncc, @presskopp, @pento, @Kelderic, @sebastian.pisula, @mckernanin, @FolioVision, @MikeHansenMe, @welcher, @cdog, @grapplerulrich, @iamfriendly, @flixos90.

 

#4-7, #customize, #dev-notes

Starter content for themes in 4.7

One of the hardest things for people setting up sites with WordPress for the first time is understanding what themes are and how a given theme can work for you, especially when there’s no content there to visualize. There are also significant gaps between local theme previews, screenshots, and .org previews. Even when there are easy-to-use site customization tools, it is difficult to figure out where to start and what things are going to be like.

To help users along that path, 4.7 introduces the concept of “starter content” – theme-specific selections of content to help showcase a theme to users and serve as a starting point for further setup of new sites. Starter content works especially well in tandem with visible edit shortcuts, allowing users to not only see what content might work best where within a theme, but from there to be able to jump to building off of that base without having to initially spend time figuring out, say, which widgets areas map where.

How it works

Starter content is applied and displayed upon entering the customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings., with no changes appearing on the live site until customizer changes are explicitly saved and published. In 4.7, this initial view of a theme with starter content will only happen for “fresh sites” – new installs that have not yet had any posts, pages, widgets, or customizer settings updated. This state is indicated in the fresh_site option with a value of 1. The current limitation is in line with prioritizing initial site setup for this release, and allows for themes to begin implementing content and ensuring that there is a solid base before introducing more complicated logic and UIUI User interface to “merge” starter content with existing content in a future release (#38624). That being said, if two themes in a given fresh site both have starter content, if the starter content from the first theme is applied and you make some changes to that starter content, when you switch to the second theme the starter content from that theme will override the starter content from the first theme only for the settings which have not been modified. Also remember that theme mods are always theme-specific, so starter content for theme switches will never be copied.

CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. provides a set of content that themes can select from (technical details below). These include a variety of widgets, pages, and nav menu items (including references for the pages), along with the ability to provide attachments, theme mods, and options. Any included images for attachments need to be from within a theme or pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party folder and cannot be loaded from an external URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. Twenty Seventeen will ship with starter content enabled; there are no plans to add the functionality to past default themes.

How to use it

Themes define a subset of core-provided starter content using add_theme_support() – let’s look at a breakdown of how Twenty Seventeen does things. In its setup function hooked to after_setup_theme, we see an array with collections of widgets, posts (pages), attachments, options, theme mods, and nav menus registered as the starter content. The customizer looks for this starter-content at after_setup_theme priority 100, so do make this call at that point or later:

add_theme_support( 'starter-content', array( /*...*/ ) )

Widgets

Each widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. area ID corresponds to one sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. registered by the theme, with the contents of each widget area array being a list of widget “symbols” that reference core-registered widget configurations. Most default widgets are available (archives, calendar, categories, meta, recent-comments, recent-posts, and search), as well as text widgets with business hours (text_business_info) and a short prompt for an “about this site” style blurb (text_about). Themes should place widgets based on what works best in that area – for instance, business info in a footer widget of a business-centric theme, or a nicely styled calendar widget in the sidebar of a blogblog (versus network, site).

Custom widgets can also be registered at the time of starter content registration or later filtered in, which will be more likely the case for plugins, as add_theme_support() for starter content will be overridden by any later calls.

// Custom registration example
add_theme_support( 'starter-content', array(
	'widgets' => array(
		'sidebar-1' => array(
			'meta_custom' => array( 'meta', array(
				'title' => 'Pre-hydrated meta widget.',
			) ),
		),
	),
);

// Plugin widget added using filters
function myprefix_starter_content_add_widget( $content, $config ) {
	if ( isset( $content['widgets']['sidebar-1'] ) ) {
		$content['widgets']['sidebar-1']['a_custom_widget'] = array(
			'my_custom_widget', array(
				'title' => 'A Special Plugin Widget',
			),
		);
	}
	return $content;
}
add_filter( 'get_theme_starter_content', 'myprefix_starter_content_add_widget', 10, 2 );

Posts (Pages)

Like widgets, core provides posts which can be referenced by symbols; all six currently in the core set are pages, but the starter content APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. can support various post types (including attachments, which are defined and handled separately). The symbols for the core-provided pages as of 4.7 are home, about, contact, blog, news, and homepage-section. The pages references by blog and news are both empty in the content area and are meant to be assigned as the page for posts (detailed with options below). Imported posts can further be used as post IDs when referenced using the symbol of the item within double curly braces, e.g. {{home}} for the static front pageStatic Front Page A WordPress website can have a dynamic blog-like front page, or a “static front page” which is used to show customized content. Typically this is the first page you see when you visit a site url, like wordpress.org for example. option.

Posts, like widgets, are also easily customizable, either by overriding specific fields for a predefined item or by defining a new custom one entirely. The available fields are post_type, post_title, post_excerpt, post_name (slug), post_content, menu_order, comment_status, thumbnail (featured imageFeatured image A featured image is the main image used on your blog archive page and is pulled when the post or page is shared on social media. The image can be used to display in widget areas on your site or in a summary list of posts. ID), and template (page template name, as would be stored in post metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.).

// Overriding/supplementing a predefined item plus a custom definition
add_theme_support( 'starter-content', array(
	'posts' => array(
		'about' => array(
			// Use a page template with the predefined about page
			'template' => 'sample-page-template.php',
		),
		'custom' => array(
			'post_type' => 'post',
			'post_title' => 'Custom Post',
			'thumbnail' => '{{featured-image-logo}}',
		),
	),
);

Attachments

While attachments are post objects, they have special handling due to the sideloading of specified media. Media must be loaded from within the theme or plugin directory – external URLs are currently disallowed for performance reasons. The location of the media, either as a full file path or relative to the theme root, is indicated in the file array item, and some other post fields are available, with post_content mapping to description and post_excerpt to caption. Imported attachments can further be used by using their respective array keys as symbols used within double curly braces, e.g. {{featured-image-logo}} as the featured image (thumbnail) for a post. In the example below, an attachment is specified and used as the featured image for the about page.

add_theme_support( 'starter-content', array(
	'attachments' => array(
		'featured-image-logo' => array(
			'post_title' => 'Featured Logo',
			'post_content' => 'Attachment Description',
			'post_excerpt' => 'Attachment Caption',
			'file' => 'assets/images/featured-logo.jpg',
		),
	),
	'posts' => array(
		'about' => array(
			// Use the above featured image with the predefined about page
			'thumbnail' => '{{featured-image-logo}}',
		),
	),
);

Nav Menus

Nav menus are also specially treated post objects. There are essentially two types of nav menu items – custom links, which require a title and url, and object references, which require type, object, and object_id, which can be a {{post}} symbolic reference.

Options and Theme Mods

Options and theme mods are more freeform and merely require a match for a name. Symbolic references to imported items are particularly useful here, such as for the page_on_front option and Twenty Seventeen’s multi-section homepage as stored in theme mods. Themes hosted on .org will likely be limited to theme mods and a subset of options; all other developers are encouraged to consider user experience and expectations first.

What does this mean for themes?

Core-provided content helps support a consistent preview experience across themes with high quality localized content, helping users understand how WordPress and that theme fit their needs. Theme authors are encouraged to select from core-provided content, but as is always the case with WordPress, starter content still has some flexibility, and will continue to mature as a feature over time.

While theme review guidelines need to be finalized and documented, it is anticipated that themes being submitted to WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ will be expected to select from core-provided content to promote consistency and to help keep the theme review process from becoming lengthier, with exceptions being made on a case by case basis. Themes being distributed outside of WordPress.org are not subject to the same review process; however, it is recommended that consistent user experiences be the primary consideration in how starter content is chosen and implemented.

What’s next?

Testing this feature with your theme or plugin does not require a fresh install every time – you can set the fresh_site option to 1 using the tool of your choice, such as wp-cliWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ or phpMyAdmin. Do note that content merging logic has not been tackled so you may not quite get the exact same effect as a truly fresh install; however, since all of the changes are held in a customizer changeset and are not otherwise live on the site, there is no data loss, unless you save and publish the starter content overrides of course.

In the future, all sites should be able to live preview new themes in ways that really showcase that theme’s capabilities, whether that’s with no content made yet or with a lot of existing content to work into the preview. This will take a lot of consideration around user expectations for content merging, and should be tackled as its own feature. There are also potentially interesting extensions such as UI for users to select from sets of content or selectively accept/reject staged changes.

And finally, to best align preview experiences in various places, theme previews on .org should also leverage starter content. Helping hands are needed here – please pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me (@helen) in SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. should you be interested!

#4-7, #dev-notes

Week in Core, November 23 – 29, 2016

Welcome back the latest issue of Week in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., covering changes [39341-39379]. Here are the highlights:

  • 39 commits
  • 30 contributors
  • 81 tickets created
  • 3 tickets reopened
  • 31 tickets closed

Ticketticket Created for both bug reports and feature development on the bug tracker. numbers based on trac timeline for the period above. The following is a summary of commits, organized by component.

Code Changes

Build/Test Tools

  • Build: Remove fsevents from npm-shrinkwrap.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. [39368] #38657
  • Add an extra WP_Error assertion when testing a valid user activation key. This provides a better failure message if the assertion does fail. [39364] #38716
  • When testing the output of wp_list_pages(), use a known and fixed date for each post so the tests don’t fail when the date changes between the beginning and end of a test. [39363] #38688
  • GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/.: Prevent untracked files from being ignored by git in bundled themes. [39362] #27207, #38779
  • Add npm-shrinkwrap.json to 4.7. [39358] #38657

Bundled Theme

  • Twenty Seventeen: Add textdomain for starter content attachment titles. [39374-39373] #38981
  • Twenty Seventeen: Ensure edit button label displays properly in other languages [39341] #38876

Customize

  • Fix regressionregression A software bug that breaks or degrades something that previously worked. Regressions are often treated as critical bugs or blockers. Recent regressions may be given higher priorities. A "3.6 regression" would be a bug in 3.6 that worked as intended in 3.5. in ability to hide fields for advanced menu properties in nav menu item controls. [39379-39378] #34391, #38952
  • Fix regression in ability to create submenus for nav menus via drag and drop. [39377-39376] #34391, #38948
  • Fix logic for previewing the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org for nav_menu_item settings for terms and post type archives. [39365] #38114, #38945
  • Refactor logic for updating custom_css posts by introducing wp_update_custom_css_post() function and renaming update filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.. [39350] #35395, #38672
  • Clean up docs and code style for customize changes in 4.7. [39345] #37770, #38908

Embeds

  • Correctly remove security attribute from iframes in IE 10 and IE 11. [39347] #38694

General

  • Git: Ignore patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. related files, so they can’t be accidentally committed. [39361] #38727
  • SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase.: Ignore patch related files, so they can’t be accidentally committed. [39360] #38727
  • Docs: Add a missing changelog entry for the point where the $tagnames parameter was added to get_shortcode_regex(). [39351] #38914

Misc

  • Trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. is now 4.8-alpha. [39357]
  • Branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". 4.7. [39356]
  • Post-4.7 RC1 bump. [39355]

Plugins

  • WP_Hook: Re-initialize any actions added directly to $wp_filter by advanced-cache.php. [39370-39369] #38929

REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.

  • Add test for creating a comment with an invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. post ID. [39375] #38816, #38991
  • Add tests for empty or “no-op” updates. [39371] #38700, #38975
  • Special case the “standard” post format to always be allowed. [39353] #38916
  • Allow unsetting a post’s password. [39352] #38919
  • Add support for comments of password-protected posts. [39349] #38692
  • Always fire the rest_insert_* actions after the related object is updated or inserted. [39348] #38905
  • Make JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. Client store schema in session storage. [39344] #38895
  • Allow unsetting of page templates in update requests. [39343] #38877
  • Update “resource” strings to use the appropriate nouns. [39342] #38811

Themes

  • Fix logic for previewing the URL for nav_menu_item settings for terms and post type archives. [39366] #38114, #38945
  • Theme starter content: Add support for featured images and page templates. [39346] #38615

TinyMCE

  • Fix the styling of notices generated by the editor UIUI User interface. [39367] #38917

Thanks to @mor10, @adamsilverstein, @afercia, @azaozz, @celloexpressions, @danielbachhuber, @davidakennedy, @dd32, @delawski, @DrewAPicture, @flixos90, @georgestephanis, @helen, @iseulde, @jnylen0, @joehoyl, @joehoyle, @johnbillion, @karmatosed, @keesiemeijer, @lucasstark, @nacin, @ocean90, @odysseygate, @pento, @rachelbaker, @ramiy, @swissspidy, @tg29359, @westonruter, and @xrm for their contributions!

#4-7, #week-in-core

Theming with Twenty Seventeen

In 4.7, WordPress gets a new default theme: Twenty Seventeen. Like all default themes, it’s easily customizable for users and developers. This post will cover developer features and a few tricks when customizing the theme.

Of note

  • Twenty Seventeen only works on 4.7 and above.
  • It uses the new video headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. and starter content features, each launched in 4.7.
  • The theme also implements new theme functions to make child theming easier.

Override enqueued styles and scripts

With the use of get_theme_file_uri, introduced in 4.7, Twenty Seventeen lets child themes override styles and scripts with ease. For example, if you want to replace the theme’s global.js file, you can do so by including the same file in your child themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. https://developer.wordpress.org/themes/advanced-topics/child-themes/. in the same path.

Filters

Twenty Seventeen includes a handful of filters, all of which are documented in line in the code.

Content width

The value is filterable in the event a child theme needs to change it.

function childtheme_content_width( $content_width ) {
    if ( twentyseventeen_is_frontpage() ) {
        $content_width = 960;
    }
    return $content_width;
}
add_filter( 'twentyseventeen_content_width', 'childtheme_content_width' );

Custom header settings

Like past default themes, Twenty Seventeen filters the arguments for add_theme_support( 'custom-header' );. These can be changed in a child theme. Here, we’ll add flex-width to the current args.

function childtheme_custom_header_args( $args ) {
    $args['flex-width'] = true;
    return $args;
}
add_filter( 'twentyseventeen_custom_header_args', 'childtheme_custom_header_args' );

Header video settings

The theme changes the default provided by CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., but that can be modified by a child theme. Here, we change the text on the button in a child theme:

function childtheme_setup() {
    remove_filter( 'header_video_settings', 'twentyseventeen_video_controls' );
}
add_action( 'after_setup_theme', 'childtheme_setup' );

function childtheme_video_controls( $settings ) {
	$settings['l10n']['play'] = '__( 'Play my awesome video', 'childtheme' );
	$settings['l10n']['pause'] = '__( 'Pause my awesome video', 'childtheme' );
	return $settings;
}
add_filter( 'header_video_settings', 'childtheme_video_controls' );

Front page sections

Twenty Seventeen uses the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. to add sections to the front page. These are filterable with the twentyseventeen_front_page_sections filer. They can changed like so:

function childtheme_front_page_sections() {
	return 6;
}
add_filter( 'twentyseventeen_front_page_sections', 'childtheme_front_page_sections' );

With 6 being a new number there. In this way, the number of sections can be adjusted in a child theme.

SVGs

One of the theme’s most notable behind-the-scenes features, the use of SVGs means better accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) for icons, they look great on any device and they’re easier to customize.

First, the list of social link icons is filterable, so child themes can change it.

function childtheme_social_links_icons( $social_links_icons ) {
    $social_links_icons['mysocialsite.com'] = 'mysocialsite';
    return $social_links_icons;
}
add_filter( 'twentyseventeen_social_links_icons', 'childtheme_social_links_icons' );

All of Twenty Seventeen’s icons are decorative in nature. But if a child theme wanted to include an icon that needed to be described in an accessible way, it can thanks to built-in options.

These examples are documented in the code itself. However, for example:

Using a title:

<?php echo twentyseventeen_get_svg( array( 'icon' => 'arrow-right', 'title' => __( 'This is title', 'childtheme' ) ) ); ?>

Another example with title and desc (description):

<?php echo twentyseventeen_get_svg( array( 'icon' => 'arrow-right', 'title' => __( 'This is title', 'childtheme' ), 'desc' => __( 'This is longer desc', 'textdomain' ) ) ); ?>

For more information on SVG accessibility, see Using ARIA to enhance SVG accessibility.

Custom Colors

Like other default themes, this one comes with some color options so you can make the theme your own. Twenty Seventeen uses saturation to create a custom color scheme that will look great. That saturation level can be adjusted, like so:

function childtheme_custom_colors_saturation() {
	return 25;
}
add_filter( 'twentyseventeen_custom_colors_saturation', 'childtheme_custom_colors_saturation' );

So the lower the number there, the more muted a color appears, and the higher it is, the more intense a color becomes.

You can also add new CSSCSS Cascading Style Sheets. to the existing CSS output for custom colors.

By adding a filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., child themes can add additional selectors onto the custom color scheme CSS. Like so:

// Add child theme selectors for color schemes.
function dynamic_seventeen_custom_colors_css( $css, $hue, $saturation ) {
	$css .= '
	.colors-custom .content-menu > article:not(.has-post-thumbnail),
	.colors-custom .content-menu > section:not(.has-post-thumbnail) {
		border-top-color: hsl( ' . $hue . ', ' . $saturation . ', 87% ); /* base: #ddd; */
	}';
	return $css;
}
add_filter( 'twentyseventeen_custom_colors_css', 'dynamic_seventeen_custom_colors_css', 10, 3 );

Enjoy customizing Twenty Seventeen and happy theming!

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

Video Headers in 4.7

WordPress 4.7 extends the Custom Header feature to introduce support for video.

Video headers are considered decorative elements — like headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. images, but with motion. With that in mind, they play automatically, loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop. by default, and don’t have sound. They work best when paired with an image, so they can progressively enhance the experience when video is supported.

Header media UIUI User interface in the customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. when a theme supports video.

Adding theme support

Adding support for video headers to a theme requires three basic steps:

Registering theme support

Support for video headers can be registered when adding support for custom headers in a theme.

add_theme_support( 'custom-header', array(
 'video' => true,
) );

Adding support this way does a few things:

  • Renames the “Header Image” customizer section to “Header Media.”
  • Registers customizer controls for selecting a video from the media library or entering a URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org to a YouTube video.
  • Enables support for Selective Refresh for header images.

Displaying the header

In previous versions of WordPress, generating the image tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) manually was the recommended way to display a header image. WordPress 4.4 introduced the_header_image_tag() to take advantage of the responsive image improvements.

In WordPress 4.7, the_custom_header_markup() unifies support for header images and videos and is the recommended method for displaying custom headers.

It prints a div that will contain a header image if one is set in the customizer and will also enqueue the wp-custom-header.js script if a video is set in the customizer. The script determines if the environment supports video, and if so, it will progressively enhance the header by replacing the image with a video.

Styling the play/pause button

When videos are ready to play, the wp-custom-header.js script inserts a button for pausing and playing the video to help improve accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility). CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. does not apply any CSSCSS Cascading Style Sheets. to the button in order to make it easier for themes to style. Themes should ensure the button is visible, fits within the design, and add icons if desired.

Pause Button
<button type="button" id="wp-custom-header-video-button" class="wp-custom-header-video-button wp-custom-header-video-play">Pause</button>

Play Button
<button type="button" id="wp-custom-header-video-button" class="wp-custom-header-video-button wp-custom-header-video-pause">Play</button>

The text for the button can be modified using the header_video_settings filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output..

Styling custom headers

When styling custom headers, it’s important to be aware of the various elements that can be used for header media.

A container div with a wp-custom-header class will always be rendered when a header image or video is available. The div may contain an image, video, or iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser. depending on the source of the video, so each of those elements needs to be considered.

The following selectors should be fairly standard for creating responsive headers:

.wp-custom-header iframe,
.wp-custom-header img,
.wp-custom-header video {
	display: block;
	height: auto;
	max-width: 100%;
}

Accessibility considerations

A button to toggle the play/pause state of the video is automatically rendered to help users who may be distracted or disoriented by motion. Voice assistance is also available using wp.a11y.speak, and like the button text, the strings can be modified using the header_video_settings filter.

Bandwidth considerations

To alleviate concerns about bandwidth, videos are only loaded on the front page for viewports that are at least 900 pixels wide and 500 pixels tall. The maximum file size is also capped at 8MB; however, we strongly encourage smaller files be used whenever possible.

Filtering the front page restriction

By default, videos are only loaded on the front page and only the header image is shown on other pages calling the_custom_header_markup(). Themes that need to display the header video on pages other than the front page can:

  • Define a custom callback for the video-active-callback header argument.
  • Use the is_header_video_active filter.

Testing the environment for video support

Themes may also want to customize the criteria used to determine whether or not a video should be embedded. The header_video_settings filter can be used to modify the minimum viewport width and height.

On the front end, the wp.customHeader.supportsVideo() method can be redefined. For instance, it might be desirable to test the user agent to prevent videos from loading on mobile devices that don’t support autoplay. As browsers introduce bandwidth APIs, it may also be worthwhile to disable video on devices with limited bandwidth.

Selective Refresh enabled by default

When registering support for video headers in a theme, header image settings in the customizer are updated to use the postMessage transport to take advantage of the Selective Refresh API introduced in WordPress 4.5. This ensures header images and videos can be updated in the customizer without refreshing the preview window.

If the_custom_header_markup() template tag isn’t being used, themes will need to update the custom header partial to use a custom render_callback, or change the transport for the header_image and header_image_data settings back to refresh.

Creating custom video handlers

Locally hosted mp4 and mov files, as well as YouTube videos, can be used for video headers by default, but it’s possible to add support for additional sources as well.

The wp-custom-header.js script exports a wp.customHeader.handlers global variable that contains a list of video handlers. Each handler accepts information about the current video to determine if it can process it, and if so, it creates the video and inserts it into the DOM.

Core registers two handlers, one for native video, and one for YouTube videos. Each handler extends a base class exposed at wp.customHeader.BaseVideoHandler and implements a basic interface to make sure all videos receive the same level of support.

In the customizer, there is validation to ensure that local videos are a supported format and file size, and that external video links are to YouTube. This validation needs to be filtered to account for custom handlers, either with the customize_validate_external_header_video and customize_validate_header_video filters to filter the core validation functions, or by changing the validation_callback on the header_video and external_header_video customizer settings. See the documentation on customizer validation for more details.

For an example of registering a custom video handler in a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, take a look at how this plugin registers support for Vimeo.

New functions and hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.

  • has_header_video() – Checks whether a header video has been set in the customizer.
  • is_header_video_active() – Checks whether a header video is eligible to be shown for the current request.
  • get_header_video_url() – Retrieve the header video URL. May be a local attachment URL or a URL for an external source.
  • the_header_video_url() – Display the header video URL.
  • has_custom_header() – Checks whether a header image or video is set in the customizer and is available for the current request.
  • get_custom_header_markup() – Retrieve the markup for displaying a custom header image (this does not include video support).
  • the_custom_header_markup() – Display the custom header markup and enqueue a script for rendering video in supported environments.

Filters

  • is_header_video_active – Whether a header video should be shown for the current request if available.
  • header_video_settings – Settings that are exported to the wp-custom-header.js script during initial page load and when updating the custom header partial in the customizer preview. The default values are:
    • videoUrl – URL for the selected video.
    • mimeType – MIME type of the selected video.
    • posterUrl – URL for the fallback header image.
    • width – Video width.
    • height – Video height.
    • minWidth – Minimum viewport width to embed a video.
    • minHeight – Minimum viewport height to embed a video.
    • l10n – An array of button text and accessibility strings.

Theme support arguments

When calling add_theme_support( 'custom-header' ), two new arguments are available:

  • video – Registers support for video headers.
  • video-active-callback – Defines a callback used to determine whether a header video should be shown for the current request. Defaults to is_front_page.

#4-7, #custom-header, #customize, #dev-notes, #themes

Extending the Custom CSS editor

With the Custom CSS project merging into WordPress Core, some of y’all may be looking to extend it and do more advanced stuff.  Maybe you help run an existing pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party (like me) that has already provided a Custom CSSCSS Cascading Style Sheets. input to WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and you’re now looking to migrate that data over.  Or maybe you want to change how it outputs.  Here’s what I’ve found so far in my work converting Jetpack’s Custom CSS module to be an enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. layer on top of the Core implementation, providing legacy feature parity.

Disclaimer: This is just what I’ve found to be useful so far, the Jetpack update is still a work in progress as I write this.

Data Structure

Core’s data store is in a Custom Post TypeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. named custom_css, and the CSS is stored in the post_content.  It sets up a new post for each theme’s custom css, and only the active theme’s one is used.  There’s no accounting for parent/child themes — it uses the slug from the current stylesheet (child themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. https://developer.wordpress.org/themes/advanced-topics/child-themes/.) as the post_name; that is, Custom CSS lookups are indexed by the return value of get_stylesheet().  Core does not yet have have a UIUI User interface for displaying the revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. for changes to Custom CSS or a way display the saved Custom CSS of inactive themes, but revisions are enabled on the post type, so no data is lost until the revision viewer makes its way into core (or the user activates a plugin that provides similar functionality). Follow #31089 for more on revisions in the customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings., for all settings not just for Custom CSS.

Getting The Custom CSS

The generated CSS itself can be gotten via the wp_get_custom_css() function, which just returns the CSS for the current theme as a string. This function is used in the wp_head callback when the CSS is printed into a style tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.).  One of the more useful functions in the Core implementation for advanced development is wp_get_custom_css_post( $stylesheet = '' ) — this will return either null or the WP_Post object if the site has any Custom CSS saved for the current site.  If you’re building a custom revision viewer, this will be the post you’ll key off of to fetch the revisions.

Filters on Read and Update

The wp_get_custom_css() function applies a wp_get_custom_css filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. to the styles just before they’re returned.  This allows for targeted tweaks such as minifying the output on the front-end before it’s echoed by stripping out excess whitespace or the like.  This filter is not meant for a theme or plugin adding styles to the front-end of the site — for that, consider enqueueing your stylesheet normally and adding any dynamic bits via wp_add_inline_style() — this way it will also handle if a child theme or plugin wants to dequeue the parent stylesheet.

Jetpack has historically provided LESS and Sass (SCSS) preprocessing for our Custom CSS module.  We’re extending the Core implementation via two filters in the WP_Customize_Custom_CSS_Setting class by storing the pre-compiled code in $post->post_content_filtered — so it is versioned correctly, but if the user disables Jetpack, the compiled CSS will still be available in $post->post_content with no data loss for the user.

When implementing a pre-processor extension to the Custom CSS functionality in core you have to do some swapping between the underlying setting value and the value that gets displayed:

  1. Replace the post_content with the post_content_filtered as the initial setting value via the customize_value_custom_css filter.
  2. Add a wp_get_custom_css filter in the customizer preview (when the customize_preview_init action triggers) to compile the value into CSS just-in-time.
  3. Override the default JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. live-preview functionality to instead register a partial for the wp-custom-css style element so that whenever the custom CSS is modified it can be re-compiled on the server and rendered via selective refresh.
  4. When the Custom CSS setting is saved in the customizer, send the saved pre-processed value to post_content_filtered and compile the value to store into post_content.

For a standalone example of building a pre-processor, see the Custom SCSS Demo plugin on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/.

Permissions

The Core implementation also is including only very basic sanitization, to the point where it would be dangerous to allow users without unfiltered_html to edit CSS.  If your plugin is adding further sanitization to the saved CSS, you can broaden the user base by remapping the edit_css capability (which Core defaults to unfiltered_html) like so:

add_filter( 'map_meta_cap', 'mycss_map_meta_cap', 20, 2 );
function mycss_map_meta_cap( $caps, $cap ) {
  if ( 'edit_css' === $cap ) {
    $caps = array( 'edit_theme_options' );
  }
  return $caps;
}

Migrating an Existing option to Core CSS

Does your plugin or theme have a custom CSS option stored as an option or a theme_mod? Consider migrating content from your custom setting to the core functionality and hiding your custom UI. Here’s a general migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. script, which can be located where you see fit in the context of your original code:

if ( function_exists( 'wp_update_custom_css_post' ) ) {
	// Migrate any existing theme CSS to the core option added in WordPress 4.7.
	$css = get_theme_mod( 'custom_theme_css' );
	if ( $css ) {
		$core_css = wp_get_custom_css(); // Preserve any CSS already added to the core option.
		$return = wp_update_custom_css_post( $core_css . $css );
		if ( ! is_wp_error( $return ) ) {
			// Remove the old theme_mod, so that the CSS is stored in only one place moving forward.
			remove_theme_mod( 'custom_theme_css' );
		}
	}
} else {
	// Back-compat for WordPress < 4.7.

I hope some of this has been useful to folks interested in diving deeper into modifying the Core Custom CSS editor.  It’s still somewhat early days for the feature, so please reach out in #core-customize on Slack with any unexpected use cases or concerns!

#4-7, #css, #customize, #dev-notes

Week in Core, November 15 – 22, 2016

Welcome back the latest issue of Week in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., covering changes [39233-39340]. Here are the highlights:

  • 108 commits
  • 53 contributors
  • 114 tickets created
  • 16 tickets reopened
  • 101 tickets closed

Ticketticket Created for both bug reports and feature development on the bug tracker. numbers based on trac timeline for the period above. The following is a summary of commits, organized by component.

Code Changes

Bundled Theme

  • Twenty Seventeen: CSSCSS Cascading Style Sheets. coding standards [39340] #38901
  • Twenty Seventeen: Ensure galleries display correctly in IE11. [39339] #38872
  • Twenty Seventeen: Avoid an undefined index notice after [39291]. [39317] #38847
  • Twenty Seventeen: Adds background-attachment: fixed; to devices that should support it [39297] #38395
  • Twenty Seventeen: Ensure the use of proper image size for custom headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. image [39291] #38847
  • Twenty Seventeen: Remove some extraneous function calls. [39286] #38848
  • Twenty Seventeen: Additional default header image optimizations. [39279] #38793
  • Twenty Seventeen: Add styles for custom header video controls. [39273] #38697
  • Twenty Seventeen: Compress the default header image. [39248] #38793

Comments

  • REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.: On Comment create, limit the ability to set the author_ip value directly. [39302] #38819
  • REST API: Change “ipv4” types to “ip” to support ipv6. [39296] #38818
  • REST API: Remove the karma property and query parameter from the Comments endpoints. [39292] #38821
  • REST API: On comment create, return an error if the type property is set to anything other than comment. [39290] #38820
  • REST API: On comment create, return an error if the post parameter does not relate to a valid WP_Post object. [39288] #38816
  • REST API: On comment create, fallback to the user_agent header value. [39287] #38817
  • Query used to fill comment descendants should reset ‘offset’ and ‘number’ params. [39274] #37696

Customize

  • Prevent selective refresh from causing infinite fallback refreshes when nav menu contains invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. items. [39333] #38890
  • Remove iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser.-specific behaviors from customize preview when previewing on frontend and not contained inside iframe. [39332] #30937, #38867
  • Ensure that WP_Customize_Manager::save_changeset_post() returns setting_validities even for supplied values that are unchanged from values in changeset. [39320] #38705, #30937, #38865
  • Ensure WP_Customize_Setting::value() returns previewed value for custom types utilizing the customize_value_{$id_base} filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.. [39318] #38864
  • Autoprefixer for [39249]. [39301] #29158
  • Remove obsolete edit shortcut style rules from Twenty Seventeen. [39285] #38776
  • Ensure Close button actually closes customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. (instead of going back) after switching to a different theme inside a customize-loader iframe. [39271] #38833
  • Prevent edit shortcut buttons from being inserted into container elements in the head or into elements which should not get interactive children. [39270] #27403, #38672, #38830
  • Allow URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org for Codex link in Additional CSS section to be translated. [39268] #35395, #38823
  • More visible focus and hover states for close and back buttons. [39249] #29158
  • Ensure edit shortcuts have same background color regardless of theme colors. [39243] #38776
  • Add !important line-height to edit shortcut buttons. [39242] #38787
  • Allow starter content to apply in a new theme when switching from another theme containing changes. [39241] #38114, #38541
  • Only show video header controls if previewing front page; show explanatory notice when controls are hidden. [39237] #38796, #38778
  • Adjust layout for edit shortcuts only when shown. [39233] #38651

Database

  • Add support for LIKE-escaped tables in ::get_table_from_query(). [39275] #38751

Emoji

General

  • PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party install: De-duplicate a conditional, introduced in [38172]. [39336] #38190
  • Docs: Use 3-digit, x.x.x style semantic versioning for @since 4.7.0 entries. [39281] #37770
  • Tests: Add a missing $message argument for assertEquals() in [39265]. [39267] #23626
  • Tests: Use assertEquals()‘ native functionality for delta comparison in test_wp_convert_bytes_to_hr(). [39265] #23626

I18Ni18n Internationalization, or the act of writing and preparing code to be fully translatable into other languages. Also see localization. Often written with a lowercase i so it is not confused with a lowercase L or the numeral 1. Often an acquired skill.

  • In wp_dropdown_languages() rename the new show_site_locale_default argument to show_option_site_default. [39331] #38632, #38871
  • Add an additional caching layer for _load_textdomain_just_in_time(). [39330] #37997
  • Introduce more translator comments for strings that contain placeholders but don’t have an accompanying translator comment. [39326] #38882
  • Move the support forums URL in update-related HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. error messages to a separate translatable string that is already used elsewhere. [39325] #38880
  • Remove an erroneous @TODO introduced in [39323]. [39324] #38882
  • Begin introducing translator comments for strings which include placeholders but no accompanying translator comment. [39323] #38882
  • REST API: Merge two error messages for edit / update. [39322] #38879
  • REST API: Update error messages in WP_REST_Comments_Controller to use the common text for permission errors. [39321] #38875
  • Use ‘WordPress hook name’ instead of ‘PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher hook name’ in translator comments added in [39315]. [39316] #38862
  • Add translator comments for strings in _deprecated_*() functions. [39315] #38862
  • Remove unnecessary __() calls in _rotate_image_resource() and _flip_image_resource(). [39314] #38862
  • REST API: Merge some more permission error strings missed in [39309]. [39313] #38857
  • Text Changes: Merge strings referring to list_users capability. [39312] #38857
  • Merge two ‘RSS Error:’ strings. [39311] #38861
  • REST API: After [39306], move author_ip argument to the correct place. [39310] #38822
  • REST API: Merge and clarify some permission error strings. [39309] #38857
  • Text Changes: Merge and clarify some permission error strings in the adminadmin (and super admin). [39308] #38857
  • Merge two ‘ERROR:’ strings. [39307] #38860
  • REST API: After [39302], clarify author_ip parameter in error message. [39306] #38822
  • REST API: Merge two similar permission error strings in class-wp-rest-comments-controller.php. [39305] #38857
  • REST API: Merge two similar permission error strings. [39304] #38857
  • REST API: Clarify parameters when used in error strings. [39298] #38822
  • REST API: After [39252] and [39264], uppercase some more ‘ID’ references in translatable strings. [39266] #38791
  • REST API: Uppercase ‘ID’ in endpoint descriptions and error messages for consistency with other strings. [39264] #38791
  • REST API: Unify some more permission error messages. [39259] #38803
  • REST API: Unify permission error messages. [39257] #38803
  • Remove “ tags from translatable strings in wp-includes/class-wp-customize-manager.php. [39254] #38802
  • REST API: Remove two duplicate strings, use the ones we already have. [39252] #38791
  • REST API: Unify permission error messages. [39251] #38791, #34521
  • REST API: After [39238] and [39239], move the remaining translator comments to preceding line. [39245] #38791
  • Docs: Apply documentation standards to the new get_available_languages filter. [39244] #38788
  • REST API: Move translator comments to preceding line. [39239] #38791
  • REST API: Add translator comments to text with placeholders. [39238] #38791
  • Add the get_available_languages filter. [39235] #38788

Media

Misc

  • REST API: Check read permissions on posts when viewing comments. [39295]
  • Small coding standards cleanup of wp-custom-header.js. [39277]
  • Post-4.7 betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 4 bump. [39263]
  • WordPress 4.7 Beta 4. [39262]

Options, MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. APIs

  • REST API: Update description strings to match already existing ones in the admin. [39335] #38807

Posts, Post Types

  • AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility): Improve the Post Attributes meta box fields labels. [39247] #38790
  • Improve sanitisation of templates’ post types. [39236] #38766

REST API

  • Set the comment type to a readonly property in the schema. [39337] #38820, #38886
  • Trim trailing slashes from routes. [39329] #38873
  • Correctly map meta keys to field names. [39328] #38786
  • Disable anonymous commenting by default. [39327] #38855
  • Add test case for users/me endpoint that the context param defaults to view. [39293] #38842
  • Allow parent property to be explicitly set to 0 when creating or updating a Post. [39289] #38852
  • Clean up argument and property types. [39250] #38792

TaxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies.

  • Update register_taxonomy hook to use WP_Taxonomy object. [39283] #38765
  • Prevent wp_list_categories() from producing not well-nested output if hide_title_if_empty is true. [39280] #38839, #33460

Text Changes

  • Merge some duplicate strings with the same meaning in error messages, adjust some other strings for consistency and accuracy. [39278] #38808
  • Unify permission error messages in wp-admin/users.php. [39258] #38804
  • Unify permission error message in wp-ajax-response.js. [39253] #34521

Themes

  • Prevent unneeded database updates in wp_get_custom_css_post(). [39338] #38866
  • Twenty Seventeen: Make all Codex links in DocBlocks use HTTPSHTTPS HTTPS is an acronym for Hyper Text Transfer Protocol Secure. HTTPS is the secure version of HTTP, the protocol over which data is sent between your browser and the website that you are connected to. The 'S' at the end of HTTPS stands for 'Secure'. It means all communications between your browser and the website are encrypted. This is especially helpful for protecting sensitive data like banking information. [39300] #38854
  • Twenty Seventeen: Rename the starter content menus to match the menu area names. [39294] #38615
  • Improve a11yAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) and extendability of custom video headers. [39272] #38678
  • Theme starter content: Add reference IDs for most default widgets. [39261] #38615
  • Theme starter content: Refine the content for pages. [39260] #38615
  • Theme starter content: Add more social link items to select from. [39256] #38615
  • Theme starter content: Revamp the credits widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. into an about widget. [39255] #38615
  • Remove front page restriction from video header functions. [39240] #38738
  • Customize: Use video-specific labels for buttons in Header Video media control. [39234] #38172

TinyMCE

  • Avoid calling editor.focus() on loading the content in the editor. It may trigger scroll-into-view in the browser. Call the quirks fix in TinyMCE directly. [39334] #38511
  • Fix automatic scroll on page load. [39299] #38511
  • Remove extra space in tooltip. [39284] #38063
  • Tews: fix Firefox issues. [39282] #36434, #38511

Upgrade/Install

Users

  • In edit_user() fall back to site’s localeLocale A locale is a combination of language and regional dialect. Usually locales correspond to countries, as is the case with Portuguese (Portugal) and Portuguese (Brazil). Other examples of locales include Canadian English and U.S. English. instead of en_US for invalid user locales. [39269] #38632, #29783, #38798

Thanks to @adamsilverstein, @afercia, @andy, @azaozz, @boonebgorges, @bradyvercher, @celloexpressions, @chesio, @ChrisWiegman, @danielbachhuber, @davidakennedy, @dd32, @derrickkoo, @dimadin, @flixos90, @folletto, @gitlost, @helen, @iseulde, @jnylen0, @joehoyle, @joemcgill, @johnbillion, @johnpgreen, @jrf, @laurelfulford, @lucasstark, @lukecavanagh, @markoheijnen, @melchoyce, @mikeschroder, @netweb, @ocean90, @odysseygate, @pento, @peterwilsoncc, @Presskopp, @rachelbaker, @ramiy, @rianrietveld, @rmccue, @schlessera, @SergeyBiryukov, @sharkomatic, @sirbrillig, @sstoqnov, @swissspidy, @tharsheblows, @timmyc, @transl8or, @welcher, @westonruter, and @yoavf for their contributions!

#4-7, #week-in-core

New Committers!

Usually, new committers are announced in line with release cycles, but we were all just too excited to wait until the 4.8 cycle started, so here they are!

First up, James Nylen (@jnylen0). James has been a driving force on the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/., both when it was a feature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins., and more recently in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. since the endpoints were merged. The tickets and comments he leaves on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. are always thorough and thoughtful, his patches are consistently excellent, and his attitude is exemplary.

Next, Adam Silverstein (@adamsilverstein). Adam has been a regular contributor for years, bringing significant improvements to the Media Grid, as well as handling large parts of the JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. work around the REST API endpoints – both in wp-api.js, and tenaciously working on porting Dashboard features across to using the endpoints.

Rounding out our guest committercommitter A developer with commit access. WordPress has five lead developers and four permanent core developers with commit access. Additionally, the project usually has a few guest or component committers - a developer receiving commit access, generally for a single release cycle (sometimes renewed) and/or for a specific component. list, Felix Arntz (@flixos90). Felix has been a contributor to Multisitemultisite Used to describe a WordPress installation with a network of multiple blogs, grouped by sites. This installation type has shared users tables, and creates separate database tables for each blog (wp_posts becomes wp_0_posts). See also network, blog, site for some time now, writing excellent patches, as well as running Office Hours and Bug Scrubs. Not only that, he’s always been willing to jump in and help in any area of Core, showing the same level of enthusiasm and consideration across the board.

Finally, we have a bumper class of guest committers to make make permanent! Pascal Birchler (@swissspidy) and Joe McGill (@joemcgill), Rachel Baker (@rachelbaker), and Mike Schroder (@mikeschroder) are now permanent committers.

Please join me in congratulating James, Adam, Felix, Pascal, Joe, Rachel, and Mike! 🎉🔥⭐️👻💯

#4-7, #commit

Media Changes in 4.7

This post provides an overview of the changes to the Media component in WordPress 4.7. See a list of all the 4.7 media tickets.

Two notable changes, enhanced PDF support in the media library and changes to the default fallbacks for alt attributes, are explained in separate posts.

https://make.wordpress.org/core/2016/11/15/enhanced-pdf-support-4-7/

https://make.wordpress.org/core/2016/11/11/improving-accessibility-of-image-alternative-text-in-4-7/

Make media library searchable by file name (#22744)

Before 4.7, if you uploaded a file to the media library and changed the title, it wasn’t possible to find that file again by searching for the file name. Now, attachment search queries will also include matches to the _wp_attached_file post metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. value.

Other enhancements and bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes

  • Added a $wp_error parameter to wp_insert_attachment() (#37813)
  • Fix Drag/Drop Ordering of Media in Chrome on touch enabled devices (#31652)
  • Avoid undefined offset notice in wp_prepare_attachment_for_js() when image_downsize filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. in used in (#34437).
  • Improve docs for image_send_to_editor filter (#34823).
  • Use wp_get_attachment_metadata() instead of get_post_meta() where appropriate (#36246).
  • Ensure wp_get_attachment_link() output text for non-images (#37343).
  • Avoid undefined index notices when pathinfo() is used (#37608).
  • Improve alignment of inputs and button heights in media edit screens (#37806).
  • Set focus when closing the media modal (#38142).

#4-7, #dev-notes, #media

Dev Chat Summary: November 16 (4.7 week 13)

This post summarizes the dev chat meeting from November 16th (agendaSlack archive).

Reminders

  • Dev Chat timing: Weekly chat has been moved to 21:00 UTC.
  • Schedule: Thursday, November 17th is the target for RC! RC means the list of tickets should be at zero (with the exception of the about page), as a release candidaterelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta). is supposed to represent software you believe you can release. It is currently at 24.
  • Tickets:For any tickets you’ve moved into the milestone, please get these resolved in the next day.
  • Dev Notesdev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase.: These should all be published this week, with a collective Field GuideField guide The field guide is a type of blogpost published on Make/Core during the release candidate phase of the WordPress release cycle. The field guide generally lists all the dev notes published during the beta cycle. This guide is linked in the about page of the corresponding version of WordPress, in the release post and in the HelpHub version page. forthcoming from @jorbin.

Dev Notes / Field Guide for 4.7

  • There are a few outstanding Dev Notes, but it’s getting close. We’re waiting on the Customize summary from @celloexpressions, Media summary from @joemcgill, Starter Content from @helen, and @davidakennedy is finishing up one on Twenty Seventeen.
    • Media summary is ready to publish, was just waiting on the PDF post from Tuesday, November 15th.
    • Video Headers post could be done by @bradyvercher, but @joemcgill own making sure it happens
  • @jorbin started drafting the Field Guide, but he’s going to need to hand off finishing it off since he will be offline starting Thursday, November 17th for a week.
    • @adamsilverstein and @jbpaul17 will work to finish things up
    • @jorbin to coordinate with Adam and Jeff to sure the remaining tasks are sorted out
    • @ipstenu happy to proofread for typos and grammar.
  • @jorbin also started the discussion to ensure the email to pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party devs goes out after the Field Guide is published.  That’s a collaboration with the metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. team and the pluginsrepo team.

Release Candidate

  • @helen (thankfully) was able to move RC back from Tuesday, November 15th to Thursday, November 17th.
  • However, we’ve got 23 tickets hanging out in the report, 22 of which need to be resolved or punted in order to reach RC.
  • [Bug Scrub of remaining 4.7 tickets proceeded]

#4-7, #core, #dev-chat, #summary