WordPress.org
Get WordPress

Make WordPress Core

Changeset 27398


Ignore:
Timestamp:
03/04/2014 08:20:28 PM (11 years ago)
Author:
nacin
Message:

Update the Customizer API inline docs.

props ericlewis.
fixes #27065.

Location:
trunk/src
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/customize.php

    r26085 r27398  
    11<?php
    22/**
    3  * Customize Controls
     3 * Theme Customize Screen.
    44 *
    55 * @package WordPress
    … …  
    1010define( 'IFRAME_REQUEST', true );
    1111
     12/** Load WordPress Administration Bootstrap */
    1213require_once( dirname( __FILE__ ) . '/admin.php' );
     14
    1315if ( ! current_user_can( 'edit_theme_options' ) )
    1416    wp_die( __( 'Cheatin&#8217; uh?' ) );
    … …  
    200202    ), wp_login_url() );
    201203
     204    // Prepare customizer settings to pass to Javascript.
    202205    $settings = array(
    203206        'theme'    => array(
    … …  
    228231    );
    229232
     233    // Prepare Customize Setting objects to pass to Javascript.
    230234    foreach ( $wp_customize->settings() as $id => $setting ) {
    231235        $settings['settings'][ $id ] = array(
    … …  
    235239    }
    236240
     241    // Prepare Customize Control objects to pass to Javascript.
    237242    foreach ( $wp_customize->controls() as $id => $control ) {
    238243        $control->to_json();

  • trunk/src/wp-includes/class-wp-customize-control.php

    r27369 r27398  
    4040     * @var int
    4141     */
    42     public $priority          = 10;
     42    public $priority = 10;
    4343
    4444    /**
    … …  
    4646     * @var string
    4747     */
    48     public $section           = '';
     48    public $section = '';
    4949
    5050    /**
    … …  
    5252     * @var string
    5353     */
    54     public $label             = '';
     54    public $label = '';
    5555
    5656    /**
    … …  
    6060     * @var array
    6161     */
    62     public $choices           = array();
     62    public $choices = array();
    6363
    6464    /**
    … …  
    7777    /**
    7878     * Constructor.
     79     *
     80     * Supplied $args override class property defaults.
    7981     *
    8082     * If $args['settings'] is not defined, use the $id as the setting ID.
    … …  
    9597        $this->manager = $manager;
    9698        $this->id = $id;
    97 
    9899
    99100        // Process settings.
    … …  
    186187
    187188    /**
    188      * Render the control. Renders the control wrapper, then calls $this->render_content().
     189     * Renders the control wrapper and calls $this->render_content() for the internals.
    189190     *
    190191     * @since 3.4.0
    … …  
    200201
    201202    /**
    202      * Get the data link parameter for a setting.
     203     * Get the data link attribute for a setting.
    203204     *
    204205     * @since 3.4.0
    … …  
    215216
    216217    /**
    217      * Render the data link parameter for a setting
     218     * Render the data link attribute for the control's input element.
    218219     *
    219220     * @since 3.4.0
    … …  
    229230     * Render the control's content.
    230231     *
    231      * Allows the content to be overriden without having to rewrite the wrapper.
     232     * Allows the content to be overriden without having to rewrite the wrapper in $this->render().
     233     *
     234     * Supports basic input types `text`, `checkbox`, `radio`, `select` and `dropdown-pages`.
    232235     *
    233236     * @since 3.4.0
    … …  
    332335     * Constructor.
    333336     *
    334      * If $args['settings'] is not defined, use the $id as the setting ID.
    335      *
    336337     * @since 3.4.0
    337338     * @uses WP_Customize_Control::__construct()
    … …  
    347348
    348349    /**
    349      * Enqueue control related scripts/styles.
     350     * Enqueue scripts/styles for the color picker.
    350351     *
    351352     * @since 3.4.0
    … …  
    467468    /**
    468469     * Constructor.
    469      *
    470      * If $args['settings'] is not defined, use the $id as the setting ID.
    471470     *
    472471     * @since 3.4.0

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

    r24687 r27398  
    22/**
    33 * Customize Manager.
     4 *
     5 * Bootstraps the Customize experience on the server-side.
     6 *
     7 * Sets up the theme-switching process if a theme other than the active one is
     8 * being previewed and customized.
     9 *
     10 * Serves as a factory for Customize Controls and Settings, and
     11 * instantiates default Customize Controls and Settings.
    412 *
    513 * @package WordPress
    … …  
    816 */
    917final class WP_Customize_Manager {
     18    /**
     19     * An instance of the theme that is being customized.
     20     *
     21     * @var WP_Theme
     22     */
    1023    protected $theme;
     24
     25    /**
     26     * The directory name of the previously active theme (within the theme_root).
     27     *
     28     * @var string
     29     */
    1130    protected $original_stylesheet;
    1231
     32    /**
     33     * Whether filters have been set to change the active theme to the theme being
     34     * customized.
     35     *
     36     * @var boolean
     37     */
    1338    protected $previewing = false;
    1439
    … …  
    2146    protected $customized;
    2247
     48    /**
     49     * $_POST values for Customize Settings.
     50     *
     51     * @var array
     52     */
    2353    private $_post_values;
    2454
    … …  
    128158            add_action( 'after_setup_theme', array( $this, 'after_setup_theme' ) );
    129159        } else {
     160            // If the requested theme is not the active theme and the user doesn't have the
     161            // switch_themes cap, bail.
    130162            if ( ! current_user_can( 'switch_themes' ) )
    131163                $this->wp_die( -1 );
    132164
    133             // If the theme isn't active, you can't preview it if it is not allowed or has errors.
     165            // If the theme has errors while loading, bail.
    134166            if ( $this->theme()->errors() )
    135167                $this->wp_die( -1 );
    136168
     169            // If the theme isn't allowed per multisite settings, bail.
    137170            if ( ! $this->theme()->is_allowed() )
    138171                $this->wp_die( -1 );
    139172        }
    140173
     174        // All good, let's do some internal business to preview the theme.
    141175        $this->start_previewing_theme();
    142176    }
    … …  
    155189
    156190    /**
    157      * Start previewing the selected theme.
    158      *
    159      * Adds filters to change the current theme.
     191     * Start previewing the selected theme by adding filters to change the current theme.
    160192     *
    161193     * @since 3.4.0
    … …  
    301333
    302334    /**
    303      * Decode the $_POST attribute used to override the WP_Customize_Setting values.
     335     * Decode the $_POST['customized'] values for a specific Customize Setting.
    304336     *
    305337     * @since 3.4.0
    306338     *
    307339     * @param mixed $setting A WP_Customize_Setting derived object
    308      * @return string Sanitized attribute
     340     * @return string $post_value Sanitized value
    309341     */
    310342    public function post_value( $setting ) {
    … …  
    488520
    489521    /**
    490      * Switch the theme and trigger the save action of each setting.
     522     * Switch the theme and trigger the save() method on each setting.
    491523     *
    492524     * @since 3.4.0
    … …  
    523555     * @since 3.4.0
    524556     *
    525      * @param string $id A specific ID of the setting. Can be a
    526      *                   theme mod or option name.
    527      * @param array $args Setting arguments.
     557     * @param WP_Customize_Setting|string $id Customize Setting object, or ID.
     558     * @param array $args                     Setting arguments; passed to WP_Customize_Setting
     559     *                                        constructor.
    528560     */
    529561    public function add_setting( $id, $args = array() ) {
    … …  
    541573     * @since 3.4.0
    542574     *
    543      * @param string $id A specific ID of the setting.
    544      * @return object The settings object.
     575     * @param string $id Customize Setting ID.
     576     * @return WP_Customize_Setting
    545577     */
    546578    public function get_setting( $id ) {
    … …  
    554586     * @since 3.4.0
    555587     *
    556      * @param string $id A specific ID of the setting.
     588     * @param string $id Customize Setting ID.
    557589     */
    558590    public function remove_setting( $id ) {
    … …  
    565597     * @since 3.4.0
    566598     *
    567      * @param string $id A specific ID of the section.
    568      * @param array $args Section arguments.
     599     * @param WP_Customize_Section|string $id   Customize Section object, or Section ID.
     600     * @param array                       $args Section arguments.
    569601     */
    570602    public function add_section( $id, $args = array() ) {
    … …  
    582614     * @since 3.4.0
    583615     *
    584      * @param string $id A specific ID of the section.
    585      * @return object The section object.
     616     * @param string $id Section ID.
     617     * @return WP_Customize_Section
    586618     */
    587619    public function get_section( $id ) {
    … …  
    595627     * @since 3.4.0
    596628     *
    597      * @param string $id A specific ID of the section.
     629     * @param string $id Section ID.
    598630     */
    599631    public function remove_section( $id ) {
    … …  
    606638     * @since 3.4.0
    607639     *
    608      * @param string $id A specific ID of the control.
    609      * @param array $args Setting arguments.
     640     * @param WP_Customize_Control|string $id   Customize Control object, or ID.
     641     * @param array                       $args Control arguments; passed to WP_Customize_Control
     642     *                                          constructor.
    610643     */
    611644    public function add_control( $id, $args = array() ) {
    … …  
    623656     * @since 3.4.0
    624657     *
    625      * @param string $id A specific ID of the control.
    626      * @return object The settings object.
     658     * @param string $id ID of the control.
     659     * @return WP_Customize_Control $control The control object.
    627660     */
    628661    public function get_control( $id ) {
    … …  
    632665
    633666    /**
    634      * Remove a customize setting.
    635      *
    636      * @since 3.4.0
    637      *
    638      * @param string $id A specific ID of the control.
     667     * Remove a customize control.
     668     *
     669     * @since 3.4.0
     670     *
     671     * @param string $id ID of the control.
    639672     */
    640673    public function remove_control( $id ) {
    … …  
    663696     * Prepare settings and sections.
    664697     *
     698     * For each, check if required related components exist,
     699     * whether the user has the necessary capabilities,
     700     * and sort by priority.
     701     *
    665702     * @since 3.4.0
    666703     */
    667704    public function prepare_controls() {
    668         // Prepare controls
    669         // Reversing makes uasort sort by time added when conflicts occur.
    670705
    671706        $this->controls = array_reverse( $this->controls );
    … …  
    681716        $this->controls = $controls;
    682717
    683         // Prepare sections
     718        // Prepare sections.
     719        // Reversing makes uasort sort by time added when conflicts occur.
    684720        $this->sections = array_reverse( $this->sections );
    685721        uasort( $this->sections, array( $this, '_cmp_priority' ) );
    … …  
    9961032
    9971033/**
    998  * Validates a hex color.
     1034 * Sanitizes a hex color.
    9991035 *
    10001036 * Returns either '', a 3 or 6 digit hex color (with #), or null.
    1001  * For validating values without a #, see sanitize_hex_color_no_hash().
     1037 * For sanitizing values without a #, see sanitize_hex_color_no_hash().
    10021038 *
    10031039 * @since 3.4.0

  • trunk/src/wp-includes/class-wp-customize-section.php

    r26892 r27398  
    22/**
    33 * Customize Section Class.
     4 *
     5 * A UI container for controls, managed by the WP_Customize_Manager.
    46 *
    57 * @package WordPress
    … …  
    810 */
    911class WP_Customize_Section {
     12    /**
     13     * @access public
     14     *
     15     * @var WP_Customize_Manager
     16     */
    1017    public $manager;
     18
     19    /**
     20     * Unique identifier.
     21     *
     22     * @var string
     23     */
    1124    public $id;
     25
     26    /**
     27     * Priority of the section which informs load order of sections.
     28     *
     29     * @var integer
     30     */
    1231    public $priority       = 10;
     32
     33    /**
     34     * Capability required for the section.
     35     *
     36     * @var string
     37     */
    1338    public $capability     = 'edit_theme_options';
    1439    public $theme_supports = '';
     40
     41    /**
     42     * Title of the section to show in UI.
     43     *
     44     * @var string
     45     */
    1546    public $title          = '';
     47
     48    /**
     49     * Description to show in the UI.
     50     *
     51     * @var string
     52     */
    1653    public $description    = '';
    1754    public $controls;
    … …  
    2057     * Constructor.
    2158     *
     59     * Any supplied $args override class property defaults.
     60     *
    2261     * @since 3.4.0
    2362     *
    2463     * @param WP_Customize_Manager $manager
    25      * @param string $id An specific ID of the section.
    26      * @param array $args Section arguments.
     64     * @param string               $id      An specific ID of the section.
     65     * @param array                $args    Section arguments.
    2766     */
    2867    function __construct( $manager, $id, $args = array() ) {
    … …  
    4281
    4382    /**
    44      * Check if the theme supports the section and check user capabilities.
     83     * Checks required user capabilities and whether the theme has the
     84     * feature support required by the section.
    4585     *
    4686     * @since 3.4.0
    … …  
    72112         * @since 3.4.0
    73113         *
    74          * @param WP_Customize_Section $this The WP_Customize_Section instance.
     114         * @param WP_Customize_Section $this WP_Customize_Section instance.
    75115         */
    76116        do_action( 'customize_render_section', $this );
    … …  
    89129
    90130    /**
    91      * Render the section.
     131     * Render the section, and the controls that have been added to it.
    92132     *
    93133     * @since 3.4.0

  • trunk/src/wp-includes/class-wp-customize-setting.php

    r27262 r27398  
    22/**
    33 * Customize Setting Class.
     4 *
     5 * Handles saving and sanitizing of settings.
    46 *
    57 * @package WordPress
    … …  
    810 */
    911class WP_Customize_Setting {
     12    /**
     13     * @access public
     14     * @var WP_Customize_Manager
     15     */
    1016    public $manager;
     17
     18    /**
     19     * @access public
     20     * @var string
     21     */
    1122    public $id;
    1223
    13     public $type            = 'theme_mod';
    14     public $capability      = 'edit_theme_options';
     24    /**
     25     * @access public
     26     * @var string
     27     */
     28    public $type = 'theme_mod';
     29
     30    /**
     31     * Capability required to edit this setting.
     32     *
     33     * @var string
     34     */
     35    public $capability = 'edit_theme_options';
     36
     37    /**
     38     * Feature a theme is required to support to enable this setting.
     39     *
     40     * @access public
     41     * @var string
     42     */
    1543    public $theme_supports  = '';
    1644    public $default         = '';
    1745    public $transport       = 'refresh';
    1846
     47    /**
     48     * Server-side sanitization callback for the setting's value.
     49     *
     50     * @var callback
     51     */
    1952    public $sanitize_callback    = '';
    2053    public $sanitize_js_callback = '';
    2154
    2255    protected $id_data = array();
    23     private $_post_value; // Cached, sanitized $_POST value.
     56
     57    /**
     58     * Cached and sanitized $_POST value for the setting.
     59     *
     60     * @access private
     61     * @var mixed
     62     */
     63    private $_post_value;
    2464
    2565    /**
    2666     * Constructor.
    2767     *
     68     * Any supplied $args override class property defaults.
     69     *
    2870     * @since 3.4.0
    2971     *
    3072     * @param WP_Customize_Manager $manager
    31      * @param string $id An specific ID of the setting. Can be a
    32      *                   theme mod or option name.
    33      * @param array $args Setting arguments.
    34      * @return WP_Customize_Setting
     73     * @param string               $id      An specific ID of the setting. Can be a
     74     *                                      theme mod or option name.
     75     * @param array                $args    Setting arguments.
     76     * @return WP_Customize_Setting $setting
    3577     */
    3678    function __construct( $manager, $id, $args = array() ) {
    … …  
    99141
    100142    /**
    101      * Set the value of the parameter for a specific theme.
     143     * Check user capabilities and theme supports, and then save
     144     * the value of the setting.
    102145     *
    103146     * @since 3.4.0
    … …  
    117160
    118161    /**
    119      * Fetches, validates, and sanitizes the $_POST value.
     162     * Fetch and sanitize the $_POST value for the setting.
    120163     *
    121164     * @since 3.4.0
    … …  
    125168     */
    126169    public final function post_value( $default = null ) {
     170        // Check for a cached value
    127171        if ( isset( $this->_post_value ) )
    128172            return $this->_post_value;
    129173
     174        // Call the manager for the post value
    130175        $result = $this->manager->post_value( $this );
    131176
    … …  
    150195
    151196    /**
    152      * Set the value of the parameter for a specific theme.
     197     * Save the value of the setting, using the related API.
    153198     *
    154199     * @since 3.4.0
    … …  
    191236
    192237    /**
    193      * Update the theme mod from the value of the parameter.
     238     * Update the option from the value of the setting.
    194239     *
    195240     * @since 3.4.0
    … …  
    211256
    212257    /**
    213      * Fetch the value of the parameter for a specific theme.
    214      *
    215      * @since 3.4.0
    216      *
    217      * @return mixed The requested value.
     258     * Fetch the value of the setting.
     259     *
     260     * @since 3.4.0
     261     *
     262     * @return mixed The value.
    218263     */
    219264    public function value() {
     265        // Get the callback that corresponds to the setting type.
    220266        switch( $this->type ) {
    221267            case 'theme_mod' :
    … …  
    239285
    240286    /**
    241      * Escape the parameter's value for use in JavaScript.
     287     * Sanitize the setting's value for use in JavaScript.
    242288     *
    243289     * @since 3.4.0
    … …  
    255301
    256302    /**
    257      * Check if the theme supports the setting and check user capabilities.
     303     * Validate user capabilities whether the theme supports the setting.
    258304     *
    259305     * @since 3.4.0
Note: See TracChangeset for help on using the changeset viewer.