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