[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

title

Body

[close]

/wp-includes/customize/ -> class-wp-customize-partial.php (source)

   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 array
  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       * @see WP_Customize_Partial::render()
 101       * @var callable Callback is called with one argument, the instance of
 102       *                 WP_Customize_Partial. The callback can either echo the
 103       *                 partial or return the partial as a string, or return false if error.
 104       */
 105      public $render_callback;
 106  
 107      /**
 108       * Whether the container element is included in the partial, or if only the contents are rendered.
 109       *
 110       * @since 4.5.0
 111       * @var bool
 112       */
 113      public $container_inclusive = false;
 114  
 115      /**
 116       * Whether to refresh the entire preview in case a partial cannot be refreshed.
 117       *
 118       * A partial render is considered a failure if the render_callback returns false.
 119       *
 120       * @since 4.5.0
 121       * @var bool
 122       */
 123      public $fallback_refresh = true;
 124  
 125      /**
 126       * Constructor.
 127       *
 128       * Supplied `$args` override class property defaults.
 129       *
 130       * If `$args['settings']` is not defined, use the $id as the setting ID.
 131       *
 132       * @since 4.5.0
 133       *
 134       * @param WP_Customize_Selective_Refresh $component Customize Partial Refresh plugin instance.
 135       * @param string                         $id        Control ID.
 136       * @param array                          $args      {
 137       *     Optional. Arguments to override class property defaults.
 138       *
 139       *     @type array|string $settings All settings IDs tied to the partial. If undefined, `$id` will be used.
 140       * }
 141       */
 142  	public function __construct( WP_Customize_Selective_Refresh $component, $id, $args = array() ) {
 143          $keys = array_keys( get_object_vars( $this ) );
 144          foreach ( $keys as $key ) {
 145              if ( isset( $args[ $key ] ) ) {
 146                  $this->$key = $args[ $key ];
 147              }
 148          }
 149  
 150          $this->component       = $component;
 151          $this->id              = $id;
 152          $this->id_data['keys'] = preg_split( '/\[/', str_replace( ']', '', $this->id ) );
 153          $this->id_data['base'] = array_shift( $this->id_data['keys'] );
 154  
 155          if ( empty( $this->render_callback ) ) {
 156              $this->render_callback = array( $this, 'render_callback' );
 157          }
 158  
 159          // Process settings.
 160          if ( ! isset( $this->settings ) ) {
 161              $this->settings = array( $id );
 162          } elseif ( is_string( $this->settings ) ) {
 163              $this->settings = array( $this->settings );
 164          }
 165  
 166          if ( empty( $this->primary_setting ) ) {
 167              $this->primary_setting = current( $this->settings );
 168          }
 169      }
 170  
 171      /**
 172       * Retrieves parsed ID data for multidimensional setting.
 173       *
 174       * @since 4.5.0
 175       *
 176       * @return array {
 177       *     ID data for multidimensional partial.
 178       *
 179       *     @type string $base ID base.
 180       *     @type array  $keys Keys for multidimensional array.
 181       * }
 182       */
 183  	final public function id_data() {
 184          return $this->id_data;
 185      }
 186  
 187      /**
 188       * Renders the template partial involving the associated settings.
 189       *
 190       * @since 4.5.0
 191       *
 192       * @param array $container_context Optional. Array of context data associated with the target container (placement).
 193       *                                 Default empty array.
 194       * @return string|array|false The rendered partial as a string, raw data array (for client-side JS template),
 195       *                            or false if no render applied.
 196       */
 197  	final public function render( $container_context = array() ) {
 198          $partial  = $this;
 199          $rendered = false;
 200  
 201          if ( ! empty( $this->render_callback ) ) {
 202              ob_start();
 203              $return_render = call_user_func( $this->render_callback, $this, $container_context );
 204              $ob_render     = ob_get_clean();
 205  
 206              if ( null !== $return_render && '' !== $ob_render ) {
 207                  _doing_it_wrong( __FUNCTION__, __( 'Partial render must echo the content or return the content string (or array), but not both.' ), '4.5.0' );
 208              }
 209  
 210              /*
 211               * Note that the string return takes precedence because the $ob_render may just\
 212               * include PHP warnings or notices.
 213               */
 214              $rendered = null !== $return_render ? $return_render : $ob_render;
 215          }
 216  
 217          /**
 218           * Filters partial rendering.
 219           *
 220           * @since 4.5.0
 221           *
 222           * @param string|array|false   $rendered          The partial value. Default false.
 223           * @param WP_Customize_Partial $partial           WP_Customize_Setting instance.
 224           * @param array                $container_context Optional array of context data associated with
 225           *                                                the target container.
 226           */
 227          $rendered = apply_filters( 'customize_partial_render', $rendered, $partial, $container_context );
 228  
 229          /**
 230           * Filters partial rendering for a specific partial.
 231           *
 232           * The dynamic portion of the hook name, `$partial->ID` refers to the partial ID.
 233           *
 234           * @since 4.5.0
 235           *
 236           * @param string|array|false   $rendered          The partial value. Default false.
 237           * @param WP_Customize_Partial $partial           WP_Customize_Setting instance.
 238           * @param array                $container_context Optional array of context data associated with
 239           *                                                the target container.
 240           */
 241          $rendered = apply_filters( "customize_partial_render_{$partial->id}", $rendered, $partial, $container_context );
 242  
 243          return $rendered;
 244      }
 245  
 246      /**
 247       * Default callback used when invoking WP_Customize_Control::render().
 248       *
 249       * Note that this method may echo the partial *or* return the partial as
 250       * a string or array, but not both. Output buffering is performed when this
 251       * is called. Subclasses can override this with their specific logic, or they
 252       * may provide an 'render_callback' argument to the constructor.
 253       *
 254       * This method may return an HTML string for straight DOM injection, or it
 255       * may return an array for supporting Partial JS subclasses to render by
 256       * applying to client-side templating.
 257       *
 258       * @since 4.5.0
 259       *
 260       * @param WP_Customize_Partial $partial Partial.
 261       * @param array                $context Context.
 262       * @return string|array|false
 263       */
 264  	public function render_callback( WP_Customize_Partial $partial, $context = array() ) {
 265          unset( $partial, $context );
 266          return false;
 267      }
 268  
 269      /**
 270       * Retrieves the data to export to the client via JSON.
 271       *
 272       * @since 4.5.0
 273       *
 274       * @return array Array of parameters passed to the JavaScript.
 275       */
 276  	public function json() {
 277          $exports = array(
 278              'settings'           => $this->settings,
 279              'primarySetting'     => $this->primary_setting,
 280              'selector'           => $this->selector,
 281              'type'               => $this->type,
 282              'fallbackRefresh'    => $this->fallback_refresh,
 283              'containerInclusive' => $this->container_inclusive,
 284          );
 285          return $exports;
 286      }
 287  
 288      /**
 289       * Checks if the user can refresh this partial.
 290       *
 291       * Returns false if the user cannot manipulate one of the associated settings,
 292       * or if one of the associated settings does not exist.
 293       *
 294       * @since 4.5.0
 295       *
 296       * @return bool False if user can't edit one of the related settings,
 297       *                    or if one of the associated settings does not exist.
 298       */
 299  	final public function check_capabilities() {
 300          if ( ! empty( $this->capability ) && ! current_user_can( $this->capability ) ) {
 301              return false;
 302          }
 303          foreach ( $this->settings as $setting_id ) {
 304              $setting = $this->component->manager->get_setting( $setting_id );
 305              if ( ! $setting || ! $setting->check_capabilities() ) {
 306                  return false;
 307              }
 308          }
 309          return true;
 310      }
 311  }


Generated: Tue Oct 22 08:20:01 2019 Cross-referenced by PHPXref 0.7