Ticket #34747: 2007d00.diff

src/wp-admin/css/customize-controls.css

@@ -418 +418 @@
         transition: left ease-in-out .18s;
 }
 
+#customize-info.no-title {
+        display:none;
+}
+
 .ios #customize-info,
 .ios #customize-theme-controls > ul > .accordion-section {
         -webkit-transition: left 0s;

src/wp-admin/customize.php

@@ -136 +136 @@
                                         ?></span>
                                         <button class="customize-help-toggle dashicons dashicons-editor-help" aria-expanded="false"><span class="screen-reader-text"><?php _e( 'Help' ); ?></span></button>
                                 </div>
-                                <div class="customize-panel-description"><?php
-                                        _e( 'The Customizer allows you to preview changes to your site before publishing them. You can also navigate to different pages on your site to preview them.' );
-                                ?></div>
+                                <div class="customize-panel-description">
+                                        <?php // Description produced with JavaScript ?>
+                                </div>
                         </div>
 
                         <div id="customize-theme-controls">

src/wp-admin/js/customize-controls.js

@@ -3231 +3231 @@
                         return;
                 }
 
-                var parent, topFocus,
+                var rootPanelDescription, customizeHelpButton, parent, topFocus,
+                        customizeInfoSection = $( '#customize-info'),
                         body = $( document.body ),
                         overlay = body.children( '.wp-full-overlay' ),
                         title = $( '#customize-info .panel-title.site-title' ),
@@ -3249 +3250 @@
                         }
                 });
 
+                rootPanelDescription = api.settings.filteredRootPanelDescription;
+                customizeInfoSection.find( '> .customize-panel-description' ).html( rootPanelDescription );
+
+                // Hide the '?' icon if the root panel description isn't present
+                customizeHelpButton = customizeInfoSection.find( '> .accordion-section-title .customize-help-toggle' );
+                if ( ! rootPanelDescription ) {
+                        customizeHelpButton.hide();
+                }
+
                 // Expand/Collapse the main customizer customize info.
