[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Customize API: WP_Customize_Partial class
   4   *
   5   * @package WordPress
   6   * @subpackage Customize
   7   * @since 4.5.0
   8   */
   9  
  10  /**
  11   * Core Customizer class for implementing selective refresh partials.
  12   *
  13   * Representation of a rendered region in the previewed page that gets
  14   * selectively refreshed when an associated setting is changed.
  15   * This class is analogous of WP_Customize_Control.
  16   *
  17   * @since 4.5.0
  18   */
  19  class WP_Customize_Partial {
  20  
  21      /**
  22       * Component.
  23       *
  24       * @since 4.5.0
  25       * @var WP_Customize_Selective_Refresh
  26       */
  27      public $component;
  28  
  29      /**
  30       * Unique identifier for the partial.
  31       *
  32       * If the partial is used to display a single setting, this would generally
  33       * be the same as the associated setting's ID.
  34       *
  35       * @since 4.5.0
  36       * @var string
  37       */
  38      public $id;
  39  
  40      /**
  41       * Parsed ID.
  42       *
  43       * @since 4.5.0
  44       * @var array {
  45       *     @type string $base ID base.
  46       *     @type array  $keys Keys for multidimensional.
  47       * }
  48       */
  49      protected $id_data = array();
  50  
  51      /**
  52       * Type of this partial.
  53       *
  54       * @since 4.5.0
  55       * @var string
  56       */
  57      public $type = 'default';
  58  
  59      /**
  60       * The jQuery selector to find the container element for the partial.
  61       *
  62       * @since 4.5.0
  63       * @var string
  64       */
  65      public $selector;
  66  
  67      /**
  68       * IDs for settings tied to the partial.
  69       *
  70       * @since 4.5.0
  71       * @var string[]
  72       */
  73      public $settings;
  74  
  75      /**
  76       * The ID for the setting that this partial is primarily responsible for rendering.
  77       *
  78       * If not supplied, it will default to the ID of the first setting.
  79       *
  80       * @since 4.5.0
  81       * @var string
  82       */
  83      public $primary_setting;
  84  
  85      /**
  86       * Capability required to edit this partial.
  87       *
  88       * Normally this is empty and the capability is derived from the capabilities
  89       * of the associated `$settings`.
  90       *
  91       * @since 4.5.0
  92       * @var string
  93       */
  94      public $capability;
  95  
  96      /**
  97       * Render callback.
  98       *
  99       * @since 4.5.0
 100       *
 101       * @see WP_Customize_Partial::render()
 102       * @var callable Callback is called with one argument, the instance of
 103       *               WP_Customize_Partial. The callback can either echo the
 104       *               partial or return the partial as a string, or return false if error.
 105       */
 106      public $render_callback;
 107  
 108      /**
 109       * Whether the container element is included in the partial, or if only the contents are rendered.
 110       *
 111       * @since 4.5.0
 112       * @var bool
 113       */
 114      public $container_inclusive = false;
 115  
 116      /**
 117       * Whether to refresh the entire preview in case a partial cannot be refreshed.
 118       *
 119       * A partial render is considered a failure if the render_callback returns false.
 120       *
 121       * @since 4.5.0
 122       * @var bool
 123       */
 124      public $fallback_refresh = true;
 125  
 126      /**
 127       * Constructor.
 128       *
 129       * Supplied `$args` override class property defaults.
 130       *
 131       * If `$args['settings']` is not defined, use the $id as the setting ID.
 132       *
 133       * @since 4.5.0
 134       *
 135       * @param WP_Customize_Selective_Refresh $component Customize Partial Refresh plugin instance.
 136       * @param string                         $id        Control ID.
 137       * @param array                          $args {
 138       *     Optional. Array of properties for the new Partials object. Default empty array.
 139       *
 140       *     @type string   $type                  Type of the partial to be created.
 141       *     @type string   $selector              The jQuery selector to find the container element for the partial, that is,
 142       *                                           a partial's placement.
 143       *     @type string[] $settings              IDs for settings tied to the partial. If undefined, `$id` will be used.
 144       *     @type string   $primary_setting       The ID for the setting that this partial is primarily responsible for
 145       *                                           rendering. If not supplied, it will default to the ID of the first setting.
 146       *     @type string   $capability            Capability required to edit this partial.
 147       *                                           Normally this is empty and the capability is derived from the capabilities
 148       *                                           of the associated `$settings`.
 149       *     @type callable $render_callback       Render callback.
 150       *                                           Callback is called with one argument, the instance of WP_Customize_Partial.
 151       *                                           The callback can either echo the partial or return the partial as a string,
 152       *                                           or return false if error.
 153       *     @type bool     $container_inclusive   Whether the container element is included in the partial, or if only
 154       *                                           the contents are rendered.
 155       *     @type bool     $fallback_refresh      Whether to refresh the entire preview in case a partial cannot be refreshed.
 156       *                                           A partial render is considered a failure if the render_callback returns
 157       *                                           false.
 158       * }
 159       */
 160  	public function __construct( WP_Customize_Selective_Refresh $component, $id, $args = array() ) {
 161          $keys = array_keys( get_object_vars( $this ) );
 162          foreach ( $keys as $key ) {
 163              if ( isset( $args[ $key ] ) ) {
 164                  $this->$key = $args[ $key ];
 165              }
 166          }
 167  
 168          $this->component       = $component;
 169          $this->id              = $id;
 170          $this->id_data['keys'] = preg_split( '/\[/', str_replace( ']', '', $this->id ) );
 171          $this->id_data['base'] = array_shift( $this->id_data['keys'] );
 172  
 173          if ( empty( $this->render_callback ) ) {
 174              $this->render_callback = array( $this, 'render_callback' );
 175          }
 176  
 177          // Process settings.
 178          if ( ! isset( $this->settings ) ) {
 179              $this->settings = array( $id );
 180          } elseif ( is_string( $this->settings ) ) {
 181              $this->settings = array( $this->settings );
 182          }
 183  
 184          if ( empty( $this->primary_setting ) ) {
 185              $this->primary_setting = current( $this->settings );
 186          }
 187      }
 188  
 189      /**
 190       * Retrieves parsed ID data for multidimensional setting.
 191       *
 192       * @since 4.5.0
 193       *
 194       * @return array {
 195       *     ID data for multidimensional partial.
 196       *
 197       *     @type string $base ID base.
 198       *     @type array  $keys Keys for multidimensional array.
 199       * }
 200       */
 201  	final public function id_data() {
 202          return $this->id_data;
 203      }
 204  
 205      /**
 206       * Renders the template partial involving the associated settings.
 207       *
 208       * @since 4.5.0
 209       *
 210       * @param array $container_context Optional. Array of context data associated with the target container (placement).
 211       *                                 Default empty array.
 212       * @return string|array|false The rendered partial as a string, raw data array (for client-side JS template),
 213       *                            or false if no render applied.
 214       */
 215  	final public function render( $container_context = array() ) {
 216          $partial  = $this;
 217          $rendered = false;
 218  
 219          if ( ! empty( $this->render_callback ) ) {
 220              ob_start();
 221              $return_render = call_user_func( $this->render_callback, $this, $container_context );
 222              $ob_render     = ob_get_clean();
 223  
 224              if ( null !== $return_render && '' !== $ob_render ) {
 225                  _doing_it_wrong( __FUNCTION__, __( 'Partial render must echo the content or return the content string (or array), but not both.' ), '4.5.0' );
 226              }
 227  
 228              /*
 229               * Note that the string return takes precedence because the $ob_render may just\
 230               * include PHP warnings or notices.
 231               */
 232              $rendered = null !== $return_render ? $return_render : $ob_render;
 233          }
 234  
 235          /**
 236           * Filters partial rendering.
 237           *
 238           * @since 4.5.0
 239           *
 240           * @param string|array|false   $rendered          The partial value. Default false.
 241           * @param WP_Customize_Partial $partial           WP_Customize_Setting instance.
 242           * @param array                $container_context Optional array of context data associated with
 243           *                                                the target container.
 244           */
 245          $rendered = apply_filters( 'customize_partial_render', $rendered, $partial, $container_context );
 246  
 247          /**
 248           * Filters partial rendering for a specific partial.
 249           *
 250           * The dynamic portion of the hook name, `$partial->ID` refers to the partial ID.
 251           *
 252           * @since 4.5.0
 253           *
 254           * @param string|array|false   $rendered          The partial value. Default false.
 255           * @param WP_Customize_Partial $partial           WP_Customize_Setting instance.
 256           * @param array                $container_context Optional array of context data associated with
 257           *                                                the target container.
 258           */
 259          $rendered = apply_filters( "customize_partial_render_{$partial->id}", $rendered, $partial, $container_context );
 260  
 261          return $rendered;
 262      }
 263  
 264      /**
 265       * Default callback used when invoking WP_Customize_Control::render().
 266       *
 267       * Note that this method may echo the partial *or* return the partial as
 268       * a string or array, but not both. Output buffering is performed when this
 269       * is called. Subclasses can override this with their specific logic, or they
 270       * may provide an 'render_callback' argument to the constructor.
 271       *
 272       * This method may return an HTML string for straight DOM injection, or it
 273       * may return an array for supporting Partial JS subclasses to render by
 274       * applying to client-side templating.
 275       *
 276       * @since 4.5.0
 277       *
 278       * @param WP_Customize_Partial $partial Partial.
 279       * @param array                $context Context.
 280       * @return string|array|false
 281       */
 282  	public function render_callback( WP_Customize_Partial $partial, $context = array() ) {
 283          unset( $partial, $context );
 284          return false;
 285      }
 286  
 287      /**
 288       * Retrieves the data to export to the client via JSON.
 289       *
 290       * @since 4.5.0
 291       *
 292       * @return array Array of parameters passed to the JavaScript.
 293       */
 294  	public function json() {
 295          $exports = array(
 296              'settings'           => $this->settings,
 297              'primarySetting'     => $this->primary_setting,
 298              'selector'           => $this->selector,
 299              'type'               => $this->type,
 300              'fallbackRefresh'    => $this->fallback_refresh,
 301              'containerInclusive' => $this->container_inclusive,
 302          );
 303          return $exports;
 304      }
 305  
 306      /**
 307       * Checks if the user can refresh this partial.
 308       *
 309       * Returns false if the user cannot manipulate one of the associated settings,
 310       * or if one of the associated settings does not exist.
 311       *
 312       * @since 4.5.0
 313       *
 314       * @return bool False if user can't edit one of the related settings,
 315       *                    or if one of the associated settings does not exist.
 316       */
 317  	final public function check_capabilities() {
 318          if ( ! empty( $this->capability ) && ! current_user_can( $this->capability ) ) {
 319              return false;
 320          }
 321          foreach ( $this->settings as $setting_id ) {
 322              $setting = $this->component->manager->get_setting( $setting_id );
 323              if ( ! $setting || ! $setting->check_capabilities() ) {
 324                  return false;
 325              }
 326          }
 327          return true;
 328      }
 329  }