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