Index: wp-admin/options.php =================================================================== --- wp-admin/options.php (revision 13159) +++ wp-admin/options.php (working copy) @@ -2,11 +2,14 @@ /** * Options Management Administration Panel. * - * Just allows for displaying of options. + * If accessed directly in a browser this page shows a list of all saved options + * along with editable fields for their values. Serialized data is not supported + * and there is no way to remove options via this page. It is not linked to from + * anywhere else in the admin. * - * This isn't referenced or linked to, but will show all of the options and - * allow editing. The issue is that serialized data is not supported to be - * modified. Options can not be removed. + * This file is also the target of the forms in core and custom options pages + * that use the Settings API. In this case it saves the new option values + * and returns the user to their page of origin. * * @package WordPress * @subpackage Administration @@ -76,6 +79,9 @@ switch($action) { +/** + * If $_GET['action'] == 'update' we are saving settings sent from a settings page + */ case 'update': if ( isset($_POST[ 'option_page' ]) ) { $option_page = $_POST[ 'option_page' ]; @@ -123,7 +129,18 @@ } } - $goback = add_query_arg( 'updated', 'true', wp_get_referer() ); + /** + * Handle settings errors and return to options page + */ + // If no settings errors were registered add a general 'updated' message. + if ( !count( get_settings_errors() ) ) + add_settings_error('general', 'settings_updated', __('Settings saved.'), 'updated'); + set_transient('settings_errors', get_settings_errors(), 30); + + /** + * Redirect back to the settings page that was submitted + */ + $goback = add_query_arg( 'updated', 'true', wp_get_referer() ); wp_redirect( $goback ); break; Index: wp-admin/options-head.php =================================================================== --- wp-admin/options-head.php (revision 13159) +++ wp-admin/options-head.php (working copy) @@ -10,8 +10,7 @@ */ wp_reset_vars(array('action', 'standalone', 'option_group_id')); -?> - -

