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