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.

Built from https://develop.svn.wordpress.org/trunk@36532


git-svn-id: http://core.svn.wordpress.org/trunk@36499 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/css/colors/_admin.scss

@@ -487,6 +487,10 @@ body.more-filters-opened .more-filters:focus:before {
 	color: $menu-highlight-text;
 }
 
+#customize-footer-actions .devices button:focus {
+	border-bottom-color: $highlight-color;
+}
+
 /* Responsive Component */
 
 div#wp-responsive-toggle a:before {

wp-admin/css/colors/blue/colors-rtl.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #096484;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #e5f8ff;

wp-admin/css/colors/blue/colors.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #096484;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #e5f8ff;

wp-admin/css/colors/coffee/colors-rtl.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #c7a589;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #f3f2f1;

wp-admin/css/colors/coffee/colors.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #c7a589;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #f3f2f1;

wp-admin/css/colors/ectoplasm/colors-rtl.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #a3b745;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #ece6f6;

wp-admin/css/colors/ectoplasm/colors.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #a3b745;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #ece6f6;

wp-admin/css/colors/light/colors-rtl.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #04a4cc;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #999;

wp-admin/css/colors/light/colors.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #04a4cc;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #999;

wp-admin/css/colors/midnight/colors-rtl.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #e14d43;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #f1f2f3;

wp-admin/css/colors/midnight/colors.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #e14d43;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #f1f2f3;

wp-admin/css/colors/ocean/colors-rtl.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #9ebaa0;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #f2fcff;

wp-admin/css/colors/ocean/colors.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #9ebaa0;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #f2fcff;

wp-admin/css/colors/sunrise/colors-rtl.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #dd823b;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #f3f1f1;

wp-admin/css/colors/sunrise/colors.css

@@ -514,6 +514,10 @@ body.more-filters-opened .more-filters:focus:before {
   color: #fff;
 }
 
+#customize-footer-actions .devices button:focus {
+  border-bottom-color: #dd823b;
+}
+
 /* Responsive Component */
 div#wp-responsive-toggle a:before {
   color: #f3f1f1;

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

@@ -610,6 +610,7 @@ p.customize-section-description {
 #customize-preview iframe {
 	width: 100%;
 	height: 100%;
+	position: absolute;
 }
 
 .wp-full-overlay-sidebar {
@@ -1311,6 +1312,127 @@ body.cheatin p {
 	color: #00a0d2;
 }
 
+/* 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;
+	right: 0;
+	width: 300px;
+	height: 45px;
+	border-top: 1px solid #ddd;
+}
+
+#customize-footer-actions .devices {
+	float: left;
+}
+
+#customize-footer-actions .devices button {
+	cursor: pointer;
+	background: transparent;
+	border: none;
+	height: 45px;
+	padding: 0 3px;
+	margin: 0 -4px 0 0;
+	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 {
+	right: 0;
+}
+
+.preview-mobile #customize-preview {
+	margin: auto -160px auto 0;
+	width: 320px;
+	height: 480px;
+	max-height: 100%;
+	max-width: 100%;
+	right: 50%;
+}
+
+.preview-tablet #customize-preview {
+	margin: auto -3in auto 0;
+	width: 6in;
+	height: 9in;
+	max-height: 100%;
+	max-width: 100%;
+	right: 50%;
+}
+
 .widget-reorder-nav span,
 .menu-item-reorder-nav button {
 	position: relative;

wp-admin/css/customize-controls.css

@@ -610,6 +610,7 @@ p.customize-section-description {
 #customize-preview iframe {
 	width: 100%;
 	height: 100%;
+	position: absolute;
 }
 
 .wp-full-overlay-sidebar {
@@ -1311,6 +1312,127 @@ body.cheatin p {
 	color: #00a0d2;
 }
 
+/* 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 {
 	position: relative;

wp-admin/customize.php

@@ -148,6 +148,26 @@ do_action( 'customize_controls_print_scripts' );
 		</div>
 
 		<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>
 				<span class="collapse-sidebar-label"><?php _e( 'Collapse' ); ?></span>

wp-admin/js/customize-controls.js

@@ -3229,7 +3229,8 @@
 			overlay = body.children( '.wp-full-overlay' ),
 			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.
 		$('#customize-controls').on( 'keydown', function( e ) {
@@ -3605,6 +3606,46 @@
 			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.
 		if ( title.length ) {
 			api( 'blogname', function( setting ) {

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

@@ -1710,6 +1710,7 @@ final class WP_Customize_Manager {
 			'nonce'    => $this->get_nonces(),
 			'autofocus' => array(),
 			'documentTitleTmpl' => $this->get_document_title_template(),
+			'previewableDevices' => $this->get_previewable_devices(),
 		);
 
 		// Prepare Customize Section objects to pass to JavaScript.
@@ -1786,6 +1787,42 @@ final class WP_Customize_Manager {
 		<?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;
+	}
+
 	/**
 	 * Register some default controls.
 	 *

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.5-alpha-36531';
+$wp_version = '4.5-alpha-36532';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.