WordPress.org

Make WordPress Core


Ignore:
Timestamp:
10/27/2016 10:08:33 PM (5 years ago)
Author:
davidakennedy
Message:

Twenty Seventeen: Improve user and developer experience with the customizer integration

  • Rename customizer JS files to customize-preview.js and customize-controls.js to align with the core file naming and make it clearer where each file runs.
  • Only show the colorscheme_hue control when there's a custom color scheme.
  • Update preview JS handling for revised front page section handling, see below.
  • Remove all references to "Theme Customizer" in code comments. It hasn't been called that since before 4.0.
  • Clarify the purpose of the JS files by updated the code comments in the file headers.
  • Improve code readability.
  • Make the arbitrary number of front page sections filterable, for UI registration and output.
  • Rename twentyseventeen_sanitize_layout to twentyseventeen_sanitize_page_layout to be clearer about what it sanitizes in case child themes or plugins consider reusing it.
  • Rename page_options setting/control to page_layout as that's more reflective of what that option does; and again, helps for potential extensions.
  • Make the page layout option contextual to pages and the sidebar being inactive, as the option only applies when there is no sidebar (per its description).
  • Condense options into a single section.
  • Add selective refresh for front page sections.
  • Locate active_callback functions within customizer.php so that they're easier to find when editing customizer registrations, similarly to sanitize callbacks.
  • Adjust the styling for placeholders for panels that aren't active.
  • Ensure that the new visible edit shortcuts don't have any issues.

Props celloexpressions.

