WordPress 4.1
[autoinstalls/wordpress.git] / wp-includes / class-wp-customize-section.php
1 <?php
2 /**
3  * Customize Section Class.
4  *
5  * A UI container for controls, managed by the WP_Customize_Manager.
6  *
7  * @package WordPress
8  * @subpackage Customize
9  * @since 3.4.0
10  */
11 class WP_Customize_Section {
12
13         /**
14          * Incremented with each new class instantiation, then stored in $instance_number.
15          *
16          * Used when sorting two instances whose priorities are equal.
17          *
18          * @since 4.1.0
19          * @access protected
20          * @var int
21          */
22         protected static $instance_count = 0;
23
24         /**
25          * Order in which this instance was created in relation to other instances.
26          *
27          * @since 4.1.0
28          * @access public
29          * @var int
30          */
31         public $instance_number;
32
33         /**
34          * WP_Customize_Manager instance.
35          *
36          * @since 3.4.0
37          * @access public
38          * @var WP_Customize_Manager
39          */
40         public $manager;
41
42         /**
43          * Unique identifier.
44          *
45          * @since 3.4.0
46          * @access public
47          * @var string
48          */
49         public $id;
50
51         /**
52          * Priority of the section which informs load order of sections.
53          *
54          * @since 3.4.0
55          * @access public
56          * @var integer
57          */
58         public $priority = 160;
59
60         /**
61          * Panel in which to show the section, making it a sub-section.
62          *
63          * @since 4.0.0
64          * @access public
65          * @var string
66          */
67         public $panel = '';
68
69         /**
70          * Capability required for the section.
71          *
72          * @since 3.4.0
73          * @access public
74          * @var string
75          */
76         public $capability = 'edit_theme_options';
77
78         /**
79          * Theme feature support for the section.
80          *
81          * @since 3.4.0
82          * @access public
83          * @var string|array
84          */
85         public $theme_supports = '';
86
87         /**
88          * Title of the section to show in UI.
89          *
90          * @since 3.4.0
91          * @access public
92          * @var string
93          */
94         public $title = '';
95
96         /**
97          * Description to show in the UI.
98          *
99          * @since 3.4.0
100          * @access public
101          * @var string
102          */
103         public $description = '';
104
105         /**
106          * Customizer controls for this section.
107          *
108          * @since 3.4.0
109          * @access public
110          * @var array
111          */
112         public $controls;
113
114         /**
115          * Type of this section.
116          *
117          * @since 4.1.0
118          * @access public
119          * @var string
120          */
121         public $type = 'default';
122
123         /**
124          * Active callback.
125          *
126          * @since 4.1.0
127          * @access public
128          *
129          * @see WP_Customize_Section::active()
130          *
131          * @var callable Callback is called with one argument, the instance of
132          *               {@see WP_Customize_Section}, and returns bool to indicate
133          *               whether the section is active (such as it relates to the URL
134          *               currently being previewed).
135          */
136         public $active_callback = '';
137
138         /**
139          * Constructor.
140          *
141          * Any supplied $args override class property defaults.
142          *
143          * @since 3.4.0
144          *
145          * @param WP_Customize_Manager $manager Customizer bootstrap instance.
146          * @param string               $id      An specific ID of the section.
147          * @param array                $args    Section arguments.
148          */
149         public function __construct( $manager, $id, $args = array() ) {
150                 $keys = array_keys( get_object_vars( $this ) );
151                 foreach ( $keys as $key ) {
152                         if ( isset( $args[ $key ] ) ) {
153                                 $this->$key = $args[ $key ];
154                         }
155                 }
156
157                 $this->manager = $manager;
158                 $this->id = $id;
159                 if ( empty( $this->active_callback ) ) {
160                         $this->active_callback = array( $this, 'active_callback' );
161                 }
162                 self::$instance_count += 1;
163                 $this->instance_number = self::$instance_count;
164
165                 $this->controls = array(); // Users cannot customize the $controls array.
166
167                 return $this;
168         }
169
170         /**
171          * Check whether section is active to current Customizer preview.
172          *
173          * @since 4.1.0
174          * @access public
175          *
176          * @return bool Whether the section is active to the current preview.
177          */
178         public final function active() {
179                 $section = $this;
180                 $active = call_user_func( $this->active_callback, $this );
181
182                 /**
183                  * Filter response of {@see WP_Customize_Section::active()}.
184                  *
185                  * @since 4.1.0
186                  *
187                  * @param bool                 $active  Whether the Customizer section is active.
188                  * @param WP_Customize_Section $section {@see WP_Customize_Section} instance.
189                  */
190                 $active = apply_filters( 'customize_section_active', $active, $section );
191
192                 return $active;
193         }
194
195         /**
196          * Default callback used when invoking {@see WP_Customize_Section::active()}.
197          *
198          * Subclasses can override this with their specific logic, or they may provide
199          * an 'active_callback' argument to the constructor.
200          *
201          * @since 4.1.0
202          * @access public
203          *
204          * @return bool Always true.
205          */
206         public function active_callback() {
207                 return true;
208         }
209
210         /**
211          * Gather the parameters passed to client JavaScript via JSON.
212          *
213          * @since 4.1.0
214          *
215          * @return array The array to be exported to the client as JSON.
216          */
217         public function json() {
218                 $array = wp_array_slice_assoc( (array) $this, array( 'title', 'description', 'priority', 'panel', 'type' ) );
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 section.
228          *
229          * @since 3.4.0
230          *
231          * @return bool False if theme doesn't support the section or user doesn't have the capability.
232          */
233         public final 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 section's content template for insertion into the Customizer pane.
247          *
248          * @since 4.1.0
249          *
250          * @return string Contents of the section.
251          */
252         public final function get_content() {
253                 ob_start();
254                 $this->maybe_render();
255                 $template = trim( ob_get_contents() );
256                 ob_end_clean();
257                 return $template;
258         }
259
260         /**
261          * Check capabilities and render the section.
262          *
263          * @since 3.4.0
264          */
265         public final function maybe_render() {
266                 if ( ! $this->check_capabilities() ) {
267                         return;
268                 }
269
270                 /**
271                  * Fires before rendering a Customizer section.
272                  *
273                  * @since 3.4.0
274                  *
275                  * @param WP_Customize_Section $this WP_Customize_Section instance.
276                  */
277                 do_action( 'customize_render_section', $this );
278                 /**
279                  * Fires before rendering a specific Customizer section.
280                  *
281                  * The dynamic portion of the hook name, `$this->id`, refers to the ID
282                  * of the specific Customizer section to be rendered.
283                  *
284                  * @since 3.4.0
285                  */
286                 do_action( "customize_render_section_{$this->id}" );
287
288                 $this->render();
289         }
290
291         /**
292          * Render the section, and the controls that have been added to it.
293          *
294          * @since 3.4.0
295          */
296         protected function render() {
297                 $classes = 'accordion-section control-section control-section-' . $this->type;
298                 ?>
299                 <li id="accordion-section-<?php echo esc_attr( $this->id ); ?>" class="<?php echo esc_attr( $classes ); ?>">
300                         <h3 class="accordion-section-title" tabindex="0">
301                                 <?php echo esc_html( $this->title ); ?>
302                                 <span class="screen-reader-text"><?php _e( 'Press return or enter to expand' ); ?></span>
303                         </h3>
304                         <ul class="accordion-section-content">
305                                 <?php if ( ! empty( $this->description ) ) : ?>
306                                         <li class="customize-section-description-container">
307                                                 <p class="description customize-section-description"><?php echo $this->description; ?></p>
308                                         </li>
309                                 <?php endif; ?>
310                         </ul>
311                 </li>
312                 <?php
313         }
314 }
315
316 /**
317  * Customizer section representing widget area (sidebar).
318  *
319  * @package WordPress
320  * @subpackage Customize
321  *
322  * @since 4.1.0
323  *
324  * @see WP_Customize_Section
325  */
326 class WP_Customize_Sidebar_Section extends WP_Customize_Section {
327
328         /**
329          * Type of this section.
330          *
331          * @since 4.1.0
332          * @access public
333          * @var string
334          */
335         public $type = 'sidebar';
336
337         /**
338          * Unique identifier.
339          *
340          * @since 4.1.0
341          * @access public
342          * @var string
343          */
344         public $sidebar_id;
345
346         /**
347          * Gather the parameters passed to client JavaScript via JSON.
348          *
349          * @since 4.1.0
350          *
351          * @return array The array to be exported to the client as JSON.
352          */
353         public function json() {
354                 $json = parent::json();
355                 $json['sidebarId'] = $this->sidebar_id;
356                 return $json;
357         }
358
359         /**
360          * Whether the current sidebar is rendered on the page.
361          *
362          * @since 4.1.0
363          * @access public
364          *
365          * @return bool Whether sidebar is rendered.
366          */
367         public function active_callback() {
368                 return $this->manager->widgets->is_sidebar_rendered( $this->sidebar_id );
369         }
370 }