Make WordPress Core

Welcome to the official blog of the core development team for the WordPress open source project.

Here, we make WordPress core. Follow our progress with general updates, status reports, and the occasional code debate.

We’d love for you to help out.

Looking to file a bug?

It’s easy to create a ticket on our bug tracker.

Want to contribute?

Get started quickly. We have some tickets marked as good first bugs for new contributors. There’s more on our reports page, like patches needing testing.

We also have a detailed handbook for contributors, complete with tutorials.

Weekly meetings

We use Slack for real-time communication. As contributors live all over the world, there are discussions happening at all hours of the day.

We have a project meeting every Wednesday at 20:00 UTC in the #core channel on Slack. (Find out more about Slack.)

You can find meeting agendas on this blog. You’re welcome to join us or listen in.

Recent Updates Toggle Comment Threads | Keyboard Shortcuts

  • Helen Hou-Sandi 6:26 am on December 3, 2016 Permalink |

    There is a quiet RC2 now available – it is a fair number of commits (50+), so please take a look through those and test as you can.

  • Nick Halsey 10:14 pm on November 30, 2016 Permalink |
    Tags: , ,   

    Customizer Improvements in 4.7 

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

    4.7 Customizer Feature Projects

    Create pages within live preview during site setup

    Add new pages while building menus and setting a static front page; 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:

    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 core dropdown-pages customizer control, themes and plugins can also allow users to create new pages for their options instead of relying on existing content. The homepage sections in Twenty Seventeen include this new allow_addition parameter. Here’s how to register a dropdown-pages control supporting new pages:

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

    Additionally, a proposal for term statuses was developed as a first step toward expanding the menus functionality to work for creating and previewing taxonomy terms in a future release (see #37915).

    Improvements to the Sliding Panels UI

    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:

    Changes to Customizer Sliding Panels/Sections in WordPress 4.7

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

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

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

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

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

    Customize Changesets (formerly Transactions)

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

    This project rewrote the internals of the customizer preview mechanism to make changes persistent. Each change made to a setting in the customizer is saved to a changeset (a new customize_changeset post type), facilitating future features such as scheduled changes, revisions, or saving and sharing drafted changes. Changesets also open the door to using the customizer to preview Ajax requests, headless sites, and 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:

    Customize Changesets (formerly Transactions) Merge Proposal

    Customize Changesets Technical Design Decisions

    Custom CSS

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

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

    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 plugin or theme does custom CSS:

    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 header feature), and starter content for more information:

    Visible Edit Shortcuts in the Customizer Preview

    Video Headers in 4.7

    Starter content for themes in 4.7

    Additional User-facing Changes

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

    Improved Custom Background Properties UI

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

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

    And even more…

    4.7 also:

    • Loads the frontend preview iframe more naturally, eliminating a lot of weirdness with JS running in an unexpected location and ensuring that JS-based routing will work (#30028)
    • Allows the search results page to be previewed, and any forms that use the GET method in general can now be submitted whereas previously they would do nothing when submitted (#20714)
    • Hides edit post links in the customizer by default. Plugins, such as Customize Posts, can restore the links if they make post editing available in the customizer (#38648), although the visible edit shortcuts should generally be used instead.
    • Shows a cursor: not-allowed for mouse users when hovering over external links in the preview, as these can’t be previewed
    • Officially removes support for the customizer in Internet Explorer 8, preventing users of this outdated browser from accessing the customizer at all (#38021)

    Additional Developer-oriented Changes

    Hue-only Color Picker

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

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

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

    Fix Sections that .cannot-expand

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

    Allow Plugins to do Comprehensive Late Validation of Settings

    To account for custom subclasses of WP_Customize_Setting that don’t apply the customize_validate_{{$setting_id}} filter, 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.


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


  • Helen Hou-Sandi 8:49 pm on November 30, 2016 Permalink |
    Tags: ,   

    Starter content for themes in 4.7 

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

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

    How it works

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

    Core provides a set of content that themes can select from (technical details below). These include a variety of widgets, pages, and nav menu items (including references for the pages), along with the ability to provide attachments, theme mods, and options. Any included images for attachments need to be from within a theme or plugin folder and cannot be loaded from an external URL. Twenty Seventeen will ship with starter content enabled; there are no plans to add the functionality to past default themes.

    How to use it

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

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


    Each widget area ID corresponds to one sidebar registered by the theme, with the contents of each widget area array being a list of widget “symbols” that reference core-registered widget configurations. Most default widgets are available (archives, calendar, categories, meta, recent-comments, recent-posts, and search), as well as text widgets with business hours (text_business_info) and a short prompt for an “about this site” style blurb (text_about). Themes should place widgets based on what works best in that area – for instance, business info in a footer widget of a business-centric theme, or a nicely styled calendar widget in the sidebar of a blog.

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

    // Custom registration example
    add_theme_support( 'starter-content', array(
    	'widgets' => array(
    		'sidebar-1' => array(
    			'meta_custom' => array( 'meta', array(
    				'title' => 'Pre-hydrated meta widget.',
    			) ),
    // Plugin widget added using filters
    function myprefix_starter_content_add_widget( $content, $config ) {
    	if ( isset( $content['widgets']['sidebar-1'] ) ) {
    		$content['widgets']['sidebar-1']['a_custom_widget'] = array(
    			'my_custom_widget', array(
    				'title' => 'A Special Plugin Widget',
    	return $content;
    add_filter( 'get_theme_starter_content', 'myprefix_starter_content_add_widget', 10, 2 );

    Posts (Pages)

    Like widgets, core provides posts which can be referenced by symbols; all six currently in the core set are pages, but the starter content API can support various post types (including attachments, which are defined and handled separately). The symbols for the core-provided pages as of 4.7 are home, about, contact, blog, news, and homepage-section. The pages references by blog and news are both empty in the content area and are meant to be assigned as the page for posts (detailed with options below). Imported posts can further be used as post IDs when referenced using the symbol of the item within double curly braces, e.g. {{home}} for the static front page option.

    Posts, like widgets, are also easily customizable, either by overriding specific fields for a predefined item or by defining a new custom one entirely. The available fields are post_type, post_title, post_excerpt, post_name (slug), post_content, menu_order, comment_status, thumbnail (featured image ID), and template (page template name, as would be stored in post meta).

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


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

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

    Nav Menus

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

    Options and Theme Mods

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

    What does this mean for themes?

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

    While theme review guidelines need to be finalized and documented, it is anticipated that themes being submitted to WordPress.org will be expected to select from core-provided content to promote consistency and to help keep the theme review process from becoming lengthier, with exceptions being made on a case by case basis. Themes being distributed outside of WordPress.org are not subject to the same review process; however, it is recommended that consistent user experiences be the primary consideration in how starter content is chosen and implemented.

    What’s next?

    Testing this feature with your theme or plugin does not require a fresh install every time – you can set the fresh_site option to 1 using the tool of your choice, such as wp-cli or phpMyAdmin. Do note that content merging logic has not been tackled so you may not quite get the exact same effect as a truly fresh install; however, since all of the changes are held in a customizer changeset and are not otherwise live on the site, there is no data loss, unless you save and publish the starter content overrides of course.

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

    And finally, to best align preview experiences in various places, theme previews on .org should also leverage starter content. Helping hands are needed here – please ping me (@helen) in Slack should you be interested!

    • Luke Cavanagh 8:55 pm on November 30, 2016 Permalink | Log in to Reply

      Thanks for sharing.

    • Madalin Tache 9:05 pm on November 30, 2016 Permalink | Log in to Reply

      That’s a really good idea! Looking forward to it!:)

    • Hardeep Asrani 9:08 pm on November 30, 2016 Permalink | Log in to Reply

      That’s gonna be a game changer for themes. 🙂

    • t-p 11:39 pm on November 30, 2016 Permalink | Log in to Reply

      To be able to live preview new themes sounds awesome 🙂

    • WPDevHQ 11:40 pm on November 30, 2016 Permalink | Log in to Reply

      Awesome news for themes.

      Will this be carried over to WordPress.org theme preview or does that not work as a `fresh_site`?

    • Omaar Osmaan 11:57 pm on November 30, 2016 Permalink | Log in to Reply

      Awesome thank you!

    • evisiontheme 9:21 am on December 1, 2016 Permalink | Log in to Reply

      Really, great idea. Thanks for the sharing it. We look forward it soon.

    • NateWr 9:39 am on December 1, 2016 Permalink | Log in to Reply

      Looks great! I suppose this has been discussed, but is there any plan to support post meta in a more generic fashion? I’m thinking a key for `post_meta` which can itself be an assoc array with a key/value map. This could be useful for previewing data from plugin custom post types which rely more heavily on post meta.

      • Helen Hou-Sandi 3:16 pm on December 1, 2016 Permalink | Log in to Reply

        Untested at the moment, but I believe this is already technically possible, just requires some more hoop jumping at the moment in the form of having to filter it in using get_theme_starter_content as opposed to being able to specify it during initial registration. That is the case for plugins as it is though, so it’s not really that much of a hoop. So to do that, you would want to use a meta_input arg with the definition of that post, the same way post_title can be specified. Can you let me know if it works?

    • Mahesh Waghmare 9:51 am on December 1, 2016 Permalink | Log in to Reply

      +1, Its nice enhancement for theme developer.

    • Ahmad Awais 2:57 pm on December 1, 2016 Permalink | Log in to Reply

      Thanks a lot Helen and all the contributors for making this happen. It’s a huge deal for me and my clients.

  • Andrew Rockwell 6:47 pm on November 30, 2016 Permalink |
    Tags: ,   

    Week in Core, November 23 – 29, 2016 

    Welcome back the latest issue of Week in Core, covering changes [39341-39379]. Here are the highlights:

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

    Ticket numbers based on trac timeline for the period above. The following is a summary of commits, organized by component.

    Code Changes

    Build/Test Tools

    • Build: Remove fsevents from npm-shrinkwrap.json [39368] #38657
    • Add an extra WP_Error assertion when testing a valid user activation key. This provides a better failure message if the assertion does fail. [39364] #38716
    • When testing the output of wp_list_pages(), use a known and fixed date for each post so the tests don’t fail when the date changes between the beginning and end of a test. [39363] #38688
    • Git: Prevent untracked files from being ignored by git in bundled themes. [39362] #27207, #38779
    • Add npm-shrinkwrap.json to 4.7. [39358] #38657

    Bundled Theme

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


    • Fix regression in ability to hide fields for advanced menu properties in nav menu item controls. [39379-39378] #34391, #38952
    • Fix regression in ability to create submenus for nav menus via drag and drop. [39377-39376] #34391, #38948
    • Fix logic for previewing the URL for nav_menu_item settings for terms and post type archives. [39365] #38114, #38945
    • Refactor logic for updating custom_css posts by introducing wp_update_custom_css_post() function and renaming update filter. [39350] #35395, #38672
    • Clean up docs and code style for customize changes in 4.7. [39345] #37770, #38908


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


    • Git: Ignore patch related files, so they can’t be accidentally committed. [39361] #38727
    • SVN: Ignore patch related files, so they can’t be accidentally committed. [39360] #38727
    • Docs: Add a missing changelog entry for the point where the $tagnames parameter was added to get_shortcode_regex(). [39351] #38914



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


    • Add test for creating a comment with an invalid post ID. [39375] #38816, #38991
    • Add tests for empty or “no-op” updates. [39371] #38700, #38975
    • Special case the “standard” post format to always be allowed. [39353] #38916
    • Allow unsetting a post’s password. [39352] #38919
    • Add support for comments of password-protected posts. [39349] #38692
    • Always fire the rest_insert_* actions after the related object is updated or inserted. [39348] #38905
    • Make JS Client store schema in session storage. [39344] #38895
    • Allow unsetting of page templates in update requests. [39343] #38877
    • Update “resource” strings to use the appropriate nouns. [39342] #38811


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


    • Fix the styling of notices generated by the editor UI. [39367] #38917

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

  • David A. Kennedy 12:22 am on November 29, 2016 Permalink |
    Tags: , , ,   

    Theming with Twenty Seventeen 

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

    Of note

    Override enqueued styles and scripts

    With the use of get_theme_file_uri, introduced in 4.7, Twenty Seventeen lets child themes override styles and scripts with ease. For example, if you want to replace the theme’s global.js file, you can do so by including the same file in your child theme in the same path.


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

    Content width

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

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

    Custom header settings

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

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

    Header video settings

    The theme changes the default provided by Core, but that can be modified by a child theme. Here, we change the text on the button in a child theme:

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

    Front page sections

    Twenty Seventeen uses the Customizer to add sections to the front page. These are filterable with the twentyseventeen_front_page_sections filer. They can changed like so:

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

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


    One of the theme’s most notable behind-the-scenes features, the use of SVGs means better accessibility for icons, they look great on any device and they’re easier to customize.

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

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

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

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

    Using a title:

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

    Another example with title and desc (description):

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

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

    Custom Colors

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

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

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

    Enjoy customizing Twenty Seventeen and happy theming!

    • djsteveb 1:30 am on November 29, 2016 Permalink | Log in to Reply

      glad to see ” all of which are documented in line in the code.”
      thanks for the tips and early warnings!

      I am sure there will be many that love the video header and many that calculate the waste of this. Without having looking at the code and such, but having some experience with video and wordpress I must ask..

      Is there an option to easily have the video auto play or not play, and instead show a thumbnail with a play button?

      Has someone gotten code to make the video auto-pause when scrolled out of view? I looked hard for this and asked for help in doing that with the flv-player plugin – but never got it working – hopefully others have figured it out by now.

      Is the video going to be self hosted / in the install files for default wordpress or is it hot linked from elsewhere? One way equals bloat for installs, the other sacrifices privacy and puts our page load speed in the hands of third parties.

      Are there options for having the video not load at all in different scenarios like cell phone screen size or 2g data connection?

      Would love to see an option to have a gif (converted to webm perhaps) showing that there is a video to be played – click to download / stream / play – otherwise the bandwidth is saved for the end user.

      Has anyone gotten anything like src set for video yet? Last version of wordpress has some auto magic for different image sizes for different screens right? Does this now work with video?

      One theme I play with has a slider that pulls an mp4 hi rez when screen size is large enough, and then chooses to load a webm version if it detects a smaller screen size – would love to see this (or similar) options in wp core like how images are dealt with.

      anyhow, love to see WP embracing video more by default – it’s great, but comes with some challenges and limitations – that I hope are mostly solved in the future. Also glad to see a focus on having the default themes made with developing in mind for the end users.. I disagree that all default themes are easy to manipulate for end users, certainly 2013 theme and those before were.. the last couple not so much imho.

      thanks to all those who have been and are working on this! the default theme is seriously important for so many reasons!

    • tobifjellner 7:09 am on November 29, 2016 Permalink | Log in to Reply

      Hi. It seems you pasted the same image four times, when attempting to illustrate the saturation setting.

  • Brady Vercher 10:25 pm on November 26, 2016 Permalink |
    Tags: , custom-header, , ,   

    Video Headers in 4.7 

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

    Video headers are considered decorative elements — like header images, but with motion. With that in mind, they play automatically, 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 UI in the customizer when a theme supports video.

    Adding theme support

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

    Registering theme support

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

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

    Adding support this way does a few things:

    • Renames the “Header Image” customizer section to “Header Media.”
    • Registers customizer controls for selecting a video from the media library or entering a URL to a YouTube video.
    • Enables support for Selective Refresh for header images.

    Displaying the header

    In previous versions of WordPress, generating the image tag manually was the recommended way to display a header image. WordPress 4.4 introduced the_header_image_tag() to take advantage of the responsive image improvements.

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

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

    Styling the play/pause button

    When videos are ready to play, the wp-custom-header.js script inserts a button for pausing and playing the video to help improve accessibility. Core does not apply any CSS to the button in order to make it easier for themes to style. Themes should ensure the button is visible, fits within the design, and add icons if desired.

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

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

    The text for the button can be modified using the header_video_settings filter.

    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 iframe depending on the source of the video, so each of those elements needs to be considered.

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

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

    Accessibility considerations

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

    Bandwidth considerations

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

    Filtering the front page restriction

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

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

    Testing the environment for video support

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

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

    Selective Refresh enabled by default

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

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

    Creating custom video handlers

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

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

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

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

    For an example of registering a custom video handler in a plugin, take a look at how this plugin registers support for Vimeo.

    New functions and hooks

    • 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.


    • 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.
    • Paal Joachim Romdahl 12:15 am on November 29, 2016 Permalink | Log in to Reply

      Thank you for a very good overview!

    • Guido Scialfa 12:36 am on December 2, 2016 Permalink | Log in to Reply

      Probably I’m doing something wrong but the height and width must be set for the custom-header or the frame will not be visible because of the ‘width’ and ‘height’ defined are 0.

      Also, it is right that if i set the header image that is for example 640×480, the video will get the same size? Because even if I set the width and height for the custom-header I get the resolution of the image.

      I’m so sorry, most probably this isn’t the right place to ask for this.

      Anyway, thank you for this new great feature 🙂

  • George Stephanis 8:03 pm on November 26, 2016 Permalink |
    Tags: , , ,   

    Extending the Custom CSS editor 

    With the Custom CSS project merging into WordPress Core, some of y’all may be looking to extend it and do more advanced stuff.  Maybe you help run an existing plugin (like me) that has already provided a Custom CSS input to WordPress core 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 enhancement 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 Type 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 theme) 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 UI for displaying the revisions for changes to Custom CSS or a way display the saved Custom CSS of inactive themes, but revisions are enabled on the post type, so no data is lost until the revision viewer makes its way into core (or the user activates a plugin that provides similar functionality). Follow #31089 for more on revisions in the customizer, 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 tag.  One of the more useful functions in the Core implementation for advanced development is wp_get_custom_css_post( $stylesheet = '' ) — this will return either null or the WP_Post object if the site has any Custom CSS saved for the current site.  If you’re building a custom revision viewer, this will be the post you’ll key off of to fetch the revisions.

    Filters on Read and Update

    The wp_get_custom_css() function applies a wp_get_custom_css filter to the styles just before they’re returned.  This allows for targeted tweaks such as minifying the output on the front-end before it’s echoed by stripping out excess whitespace or the like.  This filter is not meant for a theme or plugin adding styles to the front-end of the site — for that, consider enqueueing your stylesheet normally and adding any dynamic bits via wp_add_inline_style() — this way it will also handle if a child theme or plugin wants to dequeue the parent stylesheet.

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

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

    1. Replace the post_content with the post_content_filtered as the initial setting value via the customize_value_custom_css filter.
    2. Add a wp_get_custom_css filter in the customizer preview (when the customize_preview_init action triggers) to compile the value into CSS just-in-time.
    3. Override the default JavaScript live-preview functionality to instead register a partial for the wp-custom-css style element so that whenever the custom CSS is modified it can be re-compiled on the server and rendered via selective refresh.
    4. When the Custom CSS setting is saved in the customizer, send the saved pre-processed value to post_content_filtered and compile the value to store into post_content.

    For a standalone example of building a pre-processor, see the Custom SCSS Demo plugin on GitHub.


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

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

    Migrating an Existing option to Core CSS

    Does your plugin or theme have a custom CSS option stored as an option or a theme_mod? Consider migrating content from your custom setting to the core functionality and hiding your custom UI. Here’s a general migration script, which can be located where you see fit in the context of your original code:

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

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

    • Joy 8:25 pm on November 28, 2016 Permalink | Log in to Reply

      Given that the Custom CSS in core is brand new, and it is output last, the migration code you used:
      `$return = wp_update_custom_css_post( $core_css . $css );`
      probably should be
      `$return = wp_update_custom_css_post( $css . $core_css );`

      • George Stephanis 8:50 pm on November 28, 2016 Permalink | Log in to Reply

        But by that logic, shouldn’t it be core first, as that is what the user has set most recently?

        In practice, it doesn’t make much difference. Most of the time, if things are updated promptly, the Core CSS will be empty as it’s not been used yet.

  • Pascal Birchler 6:55 pm on November 25, 2016 Permalink |
    Tags: , ,   

    Preferred Languages: Research 

    Following the first meeting of the Preferred Languages project, some time was spent on researching popular platforms and other systems to see how they handle the issue of setting multiple preferred languages. To recap, this is needed to show things in the most suitable language for users in case their requested language is not installed.

    Browsers & Operating Systems

    All major browsers and operating systems have some UI where the user can set their preferred languages. Mostly used for the Accept-Language HTTP header, one can set multiple languages and order them by preference. These systems usually know multiple variants like German and German (Switzerland), but not formal / informal variants.

    Worth noting that on these systems you can often choose more settings that are influenced by the language, like temperature units and date formats. Related: #18146.

    The Accept-Language HTTP Header

    RFC 7231 about the HTTP/1.1 standard says the following about this header:

    The “Accept-Language” header field can be used by user agents to indicate the set of natural languages that are preferred in the response. Each language-range can be given an associated quality value representing an estimate of the user’s preference for the languages specified by that range.

    This header is quite powerful. For example, Accept-Language: da, en-gb;q=0.8, en;q=0.7 would mean: “I prefer Danish, but will accept British English and other types of English”. I can only recommend reading more about it in the RFC, as it helps getting a better understanding of the problems it tries to solve.

    This header is usually used by websites to redirect users to the correct version or display a hint like “This content is also available in XY”. While each language in the header has a specific numeric priority, there is usually only a drag & drop interface to determine the order.

    Unicode Common Locale Data Repository

    The Unicode CLDR provides key building blocks for software to support the world’s languages, with the largest and most extensive standard repository of locale data available. It contains an interesting chart about Language Matching, data that is used to match the user’s desired language/locales against an application’s supported languages/locales.

    There’s also a technical standard about Unicode Locale Data Markup Language (LDML), an XML format for the exchange of structured locale data. The section about Locale Inheritance and Language Matching is particularly interesting. For instance, it describes finding the most well suited language using a weighted graph and gives a better picture of dealing with more complex language fallbacks.

    It also takes geographic “closeness” into account, arguing that English (Slovakia) should fall back to something within Europe (e.g. British English) in preference to something far away and unrelated like English (Singapore). It’s clearly stated that these fallbacks aren’t as simple as just saying Spanish (Mexico) -> Spanish (Spain) -> English (US).

    Note that this technical standard is about finding the best supported locale based on the requested list of languages. The requested list could come from different sources, such as such as the user’s list of preferred languages in the OS Settings, or from a browser’s Accept-Language list.


    Wikipedia is built on the MediaWiki software, which has a hardcoded list of fallback chains for some locales. This is where MediaWiki will fall back on a different language if it cannot find what it needs. For example, French (Cajun) automatically falls back to French (France) when it doesn’t have all messages defined in it. Unfortunately, there’s only little documentation about this.

    Apart from that, MediaWiki distinguishes between various kinds of languages: the site content language, the user interface language and the page content language. The latter can differ from the first two and it influences the language the user views the page in, which depends on the user’s preferences, the available languages, and the defined fallbacks.

    It’s worth noting that on Wikipedia, you can not only select your preferred language, but also your preferred gender. In addition to that, you can select multiple different locales for both display and input.


    I tried the official Joomla Demo to test its language management which is a bit overwhelming at first. After installing all the available languages the user is eventually able to select their preferred language for the front end and the back end. There are a few other settings for language switching on multilingual sites, but that’s pretty much it. So basically the same settings as currently in WordPress 4.7.

    Joomla User Settings

    Joomla User Settings



    Drupal 8 has a rather powerful user interface text language detection mechanism. There is a per session, per user and per browser option in the detection settings. However, users can only choose one language, so they cannot say (in core at least) that they want German primarily and Spanish if German is not available. But the language selected by the user is part of the larger fallback system, so it may fall back further down to other options.

    The Language fallback module allows defining one fallback for a language, while the Language Hierarchy module provides a GUI to change the language fallback system. It allows setting up language hierarchies where translations of a site’s content, settings and interface can fall back to parent language translations, without ever falling back to English. This module might be the most interesting one for our research.

    Drupal Language Hierarchy

    Drupal Language Hierarchy


    TYPO3 has had a locale hierarchy since 2011. Quote:

    TYPO3 4.6 comes with a clever fallback mechanism when a label is not found in the requested language; instead of returning the default (English) version, it allows you to define your own hierarchy of locales.

    By default, French (Canada) will first use French before falling back to English. Similarly, missing labels in Brazilian Portuguese will first try to return Portuguese labels before the English ones. This feature also accommodates completely custom fallbacks.

    The same goes for the underlying Flow Framework and the Neos CMS. This is only a front end thing though. On the back end, a user can only configure one language. If there’s no translation in that language, it will fall back to the site’s default and eventually to English.

    TYPO3 Back end Language

    TYPO3 Back end Language Setting


    On WordPress.com there’s a user interface language selection in the account settings. One cannot select multiple preferred languages though, but only one.

    WordPress.com User Interface Language

    WordPress.com User Interface Language Setting


    Facebook only has a really simple language settings. Although a user can select multiple languages they understand for use in the News Feed, they can only choose one specific locale for the overall UI.The locales that Facebook supports are referenced in the Facebook Locales XML file. That file includes multiple variants for various languages, but only one variant for others. For example, there’s only de_DE, but no de_CH. Plus, you can’t choose between formal and informal variants.

    Facebook User Language Setting

    Facebook User Language Setting


    We’ve now covered a bunch of well-known web platforms and content management systems to see how they are handling this problem. Various techniques exist to assist with finding the right translation. Sometimes they are automated, but most of the time the choice is left up to the individual user.

    This research should help with the next steps of the Preferred Languages project as these observations need to be adapted for WordPress so that we can learn from them. Feel free to leave any comments about this research in the comments. After that, I try to schedule a new meeting in December where the next steps can be discussed.

    • pcarvalho 7:04 pm on November 25, 2016 Permalink | Log in to Reply

      Hi Pascal, great round up!

      in the examples you studied, did you find any that allowed for example:

      pt_PT fallback to pt_BR , then en

      and at the same time:

      pt_BR fallback to pt_PT, then en

      if its a chain, would this lead to a circular dependency?

    • Abolfazl Ahani 9:47 pm on November 25, 2016 Permalink | Log in to Reply

      Dear Pascal

      Thanks you for considering this feature in core.

      1. I thinks it is better to consider text direction (LTR vs RTL: Right To Left), like Drupal. This is important for most of MENA countries with Persian, Arabic, and Hebrew languages.

      For example this English language profile in a RTL dashboard:

      2. And it will be make it possible to select different languages for site backend and frontend, Like joomla.

      At the moment I use this plugin (https://wordpress.org/plugins/wp-parsidate/), which covers those points, as well as jajli date conversion utilities.

      Thank you guys again 🙂

      • Pascal Birchler 7:11 am on November 26, 2016 Permalink | Log in to Reply

        > I thinks it is better to consider text direction (LTR vs RTL: Right To Left), like Drupal.

        So you want to use English, but from right to left? That’s the first time I’m hearing this suggestion personally. Right now, the text direction is defined by the locale you are using, e.g. English is LTR, Arabic is RTL.

        I’m not sure a separate text direction option would be useful for the majority of users. Right now, you’d need a plugin like https://wordpress.org/plugins/rtl-tester/ to achieve this.

        > And it will be make it possible to select different languages for site backend and frontend, Like joomla.

        Good news: This is possible with WordPress 4.7, see https://make.wordpress.org/core/2016/11/07/user-admin-languages-and-locale-switching-in-4-7/.

        > At the moment I use this plugin (https://wordpress.org/plugins/wp-parsidate/), which covers those points, as well as jajli date conversion utilities.

        Interesting. Is the date format not correct when using the Persian translation for WordPress? If so, we should try to make this better in WordPress itself.

        • Abolfazl Ahani 3:26 pm on November 26, 2016 Permalink | Log in to Reply


          I use WP 4.7-RC1 and enjoy its new features, and lovely theme 2017.


          1. RTL/LTR Switch option in user Profile

          Currently site’s direction is only controlled by site’s language (1) not user’s language (2):


          1. Site frontend & backend language & direction Domain/site-name/wp-admin/options-general.php
          2. User backend language to override site language domain/user-name/wp-admin/profile.php


          It means that admin can set the first one in Persian (RTL site), but a user may set his profile language to English: in this case his site backend direction is still RTL. I tested it in this site (a site in Persian) and a user profile in English. So, I think it is good to have a backend direction option in user profile, too.


          Also, in some cases, we need to switch temporarily backend of RTL sites from RTL to LTR. Because some plugin / themes backend .css files do not support RTL and show awkwardly in RTL backends. As I said, currently I use Parsi Date plugin to solve this problem.


          1. Jalali calendar in core

          Jalali calendar (Official calendar in Iran) is not supported in core, and I use the above mentioned plugin. Yes, it is good to consider it in core.


          1. Lunar calendar

          Sometimes, I prepare Arabic language websites. But, interestingly I did not find any plugin to change the site dates to lunar calendar (official calendar of many Arab countries). I searched the for it in repository.

    • Greg Ichneumon Brown 10:20 pm on November 28, 2016 Permalink | Log in to Reply

      I was recently looking at how to do better language guessing on WP.com so let me highlight a few other non-obvious pieces:

      • On signup WP.com tries to guess the user’s language based on the following lookups: HTTP accept-lang headers are used if they are set, otherwise the user’s IP address is used to do a country lookup.
      • When selecting a language with this lookup the language is chosen based on how well translated it is. There is a hard coded list of well translated languages that we try to steer the user towards.
      • There are a lot of cases where the locale is ignored for various features. Really its a pretty simplistic way to do the fallback, the language matching chart you found is really interesting. For instance, when searching/indexing content we mostly use just the language portion of the

      We’ve discussed supporting multiple languages for things like the Reader, but don’t love the idea of adding more options to the admin to support it.

  • Andrew Rockwell 3:54 am on November 25, 2016 Permalink |
    Tags: ,   

    Week in Core, November 15 – 22, 2016 

    Welcome back the latest issue of Week in Core, covering changes [39233-39340]. Here are the highlights:

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

    Ticket numbers based on trac timeline for the period above. The following is a summary of commits, organized by component.

    Code Changes

    Bundled Theme

    • Twenty Seventeen: CSS coding standards [39340] #38901
    • Twenty Seventeen: Ensure galleries display correctly in IE11. [39339] #38872
    • Twenty Seventeen: Avoid an undefined index notice after [39291]. [39317] #38847
    • Twenty Seventeen: Adds background-attachment: fixed; to devices that should support it [39297] #38395
    • Twenty Seventeen: Ensure the use of proper image size for custom header image [39291] #38847
    • Twenty Seventeen: Remove some extraneous function calls. [39286] #38848
    • Twenty Seventeen: Additional default header image optimizations. [39279] #38793
    • Twenty Seventeen: Add styles for custom header video controls. [39273] #38697
    • Twenty Seventeen: Compress the default header image. [39248] #38793


    • REST API: On Comment create, limit the ability to set the author_ip value directly. [39302] #38819
    • REST API: Change “ipv4” types to “ip” to support ipv6. [39296] #38818
    • REST API: Remove the karma property and query parameter from the Comments endpoints. [39292] #38821
    • REST API: On comment create, return an error if the type property is set to anything other than comment. [39290] #38820
    • REST API: On comment create, return an error if the post parameter does not relate to a valid WP_Post object. [39288] #38816
    • REST API: On comment create, fallback to the user_agent header value. [39287] #38817
    • Query used to fill comment descendants should reset ‘offset’ and ‘number’ params. [39274] #37696


    • Prevent selective refresh from causing infinite fallback refreshes when nav menu contains invalid items. [39333] #38890
    • Remove iframe-specific behaviors from customize preview when previewing on frontend and not contained inside iframe. [39332] #30937, #38867
    • Ensure that WP_Customize_Manager::save_changeset_post() returns setting_validities even for supplied values that are unchanged from values in changeset. [39320] #38705, #30937, #38865
    • Ensure WP_Customize_Setting::value() returns previewed value for custom types utilizing the customize_value_{$id_base} filter. [39318] #38864
    • Autoprefixer for [39249]. [39301] #29158
    • Remove obsolete edit shortcut style rules from Twenty Seventeen. [39285] #38776
    • Ensure Close button actually closes customizer (instead of going back) after switching to a different theme inside a customize-loader iframe. [39271] #38833
    • Prevent edit shortcut buttons from being inserted into container elements in the head or into elements which should not get interactive children. [39270] #27403, #38672, #38830
    • Allow URL for Codex link in Additional CSS section to be translated. [39268] #35395, #38823
    • More visible focus and hover states for close and back buttons. [39249] #29158
    • Ensure edit shortcuts have same background color regardless of theme colors. [39243] #38776
    • Add !important line-height to edit shortcut buttons. [39242] #38787
    • Allow starter content to apply in a new theme when switching from another theme containing changes. [39241] #38114, #38541
    • Only show video header controls if previewing front page; show explanatory notice when controls are hidden. [39237] #38796, #38778
    • Adjust layout for edit shortcuts only when shown. [39233] #38651


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



    • Plugin install: De-duplicate a conditional, introduced in [38172]. [39336] #38190
    • Docs: Use 3-digit, x.x.x style semantic versioning for @since 4.7.0 entries. [39281] #37770
    • Tests: Add a missing $message argument for assertEquals() in [39265]. [39267] #23626
    • Tests: Use assertEquals()‘ native functionality for delta comparison in test_wp_convert_bytes_to_hr(). [39265] #23626


    • In wp_dropdown_languages() rename the new show_site_locale_default argument to show_option_site_default. [39331] #38632, #38871
    • Add an additional caching layer for _load_textdomain_just_in_time(). [39330] #37997
    • Introduce more translator comments for strings that contain placeholders but don’t have an accompanying translator comment. [39326] #38882
    • Move the support forums URL in update-related HTTP API error messages to a separate translatable string that is already used elsewhere. [39325] #38880
    • Remove an erroneous @TODO introduced in [39323]. [39324] #38882
    • Begin introducing translator comments for strings which include placeholders but no accompanying translator comment. [39323] #38882
    • REST API: Merge two error messages for edit / update. [39322] #38879
    • REST API: Update error messages in WP_REST_Comments_Controller to use the common text for permission errors. [39321] #38875
    • Use ‘WordPress hook name’ instead of ‘PHP hook name’ in translator comments added in [39315]. [39316] #38862
    • Add translator comments for strings in _deprecated_*() functions. [39315] #38862
    • Remove unnecessary __() calls in _rotate_image_resource() and _flip_image_resource(). [39314] #38862
    • REST API: Merge some more permission error strings missed in [39309]. [39313] #38857
    • Text Changes: Merge strings referring to list_users capability. [39312] #38857
    • Merge two ‘RSS Error:’ strings. [39311] #38861
    • REST API: After [39306], move author_ip argument to the correct place. [39310] #38822
    • REST API: Merge and clarify some permission error strings. [39309] #38857
    • Text Changes: Merge and clarify some permission error strings in the admin. [39308] #38857
    • Merge two ‘ERROR:’ strings. [39307] #38860
    • REST API: After [39302], clarify author_ip parameter in error message. [39306] #38822
    • REST API: Merge two similar permission error strings in class-wp-rest-comments-controller.php. [39305] #38857
    • REST API: Merge two similar permission error strings. [39304] #38857
    • REST API: Clarify parameters when used in error strings. [39298] #38822
    • REST API: After [39252] and [39264], uppercase some more ‘ID’ references in translatable strings. [39266] #38791
    • REST API: Uppercase ‘ID’ in endpoint descriptions and error messages for consistency with other strings. [39264] #38791
    • REST API: Unify some more permission error messages. [39259] #38803
    • REST API: Unify permission error messages. [39257] #38803
    • Remove “ tags from translatable strings in wp-includes/class-wp-customize-manager.php. [39254] #38802
    • REST API: Remove two duplicate strings, use the ones we already have. [39252] #38791
    • REST API: Unify permission error messages. [39251] #38791, #34521
    • REST API: After [39238] and [39239], move the remaining translator comments to preceding line. [39245] #38791
    • Docs: Apply documentation standards to the new get_available_languages filter. [39244] #38788
    • REST API: Move translator comments to preceding line. [39239] #38791
    • REST API: Add translator comments to text with placeholders. [39238] #38791
    • Add the get_available_languages filter. [39235] #38788



    • REST API: Check read permissions on posts when viewing comments. [39295]
    • Small coding standards cleanup of wp-custom-header.js. [39277]
    • Post-4.7 beta 4 bump. [39263]
    • WordPress 4.7 Beta 4. [39262]

    Options, Meta APIs

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

    Posts, Post Types

    • Accessibility: Improve the Post Attributes meta box fields labels. [39247] #38790
    • Improve sanitisation of templates’ post types. [39236] #38766


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


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

    Text Changes

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


    • Prevent unneeded database updates in wp_get_custom_css_post(). [39338] #38866
    • Twenty Seventeen: Make all Codex links in DocBlocks use HTTPS [39300] #38854
    • Twenty Seventeen: Rename the starter content menus to match the menu area names. [39294] #38615
    • Improve a11y and extendability of custom video headers. [39272] #38678
    • Theme starter content: Add reference IDs for most default widgets. [39261] #38615
    • Theme starter content: Refine the content for pages. [39260] #38615
    • Theme starter content: Add more social link items to select from. [39256] #38615
    • Theme starter content: Revamp the credits widget into an about widget. [39255] #38615
    • Remove front page restriction from video header functions. [39240] #38738
    • Customize: Use video-specific labels for buttons in Header Video media control. [39234] #38172


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



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

  • Gary Pendergast 2:33 am on November 24, 2016 Permalink |
    Tags: ,   

    New Committers! 

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

    First up, James Nylen (@jnylen0). James has been a driving force on the REST API, both when it was a feature plugin, and more recently in Core since the endpoints were merged. The tickets and comments he leaves on Trac are always thorough and thoughtful, his patches are consistently excellent, and his attitude is exemplary.

    Next, Adam Silverstein (@adamsilverstein). Adam has been a regular contributor for years, bringing significant improvements to the Media Grid, as well as handling large parts of the JavaScript work around the REST API endpoints – both in wp-api.js, and tenaciously working on porting Dashboard features across to using the endpoints.

    Rounding out our guest committer list, Felix Arntz (@flixos90). Felix has been a contributor to Multisite for some time now, writing excellent patches, as well as running Office Hours and Bug Scrubs. Not only that, he’s always been willing to jump in and help in any area of Core, showing the same level of enthusiasm and consideration across the board.

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

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

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc
Skip to toolbar