class-wp-customize-partial.php (10542B)
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 }