- \ No newline at end of file +settings_errors(); + +?> \ No newline at end of file Index: wp-admin/includes/template.php =================================================================== --- wp-admin/includes/template.php (revision 13159) +++ wp-admin/includes/template.php (working copy) @@ -2981,12 +2981,22 @@ /** * Add a new section to a settings page. * + * Part of the Settings API. Use this to define new settings sections for an admin page. + * Show settings sections in your admin page callback function with do_settings_sections(). + * Add settings fields to your section with add_settings_field() + * + * The $callback argument should be the name of a function that echos out any + * content you want to show at the top of the settings section before the actual + * fields. It can output nothing if you want. + * * @since 2.7.0 * - * @param string $id String for use in the 'id' attribute of tags. - * @param string $title Title of the section. - * @param string $callback Function that fills the section with the desired content. The function should echo its output. - * @param string $page The type of settings page on which to show the section (general, reading, writing, ...). + * @global $wp_settings_sections Storage array of all settings sections added to admin pages + + * @param string $id Slug-name to identify the section. Used in the 'id' attribute of tags. + * @param string $title Formatted title of the section. Shown as the heading for the section. + * @param string $callback Function that echo's out content for the section heading. + * @param string $page The slug-name of the settings page on which to show the section (general, reading, writing, ...). */ function add_settings_section($id, $title, $callback, $page) { global $wp_settings_sections; @@ -3002,15 +3012,25 @@ } /** - * Add a new field to a settings page. + * Add a new field to a section of a settings page * + * Part of the Settings API. Use this to define a settings field that will show + * as part of a settings section inside a settings page. The fields are shown using + * do_settings_fields() in do_settings-sections() + * + * The $callback argument should be the name of a function that echoes out the + * html input tags for this setting field. Use get_option() to retrive existing + * values to show. + * * @since 2.7.0 * - * @param string $id String for use in the 'id' attribute of tags. - * @param string $title Title of the field. - * @param string $callback Function that fills the field with the desired content. The function should echo its output. - * @param string $page The type of settings page on which to show the field (general, reading, writing, ...). - * @param string $section The section of the settingss page in which to show the box (default, ...). + * @global $wp_settings_fields Storage array of settings fields and info about their pages/sections + * + * @param string $id Slug-name to identify the field. Used in the 'id' attribute of tags. + * @param string $title Formatted title of the field. Shown as the label for the field during output. + * @param string $callback Function that fills the field with the desired form inputs. The function should echo its output. + * @param string $page The slug-name of the settings page on which to show the section (general, reading, writing, ...). + * @param string $section The slug-name of the section of the settingss page in which to show the box (default, ...). * @param array $args Additional arguments */ function add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array()) { @@ -3027,11 +3047,17 @@ } /** - * {@internal Missing Short Description}} + * Prints out all settings sections added to a particular settings page * + * Part of the Settings API. Use this in a settings page callback function + * to output all the sections and fields that were added to that $page with + * add_settings_section() and add_settings_field() + * + * @global $wp_settings_sections Storage array of all settings sections added to admin pages + * @global $wp_settings_fields Storage array of settings fields and info about their pages/sections * @since unknown * - * @param unknown_type $page + * @param string $page The slug name of the page whos settings sections you want to output */ function do_settings_sections($page) { global $wp_settings_sections, $wp_settings_fields; @@ -3051,12 +3077,18 @@ } /** - * {@internal Missing Short Description}} + * Print out the settings fields for a particular settings section * + * Part of the Settings API. Use this in a settings page to output + * a specific section. Should normally be called by do_settings_sections() + * rather than directly. + * + * @global $wp_settings_fields Storage array of settings fields and their pages/sections + * * @since unknown * - * @param unknown_type $page - * @param unknown_type $section + * @param string $page Slug title of the admin page who's settings fields you want to show. + * @param section $section Slug title of the settings section who's fields you want to show. */ function do_settings_fields($page, $section) { global $wp_settings_fields; @@ -3078,6 +3110,127 @@ } /** + * Register a settings error to be displayed to the user + * + * Part of the Settings API. Use this to show messages to users about settings validation + * problems, missing settings or anything else. + * + * Settings errors should be added inside the $sanitize_callback function defined in + * register_setting() for a given setting to give feedback about the submission. + * + * By default messages will show immediately after the submission that generated the error. + * Additional calls to settings_errors() can be used to show errors even when the settings + * page is first accessed. + * + * @global array $wp_settings_errors Storage array of errors registered during this pageload + * + * @param string $setting Slug title of the setting to which this error applies + * @param string $id Slug-name to identify the error. Used as part of 'id' attribute in HTML output. + * @param string $message The formatted message text to display to the user (will be shown inside styled
and

) + * @param string $type The type of message it is, controls HTML class. Use 'error' or 'updated'. + */ +function add_settings_error( $setting, $id, $message, $type = 'error' ) { + global $wp_settings_errors; + + $new_error = array( + 'setting' => $setting, + 'title' => $title, + 'message' => $message, + 'type' => $type + ); + $wp_settings_errors[] = $new_error; +} + +/** + * Fetch settings errors registered by add_settings_error() + * + * Checks the $wp_settings_errors array for any errors declared during the current + * pageload and returns them. + * + * If changes were just submitted ($_GET['updated']) and settings errors were saved + * to the 'settings_errors' transient then those errors will be returned instead. This + * is used to pass errors back across pageloads. + * + * Use the $sanitize argument to manually re-sanitize the option before returning errors. + * This is useful if you have errors or notices you want to show even when the user + * hasn't submitted data (i.e. when they first load an options page, or in admin_notices action hook) + * + * @global array $wp_settings_errors Storage array of errors registered during this pageload + * + * @param string $setting Optional slug title of a specific setting who's errors you want. + * @param boolean $sanitize Whether to re-sanitize the setting value before returning errors. + * @return array Array of settings errors + */ +function get_settings_errors( $setting = '', $sanitize = FALSE ) { + global $wp_settings_errors; + + // If $sanitize is true, manually re-run the sanitizisation for this option + // This allows the $sanitize_callback from register_setting() to run, adding + // any settings errors you want to show by default. + if ( $sanitize ) + sanitize_option( $setting, get_option($setting)); + + // If settings were passed back from options.php then use them + // Ignore transients if $sanitize is true, we dont' want the old values anyway + if ( $_GET['updated'] AND get_transient('settings_errors')) { + $settings_errors = get_transient('settings_errors'); + delete_transient('settings_errors'); + // Otherwise check global in case validation has been run on this pageload + } elseif (count( $wp_settings_errors )) { + $settings_errors = $wp_settings_errors; + } else { + return; + } + + // Filter the results to those of a specific setting if one was set + if ( $setting ) { + foreach ( (array) $settings_errors as $key => $details ) + if ( $setting != $details['setting'] ) + unset( $settings_errors[$key] ); + } + return $settings_errors; +} + +/** + * Display settings errors registered by add_settings_error() + * + * Part of the Settings API. Outputs a

for each error retrieved by get_settings_errors(). + * + * This is called automatically after a settings page based on the Settings API is submitted. + * Errors should be added during the validation callback function for a setting defined in register_setting() + * + * The $sanitize option is passed into get_settings_errors() and will re-run the setting sanitization + * on its current value. + * + * The $hide_on_update option will cause errors to only show when the settings page is first loaded. + * if the user has already saved new values it will be hidden to avoid repeating messages already + * shown in the default error reporting after submission. This is useful to show general errors like missing + * settings when the user arrives at the settings page. + * + * @param string $setting Optional slug title of a specific setting who's errors you want. + * @param boolean $sanitize Whether to re-sanitize the setting value before returning errors. + * @param boolean $hide_on_update If set to true errors will not be shown if the settings page has already been submitted. + * @return + */ +function settings_errors ( $setting = '', $sanitize = FALSE, $hide_on_update = FALSE ) { + + if ($hide_on_update AND $_GET['updated']) return; + + $settings_errors = get_settings_errors( $setting, $sanitize ); + + if ( !is_array($settings_errors) ) return; + + foreach ( $settings_errors as $key => $details ) { + $css_id = 'setting-error-' . $details['title']; + $css_class = $details['type'] . ' fade settings-error'; + $output .= "
\n"; + $output .= "

{$details['message']}

"; + $output .= "
\n"; + } + echo $output; +} + +/** * {@internal Missing Short Description}} * * @since unknown Index: wp-includes/formatting.php =================================================================== --- wp-includes/formatting.php (revision 13159) +++ wp-includes/formatting.php (working copy) @@ -2380,7 +2380,9 @@ switch ($option) { case 'admin_email': - $value = sanitize_email($value); + if (!$value = sanitize_email($value)) + add_settings_error('admin_email', 'invalid_admin_email', __('The E-Mail Address submitted was not in the right format. Please enter a valid Email Address')); + break; case 'thumbnail_size_w':