Title: customize – Make WordPress Core
---
# Tag Archives: customize
[ ](https://profiles.wordpress.org/antonvlasenko/) [Anton Vlasenko](https://profiles.wordpress.org/antonvlasenko/)
4:29 pm _on_ January 7, 2022
Tags: [5.9 ( 104 )](https://make.wordpress.org/core/tag/5-9/),
[block themes ( 8 )](https://make.wordpress.org/core/tag/block-themes/), customize,
[customizer ( 6 )](https://make.wordpress.org/core/tag/customizer/), [full-site editing ( 15 )](https://make.wordpress.org/core/tag/full-site-editing/)
# [State of the Customizer with block themes in WordPress 5.9](https://make.wordpress.org/core/2022/01/07/state-of-the-customizer-with-block-themes-in-wordpress-5-9/)
With WordPress 5.9 [bringing support for block themes](https://make.wordpress.org/core/2022/01/04/block-themes-a-new-way-to-build-themes-in-wordpress-5-9/),
this results in a few changes to how 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. works and how one can preview themes.
At a high level, this post covers how blockBlock Block is the abstract term used
to describe units of markup that, composed together, form the content or layout
of a webpage using the WordPress editor. The idea combines concepts of what in the
past may have achieved with shortcodes, custom HTML, and embed discovery into a
single consistent API and user experience. themes cannot be previewed due to the
introduction of the [Site Editor](https://wordpress.org/support/article/site-editor/)
and how the Customizer itself will only appear if a non-block theme is activated
or a site has 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. that interacts with the Customizer.
## Previewing block themes
If you activate a non-block theme like `Twenty Twenty-One`, open the Customizer,
and click on the `Change` button in the `Active theme` section, you will see a warning
message displayed for each block theme. Please see the example below:
[⌊A warning message is displayed for each block theme in the Customizer⌉⌊A warning
message is displayed for each block theme in the Customizer⌉[
It is displayed because the Customizer doesn’t support block themes. They can be
customized in the [Site Editor](https://wordpress.org/support/article/site-editor/)
instead.
As a result, to customize a block-based theme, you need to activate it first. If
you’re concerned about doing so, it’s recommended that you[ set up a test site](https://wordpress.org/support/article/test-driving-wordpress/)
first to explore the theme.
Also, it is not possible to preview inactive block themes because the [Site Editor](https://wordpress.org/support/article/site-editor/)
only works with the currently activated block theme. This means that the `Live Preview`
button is not displayed for inactive block themes.
Once [the ability to preview any block theme in the Site Editor](https://github.com/WordPress/gutenberg/issues/37201)
is implemented, it will be possible to enable the `Live Preview` button for block
themes as well.
## Previewing non-block themes
Previewing non-block themes works the same way as in WordPress 5.8. Nothing has
changed here.
## Customizer and block themes
WordPress removes the Customizer from the `Appearance` menu if a block theme is
enabled. Why? Block themes are customizable within the [Site Editor](https://wordpress.org/support/article/site-editor/)
rather than the Customizer.
However, if any callback function is registered for the `[customize_register](https://developer.wordpress.org/reference/hooks/customize_register/)`
action, the `Customize` menu item will be added. This is necessary to ensure compatibility
with plugins that still require the Customizer to be present in the `Appearance`
menu.
Because the Customizer shows up conditionally, various links have been adjusted
depending on the type of active theme to ensure a smooth user experience.
For example, if a block theme is activated, the link in the Welcome banner leads
to the [Site editor](https://wordpress.org/support/article/site-editor/). However,
if a non-block theme is active, it leads to the Customizer.
## Summary
If you need to preview or edit a block theme, activate it first. Previewing non-
block themes will continue to work the same way.
WordPress will only add the `Customize` menu item if a non-block theme is activated
or a plugin interacts with the Customizer (please see the `[customize_register](https://developer.wordpress.org/reference/hooks/customize_register/)`
action).
TracTrac An open source project by Edgewall Software that serves as a bug tracker
and project management tool for WordPress. tickets: [#54549](https://core.trac.wordpress.org/ticket/54549)(
warning messages for block themes in the Customizer), [#54460](https://core.trac.wordpress.org/ticket/54460)(
change links depending on the type of active theme), [#54337](https://core.trac.wordpress.org/ticket/54337)(
conditionally show the Customizer in the `Appearance` menu).
---
_Props to _[@annezazu](https://profiles.wordpress.org/annezazu/)_ and _[@hellofromtonya](https://profiles.wordpress.org/hellofromtonya/)_
for technical review and proofreading; props to _[@audrasjb](https://profiles.wordpress.org/audrasjb/)_
for proofreading; props to [@desrosj](https://profiles.wordpress.org/desrosj/) for
providing general feedback on this post._
[#5-9](https://make.wordpress.org/core/tag/5-9/), [#block-themes](https://make.wordpress.org/core/tag/block-themes/),
[#customize](https://make.wordpress.org/core/tag/customize/), [#customizer](https://make.wordpress.org/core/tag/customizer/),
[#full-site-editing](https://make.wordpress.org/core/tag/full-site-editing/)
[ ](https://profiles.wordpress.org/westonruter/) [Weston Ruter](https://profiles.wordpress.org/westonruter/)
11:35 pm _on_ November 3, 2017
Tags: [4.9 ( 81 )](https://make.wordpress.org/core/tag/4-9/),
customize, [dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/)
# [New Features and Enhancements with Customizer Changesets in 4.9](https://make.wordpress.org/core/2017/11/03/new-features-and-enhancements-with-customizer-changesets-in-4-9/)
In WordPress 4.7 the concept of **changesets** was introduced 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. ([#30937](https://core.trac.wordpress.org/ticket/30937)).
To understand the new Customizer improvements in 4.9, you must first go back and
review what was [proposed](https://make.wordpress.org/core/2016/10/12/customize-changesets-formerly-transactions-merge-proposal/)
and [implemented](https://make.wordpress.org/core/2016/10/12/customize-changesets-formerly-transactions-merge-proposal/)
a year ago:
> [Customize Changesets Technical Design Decisions](https://make.wordpress.org/core/2016/10/12/customize-changesets-technical-design-decisions/)
Changesets are a way to persistently store changes made via the Customizer framework.
Changesets contain the pending changes for any number of settings, and a setting
can model any object in WordPress—whether options, theme mods, nav menu items, widgets,
or even posts/pages and their postmeta. Changesets are identified by UUID (which
is the `post_name` for the `customize_changeset` post type that stores the data
as JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for
structuring data. It is used primarily to transmit data between a server and web
application, as an alternative to XML. in `post_content`). When a request is made
to WordPress with the `customize_changeset_uuid` request param—whether to the frontend
or to the REST APIREST API The REST API is an acronym for the RESTful Application
Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data.
It is how the front end of an application (think “phone app” or “website”) can communicate
with the data store (think “database” or “file system”) [https://developer.wordpress.org/rest-api/](https://developer.wordpress.org/rest-api/)—
the Customizer framework will bootstrap and all of the values from the changeset
will be read and applied to the response via WordPress filters added by the settings’
respective `WP_Customize_Setting::preview()` methods.
Only an authorized user can write changes into a changeset for a given setting (
according to its respective `capability`). But once it has been written then anyone
can preview the site with the changes in the changeset applied: all that is needed
is the UUID. Since previewing a changeset is now a readonly operation (whereas before
4.7 it was always a `POST` request), a changeset can be previewed on a site by authenticated
and _unauthenticated_ users alike. With the changeset UUID supplied when opening
the Customizer, a user can keep iterating on a set of changes over several days
or longer and only publish them once stakeholders are satisfied. Now, freelancers
and agencies will be better able to communicate and collaborate on site changes
with clients.
Once a `customize_changeset` post transitions to the `publish` status then all of
the values in the changeset will be passed into their respective `WP_Customize_Setting::
update()` methods to publish (“go live”) on the site: in version controlversion
control A version control system keeps track of the source code and revisions to
the source code. WordPress uses Subversion (SVN) for version control, with Git mirrors
for most repositories. terminology, the staged values from the changeset get committed
and pushed. All of the changes go live together in a batch save operation (originally
changesets were termed “transactions”).
As noted in the 4.7 [merge proposal](https://make.wordpress.org/core/2016/10/12/customize-changesets-formerly-transactions-merge-proposal/):
> For the initial coreCore Core is the set of software required to run WordPress.
> The Core Development Team builds WordPress. merge, no UIUI User interface changes
> are being proposed. The feature will only be exposed as the new query parameter
> on the URLURL A specific web address of a website or web page on the Internet,
> such as a website’s URL www.wordpress.org. Adding a UI to this feature will happen
> in a future release.
The future [release] is now. Where the infrastructure of changesets was merged from
the [Customize Changesets](https://wordpress.org/plugins/customize-snapshots/) feature
pluginFeature Plugin A plugin that was created with the intention of eventually
being proposed for inclusion in WordPress Core. See [Features as Plugins](https://make.wordpress.org/core/handbook/about/release-cycle/features-as-plugins/)
in 4.7, the key UI features from the 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. are now being merged in 4.9 after
a significant number of design iterations.
This dev notedev note Each important change in WordPress Core is documented in a
developers note, (usually called dev note). Good dev notes generally include a description
of the change, the decision that led to this change, and a description of how developers
are supposed to work with that change. Dev notes are published on Make/Core blog
during the beta phase of WordPress release cycle. Publishing dev notes is particularly
important when plugin/theme authors and WordPress developers need to be aware of
those changes.In general, all dev notes are compiled into a Field Guide at the beginning
of the release candidate phase. contains sections on the following:
* [Changeset Drafting](https://make.wordpress.org/core/2017/11/03/new-features-and-enhancements-with-customizer-changesets-in-4-9/#changeset-drafting)
* [Changeset Scheduling](https://make.wordpress.org/core/2017/11/03/new-features-and-enhancements-with-customizer-changesets-in-4-9/#changeset-scheduling)
* [Changeset Autoloading and Linear Mode](https://make.wordpress.org/core/2017/11/03/new-features-and-enhancements-with-customizer-changesets-in-4-9/#changeset-autoloading)
* [Changeset Branching Mode](https://make.wordpress.org/core/2017/11/03/new-features-and-enhancements-with-customizer-changesets-in-4-9/#changeset-branching-mode)
* [Autosaving Auto-Drafts and Autosave Revisions](https://make.wordpress.org/core/2017/11/03/new-features-and-enhancements-with-customizer-changesets-in-4-9/#changeset-autosaving)
* [Changeset Post Locking](https://make.wordpress.org/core/2017/11/03/new-features-and-enhancements-with-customizer-changesets-in-4-9/#changeset-post-locking)
* [Customization Drafts](https://make.wordpress.org/core/2017/11/03/new-features-and-enhancements-with-customizer-changesets-in-4-9/#changeset-customization-drafts)
[Continue reading →](https://make.wordpress.org/core/2017/11/03/new-features-and-enhancements-with-customizer-changesets-in-4-9/#more-23816)
[#4-9](https://make.wordpress.org/core/tag/4-9/), [#customize](https://make.wordpress.org/core/tag/customize/),
[#dev-notes](https://make.wordpress.org/core/tag/dev-notes/)
[ ](https://profiles.wordpress.org/westonruter/) [Weston Ruter](https://profiles.wordpress.org/westonruter/)
6:19 pm _on_ November 1, 2017
Tags: [4.9 ( 81 )](https://make.wordpress.org/core/tag/4-9/),
customize, [dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/)
# [Improvements to the Customize JS API in 4.9](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/)
There are many user-facing 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. improvements in 4.9, including: drafting/scheduling
of changesets, autosave 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.,
changeset post locking, frontend public previews, a new experience for browsing
and installing themes, updated nav menu creation UXUX User experience, and the code
editing improvements for the Custom HTMLHTML HyperText Markup Language. The semantic
scripting language primarily used for outputting content in web browsers. 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. and Additional
CSSCSS Cascading Style Sheets.. _But_ in addition to all of these, there are also
many improvements for developers which will make extending the Customizer much more
pleasant.
Something important to remember about the Customizer is that it is a single page
application that is powered by 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/).
Many developers may only interact with the PHPPHP The web scripting language in
which WordPress is primarily architected. WordPress requires PHP 7.4 or higher 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 registering controls, settings, sections, panels, and partials. But controls,
sections, and panels do not need to be registered in PHP at all. The PHP API for
registration is essentially a wrapper for the underlying JSJS JavaScript, a web
scripting language typically executed in the browser. Often used for advanced user
interfaces and behaviors. API. When you load the Customizer all of the params for
the PHP-registered constructs are exported to the client for the JavaScript API
to instantiate and initially add to the UIUI User interface, but this JS API can
dynamically instantiate additional constructs at any time thereafter in a Customizer
session. This is how new widgets, nav menus, and nav menu items are added without
requiring the entire Customizer to reload. You can also avoid statically registering
settings and partials in PHP by instead adding filters to dynamically recognize
settings and partials, allowing them to be registered on demand. All of this allows
the Customizer application to scale out to be able to customize and preview an unlimited
number of things on a site (e.g. any post or page with their postmeta in the [Customize Posts](https://wordpress.org/plugins/customize-posts/)
feature pluginFeature Plugin A plugin that was created with the intention of eventually
being proposed for inclusion in WordPress Core. See [Features as Plugins](https://make.wordpress.org/core/handbook/about/release-cycle/features-as-plugins/)).
The point here is that in order for the Customizer to scale, the JavaScript API
must be used directly. So this is why the Customizer JS API improvements in 4.9
are important as they fix many longstanding annoyances and shortcomings with the
JS API.
This dev notedev note Each important change in WordPress Core is documented in a
developers note, (usually called dev note). Good dev notes generally include a description
of the change, the decision that led to this change, and a description of how developers
are supposed to work with that change. Dev notes are published on Make/Core blog
during the beta phase of WordPress release cycle. Publishing dev notes is particularly
important when plugin/theme authors and WordPress developers need to be aware of
those changes.In general, all dev notes are compiled into a Field Guide at the beginning
of the release candidate phase. contains the following sections:
* [Elimination of Repeated ID when Adding Constructs](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#elimination-of-repeated-id-when-adding-constructs)
* [Flattened Constructor Parameters](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#flattened-constructor-parameters)
* [Default Parameters](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#default-parameters)
* [Passing Settings when Instantiating Controls](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#passing-settings-when-instantiating-controls)
* [Control Templates](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#control-templates)
* [Date/Time Control](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#date-time-control)
* [New Utility Methods](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#new-utility-methods)
* [Updates to Changeset Update Requests](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#updates-to-changeset-update-requests)
* [Discontinued Customize Loader in Core](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#discontinued-customize-loader-in-core)
* [Outer Sections](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#outer-sections)
* [Notification Improvements](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#notification-improvements)
* [Read More](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#read-more)
[Continue reading →](https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/#more-23812)
[#4-9](https://make.wordpress.org/core/tag/4-9/), [#customize](https://make.wordpress.org/core/tag/customize/),
[#dev-notes](https://make.wordpress.org/core/tag/dev-notes/)
[ ](https://profiles.wordpress.org/celloexpressions/) [Nick Halsey](https://profiles.wordpress.org/celloexpressions/)
4:00 am _on_ October 24, 2017
Tags: [4.9 ( 81 )](https://make.wordpress.org/core/tag/4-9/),
customize, [dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/),
[themes ( 43 )](https://make.wordpress.org/core/tag/themes/)
# [A New Themes Experience in the Customizer](https://make.wordpress.org/core/2017/10/24/a-new-themes-experience-in-the-customizer/)
WordPress 4.9 introduces a new experience for discovering, installing, and previewing
themes 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.. Building on [efforts during WordPress 4.7](https://make.wordpress.org/core/2016/10/03/feature-proposal-a-new-experience-for-discovering-installing-and-previewing-themes-in-the-customizer/)
development, this project prioritizes user flow, extensibility, and performance
improvements.
> A theme is the most fundamental aspect of customizing a site. This project seeks
> to unify the theme-browsing and theme-customization experiences by introducing
> a comprehensive theme browser and installer directly in the customizer.
The new flow seamlessly integrates theme management into the customization experience
by bringing a new theme browsing framework into the customization interface along
with the ability to install and live-preview a theme in a single click.
[⌊Screencast demonstrating the new themes experience in the customizer. Open the
theme browser, search and browse installed and WordPress.org themes, and then install
and preview in a single click.⌉⌊Screencast demonstrating the new themes experience
in the customizer. Open the theme browser, search and browse installed and WordPress.
org themes, and then install and preview in a single click.⌉[
The new theme browser is designed for extensibility. Third-party theme directories
are encouraged to integrate with the coreCore Core is the set of software required
to run WordPress. The Core Development Team builds WordPress. experience via plugins.
Because the new browser is built on the core customize 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., extending it is
similar to extending any other part of the customization experience. As with every
aspect of the customizer, this project approaches extensibiity modularly and in
terms of both user and developer experience. The end of this post includes a technical
overview of the new API.
Since WordPress 4.2, the customizer has loaded information about every installed
theme every time the customizer loaded. In 4.9, theme data will only be loaded when
a user visits the themes panel. The resulting performance improvement _on every
customizer load_ may be substantial on sites with a large number of installed themes,
particularly on multisitemultisite Used to describe a WordPress installation with
a network of multiple blogs, grouped by sites. This installation type has shared
users tables, and creates separate database tables for each blog (wp_posts becomes
wp_0_posts). See also **network**, **blog**, **site** networks.
For more information on the history and goals of this project, check out the original
feature proposal from last year:
> [Feature Proposal: A New Experience for Discovering, Installing, and Previewing Themes in the Customizer](https://make.wordpress.org/core/2016/10/03/feature-proposal-a-new-experience-for-discovering-installing-and-previewing-themes-in-the-customizer/)
## Theme Browsing Improvements
The changes since the previous merge proposal center around the experience of browsing
themes. The customize 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.
now serves as the global index of theme sources (installed, 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/),
upload, and any additional sources added by plugins). In the customize preview area,
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. bar controls navigation within each of those sections.
Installed themes feature an instant search filter and a count of the results. WordPress.
org themes also feature a search bar, in addition to the feature filter found in
wp-adminadmin (and super admin) and on WordPress.org. Rather than mimicking the
existing WordPress.org and wp-admin theme browsers, the customizer features a simplified
filter-oriented approach. The popular, favorites, and (randomized) featured sections
are excluded in favor of a single, filter-driven section that defaults to showing
the latest themes.
Over time, the customization team hopes to work with the theme review and 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.
teams to broadly evaluate the process of finding a theme. This future project will
be driven by research into other product discovery experiences, as well as the experiences
that third-party plugins build within the customizer for browsing themes from other
sources. Ultimately, the goal is to bring an improved and unified theme browsing
experience to WordPress.org, wp-admin, and the customizer, complete with new tags
and other taxonomies. For now, the WordPress.org theme browser within the customizer
is a starting point for a user-driven theme discovery experience.
## Customize Themes API
The remainder of this post is dedicated to the technical implementation of the new
themes experience, with three objectives: providing an example implementation of
the customize API, documenting the feature to assist in future iterations, and introducing
the API for extending the experience.
### Customize Object Structure
The context for the themes experience is contained with a custom [customize panel object](https://developer.wordpress.org/themes/customize-api/customizer-objects/#panels),`
WP_Customize_Themes_Panel` in PHPPHP The web scripting language in which WordPress
is primarily architected. WordPress requires PHP 7.4 or higher and `wp.customize.
ThemesPanel` in JSJS JavaScript, a web scripting language typically executed in
the browser. Often used for advanced user interfaces and behaviors.. This panel
is responsible for:
* The overall theme browser UIUI User interface layout
* Installing themes (via `wp.updates`)
* Loading theme previews
* Updating installed themes from WordPress.org (via `wp.updates`)
* Deleting installed themes (via `wp.updates`)
The custom themes panel object joins `WP_Customize_Widgets_Panel` and `WP_Customize_Menus_Panel`
as core examples of the intended use for panels – as contexts for distinct features,
rather than as generic containers for sections. It should generally not be necessary
to modify the core panel object when extending the themes experience.
Theme browsing is done within custom [customize section objects](https://developer.wordpress.org/themes/customize-api/customizer-objects/#sections),
which are instances of `WP_Customize_Themes_Section` in PHP and `wp.customize.ThemesSection`
in JS. In 4.9, core provides two sections for browsing themes: Installed Themes
and WordPress.org Themes. An additional section to Upload Themes will be added in
a future release. Themes Sections handle the following:
* Searching and filtering
* Loading themes (from `wp_prepare_themes_for_js()` and WordPress.org), as theme
control objects
* Rendering screenshots for theme controls as they become visible (rather than
loading all screenshots as soon as the theme data is loaded, for improved performance)
* Opening and navigating the theme details modal
The themes section was initially introduced in WordPress 4.2. In 4.9, it has been
completely reworked, most notably with the addition of built-in support for loading
theme data from WordPress.org.
Each theme within the browser is represented with a [customize control object](https://developer.wordpress.org/themes/customize-api/customizer-objects/#controls),
instances of `WP_Customize_Theme_Control` in PHP and `wp.customize.ThemeControl`
in JS. Theme controls:
* Display information about a single theme
* Provide contextual buttons to install, preview, or install and preview themes
depending on whether the theme is already installed
* Contain an internal `filter` (and sorting) method in JS, which can be used for
searching and filtering all theme controls within a section
While the theme control object was also initially introduced in WordPress 4.2, its
4.9 update completely refactors the control to [use JS templates for rendering](https://developer.wordpress.org/themes/customize-api/javascriptunderscore-js-rendered-custom-controls/).
This facilitates the updated themes section’s ability to quickly load data for large
numbers of themes within a fully JS-driven experience. Hundreds of individual theme
controls are dynamically created and deleted as users navigate the theme browsing
interface, leveraging the customize API’s ability to scale by building on functionality
initially introduced in WordPress 4.3 for the menus interface.
### Extending the Core Experience
The modular structure of the customize API allows any aspect of the new themes experience
to be modified or extended. In most cases, extensions will modify the themes section
object, or create custom themes section instances or subclasses.
There are two types of `WP_Customize_Themes_Section`s: those that load all themes
at once and search/filter theme locally (like the core installed section), and those
that search and filter themes remotely, replacing every theme control object each
time a search or filter changes. This distinction is managed with the `filter_type`
parameter. When this set to `local`, all themes are assumed to be loaded from Ajax
when the section is first loaded, and subsequent searching/filtering is applied
to the loaded collection of themes within the section. This is how the core “Installed”
section behaves – third-party sources with limited numbers of themes may consider
leveraging this implementation. When `filter_type` is set to `remote`, searching
and filtering always triggers a new remote query via Ajax. The core “WordPress.org”
section uses this approach, as it has over 5000 themes to search.
With this parameter, it is theoretically possible to create a 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. that adds an instance of `WP_Customize_Themes_Section`
that browses themes from a third-party source (using a custom `action` parameter).
The `customize_load_themes` filter facilitates loading themes from third-party sources(
or modifying the results of the core sections) within an Ajax call triggered by
a themes section. In practice, it may be desirable to create a custom themes section
object (subclassing `WP_Customize_Themes_Section`) to further customize the experience
of browsing third-party themes within the customizer.
## Additional Information & Next Steps
Most of the work for 4.9 was completed in [#37661](https://core.trac.wordpress.org/ticket/37661),
with several follow up tickets to polish the feature. In addition to iterating on
the WordPress.org theme browsing experience, there are a few improvements that are
already planned for future releases:
* [#40278](https://core.trac.wordpress.org/ticket/40278) – Introduce theme uploading
in the customizer
* [#42046](https://core.trac.wordpress.org/ticket/42046) – Clarify active and previewed
themes
* [#42140](https://core.trac.wordpress.org/ticket/42140) – Improve plurality of
the themes count string
Here is the complete design flow for the new theme browser within the customizer,
courtesy of [@folletto](https://profiles.wordpress.org/folletto/):
[⌊Mockups of the user flow through the customize themes experience in 4.9, with
additional elements for future releases⌉⌊Mockups of the user flow through the customize
themes experience in 4.9, with additional elements for future releases⌉[
Please test the new themes experience in the 4.9 betas and share any feedback or
bugs that you find [on trac](https://core.trac.wordpress.org/newticket) and in the
comments.
[#4-9](https://make.wordpress.org/core/tag/4-9/), [#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/westonruter/) [Weston Ruter](https://profiles.wordpress.org/westonruter/)
6:41 pm _on_ May 16, 2017
Tags: [4.8 ( 31 )](https://make.wordpress.org/core/tag/4-8/),
customize, [dev-notes ( 648 )](https://make.wordpress.org/core/tag/dev-notes/)
# [Customizer sidebar width is now variable](https://make.wordpress.org/core/2017/05/16/customizer-sidebar-width-is-now-variable/)
A common request for 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. has been to grant more room for the controls that appear
in its 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.. Ticketticket
Created for both bug reports and feature development on the bug tracker. [#32296](https://core.trac.wordpress.org/ticket/32296)
was created to allow the sidebar pane to be user-resizable with a grabber just like
the Dev Tools pane in Chrome can be resized. After a lot of back and forth, the
scope was reduced to remove the user-resizable aspect and to instead address a more
fundamental issue that the sidebar is exceedingly and unnecessarily narrow on high-
resolution displays. So while 4.8 doesn’t include a user-resizable controls pane,
there is still a [feature plugin](https://github.com/xwp/wp-customize-pane-resizer)
for possible future merge. Important to that end, the changes that have been merged
begin to introduce the fundamental prerequisite for a variable-width sidebar pane:**
responsive controls**.
As can be seen in [[40511]](https://core.trac.wordpress.org/changeset/40511) and
[[40567]](https://core.trac.wordpress.org/changeset/40567), no longer should Customizer
controls assume that their container will always be 300px wide. Given the new responsive
breakpoints for high-resolution screens, the pane can now be _between_ 300px and
600px wide depending on the screen width. And actually this has already been the
case on smaller screens (e.g. mobile) where the preview and pane aren’t shown at
the same time; it now also applies to very large screens where there is ample space
for both the preview and a wider pane.
Custom controls in plugins and themes should utilize alternative approaches to doing
layout than using pixel widths. Use of percentage-based widths or flexbox will help
ensure that controls will _appear properly in larger displays_, while also making
controls _future-compatible_ when the sidebar width could be user-resizable.
[#4-8](https://make.wordpress.org/core/tag/4-8/), [#customize](https://make.wordpress.org/core/tag/customize/),
[#dev-notes](https://make.wordpress.org/core/tag/dev-notes/)
[ ](https://profiles.wordpress.org/celloexpressions/) [Nick Halsey](https://profiles.wordpress.org/celloexpressions/)
10:14 pm _on_ November 30, 2016
Tags: [4.7 ( 124 )](https://make.wordpress.org/core/tag/4-7/),
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/bradyvercher/) [Brady Vercher](https://profiles.wordpress.org/bradyvercher/)
10:25 pm _on_ November 26, 2016
Tags: [4.7 ( 124 )](https://make.wordpress.org/core/tag/4-7/),
custom-header, 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 ( 124 )](https://make.wordpress.org/core/tag/4-7/),
[CSS ( 10 )](https://make.wordpress.org/core/tag/css/), 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/celloexpressions/) [Nick Halsey](https://profiles.wordpress.org/celloexpressions/)
7:18 pm _on_ November 10, 2016
Tags: [4.7 ( 124 )](https://make.wordpress.org/core/tag/4-7/),
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/)
[ ](https://profiles.wordpress.org/celloexpressions/) [Nick Halsey](https://profiles.wordpress.org/celloexpressions/)
2:49 am _on_ October 24, 2016
Tags: [4.7 ( 124 )](https://make.wordpress.org/core/tag/4-7/),
customize
# [Customize Update 2016-10-23](https://make.wordpress.org/core/2016/10/24/customize-update-2016-10-23/)
This is the weekly update post for the [customize component](https://make.wordpress.org/core/components/customize/).
It includes a summary of this week’s meeting, recent commits, and next week’s meeting
agenda.
## 4.7 Feature Proposals & Merges
Three proposal posts have been published and approved since our last update:
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/
https://make.wordpress.org/core/2016/10/11/feature-proposal-better-theme-customizations-
via-custom-css-with-live-previews/
All five of the major customize feature projects proposed for WordPress 4.7 have
been successfully merged (in order):
* [Create pages within live preview during site setup](https://make.wordpress.org/core/2016/06/16/feature-proposal-content-authorship-in-menus-with-live-preview/)–
[#34923](https://core.trac.wordpress.org/ticket/34923), [#38013](https://core.trac.wordpress.org/ticket/38013),
[#38164](https://core.trac.wordpress.org/ticket/38164)
- _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 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.._
* [Improving sliding panels UI](https://make.wordpress.org/core/2016/09/28/changes-to-customizer-sliding-panelssections-in-wordpress-4-7/)–
[#34391](https://core.trac.wordpress.org/ticket/34391), [#34343](https://core.trac.wordpress.org/ticket/34343),
[#29158](https://core.trac.wordpress.org/ticket/29158)
- _Customizer navigation is now faster, smoother, and more accessible._
* [Customize changesets (transactions)](https://make.wordpress.org/core/2016/10/12/customize-changesets-formerly-transactions-merge-proposal/)–
[#30937](https://core.trac.wordpress.org/ticket/30937)
- _Browse your site and switch themes more seamlessly within the customizer,
as your changes automatically persist in the background._
* [A new experience for themes in the customizer](https://make.wordpress.org/core/2016/10/03/feature-proposal-a-new-experience-for-discovering-installing-and-previewing-themes-in-the-customizer/)–
[#37661](https://core.trac.wordpress.org/ticket/37661)
- _Browse, install, and preview themes with a unified interface in the customizer._
* [Code-editing gateways, via CSS](https://make.wordpress.org/core/2016/10/11/feature-proposal-better-theme-customizations-via-custom-css-with-live-previews/)–
[#35395](https://core.trac.wordpress.org/ticket/35395)
- _Fine-tune your site and take your theme customizations to the next level
with custom css in the customizer._
Work continues on follow up tickets for many of these projects. Please test _everything_
in the customizer and [report any bugs to trac](https://core.trac.wordpress.org/newticket).
We still have a few pending enhancements that need to be completed by this Wednesday,
10/26, 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, sorted by
priority:
1. [#27403](https://core.trac.wordpress.org/ticket/27403) Improve UIUI User interface
for linking areas of Customizer preview to corresponding controls (desktop and
mobile) – **has-patchpatch A special text file that describes changes to code,
by identifying the files and lines which are added, removed, and altered. It may
also be referred to as a diff. A patch can be _applied_ to a codebase for testing.,
needs testing and adjustments**
2. [#38263](https://core.trac.wordpress.org/ticket/38263) Color picker: add a hue-
only mode – **has-patch, needed for Twenty Seventeen**
3. [#28536](https://core.trac.wordpress.org/ticket/28536) Add browser history and
deep linking for navigation in Customizer preview – **needs-patch** punted
4. [#38164](https://core.trac.wordpress.org/ticket/38164) Customize: assign static
front page and posts page to new pages – **has-patch**
5. [#37964](https://core.trac.wordpress.org/ticket/37964) Allow customizer controls
to be encapsulated by accepting pre-instantiated settings – **has-patch, needs
adjustments**
6. [#22058](https://core.trac.wordpress.org/ticket/22058) Improve custom background
properties UI – **has-patch**
7. [#29158](https://core.trac.wordpress.org/ticket/29158) Customizer UI Design lacks
contrast for visual hierarchy and does not match wp-adminadmin (and super admin)–**
has-commit, has-patch for 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.**
## Weekly Customize Meetings
Our past two weekly meetings have focused on preparing our projects for commit.
We’ll continue our weekly 4.7 meetings into beta and RCrelease candidate One of
the final stages in the version release cycle, this version signals the potential
to be a final release to the public. Also see [alpha (beta)](https://make.wordpress.org/core/tag/customize/?output_format=md#alpha-beta).
pending the volume of customize tickets remaining in the milestone. For this week’s
meeting, our priority will be ensuring that the 7 remaining customize enhancements
for 4.7, listed above, are committed before beta 1.
Our weekly update posts will continue on a reduced schedule now that the bulk of
4.7 development is complete, and we’ll also continue posting dev notesdev note Each
important change in WordPress Core is documented in a developers note, (usually
called dev note). Good dev notes generally include a description of the change,
the decision that led to this change, and a description of how developers are supposed
to work with that change. Dev notes are published on Make/Core blog during the beta
phase of WordPress release cycle. Publishing dev notes is particularly important
when plugin/theme authors and WordPress developers need to be aware of those changes.
In general, all dev notes are compiled into a Field Guide at the beginning of the
release candidate phase. for changes in 4.7.
## Recent Customize Commits
Here are the customize-related commits for the past two weeks:
* [[38765]](https://core.trac.wordpress.org/changeset/38765): Customize: Ensure`
customize_validate_{$setting->id}` filters apply on input post_values for WP_Customize_Setting
subclasses that neglect to apply the 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. themselves.
* [[38766]](https://core.trac.wordpress.org/changeset/38766): Customize: Improve
message displayed in widgets panel when there are no 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. areas currently
displayed in the preview.
* [[38767]](https://core.trac.wordpress.org/changeset/38767): Customize: Show Pages
section first and pre-expanded in list of available menu items.
* [[38794]](https://core.trac.wordpress.org/changeset/38794): Customize: Move Pages
below Custom Links in available nav menu items panel.
* [[38807]](https://core.trac.wordpress.org/changeset/38807): Customize: Skip triggering
initial click on pages section for available nav menu items if already open.
* **[[38810]](https://core.trac.wordpress.org/changeset/38810): Customize: Implement
customized state persistence with changesets. **
* [[38811]](https://core.trac.wordpress.org/changeset/38811): Customize: Split
out link `click.preview` and form `submit.preview` event handlers…
* **[[38813]](https://core.trac.wordpress.org/changeset/38813): Customize: Introduce
a new experience for discovering, installing, and previewing themes in the customizer.**
* **[[38829]](https://core.trac.wordpress.org/changeset/38829): Customize: Introduce
custom CSSCSS Cascading Style Sheets. for extending theme styles.**
* [[38830]](https://core.trac.wordpress.org/changeset/38830): Customize: Fix unit
tests when `twentyfifteeen` is `WP_DEFAULT_THEME` instead of `twentyfifteen.`
* [[38831]](https://core.trac.wordpress.org/changeset/38831): Customize: Improve
the labeling of background 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. images in the list mode of
the media library.
* [[38837]](https://core.trac.wordpress.org/changeset/38837): Twenty Seventeen:
Fix a PHPPHP The web scripting language in which WordPress is primarily architected.
WordPress requires PHP 7.4 or higher warning on fresh installs.
* [[38850]](https://core.trac.wordpress.org/changeset/38850): Tests: Prevent Twenty
Seventeen from interfering with Customizer tests.
* [[38851]](https://core.trac.wordpress.org/changeset/38851): Tests: Prevent Twenty
Seventeen from interfering with Customizer ajax tests.
* [[38853]](https://core.trac.wordpress.org/changeset/38853): Customize: Add sticky
headers for panels and sections.
* [[38862]](https://core.trac.wordpress.org/changeset/38862): Customize: Revert
part of [[38859]](https://core.trac.wordpress.org/changeset/38859) which caused
sections to get deactivated in the customizer.
* [[38867]](https://core.trac.wordpress.org/changeset/38867): Twenty Seventeen:
Add theme support for customize selective refresh.
* [[38881]](https://core.trac.wordpress.org/changeset/38881): Customize: Keep previously
uploaded header images in place.
Big thanks to those who contributed to patches committed this week: [@johnregan3](https://profiles.wordpress.org/johnregan3/),
[@celloexpressions](https://profiles.wordpress.org/celloexpressions/), [@folletto](https://profiles.wordpress.org/folletto/),
[@westonruter](https://profiles.wordpress.org/westonruter/), [@deltafactory](https://profiles.wordpress.org/deltafactory/),
[@coreymcollins](https://profiles.wordpress.org/coreymcollins/), [@desrosj](https://profiles.wordpress.org/desrosj/),
[@pento](https://profiles.wordpress.org/pento/), [@delawski](https://profiles.wordpress.org/delawski/),
[@davidakennedy](https://profiles.wordpress.org/davidakennedy/), [@afercia](https://profiles.wordpress.org/afercia/),
[@karmatosed](https://profiles.wordpress.org/karmatosed/), [@ryankienstra](https://profiles.wordpress.org/ryankienstra/),
[@valendesigns](https://profiles.wordpress.org/valendesigns/), [@utkarshpatel](https://profiles.wordpress.org/utkarshpatel/),
[@stubgo](https://profiles.wordpress.org/stubgo/), [@lgedeon](https://profiles.wordpress.org/lgedeon/),
[@ocean90](https://profiles.wordpress.org/ocean90/), [@mihai2u](https://profiles.wordpress.org/mihai2u/),
[@dlh](https://profiles.wordpress.org/dlh/), [@aaroncampbell](https://profiles.wordpress.org/aaroncampbell/),
[@jonathanbardo](https://profiles.wordpress.org/jonathanbardo/), [@jorbin](https://profiles.wordpress.org/jorbin/).
We’re always looking for more contributors; check out the [open customize tickets](https://core.trac.wordpress.org/query?component=Customize&status=!closed)
and swing by [#core-customize](https://wordpress.slack.com/messages/core-customize/)
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/)
to get involved. Tickets in the Future Release milestone will be considered first
for 4.8 if they have a patch.
[#4-7](https://make.wordpress.org/core/tag/4-7/), [#customize](https://make.wordpress.org/core/tag/customize/)
# Post navigation
[← Older posts](https://make.wordpress.org/core/tag/customize/page/2/?output_format=md)