Wordpress 4.6
[autoinstalls/wordpress.git] / wp-includes / class-wp-customize-section.php
1 <?php
2 /**
3  * WordPress Customize Section classes
4  *
5  * @package WordPress
6  * @subpackage Customize
7  * @since 3.4.0
8  */
9
10 /**
11  * Customize Section class.
12  *
13  * A UI container for controls, managed by the WP_Customize_Manager class.
14  *
15  * @since 3.4.0
16  *
17  * @see WP_Customize_Manager
18  */
19 class WP_Customize_Section {
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 3.4.0
47          * @access public
48          * @var WP_Customize_Manager
49          */
50         public $manager;
51
52         /**
53          * Unique identifier.
54          *
55          * @since 3.4.0
56          * @access public
57          * @var string
58          */
59         public $id;
60
61         /**
62          * Priority of the section which informs load order of sections.
63          *
64          * @since 3.4.0
65          * @access public
66          * @var integer
67          */
68         public $priority = 160;
69
70         /**
71          * Panel in which to show the section, making it a sub-section.
72          *
73          * @since 4.0.0
74          * @access public
75          * @var string
76          */
77         public $panel = '';
78
79         /**
80          * Capability required for the section.
81          *
82          * @since 3.4.0
83          * @access public
84          * @var string
85          */
86         public $capability = 'edit_theme_options';
87
88         /**
89          * Theme feature support for the section.
90          *
91          * @since 3.4.0
92          * @access public
93          * @var string|array
94          */
95         public $theme_supports = '';
96
97         /**
98          * Title of the section to show in UI.
99          *
100          * @since 3.4.0
101          * @access public
102          * @var string
103          */
104         public $title = '';
105
106         /**
107          * Description to show in the UI.
108          *
109          * @since 3.4.0
110          * @access public
111          * @var string
112          */
113         public $description = '';
114
115         /**
116          * Customizer controls for this section.
117          *
118          * @since 3.4.0
119          * @access public
120          * @var array
121          */
122         public $controls;
123
124         /**
125          * Type of this section.
126          *
127          * @since 4.1.0
128          * @access public
129          * @var string
130          */
131         public $type = 'default';
132
133         /**
134          * Active callback.
135          *
136          * @since 4.1.0
137          * @access public
138          *
139          * @see WP_Customize_Section::active()
140          *
141          * @var callable Callback is called with one argument, the instance of
142          *               WP_Customize_Section, and returns bool to indicate whether
143          *               the section is active (such as it relates to the URL currently
144          *               being previewed).
145          */
146         public $active_callback = '';
147
148         /**
149          * Constructor.
150          *
151          * Any supplied $args override class property defaults.
152          *
153          * @since 3.4.0
154          *
155          * @param WP_Customize_Manager $manager Customizer bootstrap instance.
156          * @param string               $id      An specific ID of the section.
157          * @param array                $args    Section arguments.
158          */
159         public function __construct( $manager, $id, $args = array() ) {
160                 $keys = array_keys( get_object_vars( $this ) );
161                 foreach ( $keys as $key ) {
162                         if ( isset( $args[ $key ] ) ) {
163                                 $this->$key = $args[ $key ];
164                         }
165                 }
166
167                 $this->manager = $manager;
168                 $this->id = $id;
169                 if ( empty( $this->active_callback ) ) {
170                         $this->active_callback = array( $this, 'active_callback' );
171                 }
172                 self::$instance_count += 1;
173                 $this->instance_number = self::$instance_count;
174
175                 $this->controls = array(); // Users cannot customize the $controls array.
176         }
177
178         /**
179          * Check whether section is active to current Customizer preview.
180          *
181          * @since 4.1.0
182          * @access public
183          *
184          * @return bool Whether the section is active to the current preview.
185          */
186         final public function active() {
187                 $section = $this;
188                 $active = call_user_func( $this->active_callback, $this );
189
190                 /**
191                  * Filters response of WP_Customize_Section::active().
192                  *
193                  * @since 4.1.0
194                  *
195                  * @param bool                 $active  Whether the Customizer section is active.
196                  * @param WP_Customize_Section $section WP_Customize_Section instance.
197                  */
198                 $active = apply_filters( 'customize_section_active', $active, $section );
199
200                 return $active;
201         }
202
203         /**
204          * Default callback used when invoking WP_Customize_Section::active().
205          *
206          * Subclasses can override this with their specific logic, or they may provide
207          * an 'active_callback' argument to the constructor.
208          *
209          * @since 4.1.0
210          * @access public
211          *
212          * @return true Always true.
213          */
214         public function active_callback() {
215                 return true;
216         }
217
218         /**
219          * Gather the parameters passed to client JavaScript via JSON.
220          *
221          * @since 4.1.0
222          *
223          * @return array The array to be exported to the client as JSON.
224          */
225         public function json() {
226                 $array = wp_array_slice_assoc( (array) $this, array( 'id', 'description', 'priority', 'panel', 'type' ) );
227                 $array['title'] = html_entity_decode( $this->title, ENT_QUOTES, get_bloginfo( 'charset' ) );
228                 $array['content'] = $this->get_content();
229                 $array['active'] = $this->active();
230                 $array['instanceNumber'] = $this->instance_number;
231
232                 if ( $this->panel ) {
233                         /* translators: &#9656; is the unicode right-pointing triangle, and %s is the section title in the Customizer */
234                         $array['customizeAction'] = sprintf( __( 'Customizing &#9656; %s' ), esc_html( $this->manager->get_panel( $this->panel )->title ) );
235                 } else {
236                         $array['customizeAction'] = __( 'Customizing' );
237                 }
238
239                 return $array;
240         }
241
242         /**
243          * Checks required user capabilities and whether the theme has the
244          * feature support required by the section.
245          *
246          * @since 3.4.0
247          *
248          * @return bool False if theme doesn't support the section or user doesn't have the capability.
249          */
250         final public function check_capabilities() {
251                 if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) {
252                         return false;
253                 }
254
255                 if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) {
256                         return false;
257                 }
258
259                 return true;
260         }
261
262         /**
263          * Get the section's content for insertion into the Customizer pane.
264          *
265          * @since 4.1.0
266          *
267          * @return string Contents of the section.
268          */
269         final public function get_content() {
270                 ob_start();
271                 $this->maybe_render();
272                 return trim( ob_get_clean() );
273         }
274
275         /**
276          * Check capabilities and render the section.
277          *
278          * @since 3.4.0
279          */
280         final public function maybe_render() {
281                 if ( ! $this->check_capabilities() ) {
282                         return;
283                 }
284
285                 /**
286                  * Fires before rendering a Customizer section.
287                  *
288                  * @since 3.4.0
289                  *
290                  * @param WP_Customize_Section $this WP_Customize_Section instance.
291                  */
292                 do_action( 'customize_render_section', $this );
293                 /**
294                  * Fires before rendering a specific Customizer section.
295                  *
296                  * The dynamic portion of the hook name, `$this->id`, refers to the ID
297                  * of the specific Customizer section to be rendered.
298                  *
299                  * @since 3.4.0
300                  */
301                 do_action( "customize_render_section_{$this->id}" );
302
303                 $this->render();
304         }
305
306         /**
307          * Render the section UI in a subclass.
308          *
309          * Sections are now rendered in JS by default, see WP_Customize_Section::print_template().
310          *
311          * @since 3.4.0
312          */
313         protected function render() {}
314
315         /**
316          * Render the section's JS template.
317          *
318          * This function is only run for section types that have been registered with
319          * WP_Customize_Manager::register_section_type().
320          *
321          * @since 4.3.0
322          * @access public
323          *
324          * @see WP_Customize_Manager::render_template()
325          */
326         public function print_template() {
327         ?>
328                 <script type="text/html" id="tmpl-customize-section-<?php echo $this->type; ?>">
329                         <?php $this->render_template(); ?>
330                 </script>
331         <?php
332         }
333
334         /**
335          * An Underscore (JS) template for rendering this section.
336          *
337          * Class variables for this section class are available in the `data` JS object;
338          * export custom variables by overriding WP_Customize_Section::json().
339          *
340          * @since 4.3.0
341          * @access protected
342          *
343          * @see WP_Customize_Section::print_template()
344          */
345         protected function render_template() {
346                 ?>
347                 <li id="accordion-section-{{ data.id }}" class="accordion-section control-section control-section-{{ data.type }}">
348                         <h3 class="accordion-section-title" tabindex="0">
349                                 {{ data.title }}
350                                 <span class="screen-reader-text"><?php _e( 'Press return or enter to open this section' ); ?></span>
351                         </h3>
352                         <ul class="accordion-section-content">
353                                 <li class="customize-section-description-container">
354                                         <div class="customize-section-title">
355                                                 <button class="customize-section-back" tabindex="-1">
356                                                         <span class="screen-reader-text"><?php _e( 'Back' ); ?></span>
357                                                 </button>
358                                                 <h3>
359                                                         <span class="customize-action">
360                                                                 {{{ data.customizeAction }}}
361                                                         </span>
362                                                         {{ data.title }}
363                                                 </h3>
364                                         </div>
365                                         <# if ( data.description ) { #>
366                                                 <div class="description customize-section-description">
367                                                         {{{ data.description }}}
368                                                 </div>
369                                         <# } #>
370                                 </li>
371                         </ul>
372                 </li>
373                 <?php
374         }
375 }
376
377 /** WP_Customize_Themes_Section class */
378 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-themes-section.php' );
379
380 /** WP_Customize_Sidebar_Section class */
381 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-sidebar-section.php' );
382
383 /** WP_Customize_Nav_Menu_Section class */
384 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-section.php' );
385
386 /** WP_Customize_New_Menu_Section class */
387 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-new-menu-section.php' );