|
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 } else if ( 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 } |