Changeset 38986 for trunk/src/wp-content/themes/twentyseventeen/inc/customizer.php

Timestamp:

10/27/2016 10:08:33 PM (10 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:

• trunk/src/wp-content/themes/twentyseventeen/inc/customizer.php (modified) (4 diffs)

trunk/src/wp-content/themes/twentyseventeen/inc/customizer.php

@@ -1 +1 @@
 <?php
 /**
- * Twenty Seventeen: Theme Customizer
+ * Twenty Seventeen: Customizer
  *
  * @package WordPress
@@ -63 +63 @@
 
         /**
-         * Add the Theme Options section.
+         * Theme options.
          */
-        $wp_customize->add_panel( 'options_panel', array(
-                'title'       => __( 'Theme Options', 'twentyseventeen' ),
-                'description' => __( 'Configure your theme settings', 'twentyseventeen' ),
-        ) );
-
-        // Page Options.
-        $wp_customize->add_section( 'page_options', array(
-                'title'           => __( 'Single Page Layout', 'twentyseventeen' ),
-                'active_callback' => 'twentyseventeen_is_page',
-                'panel'           => 'options_panel',
-        ) );
-
-        $wp_customize->add_setting( 'page_options', array(
+        $wp_customize->add_section( 'theme_options', array(
+                'title'    => __( 'Theme Options', 'twentyseventeen' ),
+                'priority' => 130, // Before Additional CSS.
+        ) );
+
+        $wp_customize->add_setting( 'page_layout', array(
                 'default'           => 'two-column',
-                'sanitize_callback' => 'twentyseventeen_sanitize_layout',
+                'sanitize_callback' => 'twentyseventeen_sanitize_page_layout',
                 'transport'         => 'postMessage',
         ) );
 
-        $wp_customize->add_control( 'page_options', array(
+        $wp_customize->add_control( 'page_layout', array(
                 'label'       => __( 'Page Layout', 'twentyseventeen' ),
-                'section'     => 'page_options',
+                'section'     => 'theme_options',
                 'type'        => 'radio',
                 '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' ),
@@ -92 +85 @@
                         'two-column' => __( 'Two Column', 'twentyseventeen' ),
                 ),
-        ) );
-
-        // Panel 1.
-        $wp_customize->add_section( 'panel_1', array(
-                'title'           => __( 'Panel 1', 'twentyseventeen' ),
-                'active_callback' => 'is_front_page',
-                'panel'           => 'options_panel',
-                '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' ),
-        ) );
-
-        $wp_customize->add_setting( 'panel_1', array(
-                'default'           => false,
-                'sanitize_callback' => 'absint',
-        ) );
-
-        $wp_customize->add_control( 'panel_1', array(
-                'label'   => __( 'Panel Content', 'twentyseventeen' ),
-                'section' => 'panel_1',
-                'type'    => 'dropdown-pages',
-        ) );
-
-        // Panel 2.
-        $wp_customize->add_section( 'panel_2', array(
-                'title'           => __( 'Panel 2', 'twentyseventeen' ),
-                'active_callback' => 'is_front_page',
-                'panel'           => 'options_panel',
-                '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' ),
-        ) );
-
-        $wp_customize->add_setting( 'panel_2', array(
-                'default'           => false,
-                'sanitize_callback' => 'absint',
-        ) );
-
-        $wp_customize->add_control( 'panel_2', array(
-                'label'   => __( 'Panel Content', 'twentyseventeen' ),
-                'section' => 'panel_2',
-                'type'    => 'dropdown-pages',
-        ) );
-
-        // Panel 3.
-        $wp_customize->add_section( 'panel_3', array(
-                'title'           => __( 'Panel 3', 'twentyseventeen' ),
-                'active_callback' => 'is_front_page',
-                'panel'           => 'options_panel',
-                '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' ),
-        ) );
-
-        $wp_customize->add_setting( 'panel_3', array(
-                'default'           => false,
-                'sanitize_callback' => 'absint',
-        ) );
-
-        $wp_customize->add_control( 'panel_3', array(
-                'label'   => __( 'Panel Content', 'twentyseventeen' ),
-                'section' => 'panel_3',
-                'type'    => 'dropdown-pages',
-        ) );
-
-        // Panel 4.
-        $wp_customize->add_section( 'panel_4', array(
-                'title'           => __( 'Panel 4', 'twentyseventeen' ),
-                'active_callback' => 'is_front_page',
-                'panel'           => 'options_panel',
-                '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' ),
-        ) );
-
-        $wp_customize->add_setting( 'panel_4', array(
-                'default'           => false,
-                'sanitize_callback' => 'absint',
-        ) );
-
-        $wp_customize->add_control( 'panel_4', array(
-                'label'   => __( 'Panel Content', 'twentyseventeen' ),
-                'section' => 'panel_4',
-                'type'    => 'dropdown-pages',
-        ) );
+                'active_callback' => 'twentyseventeen_is_page_without_sidebar',
+        ) );
+
+        /**
+         * Filter number of front page sections in Twenty Seventeen.
+         *
+         * @since Twenty Seventeen 1.0
+         *
+         * @param $num_sections integer
+         */
+        $num_sections = apply_filters( 'twentyseventeen_front_page_sections', 4 );
+
+        // Create a setting and control for each of the sections available in the theme.
+        for ( $i = 1; $i < ( 1 + $num_sections ); $i++ ) {
+                $wp_customize->add_setting( 'panel_' . $i, array(
+                        'default'           => false,
+                        'sanitize_callback' => 'absint',
+                        'transport'         => 'postMessage',
+                ) );
+
+                $wp_customize->add_control( 'panel_' . $i, array(
+                        /* translators: %d is the front page section number */
+                        'label'          => sprintf( __( 'Front Page Section %d Content', 'twentyseventeen' ), $i ),
+                        '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' ) ),
+                        'section'        => 'theme_options',
+                        'type'           => 'dropdown-pages',
+                        'allow_addition' => true,
+                        'active_callback' => 'twentyseventeen_is_static_front_page',
+                ) );
+
+                $wp_customize->selective_refresh->add_partial( 'panel_' . $i, array(
+                        'selector'            => '#panel' . $i,
+                        'render_callback'     => 'twentyseventeen_front_page_section',
+                        'container_inclusive' => true,
+                ) );
+        }
 }
 add_action( 'customize_register', 'twentyseventeen_customize_register' );
 
 /**
- * Sanitize a radio button.
- */
-function twentyseventeen_sanitize_layout( $input ) {
+ * Sanitize the page layout options.
+ */
+function twentyseventeen_sanitize_page_layout( $input ) {
         $valid = array(
                 'one-column' => __( 'One Column', 'twentyseventeen' ),
@@ -226 +178 @@
 
 /**
- * Binds JS handlers to make Theme Customizer preview reload changes asynchronously.
+ * Return whether we're previewing the front page and it's a static page.
+ */
+function twentyseventeen_is_static_front_page() {
+        return ( is_front_page() && ! is_home() );
+}
+
+/**
+ * Return whether we're previewing a page and there are no widgets in the sidebar.
+ */
+function twentyseventeen_is_page_without_sidebar() {
+        return ( is_page() && ! is_active_sidebar( 'sidebar-1' ) );
+}
+
+/**
+ * Bind JS handlers to instantly live-preview changes.
  */
 function twentyseventeen_customize_preview_js() {
-        wp_enqueue_script( 'twentyseventeen-customizer', get_theme_file_uri( '/assets/js/customizer.js' ), array( 'customize-preview' ), '1.0', true );
+        wp_enqueue_script( 'twentyseventeen-customize-preview', get_theme_file_uri( '/assets/js/customize-preview.js' ), array( 'customize-preview' ), '1.0', true );
 }
 add_action( 'customize_preview_init', 'twentyseventeen_customize_preview_js' );
 
 /**
- * Some extra JavaScript to improve the user experience in the Customizer for this theme.
+ * Load dynamic logic for the customizer controls area.
  */
 function twentyseventeen_panels_js() {
-        wp_enqueue_script( 'twentyseventeen-panel-customizer', get_theme_file_uri( '/assets/js/panel-customizer.js' ), array(), '1.0', true );
+        wp_enqueue_script( 'twentyseventeen-customize-controls', get_theme_file_uri( '/assets/js/customize-controls.js' ), array(), '1.0', true );
 }
 add_action( 'customize_controls_enqueue_scripts', 'twentyseventeen_panels_js' );