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