Changeset 36532

Timestamp:

02/16/2016 01:56:13 AM (9 years ago)

Author:

westonruter

Message:

Customize: Add a user-friendly way to preview site responsiveness for desktop, tablet, and mobile.

Introduces WP_Customize_Manager::get_previewable_devices() with a customize_previewable_devices filter to change the default device and which devices are available for previewing. This is a feature that was first pioneered on WordPress.com.

Props celloexpressions, folletto, valendesigns, westonruter, welcher, adamsilverstein, michaelarestad, Fab1en.
Fixes #31195.

Location:

trunk

Files:

• src/wp-admin/css/colors/_admin.scss (modified) (1 diff)
• src/wp-admin/css/customize-controls.css (modified) (2 diffs)
• src/wp-admin/customize.php (modified) (1 diff)
• src/wp-admin/js/customize-controls.js (modified) (2 diffs)
• src/wp-includes/class-wp-customize-manager.php (modified) (2 diffs)
• tests/phpunit/tests/customize/manager.php (modified) (2 diffs)
• tests/qunit/fixtures/customize-settings.js (modified) (1 diff)
• tests/qunit/wp-admin/js/customize-controls.js (modified) (1 diff)

trunk/src/wp-admin/css/colors/_admin.scss

@@ -488 +488 @@
 }
 
+#customize-footer-actions .devices button:focus {
+    border-bottom-color: $highlight-color;
+}
+
 /* Responsive Component */
 

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

@@ -611 +611 @@
     width: 100%;
     height: 100%;
+    position: absolute;
 }
 
@@ -1312 +1313 @@
 }
 
+/* Device/preview size toggles */
+
+.wp-full-overlay {
+    background: #191e23;
+}
+
+#customize-preview.wp-full-overlay-main {
+    background-color: #f1f1f1;
+}
+
+.expanded #customize-footer-actions {
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    width: 300px;
+    height: 45px;
+    border-top: 1px solid #ddd;
+}
+
+#customize-footer-actions .devices {
+    float: right;
+}
+
+#customize-footer-actions .devices button {
+    cursor: pointer;
+    background: transparent;
+    border: none;
+    height: 45px;
+    padding: 0 3px;
+    margin: 0 0 0 -4px;
+    box-shadow: none;
+    border-top: 1px solid transparent;
+    border-bottom: 4px solid transparent;
+    -webkit-transition: background .1s ease-in-out;
+    transition: background .1s ease-in-out;
+}
+
+#customize-footer-actions .devices button:focus {
+    box-shadow: none;
+    outline: none;
+}
+
+#customize-footer-actions .devices button:before {
+    display: inline-block;
+    -webkit-font-smoothing: antialiased;
+    font: normal 20px/30px "dashicons";
+    vertical-align: top;
+    margin: 3px 0;
+    padding: 4px 8px;
+    color: #656a6f;
+}
+
+#customize-footer-actions .devices button.active {
+    border-bottom-color: #191e23;
+}
+
+#customize-footer-actions .devices button:hover,
+#customize-footer-actions .devices button:focus {
+    background-color: #fff;
+}
+
+#customize-footer-actions .devices button:focus {
+    background-color: #fff;
+    border-bottom-color: #0073aa;
+}
+
+#customize-footer-actions .devices button.active:before,
+#customize-footer-actions .devices button:hover:before,
+#customize-footer-actions .devices button:focus:before {
+    color: #191e23;
+}
+
+.wp-core-ui .wp-full-overlay .collapse-sidebar:hover,
+.wp-core-ui .wp-full-overlay .collapse-sidebar:focus {
+    color: #191e23;
+}
+
+#customize-footer-actions .devices .preview-desktop:before {
+    content: "\f472";
+}
+
+#customize-footer-actions .devices .preview-tablet:before {
+    content: "\f471";
+}
+
+#customize-footer-actions .devices .preview-mobile:before {
+    content: "\f470";
+}
+
+@media screen and (max-width:1024px) {
+    #customize-footer-actions .devices {
+        display: none;
+    }
+}
+
+.collapsed #customize-footer-actions .devices button:before {
+    display: none;
+}
+
+.collapsed #customize-footer-actions .devices .preview-full {
+    left: 0;
+}
+
+.preview-mobile #customize-preview {
+    margin: auto 0 auto -160px;
+    width: 320px;
+    height: 480px;
+    max-height: 100%;
+    max-width: 100%;
+    left: 50%;
+}
+
+.preview-tablet #customize-preview {
+    margin: auto 0 auto -3in;
+    width: 6in;
+    height: 9in;
+    max-height: 100%;
+    max-width: 100%;
+    left: 50%;
+}
+
 .widget-reorder-nav span,
 .menu-item-reorder-nav button {

trunk/src/wp-admin/customize.php

@@ -149 +149 @@
 
         <div id="customize-footer-actions" class="wp-full-overlay-footer">
+            <?php $previewable_devices = $wp_customize->get_previewable_devices(); ?>
+            <?php if ( ! empty( $previewable_devices ) ) : ?>
+            <div class="devices">
+                <?php foreach ( (array) $previewable_devices as $device => $settings ) : ?>
+                    <?php
+                    if ( empty( $settings['label'] ) ) {
+                        continue;
+                    }
+                    $active = ! empty( $settings['default'] );
+                    $class = 'preview-' . $device;
+                    if ( $active ) {
+                        $class .= ' active';
+                    }
+                    ?>
+                    <button type="button" class="<?php echo esc_attr( $class ); ?>" aria-pressed="<?php echo esc_attr( $active ) ?>" data-device="<?php echo esc_attr( $device ); ?>">
+                        <span class="screen-reader-text"><?php echo esc_html( $settings['label'] ); ?></span>
+                    </button>
+                <?php endforeach; ?>
+            </div>
+            <?php endif; ?>
             <button type="button" class="collapse-sidebar button-secondary" aria-expanded="true" aria-label="<?php esc_attr_e( 'Collapse Sidebar' ); ?>">
                 <span class="collapse-sidebar-arrow"></span>

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

@@ -3230 +3230 @@
             title = $( '#customize-info .panel-title.site-title' ),
             closeBtn = $( '.customize-controls-close' ),
-            saveBtn = $( '#save' );
+            saveBtn = $( '#save' ),
+            footerActions = $( '#customize-footer-actions' );
 
         // Prevent the form from saving when enter is pressed on an input or select element.
@@ -3605 +3606 @@
             event.preventDefault();
         });
