WordPress 4.1.4-scripts
[autoinstalls/wordpress.git] / wp-includes / class-wp-customize-panel.php
1 <?php
2 /**
3  * Customize Panel Class.
4  *
5  * A UI container for sections, managed by the WP_Customize_Manager.
6  *
7  * @package WordPress
8  * @subpackage Customize
9  * @since 4.0.0
10  */
11 class WP_Customize_Panel {
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 4.0.0
37          * @access public
38          * @var WP_Customize_Manager
39          */
40         public $manager;
41
42         /**
43          * Unique identifier.
44          *
45          * @since 4.0.0
46          * @access public
47          * @var string
48          */
49         public $id;
50
51         /**
52          * Priority of the panel, defining the display order of panels and sections.
53          *
54          * @since 4.0.0
55          * @access public
56          * @var integer
57          */
58         public $priority = 160;
59
60         /**
61          * Capability required for the panel.
62          *
63          * @since 4.0.0
64          * @access public
65          * @var string
66          */
67         public $capability = 'edit_theme_options';
68
69         /**
70          * Theme feature support for the panel.
71          *
72          * @since 4.0.0
73          * @access public
74          * @var string|array
75          */
76         public $theme_supports = '';
77
78         /**
79          * Title of the panel to show in UI.
80          *
81          * @since 4.0.0
82          * @access public
83          * @var string
84          */
85         public $title = '';
86
87         /**
88          * Description to show in the UI.
89          *
90          * @since 4.0.0
91          * @access public
92          * @var string
93          */
94         public $description = '';
95
96         /**
97          * Customizer sections for this panel.
98          *
99          * @since 4.0.0
100          * @access public
101          * @var array
102          */
103         public $sections;
104
105         /**
106          * Type of this panel.
107          *
108          * @since 4.1.0
109          * @access public
110          * @var string
111          */
112         public $type = 'default';
113
114         /**
115          * Active callback.
116          *
117          * @since 4.1.0
118          * @access public
119          *
120          * @see WP_Customize_Section::active()
121          *
122          * @var callable Callback is called with one argument, the instance of
123          *               {@see WP_Customize_Section}, and returns bool to indicate
124          *               whether the section is active (such as it relates to the URL
125          *               currently being previewed).
126          */
127         public $active_callback = '';
128
129         /**
130          * Constructor.
131          *
132          * Any supplied $args override class property defaults.
133          *
134          * @since 4.0.0
135          *
136          * @param WP_Customize_Manager $manager Customizer bootstrap instance.
137          * @param string               $id      An specific ID for the panel.
138          * @param array                $args    Panel arguments.
139          */
140         public function __construct( $manager, $id, $args = array() ) {
141                 $keys = array_keys( get_object_vars( $this ) );
142                 foreach ( $keys as $key ) {
143                         if ( isset( $args[ $key ] ) ) {
144                                 $this->$key = $args[ $key ];
145                         }
146                 }
147
148                 $this->manager = $manager;
149                 $this->id = $id;
150                 if ( empty( $this->active_callback ) ) {
151                         $this->active_callback = array( $this, 'active_callback' );
152                 }
153                 self::$instance_count += 1;
154                 $this->instance_number = self::$instance_count;
155
156                 $this->sections = array(); // Users cannot customize the $sections array.
157
158                 return $this;
159         }
160
161         /**
162          * Check whether panel is active to current Customizer preview.
163          *
164          * @since 4.1.0
165          * @access public
166          *
167          * @return bool Whether the panel is active to the current preview.
168          */
169         public final function active() {
170                 $panel = $this;
171                 $active = call_user_func( $this->active_callback, $this );
172
173                 /**
174                  * Filter response of WP_Customize_Panel::active().
175                  *
176                  * @since 4.1.0
177                  *
178                  * @param bool               $active  Whether the Customizer panel is active.
179                  * @param WP_Customize_Panel $panel   {@see WP_Customize_Panel} instance.
180                  */
181                 $active = apply_filters( 'customize_panel_active', $active, $panel );
182
183                 return $active;
184         }
185
186         /**
187          * Default callback used when invoking {@see WP_Customize_Panel::active()}.
188          *
189          * Subclasses can override this with their specific logic, or they may
190          * provide an 'active_callback' argument to the constructor.
191          *
192          * @since 4.1.0
193          * @access public
194          *
195          * @return bool Always true.
196          */
197         public function active_callback() {
198                 return true;
199         }
200
201         /**
202          * Gather the parameters passed to client JavaScript via JSON.
203          *
204          * @since 4.1.0
205          *
206          * @return array The array to be exported to the client as JSON.
207          */
208         public function json() {
209                 $array = wp_array_slice_assoc( (array) $this, array( 'title', 'description', 'priority', 'type' ) );
210                 $array['content'] = $this->get_content();
211                 $array['active'] = $this->active();
212                 $array['instanceNumber'] = $this->instance_number;
213                 return $array;
214         }
215
216         /**
217          * Checks required user capabilities and whether the theme has the
218          * feature support required by the panel.
219          *
220          * @since 4.0.0
221          *
222          * @return bool False if theme doesn't support the panel or the user doesn't have the capability.
223          */
224         public final function check_capabilities() {
225                 if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) {
226                         return false;
227                 }
228
229                 if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) {
230                         return false;
231                 }
232
233                 return true;
234         }
235
236         /**
237          * Get the panel's content template for insertion into the Customizer pane.
238          *
239          * @since 4.1.0
240          *
241          * @return string Content for the panel.
242          */
243         public final function get_content() {
244                 ob_start();
245                 $this->maybe_render();
246                 $template = trim( ob_get_contents() );
247                 ob_end_clean();
248                 return $template;
249         }
250
251         /**
252          * Check capabilities and render the panel.
253          *
254          * @since 4.0.0
255          */
256         public final function maybe_render() {
257                 if ( ! $this->check_capabilities() ) {
258                         return;
259                 }
260
261                 /**
262                  * Fires before rendering a Customizer panel.
263                  *
264                  * @since 4.0.0
265                  *
266                  * @param WP_Customize_Panel $this WP_Customize_Panel instance.
267                  */
268                 do_action( 'customize_render_panel', $this );
269
270                 /**
271                  * Fires before rendering a specific Customizer panel.
272                  *
273                  * The dynamic portion of the hook name, `$this->id`, refers to
274                  * the ID of the specific Customizer panel to be rendered.
275                  *
276                  * @since 4.0.0
277                  */
278                 do_action( "customize_render_panel_{$this->id}" );
279
280                 $this->render();
281         }
282
283         /**
284          * Render the panel container, and then its contents.
285          *
286          * @since 4.0.0
287          * @access protected
288          */
289         protected function render() {
290                 $classes = 'accordion-section control-section control-panel control-panel-' . $this->type;
291                 ?>
292                 <li id="accordion-panel-<?php echo esc_attr( $this->id ); ?>" class="<?php echo esc_attr( $classes ); ?>">
293                         <h3 class="accordion-section-title" tabindex="0">
294                                 <?php echo esc_html( $this->title ); ?>
295                                 <span class="screen-reader-text"><?php _e( 'Press return or enter to open this panel' ); ?></span>
296                         </h3>
297                         <ul class="accordion-sub-container control-panel-content">
298                                 <?php $this->render_content(); ?>
299                         </ul>
300                 </li>
301                 <?php
302         }
303
304         /**
305          * Render the sections that have been added to the panel.
306          *
307          * @since 4.1.0
308          * @access protected
309          */
310         protected function render_content() {
311                 ?>
312                 <li class="panel-meta accordion-section control-section<?php if ( empty( $this->description ) ) { echo ' cannot-expand'; } ?>">
313                         <div class="accordion-section-title" tabindex="0">
314                                 <span class="preview-notice"><?php
315                                         /* translators: %s is the site/panel title in the Customizer */
316                                         echo sprintf( __( 'You are customizing %s' ), '<strong class="panel-title">' . esc_html( $this->title ) . '</strong>' );
317                                 ?></span>
318                         </div>
319                         <?php if ( ! empty( $this->description ) ) : ?>
320                                 <div class="accordion-section-content description">
321                                         <?php echo $this->description; ?>
322                                 </div>
323                         <?php endif; ?>
324                 </li>
325                 <?php
326         }
327 }