Changeset 27398 for trunk/src/wp-includes/class-wp-customize-manager.php

Timestamp:

03/04/2014 08:20:28 PM (13 years ago)

Author:

nacin

Message:

Update the Customizer API inline docs.

props ericlewis.
fixes #27065.

File:

• trunk/src/wp-includes/class-wp-customize-manager.php (modified) (19 diffs)

trunk/src/wp-includes/class-wp-customize-manager.php

@@ -2 +2 @@
 /**
  * Customize Manager.
+ *
+ * Bootstraps the Customize experience on the server-side.
+ *
+ * Sets up the theme-switching process if a theme other than the active one is
+ * being previewed and customized.
+ *
+ * Serves as a factory for Customize Controls and Settings, and
+ * instantiates default Customize Controls and Settings.
  *
  * @package WordPress
@@ -8 +16 @@
  */
 final class WP_Customize_Manager {
+        /**
+         * An instance of the theme that is being customized.
+         *
+         * @var WP_Theme
+         */
         protected $theme;
+
+        /**
+         * The directory name of the previously active theme (within the theme_root).
+         *
+         * @var string
+         */
         protected $original_stylesheet;
 
+        /**
+         * Whether filters have been set to change the active theme to the theme being
+         * customized.
+         *
+         * @var boolean
+         */
         protected $previewing = false;
 
@@ -21 +46 @@
         protected $customized;
 
+        /**
+         * $_POST values for Customize Settings.
+         *
+         * @var array
+         */
         private $_post_values;
 
@@ -128 +158 @@
                         add_action( 'after_setup_theme', array( $this, 'after_setup_theme' ) );
                 } else {
+                        // If the requested theme is not the active theme and the user doesn't have the
+                        // switch_themes cap, bail.
                         if ( ! current_user_can( 'switch_themes' ) )
                                 $this->wp_die( -1 );
 
-                        // If the theme isn't active, you can't preview it if it is not allowed or has errors.
+                        // If the theme has errors while loading, bail.
                         if ( $this->theme()->errors() )
                                 $this->wp_die( -1 );
 
+                        // If the theme isn't allowed per multisite settings, bail.
                         if ( ! $this->theme()->is_allowed() )
                                 $this->wp_die( -1 );
                 }
 
+                // All good, let's do some internal business to preview the theme.
                 $this->start_previewing_theme();
         }
@@ -155 +189 @@
 
         /**
-         * Start previewing the selected theme.
-         *
-         * Adds filters to change the current theme.
+         * Start previewing the selected theme by adding filters to change the current theme.
          *
          * @since 3.4.0
@@ -301 +333 @@
 
         /**
-         * Decode the $_POST attribute used to override the WP_Customize_Setting values.
+         * Decode the $_POST['customized'] values for a specific Customize Setting.
          *
          * @since 3.4.0
          *
          * @param mixed $setting A WP_Customize_Setting derived object
-         * @return string Sanitized attribute
+         * @return string $post_value Sanitized value
          */
         public function post_value( $setting ) {
@@ -488 +520 @@
 
         /**
-         * Switch the theme and trigger the save action of each setting.
+         * Switch the theme and trigger the save() method on each setting.
          *
          * @since 3.4.0
@@ -523 +555 @@
          * @since 3.4.0
          *
-         * @param string $id A specific ID of the setting. Can be a
-         *                   theme mod or option name.
-         * @param array $args Setting arguments.
+         * @param WP_Customize_Setting|string $id Customize Setting object, or ID.
+         * @param array $args                     Setting arguments; passed to WP_Customize_Setting
+         *                                        constructor.
          */
         public function add_setting( $id, $args = array() ) {
@@ -541 +573 @@
          * @since 3.4.0
          *
-         * @param string $id A specific ID of the setting.
-         * @return object The settings object.
+         * @param string $id Customize Setting ID.
+         * @return WP_Customize_Setting
          */
         public function get_setting( $id ) {
@@ -554 +586 @@
          * @since 3.4.0
          *
-         * @param string $id A specific ID of the setting.
+         * @param string $id Customize Setting ID.
          */
         public function remove_setting( $id ) {
@@ -565 +597 @@
          * @since 3.4.0
          *
-         * @param string $id A specific ID of the section.
-         * @param array $args Section arguments.
+         * @param WP_Customize_Section|string $id   Customize Section object, or Section ID.
+         * @param array                       $args Section arguments.
          */
         public function add_section( $id, $args = array() ) {
@@ -582 +614 @@
          * @since 3.4.0
          *
-         * @param string $id A specific ID of the section.
-         * @return object The section object.
+         * @param string $id Section ID.
+         * @return WP_Customize_Section
          */
         public function get_section( $id ) {
@@ -595 +627 @@
          * @since 3.4.0
          *
-         * @param string $id A specific ID of the section.
+         * @param string $id Section ID.
          */
         public function remove_section( $id ) {
@@ -606 +638 @@
          * @since 3.4.0
          *
-         * @param string $id A specific ID of the control.
-         * @param array $args Setting arguments.
+         * @param WP_Customize_Control|string $id   Customize Control object, or ID.
+         * @param array                       $args Control arguments; passed to WP_Customize_Control
+         *                                          constructor.
          */
         public function add_control( $id, $args = array() ) {
@@ -623 +656 @@
          * @since 3.4.0
          *
-         * @param string $id A specific ID of the control.
-         * @return object The settings object.
+         * @param string $id ID of the control.
+         * @return WP_Customize_Control $control The control object.
          */
         public function get_control( $id ) {
@@ -632 +665 @@
 
         /**
-         * Remove a customize setting.
-         *
-         * @since 3.4.0
-         *
-         * @param string $id A specific ID of the control.
+         * Remove a customize control.
+         *
+         * @since 3.4.0
+         *
+         * @param string $id ID of the control.
          */
         public function remove_control( $id ) {
@@ -663 +696 @@
          * Prepare settings and sections.
          *
+         * For each, check if required related components exist,
+         * whether the user has the necessary capabilities,
+         * and sort by priority.
+         *
          * @since 3.4.0
          */
         public function prepare_controls() {
-                // Prepare controls
-                // Reversing makes uasort sort by time added when conflicts occur.
 
                 $this->controls = array_reverse( $this->controls );
@@ -681 +716 @@
                 $this->controls = $controls;
 
-                // Prepare sections
+                // Prepare sections.
+                // Reversing makes uasort sort by time added when conflicts occur.
                 $this->sections = array_reverse( $this->sections );
                 uasort( $this->sections, array( $this, '_cmp_priority' ) );
@@ -996 +1032 @@
 
 /**
- * Validates a hex color.
+ * Sanitizes a hex color.
  *
  * Returns either '', a 3 or 6 digit hex color (with #), or null.
- * For validating values without a #, see sanitize_hex_color_no_hash().
+ * For sanitizing values without a #, see sanitize_hex_color_no_hash().
  *
  * @since 3.4.0