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]
20class 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}
331