1<?php
2/**
3 * WordPress Customize Panel classes
4 *
5 * @package WordPress
6 * @subpackage Customize
7 * @since 4.0.0
8 */
9
10// Don't load directly.
11if ( ! defined( 'ABSPATH' ) ) {
12 die( '-1' );
13}
14
15/**
16 * Customize Panel class.
17 *
18 * A UI container for sections, managed by the WP_Customize_Manager.
19 *
20 * @since 4.0.0
21 *
22 * @see WP_Customize_Manager
23 */
24#[AllowDynamicProperties]
25class WP_Customize_Panel {
26
27 /**
28 * Incremented with each new class instantiation, then stored in $instance_number.
29 *
30 * Used when sorting two instances whose priorities are equal.
31 *
32 * @since 4.1.0
33 * @var int
34 */
35 protected static $instance_count = 0;
36
37 /**
38 * Order in which this instance was created in relation to other instances.
39 *
40 * @since 4.1.0
41 * @var int
42 */
43 public $instance_number;
44
45 /**
46 * WP_Customize_Manager instance.
47 *
48 * @since 4.0.0
49 * @var WP_Customize_Manager
50 */
51 public $manager;
52
53 /**
54 * Unique identifier.
55 *
56 * @since 4.0.0
57 * @var string
58 */
59 public $id;
60
61 /**
62 * Priority of the panel, defining the display order of panels and sections.
63 *
64 * @since 4.0.0
65 * @var int
66 */
67 public $priority = 160;
68
69 /**
70 * Capability required for the panel.
71 *
72 * @since 4.0.0
73 * @var string
74 */
75 public $capability = 'edit_theme_options';
76
77 /**
78 * Theme features required to support the panel.
79 *
80 * @since 4.0.0
81 * @var mixed[]
82 */
83 public $theme_supports = '';
84
85 /**
86 * Title of the panel to show in UI.
87 *
88 * @since 4.0.0
89 * @var string
90 */
91 public $title = '';
92
93 /**
94 * Description to show in the UI.
95 *
96 * @since 4.0.0
97 * @var string
98 */
99 public $description = '';
100
101 /**
102 * Auto-expand a section in a panel when the panel is expanded when the panel only has the one section.
103 *
104 * @since 4.7.4
105 * @var bool
106 */
107 public $auto_expand_sole_section = false;
108
109 /**
110 * Customizer sections for this panel.
111 *
112 * @since 4.0.0
113 * @var array
114 */
115 public $sections;
116
117 /**
118 * Type of this panel.
119 *
120 * @since 4.1.0
121 * @var string
122 */
123 public $type = 'default';
124
125 /**
126 * Active callback.
127 *
128 * @since 4.1.0
129 *
130 * @see WP_Customize_Section::active()
131 *
132 * @var callable Callback is called with one argument, the instance of
133 * WP_Customize_Section, and returns bool to indicate whether
134 * the section is active (such as it relates to the URL currently
135 * being previewed).
136 */
137 public $active_callback = '';
138
139 /**
140 * Constructor.
141 *
142 * Any supplied $args override class property defaults.
143 *
144 * @since 4.0.0
145 *
146 * @param WP_Customize_Manager $manager Customizer bootstrap instance.
147 * @param string $id A specific ID for the panel.
148 * @param array $args {
149 * Optional. Array of properties for the new Panel object. Default empty array.
150 *
151 * @type int $priority Priority of the panel, defining the display order
152 * of panels and sections. Default 160.
153 * @type string $capability Capability required for the panel.
154 * Default `edit_theme_options`.
155 * @type mixed[] $theme_supports Theme features required to support the panel.
156 * @type string $title Title of the panel to show in UI.
157 * @type string $description Description to show in the UI.
158 * @type string $type Type of the panel.
159 * @type callable $active_callback Active callback.
160 * }
161 */
162 public function __construct( $manager, $id, $args = array() ) {
163 $keys = array_keys( get_object_vars( $this ) );
164 foreach ( $keys as $key ) {
165 if ( isset( $args[ $key ] ) ) {
166 $this->$key = $args[ $key ];
167 }
168 }
169
170 $this->manager = $manager;
171 $this->id = $id;
172 if ( empty( $this->active_callback ) ) {
173 $this->active_callback = array( $this, 'active_callback' );
174 }
175 self::$instance_count += 1;
176 $this->instance_number = self::$instance_count;
177
178 $this->sections = array(); // Users cannot customize the $sections array.
179 }
180
181 /**
182 * Check whether panel is active to current Customizer preview.
183 *
184 * @since 4.1.0
185 *
186 * @return bool Whether the panel is active to the current preview.
187 */
188 final public function active() {
189 $panel = $this;
190 $active = call_user_func( $this->active_callback, $this );
191
192 /**
193 * Filters response of WP_Customize_Panel::active().
194 *
195 * @since 4.1.0
196 *
197 * @param bool $active Whether the Customizer panel is active.
198 * @param WP_Customize_Panel $panel WP_Customize_Panel instance.
199 */
200 $active = apply_filters( 'customize_panel_active', $active, $panel );
201
202 return $active;
203 }
204
205 /**
206 * Default callback used when invoking WP_Customize_Panel::active().
207 *
208 * Subclasses can override this with their specific logic, or they may
209 * provide an 'active_callback' argument to the constructor.
210 *
211 * @since 4.1.0
212 *
213 * @return bool Always true.
214 */
215 public function active_callback() {
216 return true;
217 }
218
219 /**
220 * Gather the parameters passed to client JavaScript via JSON.
221 *
222 * @since 4.1.0
223 *
224 * @return array The array to be exported to the client as JSON.
225 */
226 public function json() {
227 $array = wp_array_slice_assoc( (array) $this, array( 'id', 'description', 'priority', 'type' ) );
228 $array['title'] = html_entity_decode( $this->title, ENT_QUOTES, get_bloginfo( 'charset' ) );
229 $array['content'] = $this->get_content();
230 $array['active'] = $this->active();
231 $array['instanceNumber'] = $this->instance_number;
232 $array['autoExpandSoleSection'] = $this->auto_expand_sole_section;
233 return $array;
234 }
235
236 /**
237 * Checks required user capabilities and whether the theme has the
238 * feature support required by the panel.
239 *
240 * @since 4.0.0
241 * @since 5.9.0 Method was marked non-final.
242 *
243 * @return bool False if theme doesn't support the panel or the user doesn't have the capability.
244 */
245 public function check_capabilities() {
246 if ( $this->capability && ! current_user_can( $this->capability ) ) {
247 return false;
248 }
249
250 if ( $this->theme_supports && ! current_theme_supports( ...(array) $this->theme_supports ) ) {
251 return false;
252 }
253
254 return true;
255 }
256
257 /**
258 * Get the panel's content template for insertion into the Customizer pane.
259 *
260 * @since 4.1.0
261 *
262 * @return string Content for the panel.
263 */
264 final public function get_content() {
265 ob_start();
266 $this->maybe_render();
267 return trim( ob_get_clean() );
268 }
269
270 /**
271 * Check capabilities and render the panel.
272 *
273 * @since 4.0.0
274 */
275 final public function maybe_render() {
276 if ( ! $this->check_capabilities() ) {
277 return;
278 }
279
280 /**
281 * Fires before rendering a Customizer panel.
282 *
283 * @since 4.0.0
284 *
285 * @param WP_Customize_Panel $panel WP_Customize_Panel instance.
286 */
287 do_action( 'customize_render_panel', $this );
288
289 /**
290 * Fires before rendering a specific Customizer panel.
291 *
292 * The dynamic portion of the hook name, `$this->id`, refers to
293 * the ID of the specific Customizer panel to be rendered.
294 *
295 * @since 4.0.0
296 */
297 do_action( "customize_render_panel_{$this->id}" );
298
299 $this->render();
300 }
301
302 /**
303 * Render the panel container, and then its contents (via `this->render_content()`) in a subclass.
304 *
305 * Panel containers are now rendered in JS by default, see WP_Customize_Panel::print_template().
306 *
307 * @since 4.0.0
308 */
309 protected function render() {}
310
311 /**
312 * Render the panel UI in a subclass.
313 *
314 * Panel contents are now rendered in JS by default, see WP_Customize_Panel::print_template().
315 *
316 * @since 4.1.0
317 */
318 protected function render_content() {}
319
320 /**
321 * Render the panel's JS templates.
322 *
323 * This function is only run for panel types that have been registered with
324 * WP_Customize_Manager::register_panel_type().
325 *
326 * @since 4.3.0
327 *
328 * @see WP_Customize_Manager::register_panel_type()
329 */
330 public function print_template() {
331 ?>
332 <script type="text/html" id="tmpl-customize-panel-<?php echo esc_attr( $this->type ); ?>-content">
333 <?php $this->content_template(); ?>
334 </script>
335 <script type="text/html" id="tmpl-customize-panel-<?php echo esc_attr( $this->type ); ?>">
336 <?php $this->render_template(); ?>
337 </script>
338 <?php
339 }
340
341 /**
342 * An Underscore (JS) template for rendering this panel's container.
343 *
344 * Class variables for this panel class are available in the `data` JS object;
345 * export custom variables by overriding WP_Customize_Panel::json().
346 *
347 * @see WP_Customize_Panel::print_template()
348 *
349 * @since 4.3.0
350 */
351 protected function render_template() {
352 ?>
353 <li id="accordion-panel-{{ data.id }}" class="accordion-section control-section control-panel control-panel-{{ data.type }}">
354 <h3 class="accordion-section-title">
355 <button type="button" class="accordion-trigger" aria-expanded="false" aria-controls="{{ data.id }}-content">
356 {{ data.title }}
357 </button>
358 </h3>
359 <ul class="accordion-sub-container control-panel-content" id="{{ data.id }}-content"></ul>
360 </li>
361 <?php
362 }
363
364 /**
365 * An Underscore (JS) template for this panel's content (but not its container).
366 *
367 * Class variables for this panel class are available in the `data` JS object;
368 * export custom variables by overriding WP_Customize_Panel::json().
369 *
370 * @see WP_Customize_Panel::print_template()
371 *
372 * @since 4.3.0
373 */
374 protected function content_template() {
375 ?>
376 <li class="panel-meta customize-info accordion-section <# if ( ! data.description ) { #> cannot-expand<# } #>">
377 <button class="customize-panel-back" tabindex="-1"><span class="screen-reader-text">
378 <?php
379 /* translators: Hidden accessibility text. */
380 _e( 'Back' );
381 ?>
382 </span></button>
383 <div class="accordion-section-title">
384 <span class="preview-notice">
385 <?php
386 /* translators: %s: The site/panel title in the Customizer. */
387 printf( __( 'You are customizing %s' ), '<strong class="panel-title">{{ data.title }}</strong>' );
388 ?>
389 </span>
390 <# if ( data.description ) { #>
391 <button type="button" class="customize-help-toggle dashicons dashicons-editor-help" aria-expanded="false"><span class="screen-reader-text">
392 <?php
393 /* translators: Hidden accessibility text. */
394 _e( 'Help' );
395 ?>
396 </span></button>
397 <# } #>
398 </div>
399 <# if ( data.description ) { #>
400 <div class="description customize-panel-description">
401 {{{ data.description }}}
402 </div>
403 <# } #>
404
405 <div class="customize-control-notifications-container"></div>
406 </li>
407 <?php
408 }
409}
410
411/** WP_Customize_Nav_Menus_Panel class */
412require_once ABSPATH . WPINC . '/customize/class-wp-customize-nav-menus-panel.php';
413