Title: 4.7 – Make WordPress Core
---
# Tag Archives: 4.7
[ ](https://profiles.wordpress.org/jorbin/) [Aaron Jorbin](https://profiles.wordpress.org/jorbin/)
9:05 pm _on_ December 5, 2016
Tags: 4.7, [dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/),
[field guide ( 35 )](https://make.wordpress.org/core/tag/field-guide/)
# [WordPress 4.7 Field Guide](https://make.wordpress.org/core/2016/12/05/wordpress-4-7-field-guide/)
WordPress 4.7 is shaping up to be the best WordPress yet! Users will receive new
and refined features that make it easier to “Make your site, YOUR site”, and developers
will be able to take advantage of 173 enhancements and feature requests added.
Let’s look at the many improvements coming in 4.7…
### RESTing, RESTing: 1, 2, 3
The foundation for RESTful APIs has been in coreCore Core is the set of software
required to run WordPress. The Core Development Team builds WordPress. since 4.4,
and 4.7 sees the addition of Content Endpoints after a [healthy discussion](https://make.wordpress.org/core/2016/10/13/merge-proposal-discussion-rest-api-content-endpoints/).
We’ve defined [four success metrics](https://make.wordpress.org/core/2016/10/19/wordpress-rest-api-success-metrics/)
as part of the merge discussion and you can help by building themes and plugins
on top of the 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., using the API in custom development projects, and utilizing the API
for a feature project, core features, or patches. So, dive in, start playing around,
and let us know what you build!
https://make.wordpress.org/core/2016/10/08/rest-api-merge-proposal-part-2-content-
api/
### It don’t mean a thing, if you ain’t got a theme
No matter if you are building themes for public consumption, as a bespoke project
for a major public company, or anything in between WordPress 4.7 has something to
help you.
https://make.wordpress.org/core/2016/11/29/theming-with-twenty-seventeen/
https://make.wordpress.org/core/2016/11/26/video-headers-in-4-7/
https://make.wordpress.org/core/?p=20650
https://make.wordpress.org/core/2016/11/10/visible-edit-shortcuts-in-the-customizer-
preview/
https://make.wordpress.org/core/2016/11/07/whitespace-changes-in-navigation-for-
4-7/
https://make.wordpress.org/core/2016/11/03/post-type-templates-in-4-7/
https://make.wordpress.org/core/2016/11/03/new-post-type-labels-in-4-7/
https://make.wordpress.org/core/2016/09/09/new-functions-hooks-and-behaviour-for-
theme-developers-in-wordpress-4-7/
### The Voyages of USS Media
Two notable changes, enhanced PDF support in the media library and changes to the
default fallbacks for image 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/
[Media also received other exciting enhancements and bug fixes you should check out](https://make.wordpress.org/core/2016/11/22/media-changes-in-4-7/).
### Around the World
The way users understand the words on WordPress are important and now users will
be able to select their personal preferred language.
https://make.wordpress.org/core/2016/11/07/user-admin-languages-and-locale-switching-
in-4-7/
### For Whom Customization Tolls
The customize component will now support the ability to create pages within live
preview during site setup; will have a faster, smoother, and more accessible navigation;
will automatically persist your changes in the background while you browse your
site and switch themes; and will let you fine-tune your site with custom CSSCSS
Cascading Style Sheets..
https://make.wordpress.org/core/?p=20534
https://make.wordpress.org/core/2016/10/12/customize-changesets-technical-design-
decisions/
https://make.wordpress.org/core/2016/09/28/changes-to-customizer-sliding-panelssections-
in-wordpress-4-7/
https://make.wordpress.org/core/2016/11/26/extending-the-custom-css-editor/
### Reading, Writing and Teriffic
Whether you’re creating content in the WordPress Adminadmin (and super admin) or
concerned about comment moderation, we’ve got updates that will be sure to please
you.
https://make.wordpress.org/core/2016/10/28/editor-changes-in-4-7/
https://make.wordpress.org/core/2016/10/11/comment-allowed-checks-in-wordpress-4-
7/
### The Foundation of WordPress
For those who like to get “under the hood” of WordPress, we’ve got some improvements
that will hopefully make your life easier.
https://make.wordpress.org/core/2016/11/07/changed-loading-order-for-current-user-
in-4-7/
https://make.wordpress.org/core/2016/11/04/multisite-focused-changes-in-4-7/
https://make.wordpress.org/core/2016/11/03/attributes-for-resource-hints-in-4-7/
https://make.wordpress.org/core/2016/11/02/wp_list_sort-and-wp_list_util-in-4-7/
https://make.wordpress.org/core/2016/10/29/wp_taxonomy-in-4-7/
https://make.wordpress.org/core/2016/10/28/fine-grained-capabilities-for-taxonomy-
terms-in-4-7/
https://make.wordpress.org/core/2016/09/08/wp_hook-next-generation-actions-and-filters/
https://make.wordpress.org/core/2016/10/26/registering-your-settings-in-wordpress-
4-7/
### But Wait, There is More!
Over 447 bugs, 165 enhancements, 8 feature requests, and 15 blessed tasks have been
[marked as fixed in WordPress 4.7](https://core.trac.wordpress.org/query?status=closed&milestone=4.7&group=component&col=id&col=summary&col=owner&col=type&col=priority&col=component&col=version&order=priority).
Some additional ones to highlight include:
* Make media library searchable by file name ([#22744](https://core.trac.wordpress.org/ticket/22744))
* Improved Custom Background Properties UIUI User interface ([#22058](https://core.trac.wordpress.org/ticket/22058))
* Hue-only Color Picker ([#38263](https://core.trac.wordpress.org/ticket/38263))
* Fix Sections that `.cannot-expand` ([#37980](https://core.trac.wordpress.org/ticket/37980))
* Allow Plugins to do Comprehensive Late Validation of Settings ([#37638](https://core.trac.wordpress.org/ticket/37638))
Please, test your code. Fixing issues now, before 4.7 is released, helps you and
helps millions of WordPress sites.
[#4-7](https://make.wordpress.org/core/tag/4-7/), [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/),
[#field-guide](https://make.wordpress.org/core/tag/field-guide/)
[ ](https://profiles.wordpress.org/celloexpressions/) [Nick Halsey](https://profiles.wordpress.org/celloexpressions/)
10:14 pm _on_ November 30, 2016
Tags: 4.7, [customize ( 67 )](https://make.wordpress.org/core/tag/customize/),
[dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/)
# [Customizer Improvements in 4.7](https://make.wordpress.org/core/2016/11/30/customizer-improvements-in-4-7/)
WordPress 4.7 has been the most active release on record for [the customize component](https://make.wordpress.org/core/component/customize),
with four major feature projects merging and shipping with 4.7 and [over 90 tickets closed as fixed](https://core.trac.wordpress.org/query?status=closed&component=Customize&milestone=4.7&groupdesc=1&group=type&col=id&col=summary&col=owner&col=priority&col=version&col=changetime&col=focuses&col=reporter&desc=1&order=changetime).
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:
```notranslate
$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](https://make.wordpress.org/core/2016/10/04/proposal-status-api-for-taxonomy-terms/)
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](https://codex.wordpress.org/Taxonomies#Default_Taxonomies).
terms in a future release (see [#37915](https://core.trac.wordpress.org/ticket/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](https://core.trac.wordpress.org/ticket/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](https://core.trac.wordpress.org/ticket/29158). This completes
a refresh of the customizer controls pane’s UI design that began in WordPress 4.3
with [#31336](https://core.trac.wordpress.org/ticket/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/](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](https://core.trac.wordpress.org/ticket/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](https://core.trac.wordpress.org/ticket/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/](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](https://core.trac.wordpress.org/query?status=closed&component=Customize&milestone=4.7&groupdesc=1&group=type&col=id&col=summary&col=owner&col=priority&col=version&col=changetime&col=focuses&col=reporter&desc=1&order=changetime),
we can’t cover everything here. But, here are a few more highlights:
### [[Improved Custom Background Properties UI
[#22058](https://core.trac.wordpress.org/ticket/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](https://core.trac.wordpress.org/ticket/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](https://core.trac.wordpress.org/ticket/20714))
* Hides edit post links in the customizer by default. Plugins, such as [Customize Posts](https://wordpress.org/plugins/customize-posts/),
can restore the links if they make post editing available in the customizer (
[#38648](https://core.trac.wordpress.org/ticket/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](https://core.trac.wordpress.org/ticket/38021))
## Additional Developer-oriented Changes
### [[Hue-only Color Picker
[#38263](https://core.trac.wordpress.org/ticket/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:
```notranslate
$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](https://github.com/WordPress/twentyseventeen/pull/324/files#diff-c6cfd16cf4d2c86fe26ff272d81a7695)
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](https://core.trac.wordpress.org/ticket/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](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](https://core.trac.wordpress.org/ticket/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](https://profiles.wordpress.org/westonruter/),
[@celloexpressions](https://profiles.wordpress.org/celloexpressions/), [@afercia](https://profiles.wordpress.org/afercia/),
[@sirbrillig](https://profiles.wordpress.org/sirbrillig/), [@ryankienstra](https://profiles.wordpress.org/ryankienstra/),
[@helen](https://profiles.wordpress.org/helen/), [@ocean90](https://profiles.wordpress.org/ocean90/),
[@melchoyce](https://profiles.wordpress.org/melchoyce/), [@bradyvercher](https://profiles.wordpress.org/bradyvercher/),
[@folletto](https://profiles.wordpress.org/folletto/), [@johnbillion](https://profiles.wordpress.org/johnbillion/),
[@delawski](https://profiles.wordpress.org/delawski/), [@karmatosed](https://profiles.wordpress.org/karmatosed/),
[@georgestephanis](https://profiles.wordpress.org/georgestephanis/), [@dlh](https://profiles.wordpress.org/dlh/),
[@curdin](https://profiles.wordpress.org/curdin/), [@valendesigns](https://profiles.wordpress.org/valendesigns/),
[@mattwiebe](https://profiles.wordpress.org/mattwiebe/), [@michaelarestad](https://profiles.wordpress.org/michaelarestad/),
[@joemcgill](https://profiles.wordpress.org/joemcgill/), [@sstoqnov](https://profiles.wordpress.org/sstoqnov/),
[@lgedeon](https://profiles.wordpress.org/lgedeon/), [@mihai2u](https://profiles.wordpress.org/mihai2u/),
[@coreymcollins](https://profiles.wordpress.org/coreymcollins/), [@stubgo](https://profiles.wordpress.org/stubgo/),
[@utkarshpatel](https://profiles.wordpress.org/utkarshpatel/), [@desrosj](https://profiles.wordpress.org/desrosj/),
[@odysseygate](https://profiles.wordpress.org/odysseygate/), [@johnregan3](https://profiles.wordpress.org/johnregan3/),
[@aaroncampbell](https://profiles.wordpress.org/aaroncampbell/), [@mapk](https://profiles.wordpress.org/mapk/),
[@iseulde](https://profiles.wordpress.org/iseulde/), [@mrahmadawais](https://profiles.wordpress.org/mrahmadawais/),
[@vishalkakadiya](https://profiles.wordpress.org/vishalkakadiya/), [@sayedwp](https://profiles.wordpress.org/sayedwp/),
[@hugobaeta](https://profiles.wordpress.org/hugobaeta/), [@jonathanbardo](https://profiles.wordpress.org/jonathanbardo/),
[@jorbin](https://profiles.wordpress.org/jorbin/), [@tristangemus](https://profiles.wordpress.org/tristangemus/),
[@deltafactory](https://profiles.wordpress.org/deltafactory/), [@kkoppenhaver](https://profiles.wordpress.org/kkoppenhaver/),
[@seancjones](https://profiles.wordpress.org/seancjones/), [@Presskopp](https://profiles.wordpress.org/Presskopp/),
[@Mista-Flo](https://profiles.wordpress.org/Mista-Flo/), [@nikeo](https://profiles.wordpress.org/nikeo/),
[@adamsilverstein](https://profiles.wordpress.org/adamsilverstein/), [@lukecavanagh](https://profiles.wordpress.org/lukecavanagh/),
[@coffee2code](https://profiles.wordpress.org/coffee2code/), [@peterwilsoncc](https://profiles.wordpress.org/peterwilsoncc/),
[@presskopp](https://profiles.wordpress.org/Presskopp/), [@pento](https://profiles.wordpress.org/pento/),
[@Kelderic](https://profiles.wordpress.org/Kelderic/), [@sebastian.pisula](https://profiles.wordpress.org/sebastian.pisula/),
[@mckernanin](https://profiles.wordpress.org/mckernanin/), [@FolioVision](https://profiles.wordpress.org/FolioVision/),
[@MikeHansenMe](https://profiles.wordpress.org/MikeHansenMe/), [@welcher](https://profiles.wordpress.org/welcher/),
[@cdog](https://profiles.wordpress.org/cdog/), [@grapplerulrich](https://profiles.wordpress.org/grapplerulrich/),
[@iamfriendly](https://profiles.wordpress.org/iamfriendly/), [@flixos90](https://profiles.wordpress.org/flixos90/).
[#4-7](https://make.wordpress.org/core/tag/4-7/), [#customize](https://make.wordpress.org/core/tag/customize/),
[#dev-notes](https://make.wordpress.org/core/tag/dev-notes/)
[ ](https://profiles.wordpress.org/helen/) [Helen Hou-Sandi](https://profiles.wordpress.org/helen/)
8:49 pm _on_ November 30, 2016
Tags: 4.7, [dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/)
# [Starter content for themes in 4.7](https://make.wordpress.org/core/2016/11/30/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](https://make.wordpress.org/core/2016/11/10/visible-edit-shortcuts-in-the-customizer-preview/),
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](https://core.trac.wordpress.org/ticket/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/](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](https://core.trac.wordpress.org/browser/trunk/src/wp-includes/theme.php?rev=39373#L1910)
using `add_theme_support()` – let’s look at a breakdown of [how Twenty Seventeen does things](https://core.trac.wordpress.org/browser/trunk/src/wp-content/themes/twentyseventeen/functions.php?rev=39373#L106).
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.
```notranslate
// 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.).
```notranslate
// 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.
```notranslate
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/](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/](http://wp-cli.org/) [https://make.wordpress.org/cli/](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](https://make.wordpress.org/core/2016/10/12/customize-changesets-technical-design-decisions/)
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 capabilitiescapability A **capability** is permission
to perform one or more types of task. Checking if a user has a capability is performed
by the `current_user_can` function. Each user of a WordPress site might have some
permissions but not others, depending on their role. For example, users who have
the Author role usually have permission to edit their own posts (the “edit_posts”
capability), but not permission to edit other users’ posts (the “edit_others_posts”
capability)., 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](https://profiles.wordpress.org/helen/)) in SlackSlack
Slack is a Collaborative Group Chat Platform [https://slack.com/](https://slack.com/).
The WordPress community has its own Slack Channel at [https://make.wordpress.org/chat/](https://make.wordpress.org/chat/)
should you be interested!
[#4-7](https://make.wordpress.org/core/tag/4-7/), [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/)
[ ](https://profiles.wordpress.org/davidakennedy/) [David A. Kennedy](https://profiles.wordpress.org/davidakennedy/)
12:22 am _on_ November 29, 2016
Tags: 4.7, [bundled-theme ( 84 )](https://make.wordpress.org/core/tag/bundled-theme/),
[dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/), [twenty-seventeen ( 17 )](https://make.wordpress.org/core/tag/twenty-seventeen/)
# [Theming with Twenty Seventeen](https://make.wordpress.org/core/2016/11/29/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](https://make.wordpress.org/core/2016/09/09/new-functions-hooks-and-behaviour-for-theme-developers-in-wordpress-4-7/).
## 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/](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.
```notranslate
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.
```notranslate
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:
```notranslate
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:
```notranslate
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](https://css-tricks.com/using-svg/)
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.
```notranslate
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:
```notranslate
'arrow-right', 'title' => __( 'This is title', 'childtheme' ) ) ); ?>
```
Another example with title and desc (description):
```notranslate
'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_](https://www.paciellogroup.com/blog/2013/12/using-aria-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:
```notranslate
function childtheme_custom_colors_saturation() {
return 25;
}
add_filter( 'twentyseventeen_custom_colors_saturation', 'childtheme_custom_colors_saturation' );
```
[](https://make.wordpress.org/core/2016/11/29/theming-with-twenty-seventeen/paste-1479936661525/#main)
Saturation at 25. [](https://make.wordpress.org/core/2016/11/29/theming-with-twenty-seventeen/paste-1479936678299/#main)
Saturation at 50 (default). [](https://make.wordpress.org/core/2016/11/29/theming-with-twenty-seventeen/paste-1479936691280/#main)
Saturation at 75.
[](https://make.wordpress.org/core/2016/11/29/theming-with-twenty-seventeen/paste-1479936702694/#main)
Saturation at 100.
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](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:
```notranslate
// 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](https://make.wordpress.org/core/tag/4-7/), [#bundled-theme](https://make.wordpress.org/core/tag/bundled-theme/),
[#dev-notes](https://make.wordpress.org/core/tag/dev-notes/), [#twenty-seventeen](https://make.wordpress.org/core/tag/twenty-seventeen/)
[ ](https://profiles.wordpress.org/bradyvercher/) [Brady Vercher](https://profiles.wordpress.org/bradyvercher/)
10:25 pm _on_ November 26, 2016
Tags: 4.7, custom-header, [customize ( 67 )](https://make.wordpress.org/core/tag/customize/),
[dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/), [themes ( 43 )](https://make.wordpress.org/core/tag/themes/)
# [Video Headers in 4.7](https://make.wordpress.org/core/2016/11/26/video-headers-in-4-7/)
WordPress 4.7 extends the [Custom Header](https://developer.wordpress.org/themes/functionality/custom-headers/)
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](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](https://developer.wordpress.org/themes/functionality/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](https://make.wordpress.org/core/2015/11/10/responsive-images-in-wordpress-4-4/).
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**
``
**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](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](https://make.wordpress.org/core/2016/02/16/selective-refresh-in-the-customizer/)
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](https://make.wordpress.org/core/2016/07/05/customizer-apis-in-4-6-for-setting-validation-and-notifications/)
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/](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](https://github.com/bradyvercher/custom-header-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](https://make.wordpress.org/core/tag/4-7/), [#custom-header](https://make.wordpress.org/core/tag/custom-header/),
[#customize](https://make.wordpress.org/core/tag/customize/), [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/),
[#themes](https://make.wordpress.org/core/tag/themes/)
[ ](https://profiles.wordpress.org/georgestephanis/) [George Stephanis](https://profiles.wordpress.org/georgestephanis/)
8:03 pm _on_ November 26, 2016
Tags: 4.7, [CSS ( 10 )](https://make.wordpress.org/core/tag/css/),
[customize ( 67 )](https://make.wordpress.org/core/tag/customize/), [dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/)
# [Extending the Custom CSS editor](https://make.wordpress.org/core/2016/11/26/extending-the-custom-css-editor/)
With the [Custom CSS project](https://make.wordpress.org/core/2016/10/11/feature-proposal-better-theme-customizations-via-custom-css-with-live-previews/)
[merging into WordPress Core](https://core.trac.wordpress.org/changeset/38829),
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/](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/](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](https://core.trac.wordpress.org/ticket/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 = '' )`](https://github.com/WordPress/WordPress/blob/ad80e08c17491c870fc834ef382303dc7ac3cd63/wp-includes/theme.php#L1576-L1621)—
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](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](https://core.trac.wordpress.org/changeset/39209)
in the [`WP_Customize_Custom_CSS_Setting` class](https://github.com/WordPress/WordPress/blob/ad80e08c17491c870fc834ef382303dc7ac3cd63/wp-includes/customize/class-wp-customize-custom-css-setting.php)
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](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](https://github.com/xwp/wp-custom-scss-demo)
plugin on GitHubGitHub GitHub is a website that offers online implementation of
git repositories that 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 by the repository
owner. [https://github.com/](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` capabilitycapability A **capability**
is permission to perform one or more types of task. Checking if a user has a capability
is performed by the `current_user_can` function. Each user of a WordPress site might
have some permissions but not others, depending on their role. For example, users
who have the Author role usually have permission to edit their own posts (the “edit_posts”
capability), but not permission to edit other users’ posts (the “edit_others_posts”
capability). ([which Core defaults to `unfiltered_html`](https://github.com/WordPress/WordPress/blob/3a449ea5439b547cf3f9119cbfe9503cadeaeedb/wp-includes/capabilities.php#L344-L353))
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:
```notranslate
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](https://wordpress.slack.com/messages/core-customize/)
on [Slack ](https://chat.wordpress.org/)with any unexpected use cases or concerns!
[#4-7](https://make.wordpress.org/core/tag/4-7/), [#css](https://make.wordpress.org/core/tag/css/),
[#customize](https://make.wordpress.org/core/tag/customize/), [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/)
[ ](https://profiles.wordpress.org/joemcgill/) [Joe McGill](https://profiles.wordpress.org/joemcgill/)
9:20 pm _on_ November 22, 2016
Tags: 4.7, [dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/),
[media ( 93 )](https://make.wordpress.org/core/tag/media/)
# [Media Changes in 4.7](https://make.wordpress.org/core/2016/11/22/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](https://core.trac.wordpress.org/query?component=Media&milestone=4.7&col=id&col=summary&col=status&col=owner&col=type&col=priority&col=version&order=priority).
Two notable changes, [enhanced PDF support in the media library](https://make.wordpress.org/core/2016/11/15/enhanced-pdf-support-4-7/)
and [changes to the default fallbacks for `alt` attributes](https://make.wordpress.org/core/wp-admin/post.php?post=20579),
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](https://core.trac.wordpress.org/ticket/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](https://core.trac.wordpress.org/ticket/37813))
* Fix Drag/Drop Ordering of Media in Chrome on touch enabled devices ([#31652](https://core.trac.wordpress.org/ticket/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](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](https://core.trac.wordpress.org/ticket/34437)).
* Improve docs for `image_send_to_editor` filter ([#34823](https://core.trac.wordpress.org/ticket/34823)).
* Use `wp_get_attachment_metadata()` instead of `get_post_meta()` where appropriate(
[#36246](https://core.trac.wordpress.org/ticket/36246)).
* Ensure `wp_get_attachment_link()` output text for non-images ([#37343](https://core.trac.wordpress.org/ticket/37343)).
* Avoid undefined index notices when `pathinfo()` is used ([#37608](https://core.trac.wordpress.org/ticket/37608)).
* Improve alignment of inputs and button heights in media edit screens ([#37806](https://core.trac.wordpress.org/ticket/37806)).
* Set focus when closing the media modal ([#38142](https://core.trac.wordpress.org/ticket/38142)).
[#4-7](https://make.wordpress.org/core/tag/4-7/), [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/),
[#media](https://make.wordpress.org/core/tag/media/)
[ ](https://profiles.wordpress.org/kirasong/) [Kira Schroder](https://profiles.wordpress.org/kirasong/)
6:12 pm _on_ November 15, 2016
Tags: 4.7, [dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/),
[media ( 93 )](https://make.wordpress.org/core/tag/media/)
# [Enhanced PDF Support in WordPress 4.7](https://make.wordpress.org/core/2016/11/15/enhanced-pdf-support-4-7/)
WordPress 4.7 makes it easier to preview PDFs in the media library by generating
image representations of the first page, which are now used throughout the media
library and media attachment screens.
[[
If a `WP_Image_Editor` is available that supports PDF, the following sizes are generated:
* Full size representation, rendered at 128dpi.
* Thumbnail (without cropping)
* Medium
* Large
The sizes generated can be modified, or the feature disabled entirely via the new`
fallback_intermediate_image_sizes` filterFilter Filters are one of the two types
of Hooks [https://codex.wordpress.org/Plugin_API/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., and are all stored in the `sizes` array in attachment 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..
The preview images generated are used within the Media screen, Gallery, Attachment
Details, and on the Attachment page for PDFs.
[[
[[CoreCore Core is the set of software required to run WordPress. The Core Development
Team builds WordPress. support is provided through `WP_Image_Editor_Imagick` and
requires Imagick, ImageMagick, and Ghostscript support. When not supported, or if
the generation fails, WordPress falls back to previous behavior and saves the attachment
without adding image previews to meta.
For more context, see [#31050](https://core.trac.wordpress.org/ticket/31050) for
the primary ticketticket Created for both bug reports and feature development on
the bug tracker. and [#38594](https://core.trac.wordpress.org/ticket/38594) for
the filter.
### Updated:
Since this change requires having Imagick load only the first page of a PDF for
performance reasons, this means that if you rely on core loading the entire PDF
for your extension of `WP_Image_Editor_Imagick`, this will no longer function as
expected (See: [#38832](https://core.trac.wordpress.org/ticket/38832)).
As a result, in [[39303]](https://core.trac.wordpress.org/changeset/39303), the
PDF setup code was moved to `WP_Image_Editor_Imagick->pdf_setup()`, which can be
overridden to restore the previous behavior if needed.
[#4-7](https://make.wordpress.org/core/tag/4-7/), [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/),
[#media](https://make.wordpress.org/core/tag/media/)
[ ](https://profiles.wordpress.org/joemcgill/) [Joe McGill](https://profiles.wordpress.org/joemcgill/)
5:40 pm _on_ November 11, 2016
Tags: 4.7, [accessibility ( 59 )](https://make.wordpress.org/core/tag/accessibility/),
[dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/), [media ( 93 )](https://make.wordpress.org/core/tag/media/)
# [Improving accessibility of image alternative text in 4.7](https://make.wordpress.org/core/2016/11/11/improving-accessibility-of-image-alternative-text-in-4-7/)
WordPress 4.7 includes a change to the way image `alt` attribute values are generated.
Formerly, any time WordPress created the markup for an image with an empty `alt`
value, it would attempt to use either the caption text or the image title—in that
order—as a fallback value.
In 4.7, we have removed this fallback behavior.
To ensure your images having meaningful alternative text, you should make sure to
set a value for alt text in your media library.
## How removing fallbacks improves 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)
The intent of the fallbacks were to ensure each image included alternative text.
In practice however, this fallback behavior often resulted in poor user experiences
for people using screen readers. As counterintuitive as that may seem, let’s take
a look at some common examples.
Consider a situation where we’ve uploaded an image named “edbc4ef7.jpg” without
changing any additional information. WordPress will generate the image title from
the file name as shown in the following screenshot of the insert media modal.
Attachment details for an image shown in the insert media modal.
Formerly, inserting this image in a post would result in HTMLHTML HyperText Markup
Language. The semantic scripting language primarily used for outputting content
in web browsers. similar to this (simplified slightly for clarity):
```
```
A person using a screenreader on this page would end up hearing the file name read
to them, which is not the most helpful experience, and can be quite frustrating
when the file name is lengthy.
For another example, setting a caption value but no alternative text would result
in markup that looks something like this:
```
This is a caption.
```
Notice that the `alt` value and the `figcaption` text are redundant? WebAIM [describes two ways](http://webaim.org/techniques/alttext/#basics)
of presenting alternative text:
* Within the `alt` attribute of the `img` element.
* Within the context or surroundings of the image itself.
The same article goes on to explain that an `alt` [attribute value may be omitted](http://webaim.org/techniques/alttext/#figure)
when an identical `figcaption` is present, to avoid redundancy; but best practice
when using a `figcaption` is to provide a separate and different `alt` attribute
to describe that image to users of screen readers.
In each case, omitting the `alt` attribute entirely may result in screen readers
reading the file name from the `src` attribute, so WordPress includes an `alt` attribute
with an empty value, i.e. `alt=""`, whenever the alternative text hasn’t been explicitly
set—a technique that is common when an image is decorative.
This change will not affect content already published, but will be the expected
behavior for any new content published after upgrading to 4.7. For more background
on this issue, see ticketticket Created for both bug reports and feature development
on the bug tracker. [#34635](https://core.trac.wordpress.org/ticket/34635).
[#4-7](https://make.wordpress.org/core/tag/4-7/), [#accessibility](https://make.wordpress.org/core/tag/accessibility/),
[#dev-notes](https://make.wordpress.org/core/tag/dev-notes/), [#media](https://make.wordpress.org/core/tag/media/)
[ ](https://profiles.wordpress.org/celloexpressions/) [Nick Halsey](https://profiles.wordpress.org/celloexpressions/)
7:18 pm _on_ November 10, 2016
Tags: 4.7, [customize ( 67 )](https://make.wordpress.org/core/tag/customize/),
[dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/), [themes ( 43 )](https://make.wordpress.org/core/tag/themes/)
# [Visible Edit Shortcuts in the Customizer Preview](https://make.wordpress.org/core/2016/11/10/visible-edit-shortcuts-in-the-customizer-preview/)
[#27403](https://core.trac.wordpress.org/ticket/27403) added visible edit shortcuts
to 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. preview, making it easier to see which elements of your site are editable
in the customizer and how to edit them. Here’s a demo with Twenty Fifteen (note
that the ability to toggle icons off has since been removed):
[[
## Implementation: Selective Refresh Partials
Visible edit shortcuts are an extension of the existing “shift-click-to-edit” functionality
built into customizer partials. Partials are sections of the front end of the site,
in the customizer preview, that are associated with customizer settings. When settings
change, their associated partials are selectively refreshed via an Ajax call without
reloading the entire preview. Partials are to the customizer preview what controls
are to the customizer editing pane: a visual representation of a setting.
Buttons are now injected into partials within the preview to expose this relationship
visually and to users of all input modes. However, the role of the customizer preview
is to provide an accurate representation of the frontend of the site as it’ll appear
once changes are published. Accordingly, visible edit shortcuts pose a challenge
as they have the potential to significantly hamper the preview-ability of the preview.
To balance between discoverability and providing an accurate preview, the initial
coreCore Core is the set of software required to run WordPress. The Core Development
Team builds WordPress. iteration showed a flash of the buttons when the preview
first loads, then hid them. To show the shortcuts, or to toggle them on and off,
you could click/tap anywhere in the preview (except on a link or `button`). Keyboard
users had a `screen-reader-text` button (visible on focus) to toggle the shortcuts
on and off. This functionality was removed in [[39131]](https://core.trac.wordpress.org/changeset/39131)
and icons are currently persistently visible when customizing but hidden when the
controls are collapsed, and [supplemental usability testing validated this decision](https://make.wordpress.org/design/2016/11/04/4-7-beta-1-user-testing-in-the-customizer-and-with-twenty-seventeen/).
## Background & Prior Implementations
Shift-click to edit an element in the customizer preview was first implemented with
the [widget customizer](https://make.wordpress.org/core/2014/01/28/widget-customizer-feature-as-plugin-merge-proposal/)
project in WordPress 3.9. Visual approaches to exposing this functionality were
explored, but left for a future release. Selective refresh was also first proposed,
and put on hold pending development of the concept.
The [first core implementation of selective refresh](https://make.wordpress.org/core/2015/07/29/fast-previewing-changes-to-menus-in-the-customizer/)
came with [menu management in the customizer](https://make.wordpress.org/core/2015/06/03/feature-plugin-merge-proposal-menu-customizer/)
in WordPress 4.3. Menus include shift-click-to-edit on a per-menu-item bases, further
demonstrating the powerful potential of associating portions of the customizer preview
with their associated settings and controls.
WordPress.comWordPress.com An online implementation of WordPress code that lets
you immediately access a new WordPress environment to publish your content. WordPress.
com is a private company owned by Automattic that hosts the largest multisite in
the world. This is arguably the best place to start blogging if you have never touched
WordPress before. [https://wordpress.com/](https://wordpress.com/) currently supports
a similar feature with visible edit icons in the customizer. This approach serves
as the inspiration for the final UIUI User interface being introduced in core, with
additional UXUX User experience adjustments and a complete rewrite of the implementation
to make it compatible with as many themes as possible.
## Adding Theme Support
Theme support for this feature is all about supporting [selective refresh, which was added in WordPress 4.5](https://make.wordpress.org/core/2016/02/16/selective-refresh-in-the-customizer/).
In some cases, a small amount of additional CSSCSS Cascading Style Sheets. will
be required to ensure that the shortcuts are positioned properly. Edit shortcuts
will be enabled by default for all themes, but are contingent on themes supporting
selective refresh.
### Selective Refresh for Widgets
See the post from WordPress 4.5 for adding support for selective refresh for widgets.
In most cases, `add_theme_support( 'customize-selective-refresh-widgets' )` is the
only requirement:
https://make.wordpress.org/core/2016/03/22/implementing-selective-refresh-support-
for-widgets/
### Selective Refresh for Menus
Menus support selective refresh out of the box unless: a custom nav menu walker
is used, the `echo` argument is `false`, or `wp_nav_menu` isn’t used. In those cases,
you’ll need to add support directly. Some themes may still be missing full support
for selective refresh of menus, which has been enabled by default since WordPress
4.3. Reference the post for details, but note that it predates the core implementation
of an 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. for selective refresh:
https://make.wordpress.org/core/2015/07/29/fast-previewing-changes-to-menus-in-the-
customizer/
### Selective Refresh for Custom Options
Custom logo (since 4.5) and 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. video (since 4.7) support selective
refresh automatically if you use the core features via `add_theme_support`. Other
core options such as the site title and tagline or header images can support selective
refresh if you register partials for them and set their settings’ `transport` argument
to `postMessage`. Here’s an example from Twenty Fifteen:
```notranslate
$wp_customize->get_setting( 'blogname' )->transport = 'postMessage';
$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
$wp_customize->selective_refresh->add_partial( 'blogname', array(
'selector' => '.site-title a',
'render_callback' => 'twentyfifteen_customize_partial_blogname',
) );
$wp_customize->selective_refresh->add_partial( 'blogdescription', array(
'selector' => '.site-description',
'render_callback' => 'twentyfifteen_customize_partial_blogdescription',
) );
```
Where the render callbacks call `bloginfo( 'name' );` and `bloginfo( 'description');`
For more details on adding support for selective refresh for custom theme options,
[reference the official customizer documentation](https://developer.wordpress.org/themes/advanced-topics/customizer-api/#selective-refresh-fast-accurate-updates).
### Support in Default Themes
Twenty Eleven through Sixteen support selective refresh as of WordPress 4.5, and
also support edit icons for most of their features as a result. Twenty Fourteen
and Sixteen require a few very minor positioning tweaks to ensure that all of the
icons are visible. This is typical of what most themes could expect needing to add.
Twenty Seventeen will be a great showcase for this new functionality, as the first
theme to ship natively with selective refresh support and with visible edit shortcuts.
A few additional adjustments in this new theme will ensure that every option can
be previewed with selective refresh and provides visible edit shortcuts where appropriate.
## Limitations & Future Iterations
The biggest limitation of the current approach is that implementation is entirely
dependent on themes supporting it. However, unlike with many other theme-supported
features, there is no `add_theme_support` for visible edit shortcuts. Where themes
are already using selective refresh, shortcuts will be available out of the box
in WordPress 4.7. To add theme support for edit shortcuts, themes need to add theme
support for selective refresh, another newer customizer feature that allows the
customizer preview to update granularly. Selective refresh provides superior user
experience to the default `refresh` behavior because the preview context is not
lost when changes are made.
Edit shortcuts currently rely on the presence of selective refresh partials for
every setting that needs an icon. Some settings may be previewed exclusively with
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](https://www.javascript.com/)
via postMessage. Icons also aren’t needed for every option; for example, layout
or color options are broader than a specific area of the site, so they aren’t associated
with a particular edit icon in the preview. In the future, a structured JavaScript
API for partials in the customizer preview could facilitate adding icons to JSJS
JavaScript, a web scripting language typically executed in the browser. Often used
for advanced user interfaces and behaviors.-previewed settings that don’t use selective
refresh.
Visible edit shortcuts are also the first step toward exploring the potential to
edit elements of a site directly within the customizer preview. For this to be fully
investigated, it’s imperative that a majority of themes and customizer option support
selective refresh so that areas of the preview are associated with the appropriate
customizer settings and so that context-disrupting full page reloads can be minimized.
## Contributors & Call for Help
[@sirbrillig](https://profiles.wordpress.org/sirbrillig/) led development of the
feature for core based on the equivalent feature on WordPress.com. Core props went
to [@sirbrillig](https://profiles.wordpress.org/sirbrillig/), [@mattwiebe](https://profiles.wordpress.org/mattwiebe/),
[@celloexpressions](https://profiles.wordpress.org/celloexpressions/), [@melchoyce](https://profiles.wordpress.org/melchoyce/),
[@westonruter](https://profiles.wordpress.org/westonruter/), and [@afercia](https://profiles.wordpress.org/afercia/).
Thanks to everyone who has contributed so far!
**Now, _your_ help is needed! Here’s what you can do to make this feature shine
in WordPress 4.7**:
* _Theme authors_: add support for selective refresh to your themes. Start with
widgets and make sure it’s working for menus, then make sure you’re using the
core custom logo feature. Then, add selective refresh to the site title and tagline,
header images, and any custom options with associated regions on the frontend.
* _Theme authors_: adjust icon positioning in your theme’s CSS. You can add styles
to`.customize-partial-icon button` to adjust all icons, and scope that to a specific
container or even `.customize-partial-icon-setting_id` to adjust a particular
edit icon. Note: these were updated with [[39136]](https://core.trac.wordpress.org/changeset/39136).
* _Everyone_: test edit shortcuts with your current theme with WordPress 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. 1 (or newer). Most
themes should be able to support them on widgets, menus, and logos with minimal
effort. Contact your theme’s developer with any bugs or missing edit icon support,
refer them to this post, and ask them to add support for visible edit shortcuts.
* _Everyone_: test as many themes as possible and look for anywhere the shortcuts
don’t display as expected, or at all. Contact the theme author with your findings,
refer them to this post, and ask them to improve support for visible edit shortcuts
in their themes.
[#4-7](https://make.wordpress.org/core/tag/4-7/), [#customize](https://make.wordpress.org/core/tag/customize/),
[#dev-notes](https://make.wordpress.org/core/tag/dev-notes/), [#themes](https://make.wordpress.org/core/tag/themes/)
# Post navigation
[← Older posts](https://make.wordpress.org/core/tag/4-7+dev-notes/page/2/?output_format=md)
```
A person using a screenreader on this page would end up hearing the file name read
to them, which is not the most helpful experience, and can be quite frustrating
when the file name is lengthy.
For another example, setting a caption value but no alternative text would result
in markup that looks something like this:
```