-                $( '.customize-info' ).find( '> .accordion-section-title .customize-help-toggle' ).on( 'click keydown', function( event ) {
+                customizeHelpButton.on( 'click keydown', function( event ) {
                         if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
                                 return;
                         }
@@ -3654 +3664 @@
                 } );
 
                 // Bind site title display to the corresponding field.
-                if ( title.length ) {
-                        api( 'blogname', function( setting ) {
-                                var updateTitle = function() {
+                api( 'blogname', function( setting ) {
+                        var updateTitle = function() {
+
+                                // Set the Customizer title.
+                                if ( api.settings.isRootPanelTitleFiltered ) {
+                                        title.text( api.settings.filteredRootPanelTitle || '' );
+                                } else {
                                         title.text( $.trim( setting() ) || api.l10n.untitledBlogName );
-                                };
-                                setting.bind( updateTitle );
-                                updateTitle();
-                        } );
-                }
+                                }
+
+                                // If there's no title, set a class on the info section. The CSS will hide it.
+                                if ( ! title.text().length ) {
+                                        customizeInfoSection.addClass( 'no-title' );
+                                } else {
+                                        customizeInfoSection.removeClass( 'no-title' );
+                                }
+
+                        };
+                        setting.bind( updateTitle );
+                        updateTitle();
+                } );
 
                 /*
                  * Create a postMessage connection with a parent frame,

src/wp-includes/class-wp-customize-manager.php

@@ -184 +184 @@
         protected $return_url;
 
         /**
+         * Original title of the Customizer, before being filtered.
+         *
+         * @since 4.6
+         * @access protected
+         * @var string
+         */
+        protected $original_customizer_title;
+
+        /**
+         * Filtered title of the Customizer, shown in the top of the root panel.
+         *
+         * @since 4.6
+         * @access protected
+         * @var string
+         */
+        protected $filtered_root_panel_title;
+
+        /**
+         * Filtered description of the Customizer, below the title.
+         *
+         * @since 4.6
+         * @access protected
+         * @var string
+         */
+        protected $filtered_root_panel_description;
+
+        /**
          * Mapping of 'panel', 'section', 'control' to the ID which should be autofocused.
          *
          * @since 4.4.0
@@ -1601 +1628 @@
         }
 
         /**
+         * Set Customizer title at top of root Customizer panel.
+         *
+         * Appears after text "You are customizing."
+         *
+         * @since 4.6
+         * @access public
+         */
+        public function set_filtered_root_panel_title() {
+                $this->original_customizer_title = get_bloginfo( 'name' );
+
+                /**
+                 * Filter title in root Customizer panel.
+                 *
+                 * @since 4.6
+                 *
+                 * @param string $customizer_title Appears at top of root Customizer panel.
+                 */
+                $this->filtered_root_panel_title = apply_filters( 'customize_root_panel_title', $this->original_customizer_title );
+        }
+
+        /**
+         * Get Customizer title at top of root Customizer panel
+         *
+         * Appears above the description.
+         *
+         * @since 4.6
+         * @access public
+         */
+        public function get_filtered_root_panel_title() {
+                if ( isset( $this->filtered_root_panel_title ) ) {
+                        return $this->filtered_root_panel_title;
+                }
+        }
+
+        /**
+         * Whether the Customizer root panel title has been filtered.
+         *
+         * True if this title is different from the original title.
+         *
+         * @since 4.6
+         * @access public
+         *
+         * @return bool
+         */
+        public function is_root_panel_title_filtered() {
+                if ( ( isset( $this->filtered_root_panel_title ) ) && ( isset( $this->original_customizer_title ) ) ) {
+                        return ( $this->filtered_root_panel_title !== $this->original_customizer_title );
+                } else {
+                        return false;
+                }
+        }
+
+        /**
+         * Set Customizer description.
+         *
+         * To be shown at the top of the Customizer root panel.
+         *
+         * @since 4.6
+         * @access public
+         */
+        public function set_filtered_root_panel_description() {
+
+                /**
+                 * Filter description in primary Customizer panel.
+                 *
+                 * @since 4.6
+                 *
+                 * @param string $customizer_description Appears at top of root Customizer panel, under Customizer title.
+                 */
+                $this->filtered_root_panel_description = apply_filters( 'customize_root_panel_description', __( 'The Customizer allows you to preview changes to your site before publishing them. You can also navigate to different pages on your site to preview them.' ) );
+        }
+
+        /**
+         * Get Customizer description, to be shown in the root panel.
+         *
+         * Appears after "You are customizing" and the Customizer title.
+         *
+         * @since 4.6
+         * @access public
+         */
+        public function get_filtered_root_panel_description() {
+                if ( isset( $this->filtered_root_panel_description ) ) {
+                        return $this->filtered_root_panel_description;
+                }
+        }
+
+        /**
          * Set the autofocused constructs.
          *
          * @since 4.4.0
@@ -1686 +1800 @@
                         $allowed_urls[] = home_url( '/', 'https' );
                 }
 
+                // Set title and description displayed at top of root Customizer panel.
+                $this->set_filtered_root_panel_title();
+                $this->set_filtered_root_panel_description();
+
                 /**
                  * Filter the list of URLs allowed to be clicked and followed in the Customizer preview.
                  *
@@ -1727 +1845 @@
                         'documentTitleTmpl' => $this->get_document_title_template(),
                         'previewableDevices' => $this->get_previewable_devices(),
                         'selectiveRefreshEnabled' => isset( $this->selective_refresh ),
+                        'filteredRootPanelTitle' => $this->get_filtered_root_panel_title(),
+                        'isRootPanelTitleFiltered' => $this->is_root_panel_title_filtered(),
+                        'filteredRootPanelDescription' => $this->get_filtered_root_panel_description(),
                 );
 
                 // Prepare Customize Section objects to pass to JavaScript.

tests/phpunit/tests/customize/manager.php

@@ -340 +340 @@
         }
 
         /**
+         * Test get_filtered_root_panel_title()/set_filtered_root_panel_title() methods.
+         *
+         * @see WP_Customize_Manager::get_filtered_root_panel_title();
+         * @see WP_Customize_Manager::set_filtered_root_panel_title();
+         */
+        function test_get_filtered_root_panel_title() {
+                $this->assertEmpty( $this->manager->get_filtered_root_panel_title() );
+
+                $this->manager->set_filtered_root_panel_title();
+                $this->assertEquals( get_bloginfo( 'name' ), $this->manager->get_filtered_root_panel_title() );
+
+                add_filter( 'customize_root_panel_title', array( $this, 'filter_root_panel_title' ) );
+                $this->manager->set_filtered_root_panel_title();
+                $this->assertEquals( 'New Title', $this->manager->get_filtered_root_panel_title() );
+        }
+
+        /**
+         * Test is_root_panel_title_filtered() method.
+         *
+         * @see WP_Customize_Manager::is_root_panel_title_filtered();
+         */
+        function test_is_root_panel_title_filtered() {
+                $this->manager->set_filtered_root_panel_title();
+                $this->assertEquals( false, $this->manager->is_root_panel_title_filtered() );
+
+                $filtered_title = 'foo';
+                add_filter( 'customize_root_panel_title', array( $this, 'filter_root_panel_title' ) );
+                $this->manager->set_filtered_root_panel_title();
+                $this->assertEquals( true, $this->manager->is_root_panel_title_filtered() );
+        }
+
+        /**
+         * Filter for title at top of root panel.
+         *
+         * @return string Title.
+         */
+        function filter_root_panel_title() {
+                return 'New Title';
+        }
+
+        /**
+         * Test get_filtered_root_panel_description()/set_filtered_root_panel_description() methods.
+         *
+         * @see WP_Customize_Manager::get_filtered_root_panel_title();
+         * @see WP_Customize_Manager::set_filtered_root_panel_title();
+         */
+        function test_get_filtered_root_panel_description() {
+                $this->assertEmpty( $this->manager->get_filtered_root_panel_description() );
+
+                $this->manager->set_filtered_root_panel_description();
+                $original_description = __( 'The Customizer allows you to preview changes to your site before publishing them. You can also navigate to different pages on your site to preview them.' );
+                $this->assertEquals( $original_description, $this->manager->get_filtered_root_panel_description() );
+
+                $filtered_description = 'bar';
+                add_filter( 'customize_root_panel_description', array( $this, 'filter_root_panel_description' ) );
+                $this->manager->set_filtered_root_panel_description();
+                $this->assertEquals( 'bar', $this->manager->get_filtered_root_panel_description() );
+        }
+
+        /**
+         * Filter for description at top of root panel.
+         *
+         * @return string Description.
+         */
+        function filter_root_panel_description() {
+                return 'bar';
+        }
+
+        /**
          * Test get_autofocus()/set_autofocus() methods.
          *
          * @see WP_Customize_Manager::get_autofocus()
@@ -425 +494 @@
                 $data = json_decode( $json, true );
                 $this->assertNotEmpty( $data );
 
-                $this->assertEqualSets( array( 'theme', 'url', 'browser', 'panels', 'sections', 'nonce', 'autofocus', 'documentTitleTmpl', 'previewableDevices', 'selectiveRefreshEnabled' ), array_keys( $data ) );
+                $this->assertEqualSets( array( 'theme', 'url', 'browser', 'panels', 'sections', 'nonce', 'autofocus', 'documentTitleTmpl', 'previewableDevices', 'selectiveRefreshEnabled', 'filteredRootPanelTitle', 'isRootPanelTitleFiltered', 'filteredRootPanelDescription' ), array_keys( $data ) );
                 $this->assertEquals( $autofocus, $data['autofocus'] );
                 $this->assertArrayHasKey( 'save', $data['nonce'] );
                 $this->assertArrayHasKey( 'preview', $data['nonce'] );