Customize: Improve extensibility of Custom CSS.

* Add `customize_value_custom_css` filter to `WP_Customize_Custom_CSS::value()` method.
* Introduce `customize_update_custom_css_post_content_args` filter in `WP_Customize_Custom_CSS::update()` method.
* Make clear that `wp_get_custom_css()` and `wp_get_custom_css` filter are specifically for obtaining the value to render/display. Eliminate use of `wp_get_custom_css()` when getting the setting value. Use the underlying `post_value` directly when `is_previewed`.
* Move anonymous functions handing JS previewing for `custom_logo`, `custom_css`, and `background` into named functions on the `wp.customize.settingPreviewHandlers` to allow plugins to override/extend preview logic.
* Update `_custom_background_cb` to always print a `style` tag wen in the customizer preview, and update background preview logic to replace existing style element instead of appending a new style to the head so that background changes don't unexpectedly override any Custom CSS in the preview's stylesheet cascade.

Props westonruter, georgestephanis.
See #22058.
Fixes #38672.

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


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

wp-includes/customize/class-wp-customize-custom-css-setting.php

@@ -100,10 +100,13 @@ final class WP_Customize_Custom_CSS_Setting extends WP_Customize_Setting {
 	}
 
 	/**
-	 * Filter wp_get_custom_css for applying customized value to return value.
+	 * Filter `wp_get_custom_css` for applying the customized value.
+	 *
+	 * This is used in the preview when `wp_get_custom_css()` is called for rendering the styles.
 	 *
 	 * @since 4.7.0
 	 * @access private
+	 * @see wp_get_custom_css()
 	 *
 	 * @param string $css        Original CSS.
 	 * @param string $stylesheet Current stylesheet.
@@ -120,18 +123,31 @@ final class WP_Customize_Custom_CSS_Setting extends WP_Customize_Setting {
 	}
 
 	/**
-	 * Fetch the value of the setting.
+	 * Fetch the value of the setting. Will return the previewed value when `preview()` is called.
 	 *
 	 * @since 4.7.0
 	 * @access public
+	 * @see WP_Customize_Setting::value()
 	 *
 	 * @return string
 	 */
 	public function value() {
-		$value = wp_get_custom_css( $this->stylesheet );
+		$id_base = $this->id_data['base'];
+		if ( $this->is_previewed && null !== $this->post_value( null ) ) {
+			return $this->post_value();
+		}
+		$value = '';
+		$post = wp_get_custom_css_post( $this->stylesheet );
+		if ( $post ) {
+			$value = $post->post_content;
+		}
 		if ( empty( $value ) ) {
 			$value = $this->default;
 		}
+
+		/** This filter is documented in wp-includes/class-wp-customize-setting.php */
+		$value = apply_filters( "customize_value_{$id_base}", $value, $this );
+
 		return $value;
 	}
 
@@ -226,13 +242,56 @@ final class WP_Customize_Custom_CSS_Setting extends WP_Customize_Setting {
 	 * @return int|false The post ID or false if the value could not be saved.
 	 */
 	public function update( $css ) {
+		$setting = $this;
+
+		if ( empty( $css ) ) {
+			$css = '';
+		}
 
 		$args = array(
-			'post_content' => $css ? $css : '',
-			'post_title' => $this->stylesheet,
-			'post_name' => sanitize_title( $this->stylesheet ),
-			'post_type' => 'custom_css',
-			'post_status' => 'publish',
+			'post_content' => $css,
+			'post_content_filtered' => '',
+		);
+
+		/**
+		 * Filters the `post_content` and `post_content_filtered` args for a `custom_css` post being updated.
+		 *
+		 * This filter can be used by plugin that offer CSS pre-processors, to store the original
+		 * pre-processed CSS in `post_content_filtered` and then store processed CSS in `post_content`.
+		 * When used in this way, the `post_content_filtered` should be supplied as the setting value
+		 * instead of `post_content` via a the `customize_value_custom_css` filter, for example:
+		 *
+		 * <code>
+		 * add_filter( 'customize_value_custom_css', function( $value, $setting ) {
+		 *     $post = wp_get_custom_css_post( $setting->stylesheet );
+		 *     if ( $post && ! empty( $post->post_content_filtered ) ) {
+		 *         $css = $post->post_content_filtered;
+		 *     }
+		 *     return $css;
+		 * }, 10, 2 );
+		 * </code>
+		 *
+		 * @since 4.7.0
+		 * @param array  $args {
+		 *     Content post args (unslashed) for `wp_update_post()`/`wp_insert_post()`.
+		 *
+		 *     @type string $post_content          CSS.
+		 *     @type string $post_content_filtered Pre-processed CSS. Normally empty string.
+		 * }
+		 * @param string                          $css     Original CSS being updated.
+		 * @param WP_Customize_Custom_CSS_Setting $setting Custom CSS Setting.
+		 */
+		$args = apply_filters( 'customize_update_custom_css_post_content_args', $args, $css, $setting );
+		$args = wp_array_slice_assoc( $args, array( 'post_content', 'post_content_filtered' ) );
+
+		$args = array_merge(
+			$args,
+			array(
+				'post_title' => $this->stylesheet,
+				'post_name' => sanitize_title( $this->stylesheet ),
+				'post_type' => 'custom_css',
+				'post_status' => 'publish',
+			)
 		);
 
 		// Update post if it already exists, otherwise create a new one.

wp-includes/js/customize-preview.js

@@ -594,6 +594,63 @@
 		};
 	} )();
 
