<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[27398] trunk/src: Update the Customizer API inline docs.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/27398">27398</a></dd>
<dt>Author</dt> <dd>nacin</dd>
<dt>Date</dt> <dd>2014-03-04 20:20:28 +0000 (Tue, 04 Mar 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>Update the Customizer API inline docs.
props ericlewis.
fixes <a href="http://core.trac.wordpress.org/ticket/27065">#27065</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpadmincustomizephp">trunk/src/wp-admin/customize.php</a></li>
<li><a href="#trunksrcwpincludesclasswpcustomizecontrolphp">trunk/src/wp-includes/class-wp-customize-control.php</a></li>
<li><a href="#trunksrcwpincludesclasswpcustomizemanagerphp">trunk/src/wp-includes/class-wp-customize-manager.php</a></li>
<li><a href="#trunksrcwpincludesclasswpcustomizesectionphp">trunk/src/wp-includes/class-wp-customize-section.php</a></li>
<li><a href="#trunksrcwpincludesclasswpcustomizesettingphp">trunk/src/wp-includes/class-wp-customize-setting.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpadmincustomizephp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-admin/customize.php (27397 => 27398)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-admin/customize.php 2014-03-04 20:06:14 UTC (rev 27397)
+++ trunk/src/wp-admin/customize.php 2014-03-04 20:20:28 UTC (rev 27398)
</span><span class="lines">@@ -1,6 +1,6 @@
</span><span class="cx"> <?php
</span><span class="cx"> /**
</span><del>- * Customize Controls
</del><ins>+ * Theme Customize Screen.
</ins><span class="cx"> *
</span><span class="cx"> * @package WordPress
</span><span class="cx"> * @subpackage Customize
</span><span class="lines">@@ -9,7 +9,9 @@
</span><span class="cx">
</span><span class="cx"> define( 'IFRAME_REQUEST', true );
</span><span class="cx">
</span><ins>+/** Load WordPress Administration Bootstrap */
</ins><span class="cx"> require_once( dirname( __FILE__ ) . '/admin.php' );
</span><ins>+
</ins><span class="cx"> if ( ! current_user_can( 'edit_theme_options' ) )
</span><span class="cx"> wp_die( __( 'Cheatin’ uh?' ) );
</span><span class="cx">
</span><span class="lines">@@ -199,6 +201,7 @@
</span><span class="cx"> 'customize-login' => 1
</span><span class="cx"> ), wp_login_url() );
</span><span class="cx">
</span><ins>+ // Prepare customizer settings to pass to Javascript.
</ins><span class="cx"> $settings = array(
</span><span class="cx"> 'theme' => array(
</span><span class="cx"> 'stylesheet' => $wp_customize->get_stylesheet(),
</span><span class="lines">@@ -227,6 +230,7 @@
</span><span class="cx"> ),
</span><span class="cx"> );
</span><span class="cx">
</span><ins>+ // Prepare Customize Setting objects to pass to Javascript.
</ins><span class="cx"> foreach ( $wp_customize->settings() as $id => $setting ) {
</span><span class="cx"> $settings['settings'][ $id ] = array(
</span><span class="cx"> 'value' => $setting->js_value(),
</span><span class="lines">@@ -234,6 +238,7 @@
</span><span class="cx"> );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+ // Prepare Customize Control objects to pass to Javascript.
</ins><span class="cx"> foreach ( $wp_customize->controls() as $id => $control ) {
</span><span class="cx"> $control->to_json();
</span><span class="cx"> $settings['controls'][ $id ] = $control->json;
</span></span></pre></div>
<a id="trunksrcwpincludesclasswpcustomizecontrolphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/class-wp-customize-control.php (27397 => 27398)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/class-wp-customize-control.php 2014-03-04 20:06:14 UTC (rev 27397)
+++ trunk/src/wp-includes/class-wp-customize-control.php 2014-03-04 20:20:28 UTC (rev 27398)
</span><span class="lines">@@ -39,19 +39,19 @@
</span><span class="cx"> * @access public
</span><span class="cx"> * @var int
</span><span class="cx"> */
</span><del>- public $priority = 10;
</del><ins>+ public $priority = 10;
</ins><span class="cx">
</span><span class="cx"> /**
</span><span class="cx"> * @access public
</span><span class="cx"> * @var string
</span><span class="cx"> */
</span><del>- public $section = '';
</del><ins>+ public $section = '';
</ins><span class="cx">
</span><span class="cx"> /**
</span><span class="cx"> * @access public
</span><span class="cx"> * @var string
</span><span class="cx"> */
</span><del>- public $label = '';
</del><ins>+ public $label = '';
</ins><span class="cx">
</span><span class="cx"> /**
</span><span class="cx"> * @todo: Remove choices
</span><span class="lines">@@ -59,7 +59,7 @@
</span><span class="cx"> * @access public
</span><span class="cx"> * @var array
</span><span class="cx"> */
</span><del>- public $choices = array();
</del><ins>+ public $choices = array();
</ins><span class="cx">
</span><span class="cx"> /**
</span><span class="cx"> * @access public
</span><span class="lines">@@ -77,6 +77,8 @@
</span><span class="cx"> /**
</span><span class="cx"> * Constructor.
</span><span class="cx"> *
</span><ins>+ * Supplied $args override class property defaults.
+ *
</ins><span class="cx"> * If $args['settings'] is not defined, use the $id as the setting ID.
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="lines">@@ -95,7 +97,6 @@
</span><span class="cx"> $this->manager = $manager;
</span><span class="cx"> $this->id = $id;
</span><span class="cx">
</span><del>-
</del><span class="cx"> // Process settings.
</span><span class="cx"> if ( empty( $this->settings ) )
</span><span class="cx"> $this->settings = $id;
</span><span class="lines">@@ -185,7 +186,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Render the control. Renders the control wrapper, then calls $this->render_content().
</del><ins>+ * Renders the control wrapper and calls $this->render_content() for the internals.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span><span class="lines">@@ -199,7 +200,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Get the data link parameter for a setting.
</del><ins>+ * Get the data link attribute for a setting.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="lines">@@ -214,7 +215,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Render the data link parameter for a setting
</del><ins>+ * Render the data link attribute for the control's input element.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> * @uses WP_Customize_Control::get_link()
</span><span class="lines">@@ -228,8 +229,10 @@
</span><span class="cx"> /**
</span><span class="cx"> * Render the control's content.
</span><span class="cx"> *
</span><del>- * Allows the content to be overriden without having to rewrite the wrapper.
</del><ins>+ * Allows the content to be overriden without having to rewrite the wrapper in $this->render().
</ins><span class="cx"> *
</span><ins>+ * Supports basic input types `text`, `checkbox`, `radio`, `select` and `dropdown-pages`.
+ *
</ins><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span><span class="cx"> protected function render_content() {
</span><span class="lines">@@ -331,8 +334,6 @@
</span><span class="cx"> /**
</span><span class="cx"> * Constructor.
</span><span class="cx"> *
</span><del>- * If $args['settings'] is not defined, use the $id as the setting ID.
- *
</del><span class="cx"> * @since 3.4.0
</span><span class="cx"> * @uses WP_Customize_Control::__construct()
</span><span class="cx"> *
</span><span class="lines">@@ -346,7 +347,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Enqueue control related scripts/styles.
</del><ins>+ * Enqueue scripts/styles for the color picker.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span><span class="lines">@@ -467,8 +468,6 @@
</span><span class="cx"> /**
</span><span class="cx"> * Constructor.
</span><span class="cx"> *
</span><del>- * If $args['settings'] is not defined, use the $id as the setting ID.
- *
</del><span class="cx"> * @since 3.4.0
</span><span class="cx"> * @uses WP_Customize_Upload_Control::__construct()
</span><span class="cx"> *
</span></span></pre></div>
<a id="trunksrcwpincludesclasswpcustomizemanagerphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/class-wp-customize-manager.php (27397 => 27398)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/class-wp-customize-manager.php 2014-03-04 20:06:14 UTC (rev 27397)
+++ trunk/src/wp-includes/class-wp-customize-manager.php 2014-03-04 20:20:28 UTC (rev 27398)
</span><span class="lines">@@ -2,14 +2,39 @@
</span><span class="cx"> /**
</span><span class="cx"> * Customize Manager.
</span><span class="cx"> *
</span><ins>+ * 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.
+ *
</ins><span class="cx"> * @package WordPress
</span><span class="cx"> * @subpackage Customize
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span><span class="cx"> final class WP_Customize_Manager {
</span><ins>+ /**
+ * An instance of the theme that is being customized.
+ *
+ * @var WP_Theme
+ */
</ins><span class="cx"> protected $theme;
</span><ins>+
+ /**
+ * The directory name of the previously active theme (within the theme_root).
+ *
+ * @var string
+ */
</ins><span class="cx"> protected $original_stylesheet;
</span><span class="cx">
</span><ins>+ /**
+ * Whether filters have been set to change the active theme to the theme being
+ * customized.
+ *
+ * @var boolean
+ */
</ins><span class="cx"> protected $previewing = false;
</span><span class="cx">
</span><span class="cx"> protected $settings = array();
</span><span class="lines">@@ -20,6 +45,11 @@
</span><span class="cx">
</span><span class="cx"> protected $customized;
</span><span class="cx">
</span><ins>+ /**
+ * $_POST values for Customize Settings.
+ *
+ * @var array
+ */
</ins><span class="cx"> private $_post_values;
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="lines">@@ -127,17 +157,21 @@
</span><span class="cx"> // Once the theme is loaded, we'll validate it.
</span><span class="cx"> add_action( 'after_setup_theme', array( $this, 'after_setup_theme' ) );
</span><span class="cx"> } else {
</span><ins>+ // If the requested theme is not the active theme and the user doesn't have the
+ // switch_themes cap, bail.
</ins><span class="cx"> if ( ! current_user_can( 'switch_themes' ) )
</span><span class="cx"> $this->wp_die( -1 );
</span><span class="cx">
</span><del>- // If the theme isn't active, you can't preview it if it is not allowed or has errors.
</del><ins>+ // If the theme has errors while loading, bail.
</ins><span class="cx"> if ( $this->theme()->errors() )
</span><span class="cx"> $this->wp_die( -1 );
</span><span class="cx">
</span><ins>+ // If the theme isn't allowed per multisite settings, bail.
</ins><span class="cx"> if ( ! $this->theme()->is_allowed() )
</span><span class="cx"> $this->wp_die( -1 );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+ // All good, let's do some internal business to preview the theme.
</ins><span class="cx"> $this->start_previewing_theme();
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -154,10 +188,8 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Start previewing the selected theme.
</del><ins>+ * Start previewing the selected theme by adding filters to change the current theme.
</ins><span class="cx"> *
</span><del>- * Adds filters to change the current theme.
- *
</del><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span><span class="cx"> public function start_previewing_theme() {
</span><span class="lines">@@ -300,12 +332,12 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Decode the $_POST attribute used to override the WP_Customize_Setting values.
</del><ins>+ * Decode the $_POST['customized'] values for a specific Customize Setting.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="cx"> * @param mixed $setting A WP_Customize_Setting derived object
</span><del>- * @return string Sanitized attribute
</del><ins>+ * @return string $post_value Sanitized value
</ins><span class="cx"> */
</span><span class="cx"> public function post_value( $setting ) {
</span><span class="cx"> if ( ! isset( $this->_post_values ) ) {
</span><span class="lines">@@ -487,7 +519,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Switch the theme and trigger the save action of each setting.
</del><ins>+ * Switch the theme and trigger the save() method on each setting.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span><span class="lines">@@ -522,9 +554,9 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $id A specific ID of the setting. Can be a
- * theme mod or option name.
- * @param array $args Setting arguments.
</del><ins>+ * @param WP_Customize_Setting|string $id Customize Setting object, or ID.
+ * @param array $args Setting arguments; passed to WP_Customize_Setting
+ * constructor.
</ins><span class="cx"> */
</span><span class="cx"> public function add_setting( $id, $args = array() ) {
</span><span class="cx"> if ( is_a( $id, 'WP_Customize_Setting' ) )
</span><span class="lines">@@ -540,8 +572,8 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $id A specific ID of the setting.
- * @return object The settings object.
</del><ins>+ * @param string $id Customize Setting ID.
+ * @return WP_Customize_Setting
</ins><span class="cx"> */
</span><span class="cx"> public function get_setting( $id ) {
</span><span class="cx"> if ( isset( $this->settings[ $id ] ) )
</span><span class="lines">@@ -553,7 +585,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $id A specific ID of the setting.
</del><ins>+ * @param string $id Customize Setting ID.
</ins><span class="cx"> */
</span><span class="cx"> public function remove_setting( $id ) {
</span><span class="cx"> unset( $this->settings[ $id ] );
</span><span class="lines">@@ -564,8 +596,8 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $id A specific ID of the section.
- * @param array $args Section arguments.
</del><ins>+ * @param WP_Customize_Section|string $id Customize Section object, or Section ID.
+ * @param array $args Section arguments.
</ins><span class="cx"> */
</span><span class="cx"> public function add_section( $id, $args = array() ) {
</span><span class="cx"> if ( is_a( $id, 'WP_Customize_Section' ) )
</span><span class="lines">@@ -581,8 +613,8 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $id A specific ID of the section.
- * @return object The section object.
</del><ins>+ * @param string $id Section ID.
+ * @return WP_Customize_Section
</ins><span class="cx"> */
</span><span class="cx"> public function get_section( $id ) {
</span><span class="cx"> if ( isset( $this->sections[ $id ] ) )
</span><span class="lines">@@ -594,7 +626,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $id A specific ID of the section.
</del><ins>+ * @param string $id Section ID.
</ins><span class="cx"> */
</span><span class="cx"> public function remove_section( $id ) {
</span><span class="cx"> unset( $this->sections[ $id ] );
</span><span class="lines">@@ -605,8 +637,9 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $id A specific ID of the control.
- * @param array $args Setting arguments.
</del><ins>+ * @param WP_Customize_Control|string $id Customize Control object, or ID.
+ * @param array $args Control arguments; passed to WP_Customize_Control
+ * constructor.
</ins><span class="cx"> */
</span><span class="cx"> public function add_control( $id, $args = array() ) {
</span><span class="cx"> if ( is_a( $id, 'WP_Customize_Control' ) )
</span><span class="lines">@@ -622,8 +655,8 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $id A specific ID of the control.
- * @return object The settings object.
</del><ins>+ * @param string $id ID of the control.
+ * @return WP_Customize_Control $control The control object.
</ins><span class="cx"> */
</span><span class="cx"> public function get_control( $id ) {
</span><span class="cx"> if ( isset( $this->controls[ $id ] ) )
</span><span class="lines">@@ -631,11 +664,11 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Remove a customize setting.
</del><ins>+ * Remove a customize control.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $id A specific ID of the control.
</del><ins>+ * @param string $id ID of the control.
</ins><span class="cx"> */
</span><span class="cx"> public function remove_control( $id ) {
</span><span class="cx"> unset( $this->controls[ $id ] );
</span><span class="lines">@@ -662,11 +695,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Prepare settings and sections.
</span><span class="cx"> *
</span><ins>+ * For each, check if required related components exist,
+ * whether the user has the necessary capabilities,
+ * and sort by priority.
+ *
</ins><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span><span class="cx"> public function prepare_controls() {
</span><del>- // Prepare controls
- // Reversing makes uasort sort by time added when conflicts occur.
</del><span class="cx">
</span><span class="cx"> $this->controls = array_reverse( $this->controls );
</span><span class="cx"> $controls = array();
</span><span class="lines">@@ -680,7 +715,8 @@
</span><span class="cx"> }
</span><span class="cx"> $this->controls = $controls;
</span><span class="cx">
</span><del>- // Prepare sections
</del><ins>+ // Prepare sections.
+ // Reversing makes uasort sort by time added when conflicts occur.
</ins><span class="cx"> $this->sections = array_reverse( $this->sections );
</span><span class="cx"> uasort( $this->sections, array( $this, '_cmp_priority' ) );
</span><span class="cx"> $sections = array();
</span><span class="lines">@@ -995,10 +1031,10 @@
</span><span class="cx"> };
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Validates a hex color.
</del><ins>+ * Sanitizes a hex color.
</ins><span class="cx"> *
</span><span class="cx"> * Returns either '', a 3 or 6 digit hex color (with #), or null.
</span><del>- * For validating values without a #, see sanitize_hex_color_no_hash().
</del><ins>+ * For sanitizing values without a #, see sanitize_hex_color_no_hash().
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span></span></pre></div>
<a id="trunksrcwpincludesclasswpcustomizesectionphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/class-wp-customize-section.php (27397 => 27398)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/class-wp-customize-section.php 2014-03-04 20:06:14 UTC (rev 27397)
+++ trunk/src/wp-includes/class-wp-customize-section.php 2014-03-04 20:20:28 UTC (rev 27398)
</span><span class="lines">@@ -2,28 +2,67 @@
</span><span class="cx"> /**
</span><span class="cx"> * Customize Section Class.
</span><span class="cx"> *
</span><ins>+ * A UI container for controls, managed by the WP_Customize_Manager.
+ *
</ins><span class="cx"> * @package WordPress
</span><span class="cx"> * @subpackage Customize
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span><span class="cx"> class WP_Customize_Section {
</span><ins>+ /**
+ * @access public
+ *
+ * @var WP_Customize_Manager
+ */
</ins><span class="cx"> public $manager;
</span><ins>+
+ /**
+ * Unique identifier.
+ *
+ * @var string
+ */
</ins><span class="cx"> public $id;
</span><ins>+
+ /**
+ * Priority of the section which informs load order of sections.
+ *
+ * @var integer
+ */
</ins><span class="cx"> public $priority = 10;
</span><ins>+
+ /**
+ * Capability required for the section.
+ *
+ * @var string
+ */
</ins><span class="cx"> public $capability = 'edit_theme_options';
</span><span class="cx"> public $theme_supports = '';
</span><ins>+
+ /**
+ * Title of the section to show in UI.
+ *
+ * @var string
+ */
</ins><span class="cx"> public $title = '';
</span><ins>+
+ /**
+ * Description to show in the UI.
+ *
+ * @var string
+ */
</ins><span class="cx"> public $description = '';
</span><span class="cx"> public $controls;
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="cx"> * Constructor.
</span><span class="cx"> *
</span><ins>+ * Any supplied $args override class property defaults.
+ *
</ins><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="cx"> * @param WP_Customize_Manager $manager
</span><del>- * @param string $id An specific ID of the section.
- * @param array $args Section arguments.
</del><ins>+ * @param string $id An specific ID of the section.
+ * @param array $args Section arguments.
</ins><span class="cx"> */
</span><span class="cx"> function __construct( $manager, $id, $args = array() ) {
</span><span class="cx"> $keys = array_keys( get_class_vars( __CLASS__ ) );
</span><span class="lines">@@ -41,7 +80,8 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Check if the theme supports the section and check user capabilities.
</del><ins>+ * Checks required user capabilities and whether the theme has the
+ * feature support required by the section.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="lines">@@ -71,7 +111,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param WP_Customize_Section $this The WP_Customize_Section instance.
</del><ins>+ * @param WP_Customize_Section $this WP_Customize_Section instance.
</ins><span class="cx"> */
</span><span class="cx"> do_action( 'customize_render_section', $this );
</span><span class="cx"> /**
</span><span class="lines">@@ -88,7 +128,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Render the section.
</del><ins>+ * Render the section, and the controls that have been added to it.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span></span></pre></div>
<a id="trunksrcwpincludesclasswpcustomizesettingphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/class-wp-customize-setting.php (27397 => 27398)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/class-wp-customize-setting.php 2014-03-04 20:06:14 UTC (rev 27397)
+++ trunk/src/wp-includes/class-wp-customize-setting.php 2014-03-04 20:20:28 UTC (rev 27398)
</span><span class="lines">@@ -2,36 +2,78 @@
</span><span class="cx"> /**
</span><span class="cx"> * Customize Setting Class.
</span><span class="cx"> *
</span><ins>+ * Handles saving and sanitizing of settings.
+ *
</ins><span class="cx"> * @package WordPress
</span><span class="cx"> * @subpackage Customize
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> */
</span><span class="cx"> class WP_Customize_Setting {
</span><ins>+ /**
+ * @access public
+ * @var WP_Customize_Manager
+ */
</ins><span class="cx"> public $manager;
</span><ins>+
+ /**
+ * @access public
+ * @var string
+ */
</ins><span class="cx"> public $id;
</span><span class="cx">
</span><del>- public $type = 'theme_mod';
- public $capability = 'edit_theme_options';
</del><ins>+ /**
+ * @access public
+ * @var string
+ */
+ public $type = 'theme_mod';
+
+ /**
+ * Capability required to edit this setting.
+ *
+ * @var string
+ */
+ public $capability = 'edit_theme_options';
+
+ /**
+ * Feature a theme is required to support to enable this setting.
+ *
+ * @access public
+ * @var string
+ */
</ins><span class="cx"> public $theme_supports = '';
</span><span class="cx"> public $default = '';
</span><span class="cx"> public $transport = 'refresh';
</span><span class="cx">
</span><ins>+ /**
+ * Server-side sanitization callback for the setting's value.
+ *
+ * @var callback
+ */
</ins><span class="cx"> public $sanitize_callback = '';
</span><span class="cx"> public $sanitize_js_callback = '';
</span><span class="cx">
</span><span class="cx"> protected $id_data = array();
</span><del>- private $_post_value; // Cached, sanitized $_POST value.
</del><span class="cx">
</span><span class="cx"> /**
</span><ins>+ * Cached and sanitized $_POST value for the setting.
+ *
+ * @access private
+ * @var mixed
+ */
+ private $_post_value;
+
+ /**
</ins><span class="cx"> * Constructor.
</span><span class="cx"> *
</span><ins>+ * Any supplied $args override class property defaults.
+ *
</ins><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="cx"> * @param WP_Customize_Manager $manager
</span><del>- * @param string $id An specific ID of the setting. Can be a
- * theme mod or option name.
- * @param array $args Setting arguments.
- * @return WP_Customize_Setting
</del><ins>+ * @param string $id An specific ID of the setting. Can be a
+ * theme mod or option name.
+ * @param array $args Setting arguments.
+ * @return WP_Customize_Setting $setting
</ins><span class="cx"> */
</span><span class="cx"> function __construct( $manager, $id, $args = array() ) {
</span><span class="cx"> $keys = array_keys( get_class_vars( __CLASS__ ) );
</span><span class="lines">@@ -98,7 +140,8 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Set the value of the parameter for a specific theme.
</del><ins>+ * Check user capabilities and theme supports, and then save
+ * the value of the setting.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="lines">@@ -116,7 +159,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Fetches, validates, and sanitizes the $_POST value.
</del><ins>+ * Fetch and sanitize the $_POST value for the setting.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="lines">@@ -124,9 +167,11 @@
</span><span class="cx"> * @return mixed The default value on failure, otherwise the sanitized value.
</span><span class="cx"> */
</span><span class="cx"> public final function post_value( $default = null ) {
</span><ins>+ // Check for a cached value
</ins><span class="cx"> if ( isset( $this->_post_value ) )
</span><span class="cx"> return $this->_post_value;
</span><span class="cx">
</span><ins>+ // Call the manager for the post value
</ins><span class="cx"> $result = $this->manager->post_value( $this );
</span><span class="cx">
</span><span class="cx"> if ( isset( $result ) )
</span><span class="lines">@@ -149,7 +194,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Set the value of the parameter for a specific theme.
</del><ins>+ * Save the value of the setting, using the related API.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="lines">@@ -190,7 +235,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Update the theme mod from the value of the parameter.
</del><ins>+ * Update the option from the value of the setting.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="lines">@@ -210,13 +255,14 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Fetch the value of the parameter for a specific theme.
</del><ins>+ * Fetch the value of the setting.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @return mixed The requested value.
</del><ins>+ * @return mixed The value.
</ins><span class="cx"> */
</span><span class="cx"> public function value() {
</span><ins>+ // Get the callback that corresponds to the setting type.
</ins><span class="cx"> switch( $this->type ) {
</span><span class="cx"> case 'theme_mod' :
</span><span class="cx"> $function = 'get_theme_mod';
</span><span class="lines">@@ -238,7 +284,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Escape the parameter's value for use in JavaScript.
</del><ins>+ * Sanitize the setting's value for use in JavaScript.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><span class="lines">@@ -254,7 +300,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Check if the theme supports the setting and check user capabilities.
</del><ins>+ * Validate user capabilities whether the theme supports the setting.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span></span></pre>
</div>
</div>
</body>
</html>