+
+        // Previewed device bindings.
+        api.previewedDevice = new api.Value();
+
+        // Set the default device.
+        api.bind( 'ready', function() {
+            _.find( api.settings.previewableDevices, function( value, key ) {
+                if ( true === value['default'] ) {
+                    api.previewedDevice.set( key );
+                    return true;
+                }
+            } );
+        } );
+
+        // Set the toggled device.
+        footerActions.find( '.devices button' ).on( 'click', function( event ) {
+            api.previewedDevice.set( $( event.currentTarget ).data( 'device' ) );
+        });
+
+        // Bind device changes.
+        api.previewedDevice.bind( function( newDevice ) {
+            var overlay = $( '.wp-full-overlay' ),
+                devices = '';
+
+            footerActions.find( '.devices button' )
+                .removeClass( 'active' )
+                .attr( 'aria-pressed', false );
+
+            footerActions.find( '.devices .preview-' + newDevice )
+                .addClass( 'active' )
+                .attr( 'aria-pressed', true );
+
+            $.each( api.settings.previewableDevices, function( device ) {
+                devices += ' preview-' + device;
+            } );
+
+            overlay
+                .removeClass( devices )
+                .addClass( 'preview-' + newDevice );
+        } );
 
         // Bind site title display to the corresponding field.

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

@@ -1711 +1711 @@
             'autofocus' => array(),
             'documentTitleTmpl' => $this->get_document_title_template(),
+            'previewableDevices' => $this->get_previewable_devices(),
         );
 
@@ -1785 +1786 @@
         </script>
         <?php