+	api.settingPreviewHandlers = {
+
+		/**
+		 * Preview changes to custom logo.
+		 *
+		 * @param {number} attachmentId Attachment ID for custom logo.
+		 * @returns {void}
+		 */
+		custom_logo: function( attachmentId ) {
+			$( 'body' ).toggleClass( 'wp-custom-logo', !! attachmentId );
+		},
+
+		/**
+		 * Preview changes to custom css.
+		 *
+		 * @param {string} value Custom CSS..
+		 * @returns {void}
+		 */
+		custom_css: function( value ) {
+			$( '#wp-custom-css' ).text( value );
+		},
+
+		/**
+		 * Preview changes to any of the background settings.
+		 *
+		 * @returns {void}
+		 */
+		background: function() {
+			var css = '', settings = {};
+
+			_.each( ['color', 'image', 'preset', 'position_x', 'position_y', 'size', 'repeat', 'attachment'], function( prop ) {
+				settings[ prop ] = api( 'background_' + prop );
+			} );
+
+			/*
+			 * The body will support custom backgrounds if either the color or image are set.
+			 *
+			 * See get_body_class() in /wp-includes/post-template.php
+			 */
+			$( document.body ).toggleClass( 'custom-background', !! ( settings.color() || settings.image() ) );
+
+			if ( settings.color() ) {
+				css += 'background-color: ' + settings.color() + ';';
+			}
+
+			if ( settings.image() ) {
+				css += 'background-image: url("' + settings.image() + '");';
+				css += 'background-size: ' + settings.size() + ';';
+				css += 'background-position: ' + settings.position_x() + ' ' + settings.position_y() + ';';
+				css += 'background-repeat: ' + settings.repeat() + ';';
+				css += 'background-attachment: ' + settings.attachment() + ';';
+			}
+
+			$( '#custom-background-css' ).text( 'body.custom-background { ' + css + ' }' );
+		}
+	};
+
 	$( function() {
 		var bg, setValue;
 
@@ -759,39 +816,9 @@
 			return 'background_' + prop;
 		} );
 
-		api.when.apply( api, bg ).done( function( color, image, preset, positionX, positionY, size, repeat, attachment ) {
-			var body = $(document.body),
-				head = $('head'),
-				style = $('#custom-background-css'),
-				update;
-
-			update = function() {
-				var css = '';
-
-				// The body will support custom backgrounds if either
-				// the color or image are set.
-				//
-				// See get_body_class() in /wp-includes/post-template.php
-				body.toggleClass( 'custom-background', !! ( color() || image() ) );
-
-				if ( color() )
-					css += 'background-color: ' + color() + ';';
-
-				if ( image() ) {
-					css += 'background-image: url("' + image() + '");';
-					css += 'background-size: ' + size() + ';';
-					css += 'background-position: ' + positionX() + ' ' + positionY() + ';';
-					css += 'background-repeat: ' + repeat() + ';';
-					css += 'background-attachment: ' + attachment() + ';';
-				}
-
-				// Refresh the stylesheet by removing and recreating it.
-				style.remove();
-				style = $('<style type="text/css" id="custom-background-css">body.custom-background { ' + css + ' }</style>').appendTo( head );
-			};
-
+		api.when.apply( api, bg ).done( function() {
 			$.each( arguments, function() {
-				this.bind( update );
+				this.bind( api.settingPreviewHandlers.background );
 			});
 		});
 
@@ -802,17 +829,13 @@
 		 *
 		 * @since 4.5.0
 		 */
-		api( 'custom_logo', function( setting ) {
-			$( 'body' ).toggleClass( 'wp-custom-logo', !! setting.get() );
-			setting.bind( function( attachmentId ) {
-				$( 'body' ).toggleClass( 'wp-custom-logo', !! attachmentId );
-			});
-		});
+		api( 'custom_logo', function ( setting ) {
+			api.settingPreviewHandlers.custom_logo.call( setting, setting.get() );
+			setting.bind( api.settingPreviewHandlers.custom_logo );
+		} );
 
-		api( 'custom_css[' + api.settings.theme.stylesheet + ']', function( value ) {
-			value.bind( function( to ) {
-				$( '#wp-custom-css' ).text( to );
-			} );
+		api( 'custom_css[' + api.settings.theme.stylesheet + ']', function( setting ) {
+			setting.bind( api.settingPreviewHandlers.custom_css );
 		} );
 
 		api.trigger( 'preview-ready' );

wp-includes/theme.php

@@ -1500,8 +1500,12 @@ function _custom_background_cb() {
 		$color = false;
 	}
 
-	if ( ! $background && ! $color )
+	if ( ! $background && ! $color ) {
+		if ( is_customize_preview() ) {
+			echo '<style type="text/css" id="custom-background-css"></style>';
+		}
 		return;
+	}
 
 	$style = $color ? "background-color: #$color;" : '';
 
@@ -1621,7 +1625,7 @@ function wp_get_custom_css_post( $stylesheet = '' ) {
 }
 
 /**
- * Fetch the saved Custom CSS content.
+ * Fetch the saved Custom CSS content for rendering.
  *
  * @since 4.7.0
  * @access public

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.7-beta3-39208';
+$wp_version = '4.7-beta3-39209';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.