Fixes #38426.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-content/themes/twentyseventeen/inc/customizer.php

    r38985 r38986  
    11<?php
    22/**
    3  * Twenty Seventeen: Theme Customizer
     3 * Twenty Seventeen: Customizer
    44 *
    55 * @package WordPress
     
    6363
    6464    /**
    65      * Add the Theme Options section.
     65     * Theme options.
    6666     */
    67     $wp_customize->add_panel( 'options_panel', array(
    68         'title'       => __( 'Theme Options', 'twentyseventeen' ),
    69         'description' => __( 'Configure your theme settings', 'twentyseventeen' ),
    70     ) );
    71 
    72     // Page Options.
    73     $wp_customize->add_section( 'page_options', array(
    74         'title'           => __( 'Single Page Layout', 'twentyseventeen' ),
    75         'active_callback' => 'twentyseventeen_is_page',
    76         'panel'           => 'options_panel',
    77     ) );
    78 
    79     $wp_customize->add_setting( 'page_options', array(
     67    $wp_customize->add_section( 'theme_options', array(
     68        'title'    => __( 'Theme Options', 'twentyseventeen' ),
     69        'priority' => 130, // Before Additional CSS.
     70    ) );
     71
     72    $wp_customize->add_setting( 'page_layout', array(
    8073        'default'           => 'two-column',
    81         'sanitize_callback' => 'twentyseventeen_sanitize_layout',
     74        'sanitize_callback' => 'twentyseventeen_sanitize_page_layout',
    8275        'transport'         => 'postMessage',
    8376    ) );
    8477
    85     $wp_customize->add_control( 'page_options', array(
     78    $wp_customize->add_control( 'page_layout', array(
    8679        'label'       => __( 'Page Layout', 'twentyseventeen' ),
    87         'section'     => 'page_options',
     80        'section'     => 'theme_options',
    8881        'type'        => 'radio',
    8982        'description' => __( 'When no sidebar widgets are assigned, you can opt to display all pages with a one column or two column layout. When the two column layout is assigned, the page title is in one column and content is in the other.', 'twentyseventeen' ),
     
    9285            'two-column' => __( 'Two Column', 'twentyseventeen' ),
    9386        ),
    94     ) );
    95 
    96     // Panel 1.
    97     $wp_customize->add_section( 'panel_1', array(
    98         'title'           => __( 'Panel 1', 'twentyseventeen' ),
    99         'active_callback' => 'is_front_page',
    100         'panel'           => 'options_panel',
    101         'description'     => __( 'Add an image to your panel by setting a featured image in the page editor. If you don&rsquo;t select a page, this panel will not be displayed.', 'twentyseventeen' ),
    102     ) );
    103 
    104     $wp_customize->add_setting( 'panel_1', array(
    105         'default'           => false,
    106         'sanitize_callback' => 'absint',
    107     ) );
    108 
    109     $wp_customize->add_control( 'panel_1', array(
    110         'label'   => __( 'Panel Content', 'twentyseventeen' ),
    111         'section' => 'panel_1',
    112         'type'    => 'dropdown-pages',
    113     ) );
    114 
    115     // Panel 2.
    116     $wp_customize->add_section( 'panel_2', array(
    117         'title'           => __( 'Panel 2', 'twentyseventeen' ),
    118         'active_callback' => 'is_front_page',
    119         'panel'           => 'options_panel',
    120         'description'     => __( 'Add an image to your panel by setting a featured image in the page editor. If you don&rsquo;t select a page, this panel will not be displayed.', 'twentyseventeen' ),
    121     ) );
    122 
    123     $wp_customize->add_setting( 'panel_2', array(
    124         'default'           => false,
    125         'sanitize_callback' => 'absint',
    126     ) );
    127 
    128     $wp_customize->add_control( 'panel_2', array(
    129         'label'   => __( 'Panel Content', 'twentyseventeen' ),
    130         'section' => 'panel_2',
    131         'type'    => 'dropdown-pages',
    132     ) );
    133 
    134     // Panel 3.
    135     $wp_customize->add_section( 'panel_3', array(
    136         'title'           => __( 'Panel 3', 'twentyseventeen' ),
    137         'active_callback' => 'is_front_page',
    138         'panel'           => 'options_panel',
    139         'description'     => __( 'Add an image to your panel by setting a featured image in the page editor. If you don&rsquo;t select a page, this panel will not be displayed.', 'twentyseventeen' ),
    140     ) );
    141 
    142     $wp_customize->add_setting( 'panel_3', array(
    143         'default'           => false,
    144         'sanitize_callback' => 'absint',
    145     ) );
    146 
    147     $wp_customize->add_control( 'panel_3', array(
    148         'label'   => __( 'Panel Content', 'twentyseventeen' ),
    149         'section' => 'panel_3',
    150         'type'    => 'dropdown-pages',
    151     ) );
    152 
    153     // Panel 4.
    154     $wp_customize->add_section( 'panel_4', array(
    155         'title'           => __( 'Panel 4', 'twentyseventeen' ),
    156         'active_callback' => 'is_front_page',
    157         'panel'           => 'options_panel',
    158         'description'     => __( 'Add an image to your panel by setting a featured image in the page editor. If you don&rsquo;t select a page, this panel will not be displayed.', 'twentyseventeen' ),
    159     ) );
    160 
    161     $wp_customize->add_setting( 'panel_4', array(
    162         'default'           => false,
    163         'sanitize_callback' => 'absint',
    164     ) );
    165 
    166     $wp_customize->add_control( 'panel_4', array(
    167         'label'   => __( 'Panel Content', 'twentyseventeen' ),
    168         'section' => 'panel_4',
    169         'type'    => 'dropdown-pages',
    170     ) );
     87        'active_callback' => 'twentyseventeen_is_page_without_sidebar',
     88    ) );
     89
     90    /**
     91     * Filter number of front page sections in Twenty Seventeen.
     92     *
     93     * @since Twenty Seventeen 1.0
     94     *
     95     * @param $num_sections integer
     96     */
     97    $num_sections = apply_filters( 'twentyseventeen_front_page_sections', 4 );
     98
     99    // Create a setting and control for each of the sections available in the theme.
     100    for ( $i = 1; $i < ( 1 + $num_sections ); $i++ ) {
     101        $wp_customize->add_setting( 'panel_' . $i, array(
     102            'default'           => false,
     103            'sanitize_callback' => 'absint',
     104            'transport'         => 'postMessage',
     105        ) );
     106
     107        $wp_customize->add_control( 'panel_' . $i, array(
     108            /* translators: %d is the front page section number */
     109            'label'          => sprintf( __( 'Front Page Section %d Content', 'twentyseventeen' ), $i ),
     110            'description'    => ( 1 !== $i ? '' : __( 'Select pages to feature in each area from the dropdowns. Add an image to a section by setting a featured image in the page editor. Empty sections will not be displayed.', 'twentyseventeen' ) ),
     111            'section'        => 'theme_options',
     112            'type'           => 'dropdown-pages',
     113            'allow_addition' => true,
     114            'active_callback' => 'twentyseventeen_is_static_front_page',
     115        ) );
     116
     117        $wp_customize->selective_refresh->add_partial( 'panel_' . $i, array(
     118            'selector'            => '#panel' . $i,
     119            'render_callback'     => 'twentyseventeen_front_page_section',
     120            'container_inclusive' => true,
     121        ) );
     122    }
    171123}
    172124add_action( 'customize_register', 'twentyseventeen_customize_register' );
    173125
    174126/**
    175  * Sanitize a radio button.
    176  */
    177 function twentyseventeen_sanitize_layout( $input ) {
     127 * Sanitize the page layout options.
     128 */
     129function twentyseventeen_sanitize_page_layout( $input ) {
    178130    $valid = array(
    179131        'one-column' => __( 'One Column', 'twentyseventeen' ),
     
    226178
    227179/**
    228  * Binds JS handlers to make Theme Customizer preview reload changes asynchronously.
     180 * Return whether we're previewing the front page and it's a static page.
     181 */
     182function twentyseventeen_is_static_front_page() {
     183    return ( is_front_page() && ! is_home() );
     184}
     185
     186/**
     187 * Return whether we're previewing a page and there are no widgets in the sidebar.
     188 */
     189function twentyseventeen_is_page_without_sidebar() {
     190    return ( is_page() && ! is_active_sidebar( 'sidebar-1' ) );
     191}
     192
     193/**
     194 * Bind JS handlers to instantly live-preview changes.
    229195 */
    230196function twentyseventeen_customize_preview_js() {
    231     wp_enqueue_script( 'twentyseventeen-customizer', get_theme_file_uri( '/assets/js/customizer.js' ), array( 'customize-preview' ), '1.0', true );
     197    wp_enqueue_script( 'twentyseventeen-customize-preview', get_theme_file_uri( '/assets/js/customize-preview.js' ), array( 'customize-preview' ), '1.0', true );
    232198}
    233199add_action( 'customize_preview_init', 'twentyseventeen_customize_preview_js' );
    234200
    235201/**
    236  * Some extra JavaScript to improve the user experience in the Customizer for this theme.
     202 * Load dynamic logic for the customizer controls area.
    237203 */
    238204function twentyseventeen_panels_js() {
    239     wp_enqueue_script( 'twentyseventeen-panel-customizer', get_theme_file_uri( '/assets/js/panel-customizer.js' ), array(), '1.0', true );
     205    wp_enqueue_script( 'twentyseventeen-customize-controls', get_theme_file_uri( '/assets/js/customize-controls.js' ), array(), '1.0', true );
    240206}
    241207add_action( 'customize_controls_enqueue_scripts', 'twentyseventeen_panels_js' );
Note: See TracChangeset for help on using the changeset viewer.