vhad/wordpress-develop
1
0
Fork 0
mirror of https://github.com/gosticks/wordpress-develop.git synced 2026-10-06 15:47:05 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Customize: Add selective refresh framework with implementation for widgets and re-implementation for nav menus.

Browse Source 
See https://make.wordpress.org/core/2016/02/16/selective-refresh-in-the-customizer/.

Props westonruter, valendesigns, DrewAPicture, ocean90.
Fixes #27355.


git-svn-id: https://develop.svn.wordpress.org/trunk@36586 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Weston Ruter
2016-02-19 18:40:06 +00:00
parent 29e2274793
commit 03360d143d
23 changed files with 4204 additions and 578 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php
+2 -1
View File
@@ -67,10 +67,11 @@ class WP_Customize_Nav_Menu_Item_Setting extends WP_Customize_Setting {
* Default transport.
*
* @since 4.3.0
* @since 4.5.0 Default changed to 'refresh'
* @access public
* @var string
*/
public $transport = 'postMessage';
public $transport = 'refresh';
/**
* The post ID represented by this setting instance. This is the db_id.
src/wp-includes/customize/class-wp-customize-partial.php
+288
View File
@@ -0,0 +1,288 @@
<?php
/**
* WordPress Customize Partial class
*
* @package WordPress
* @subpackage Customize
* @since 4.5.0
*/
/**
* Customize Partial class.
*
* Representation of a rendered region in the previewed page that gets
* selectively refreshed when an associated setting is changed.
* This class is analogous of WP_Customize_Control.
*
* @since 4.5.0
*/
class WP_Customize_Partial {
/**
* Component.
*
* @since 4.5.0
* @access public
* @var WP_Customize_Selective_Refresh
*/
public $component;
/**
* Unique identifier for the partial.
*
* If the partial is used to display a single setting, this would generally
* be the same as the associated setting's ID.
*
* @since 4.5.0
* @access public
* @var string
*/
public $id;
/**
* Parsed ID.
*
* @since 4.5.0
* @access private
* @var array {
* @type string $base ID base.
* @type array $keys Keys for multidimensional.
* }
*/
protected $id_data = array();
/**
* Type of this partial.
*
* @since 4.5.0
* @access public
* @var string
*/
public $type = 'default';
/**
* The jQuery selector to find the container element for the partial.
*
* @since 4.5.0
* @access public
* @var string
*/
public $selector;
/**
* All settings tied to the partial.
*
* @access public
* @since 4.5.0
* @var WP_Customize_Setting[]
*/
public $settings;
/**
* The ID for the setting that this partial is primarily responsible for rendering.
*
* If not supplied, it will default to the ID of the first setting.
*
* @since 4.5.0
* @access public
* @var string
*/
public $primary_setting;
/**
* Render callback.
*
* @since 4.5.0
* @access public
* @see WP_Customize_Partial::render()
* @var callable Callback is called with one argument, the instance of
* WP_Customize_Partial. The callback can either echo the
* partial or return the partial as a string, or return false if error.
*/
public $render_callback;
/**
* Whether the container element is included in the partial, or if only the contents are rendered.
*
* @since 4.5.0
* @access public
* @var bool
*/
public $container_inclusive = false;
/**
* Whether to refresh the entire preview in case a partial cannot be refreshed.
*
* A partial render is considered a failure if the render_callback returns false.
*
* @since 4.5.0
* @access public
* @var bool
*/
public $fallback_refresh = true;
/**
* Constructor.
*
* Supplied `$args` override class property defaults.
*
* If `$args['settings']` is not defined, use the $id as the setting ID.
*
* @since 4.5.0
* @access public
*
* @param WP_Customize_Selective_Refresh $component Customize Partial Refresh plugin instance.
* @param string $id Control ID.
* @param array $args {
* Optional. Arguments to override class property defaults.
*
* @type array|string $settings All settings IDs tied to the partial. If undefined, `$id` will be used.
* }
*/
public function __construct( WP_Customize_Selective_Refresh $component, $id, $args = array() ) {
$keys = array_keys( get_object_vars( $this ) );
foreach ( $keys as $key ) {
if ( isset( $args[ $key ] ) ) {
$this->$key = $args[ $key ];
}
}
$this->component = $component;
$this->id = $id;
$this->id_data['keys'] = preg_split( '/\[/', str_replace( ']', '', $this->id ) );
$this->id_data['base'] = array_shift( $this->id_data['keys'] );
if ( empty( $this->render_callback ) ) {
$this->render_callback = array( $this, 'render_callback' );
}
// Process settings.
if ( empty( $this->settings ) ) {
$this->settings = array( $id );
} else if ( is_string( $this->settings ) ) {
$this->settings = array( $this->settings );
}
if ( empty( $this->primary_setting ) ) {
$this->primary_setting = current( $this->settings );
}
}
/**
* Retrieves parsed ID data for multidimensional setting.
*
* @since 4.5.0
* @access public
*
* @return array {
* ID data for multidimensional partial.
*
* @type string $base ID base.
* @type array $keys Keys for multidimensional array.
* }
*/
final public function id_data() {
return $this->id_data;
}
/**
* Renders the template partial involving the associated settings.
*
* @since 4.5.0
* @access public
*
* @param array $container_context Optional. Array of context data associated with the target container (placement).
* Default empty array.
* @return string|array|false The rendered partial as a string, raw data array (for client-side JS template),
* or false if no render applied.
*/
final public function render( $container_context = array() ) {
$partial = $this;
$rendered = false;
if ( ! empty( $this->render_callback ) ) {
ob_start();
$return_render = call_user_func( $this->render_callback, $this, $container_context );
$ob_render = ob_get_clean();
if ( null !== $return_render && '' !== $ob_render ) {
_doing_it_wrong( __FUNCTION__, __( 'Partial render must echo the content or return the content string (or array), but not both.' ), '4.5.0' );
}
/*
* Note that the string return takes precedence because the $ob_render may just\
* include PHP warnings or notices.
*/
$rendered = null !== $return_render ? $return_render : $ob_render;
}
/**
* Filters partial rendering.
*
* @since 4.5.0
*
* @param string|array|false $rendered The partial value. Default false.
* @param WP_Customize_Partial $partial WP_Customize_Setting instance.
* @param array $container_context Optional array of context data associated with
* the target container.
*/
$rendered = apply_filters( 'customize_partial_render', $rendered, $partial, $container_context );
/**
* Filters partial rendering for a specific partial.
*
* The dynamic portion of the hook name, `$partial->ID` refers to the partial ID.
*
* @since 4.5.0
*
* @param string|array|false $rendered The partial value. Default false.
* @param WP_Customize_Partial $partial WP_Customize_Setting instance.
* @param array $container_context Optional array of context data associated with
* the target container.
*/
$rendered = apply_filters( "customize_partial_render_{$partial->id}", $rendered, $partial, $container_context );
return $rendered;
}
/**
* Default callback used when invoking WP_Customize_Control::render().
*
* Note that this method may echo the partial *or* return the partial as
* a string or array, but not both. Output buffering is performed when this
* is called. Subclasses can override this with their specific logic, or they
* may provide an 'render_callback' argument to the constructor.
*
* This method may return an HTML string for straight DOM injection, or it
* may return an array for supporting Partial JS subclasses to render by
* applying to client-side templating.
*
* @since 4.5.0
* @access public
*
* @return string|array|false
*/
public function render_callback() {
return false;
}
/**
* Retrieves the data to export to the client via JSON.
*
* @since 4.5.0
* @access public
*
* @return array Array of parameters passed to the JavaScript.
*/
public function json() {
$exports = array(
'settings' => $this->settings,
'primarySetting' => $this->primary_setting,
'selector' => $this->selector,
'type' => $this->type,
'fallbackRefresh' => $this->fallback_refresh,
'containerInclusive' => $this->container_inclusive,
);
return $exports;
}
}
src/wp-includes/customize/class-wp-customize-selective-refresh.php
+437
View File
@@ -0,0 +1,437 @@
<?php
/**
* WordPress Customize Selective Refresh class
*
* @package WordPress
* @subpackage Customize
* @since 4.5.0
*/
/**
* WordPress Customize Selective Refresh class.
*
* @since 4.5.0
*/
class WP_Customize_Selective_Refresh {
/**
* Query var used in requests to render partials.
*
* @since 4.5.0
*/
const RENDER_QUERY_VAR = 'wp_customize_render_partials';
/**
* Customize manager.
*
* @var WP_Customize_Manager
*/
public $manager;
/**
* Registered instances of WP_Customize_Partial.
*
* @since 4.5.0
* @access protected
* @var WP_Customize_Partial[]
*/
protected $partials = array();
/**
* Log of errors triggered when partials are rendered.
*
* @since 4.5.0
* @access private
* @var array
*/
protected $triggered_errors = array();
/**
* Keep track of the current partial being rendered.
*
* @since 4.5.0
* @access private
* @var string
*/
protected $current_partial_id;
/**
* Plugin bootstrap for Partial Refresh functionality.
*
* @since 4.5.0
* @access public
*
* @param WP_Customize_Manager $manager Manager instance.
*/
public function __construct( WP_Customize_Manager $manager ) {
$this->manager = $manager;
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-partial.php' );
add_action( 'customize_preview_init', array( $this, 'init_preview' ) );
}
/**
* Retrieves the registered partials.
*
* @since 4.5.0
* @access public
*
* @return array Partials.
*/
public function partials() {
return $this->partials;
}
/**
* Adds a partial.
*
* @since 4.5.0
* @access public
*
* @param WP_Customize_Partial|string $id Customize Partial object, or Panel ID.
* @param array $args Optional. Partial arguments. Default empty array.
* @return WP_Customize_Partial The instance of the panel that was added.
*/
public function add_partial( $id, $args = array() ) {
if ( $id instanceof WP_Customize_Partial ) {
$partial = $id;
} else {
$class = 'WP_Customize_Partial';
/** This filter (will be) documented in wp-includes/class-wp-customize-manager.php */
$args = apply_filters( 'customize_dynamic_partial_args', $args, $id );
/** This filter (will be) documented in wp-includes/class-wp-customize-manager.php */
$class = apply_filters( 'customize_dynamic_partial_class', $class, $id, $args );
$partial = new $class( $this, $id, $args );
}
$this->partials[ $partial->id ] = $partial;
return $partial;
}
/**
* Retrieves a partial.
*
* @since 4.5.0
* @access public
*
* @param string $id Customize Partial ID.
* @return WP_Customize_Partial|null The partial, if set. Otherwise null.
*/
public function get_partial( $id ) {
if ( isset( $this->partials[ $id ] ) ) {
return $this->partials[ $id ];
} else {
return null;
}
}
/**
* Removes a partial.
*
* @since 4.5.0
* @access public
*
* @param string $id Customize Partial ID.
*/
public function remove_partial( $id ) {
unset( $this->partials[ $id ] );
}
/**
* Initializes the Customizer preview.
*
* @since 4.5.0
* @access public
*/
public function init_preview() {
add_action( 'template_redirect', array( $this, 'handle_render_partials_request' ) );
add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_preview_scripts' ) );
}
/**
* Enqueues preview scripts.
*
* @since 4.5.0
* @access public
*/
public function enqueue_preview_scripts() {
wp_enqueue_script( 'customize-selective-refresh' );
add_action( 'wp_footer', array( $this, 'export_preview_data' ), 1000 );
}
/**
* Exports data in preview after it has finished rendering so that partials can be added at runtime.
*
* @since 4.5.0
* @access public
*/
public function export_preview_data() {
$partials = array();
foreach ( $this->partials() as $partial ) {
$partials[ $partial->id ] = $partial->json();
}
$exports = array(
'partials' => $partials,
'renderQueryVar' => self::RENDER_QUERY_VAR,
'l10n' => array(
'shiftClickToEdit' => __( 'Shift-click to edit this element.' ),
/* translators: %s: message from JS error */
'errorMessageTpl' => __( 'Script error: %s' ),
/* translators: %s: document.write() */
'badDocumentWrite' => sprintf( __( '%s is forbidden' ), 'document.write()' ),
),
);
// Export data to JS.
echo sprintf( '<script>var _customizePartialRefreshExports = %s;</script>', wp_json_encode( $exports ) );
}
/**
* Registers dynamically-created partials.
*
* @since 4.5.0
* @access public
*
* @see WP_Customize_Manager::add_dynamic_settings()
*
* @param array $partial_ids The partial ID to add.
* @return array Added WP_Customize_Partial instances.
*/
public function add_dynamic_partials( $partial_ids ) {
$new_partials = array();
foreach ( $partial_ids as $partial_id ) {
// Skip partials already created.
$partial = $this->get_partial( $partial_id );
if ( $partial ) {
continue;
}
$partial_args = false;
$partial_class = 'WP_Customize_Partial';
/**
* Filters a dynamic partial's constructor arguments.
*
* For a dynamic partial to be registered, this filter must be employed
* to override the default false value with an array of args to pass to
* the WP_Customize_Partial constructor.
*
* @since 4.5.0
*
* @param false|array $partial_args The arguments to the WP_Customize_Partial constructor.
* @param string $partial_id ID for dynamic partial.
*/
$partial_args = apply_filters( 'customize_dynamic_partial_args', $partial_args, $partial_id );
if ( false === $partial_args ) {
continue;
}
/**
* Filters the class used to construct partials.
*
* Allow non-statically created partials to be constructed with custom WP_Customize_Partial subclass.
*
* @since 4.5.0
*
* @param string $partial_class WP_Customize_Partial or a subclass.
* @param string $partial_id ID for dynamic partial.
* @param array $partial_args The arguments to the WP_Customize_Partial constructor.
*/
$partial_class = apply_filters( 'customize_dynamic_partial_class', $partial_class, $partial_id, $partial_args );
$partial = new $partial_class( $this, $partial_id, $partial_args );
$this->add_partial( $partial );
$new_partials[] = $partial;
}
return $new_partials;
}
/**
* Checks whether the request is for rendering partials.
*
* Note that this will not consider whether the request is authorized or valid,
* just that essentially the route is a match.
*
* @since 4.5.0
* @access public
*
* @return bool Whether the request is for rendering partials.
*/
public function is_render_partials_request() {
return ! empty( $_POST[ self::RENDER_QUERY_VAR ] );
}
/**
* Handles PHP errors triggered during rendering the partials.
*
* These errors will be relayed back to the client in the Ajax response.
*
* @since 4.5.0
* @access private
*
* @param int $errno Error number.
* @param string $errstr Error string.
* @param string $errfile Error file.
* @param string $errline Error line.
* @return true Always true.
*/
public function handle_error( $errno, $errstr, $errfile = null, $errline = null ) {
$this->triggered_errors[] = array(
'partial' => $this->current_partial_id,
'error_number' => $errno,
'error_string' => $errstr,
'error_file' => $errfile,
'error_line' => $errline,
);
return true;
}
/**
* Handles the Ajax request to return the rendered partials for the requested placements.
*
* @since 4.5.0
* @access public
*/
public function handle_render_partials_request() {
if ( ! $this->is_render_partials_request() ) {
return;
}
$this->manager->remove_preview_signature();
/*
* Note that is_customize_preview() returning true will entail that the
* user passed the 'customize' capability check and the nonce check, since
* WP_Customize_Manager::setup_theme() is where the previewing flag is set.
*/
if ( ! is_customize_preview() ) {
status_header( 403 );
wp_send_json_error( 'expected_customize_preview' );
} else if ( ! isset( $_POST['partials'] ) ) {
status_header( 400 );
wp_send_json_error( 'missing_partials' );
}
$partials = json_decode( wp_unslash( $_POST['partials'] ), true );
if ( ! is_array( $partials ) ) {
wp_send_json_error( 'malformed_partials' );
}
$this->add_dynamic_partials( array_keys( $partials ) );
/**
* Fires immediately before partials are rendered.
*
* Plugins may do things like call wp_enqueue_scripts() and gather a list of the scripts
* and styles which may get enqueued in the response.
*
* @since 4.5.0
*
* @param WP_Customize_Selective_Refresh $this Selective refresh component.
* @param array $partials Placements' context data for the partials rendered in the request.
* The array is keyed by partial ID, with each item being an array of
* the placements' context data.
*/
do_action( 'customize_render_partials_before', $this, $partials );
set_error_handler( array( $this, 'handle_error' ), error_reporting() );
$contents = array();
foreach ( $partials as $partial_id => $container_contexts ) {
$this->current_partial_id = $partial_id;
if ( ! is_array( $container_contexts ) ) {
wp_send_json_error( 'malformed_container_contexts' );
}
$partial = $this->get_partial( $partial_id );
if ( ! $partial ) {
$contents[ $partial_id ] = null;
continue;
}
$contents[ $partial_id ] = array();
// @todo The array should include not only the contents, but also whether the container is included?
if ( empty( $container_contexts ) ) {
// Since there are no container contexts, render just once.
$contents[ $partial_id ][] = $partial->render( null );
} else {
foreach ( $container_contexts as $container_context ) {
$contents[ $partial_id ][] = $partial->render( $container_context );
}
}
}
$this->current_partial_id = null;
restore_error_handler();
/**
* Fires immediately after partials are rendered.
*
* Plugins may do things like call wp_footer() to scrape scripts output and return them
* via the {@see 'customize_render_partials_response'} filter.
*
* @since 4.5.0
*
* @param WP_Customize_Selective_Refresh $this Selective refresh component.
* @param array $partials Placements' context data for the partials rendered in the request.
* The array is keyed by partial ID, with each item being an array of
* the placements' context data.
*/
do_action( 'customize_render_partials_after', $this, $partials );
$response = array(
'contents' => $contents,
);
if ( defined( 'WP_DEBUG_DISPLAY' ) && WP_DEBUG_DISPLAY ) {
$response['errors'] = $this->triggered_errors;
}
/**
* Filters the response from rendering the partials.
*
* Plugins may use this filter to inject `$scripts` and `$styles`, which are dependencies
* for the partials being rendered. The response data will be available to the client via
* the `render-partials-response` JS event, so the client can then inject the scripts and
* styles into the DOM if they have not already been enqueued there.
*
* If plugins do this, they'll need to take care for any scripts that do `document.write()`
* and make sure that these are not injected, or else to override the function to no-op,
* or else the page will be destroyed.
*
* Plugins should be aware that `$scripts` and `$styles` may eventually be included by
* default in the response.
*
* @since 4.5.0
*
* @param array $response {
* Response.
*
* @type array $contents Associative array mapping a partial ID its corresponding array of contents
* for the containers requested.
* @type array $errors List of errors triggered during rendering of partials, if `WP_DEBUG_DISPLAY`
* is enabled.
* }
* @param WP_Customize_Selective_Refresh $this Selective refresh component.
* @param array $partials Placements' context data for the partials rendered in the request.
* The array is keyed by partial ID, with each item being an array of
* the placements' context data.
*/
$response = apply_filters( 'customize_render_partials_response', $response, $this, $partials );
wp_send_json_success( $response );
}
}