+    }
+
+    /**
+     * Returns a list of devices to allow previewing.
+     *
+     * @access public
+     * @since 4.5.0
+     *
+     * @return array List of devices with labels and default setting.
+     */
+    public function get_previewable_devices() {
+        $devices = array(
+            'desktop' => array(
+                'label' => __( 'Enter desktop preview mode' ),
+                'default' => true,
+            ),
+            'tablet' => array(
+                'label' => __( 'Enter tablet preview mode' ),
+            ),
+            'mobile' => array(
+                'label' => __( 'Enter mobile preview mode' ),
+            ),
+        );
+
+        /**
+         * Filter the available devices to allow previewing in the Customizer.
+         *
+         * @since 4.5.0
+         *
+         * @see WP_Customize_Manager::get_previewable_devices()
+         *
+         * @param array $devices List of devices with labels and default setting.
+         */
+        $devices = apply_filters( 'customize_previewable_devices', $devices );
+
+        return $devices;
     }
 

trunk/tests/phpunit/tests/customize/manager.php

@@ -426 +426 @@
         $this->assertNotEmpty( $data );
 
-        $this->assertEqualSets( array( 'theme', 'url', 'browser', 'panels', 'sections', 'nonce', 'autofocus', 'documentTitleTmpl' ), array_keys( $data ) );
+        $this->assertEqualSets( array( 'theme', 'url', 'browser', 'panels', 'sections', 'nonce', 'autofocus', 'documentTitleTmpl', 'previewableDevices' ), array_keys( $data ) );
         $this->assertEquals( $autofocus, $data['autofocus'] );
         $this->assertArrayHasKey( 'save', $data['nonce'] );
@@ -717 +717 @@
         $this->assertEquals( $control_id, $result_control->id );
     }
+
+
+    /**
+     * Testing the return values both with and without filter.
+     *
+     * @ticket 31195
+     */
+    function test_get_previewable_devices() {
+
+        // Setup the instance.
+        $manager = new WP_Customize_Manager();
+
+        // The default devices list.
+        $default_devices = array(
+            'desktop' => array(
+                'label'   => __( 'Enter desktop preview mode' ),
+                'default' => true,
+            ),
+            'tablet'  => array(
+                'label' => __( 'Enter tablet preview mode' ),
+            ),
+            'mobile'  => array(
+                'label' => __( 'Enter mobile preview mode' ),
+            ),
+        );
+
+        // Control test.
+        $devices = $manager->get_previewable_devices();
+        $this->assertSame( $default_devices, $devices );
+
+        // Adding the filter.
+        add_filter( 'customize_previewable_devices', array( $this, 'filter_customize_previewable_devices' ) );
+        $devices = $manager->get_previewable_devices();
+        $this->assertSame( $this->filtered_device_list(), $devices );
+
+        // Clean up.
+        remove_filter( 'customize_previewable_devices', array( $this, 'filter_customize_previewable_devices' ) );
+    }
+
+    /**
+     * Helper method for test_get_previewable_devices.
+     *
+     * @return array
+     */
+    function filtered_device_list() {
+        return array(
+            'custom-device' => array(
+                'label' => __( 'Enter custom-device preview mode' ),
+                'default' => true,
+            ),
+        );
+    }
+
+    /**
+     * Callback for the customize_previewable_devices filter.
+     *
+     * @param array $devices The list of devices.
+     *
+     * @return array
+     */
+    function filter_customize_previewable_devices( $devices ) {
+        return $this->filtered_device_list();
+    }
 }
 

trunk/tests/qunit/fixtures/customize-settings.js

@@ -131 +131 @@
         'parent': 'http://example.org/wp-admin/',
         'preview': 'http://example.org/'
+    },
+    'previewableDevices': {
+        'desktop': {
+            'label': 'Enter desktop preview mode',
+            'default': true
+        },
+        'tablet': {
+            'label': 'Enter tablet preview mode'
+        },
+        'mobile': {
+            'label': 'Enter mobile preview mode'
+        }
     }
 };

trunk/tests/qunit/wp-admin/js/customize-controls.js

@@ -76 +76 @@
 
     };
+
+    module( 'Customizer Previewed Device' );
+    test( 'Previewed device defaults to desktop.', function () {
+        equal( wp.customize.previewedDevice.get(), 'desktop' );
+    } );
 
     module( 'Customizer Setting in Fixture' );