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