WordPress.org

Make WordPress Core

Ticket #11474: settings_api_add_errors-13159.diff

File settings_api_add_errors-13159.diff, 13.2 KB (added by jeremyclarke, 12 years ago)

Patch to add error reporting and documentation to Settings API

  • wp-admin/options.php

     
    22/**
    33 * Options Management Administration Panel.
    44 *
    5  * Just allows for displaying of options.
     5 * If accessed directly in a browser this page shows a list of all saved options
     6 * along with editable fields for their values. Serialized data is not supported
     7 * and there is no way to remove options via this page. It is not linked to from
     8 * anywhere else in the admin.
    69 *
    7  * This isn't referenced or linked to, but will show all of the options and
    8  * allow editing. The issue is that serialized data is not supported to be
    9  * modified. Options can not be removed.
     10 * This file is also the target of the forms in core and custom options pages
     11 * that use the Settings API. In this case it saves the new option values
     12 * and returns the user to their page of origin.
    1013 *
    1114 * @package WordPress
    1215 * @subpackage Administration
     
    7679
    7780switch($action) {
    7881
     82/**
     83 * If $_GET['action'] == 'update' we are saving settings sent from a settings page
     84 */
    7985case 'update':
    8086        if ( isset($_POST[ 'option_page' ]) ) {
    8187                $option_page = $_POST[ 'option_page' ];
     
    123129                }
    124130        }
    125131
    126         $goback = add_query_arg( 'updated', 'true', wp_get_referer() );
     132        /**
     133         *  Handle settings errors and return to options page
     134         */
     135        // If no settings errors were registered add a general 'updated' message.
     136        if ( !count( get_settings_errors() ) )
     137                add_settings_error('general', 'settings_updated', __('Settings saved.'), 'updated');
     138        set_transient('settings_errors', get_settings_errors(), 30);
     139
     140        /**
     141         * Redirect back to the settings page that was submitted
     142         */
     143        $goback = add_query_arg( 'updated', 'true',  wp_get_referer() );
    127144        wp_redirect( $goback );
    128145        break;
    129146
  • wp-admin/options-head.php

     
    1010 */
    1111
    1212wp_reset_vars(array('action', 'standalone', 'option_group_id'));
    13 ?>
    1413
    15 <?php if (isset($_GET['updated'])) : ?>
    16 <div id="message" class="updated"><p><strong><?php _e('Settings saved.') ?></strong></p></div>
    17 <?php endif; ?>
    18  No newline at end of file
     14settings_errors();
     15
     16?>
     17 No newline at end of file
  • wp-admin/includes/template.php

     
    29812981/**
    29822982 * Add a new section to a settings page.
    29832983 *
     2984 * Part of the Settings API. Use this to define new settings sections for an admin page.
     2985 * Show settings sections in your admin page callback function with do_settings_sections().
     2986 * Add settings fields to your section with add_settings_field()
     2987 *
     2988 * The $callback argument should be the name of a function that echos out any
     2989 * content you want to show at the top of the settings section before the actual
     2990 * fields. It can output nothing if you want.
     2991 *
    29842992 * @since 2.7.0
    29852993 *
    2986  * @param string $id String for use in the 'id' attribute of tags.
    2987  * @param string $title Title of the section.
    2988  * @param string $callback Function that fills the section with the desired content. The function should echo its output.
    2989  * @param string $page The type of settings page on which to show the section (general, reading, writing, ...).
     2994 * @global $wp_settings_sections Storage array of all settings sections added to admin pages
     2995
     2996 * @param string $id Slug-name to identify the section. Used in the 'id' attribute of tags.
     2997 * @param string $title Formatted title of the section. Shown as the heading for the section.
     2998 * @param string $callback Function that echo's out content for the section heading.
     2999 * @param string $page The slug-name of the settings page on which to show the section (general, reading, writing, ...).
    29903000 */
    29913001function add_settings_section($id, $title, $callback, $page) {
    29923002        global $wp_settings_sections;
     
    30023012}
    30033013
    30043014/**
    3005  * Add a new field to a settings page.
     3015 * Add a new field to a section of a settings page
    30063016 *
     3017 * Part of the Settings API. Use this to define a settings field that will show
     3018 * as part of a settings section inside a settings page. The fields are shown using
     3019 * do_settings_fields() in do_settings-sections()
     3020 *
     3021 * The $callback argument should be the name of a function that echoes out the
     3022 * html input tags for this setting field. Use get_option() to retrive existing
     3023 * values to show.
     3024 *
    30073025 * @since 2.7.0
    30083026 *
    3009  * @param string $id String for use in the 'id' attribute of tags.
    3010  * @param string $title Title of the field.
    3011  * @param string $callback Function that fills the field with the desired content. The function should echo its output.
    3012  * @param string $page The type of settings page on which to show the field (general, reading, writing, ...).
    3013  * @param string $section The section of the settingss page in which to show the box (default, ...).
     3027 * @global $wp_settings_fields Storage array of settings fields and info about their pages/sections
     3028 *
     3029 * @param string $id Slug-name to identify the field. Used in the 'id' attribute of tags.
     3030 * @param string $title Formatted title of the field. Shown as the label for the field during output.
     3031 * @param string $callback Function that fills the field with the desired form inputs. The function should echo its output.
     3032 * @param string $page The slug-name of the settings page on which to show the section (general, reading, writing, ...).
     3033 * @param string $section The slug-name of the section of the settingss page in which to show the box (default, ...).
    30143034 * @param array $args Additional arguments
    30153035 */
    30163036function add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array()) {
     
    30273047}
    30283048
    30293049/**
    3030  * {@internal Missing Short Description}}
     3050 * Prints out all settings sections added to a particular settings page
    30313051 *
     3052 * Part of the Settings API. Use this in a settings page callback function
     3053 * to output all the sections and fields that were added to that $page with
     3054 * add_settings_section() and add_settings_field()
     3055 *
     3056 * @global $wp_settings_sections Storage array of all settings sections added to admin pages
     3057 * @global $wp_settings_fields Storage array of settings fields and info about their pages/sections
    30323058 * @since unknown
    30333059 *
    3034  * @param unknown_type $page
     3060 * @param string $page The slug name of the page whos settings sections you want to output
    30353061 */
    30363062function do_settings_sections($page) {
    30373063        global $wp_settings_sections, $wp_settings_fields;
     
    30513077}
    30523078
    30533079/**
    3054  * {@internal Missing Short Description}}
     3080 * Print out the settings fields for a particular settings section
    30553081 *
     3082 * Part of the Settings API. Use this in a settings page to output
     3083 * a specific section. Should normally be called by do_settings_sections()
     3084 * rather than directly.
     3085 *
     3086 * @global $wp_settings_fields Storage array of settings fields and their pages/sections
     3087 *
    30563088 * @since unknown
    30573089 *
    3058  * @param unknown_type $page
    3059  * @param unknown_type $section
     3090 * @param string $page Slug title of the admin page who's settings fields you want to show.
     3091 * @param section $section Slug title of the settings section who's fields you want to show.
    30603092 */
    30613093function do_settings_fields($page, $section) {
    30623094        global $wp_settings_fields;
     
    30783110}
    30793111
    30803112/**
     3113 * Register a settings error to be displayed to the user
     3114 *
     3115 * Part of the Settings API. Use this to show messages to users about settings validation
     3116 * problems, missing settings or anything else.
     3117 *
     3118 * Settings errors should be added inside the $sanitize_callback function defined in
     3119 * register_setting() for a given setting to give feedback about the submission.
     3120 *
     3121 * By default messages will show immediately after the submission that generated the error.
     3122 * Additional calls to settings_errors() can be used to show errors even when the settings
     3123 * page is first accessed.
     3124 *
     3125 * @global array $wp_settings_errors Storage array of errors registered during this pageload
     3126 *
     3127 * @param string $setting Slug title of the setting to which this error applies
     3128 * @param string $id Slug-name to identify the error. Used as part of 'id' attribute in HTML output.
     3129 * @param string $message The formatted message text to display to the user (will be shown inside styled <div> and <p>)
     3130 * @param string $type The type of message it is, controls HTML class. Use 'error' or 'updated'.
     3131 */
     3132function add_settings_error( $setting, $id, $message, $type = 'error' ) {
     3133        global $wp_settings_errors;
     3134
     3135        $new_error = array(
     3136                'setting' => $setting,
     3137                'title' => $title,
     3138                'message' => $message,
     3139                'type' => $type
     3140        );
     3141        $wp_settings_errors[] = $new_error;
     3142}
     3143
     3144/**
     3145 * Fetch settings errors registered by add_settings_error()
     3146 *
     3147 * Checks the $wp_settings_errors array for any errors declared during the current
     3148 * pageload and returns them.
     3149 *
     3150 * If changes were just submitted ($_GET['updated']) and settings errors were saved
     3151 * to the 'settings_errors' transient then those errors will be returned instead. This
     3152 * is used to pass errors back across pageloads.
     3153 *
     3154 * Use the $sanitize argument to manually re-sanitize the option before returning errors.
     3155 * This is useful if you have errors or notices you want to show even when the user
     3156 * hasn't submitted data (i.e. when they first load an options page, or in admin_notices action hook)
     3157 *
     3158 * @global array $wp_settings_errors Storage array of errors registered during this pageload
     3159 *
     3160 * @param string $setting Optional slug title of a specific setting who's errors you want.
     3161 * @param boolean $sanitize Whether to re-sanitize the setting value before returning errors.
     3162 * @return array Array of settings errors
     3163 */
     3164function get_settings_errors( $setting = '', $sanitize = FALSE ) {
     3165        global $wp_settings_errors;
     3166
     3167        // If $sanitize is true, manually re-run the sanitizisation for this option
     3168        // This allows the $sanitize_callback from register_setting() to run, adding
     3169        // any settings errors you want to show by default.
     3170        if ( $sanitize )
     3171                sanitize_option( $setting, get_option($setting));
     3172
     3173        // If settings were passed back from options.php then use them
     3174        // Ignore transients if $sanitize is true, we dont' want the old values anyway
     3175        if ( $_GET['updated'] AND get_transient('settings_errors')) {
     3176                $settings_errors = get_transient('settings_errors');
     3177                delete_transient('settings_errors');
     3178        // Otherwise check global in case validation has been run on this pageload
     3179        } elseif (count( $wp_settings_errors )) {
     3180                $settings_errors = $wp_settings_errors;
     3181        } else {
     3182                return;
     3183        }
     3184
     3185        // Filter the results to those of a specific setting if one was set
     3186        if ( $setting ) {
     3187                foreach ( (array) $settings_errors as $key => $details )
     3188                        if ( $setting != $details['setting'] )
     3189                                unset( $settings_errors[$key] );
     3190        }
     3191        return $settings_errors;
     3192}
     3193
     3194/**
     3195 * Display settings errors registered by add_settings_error()
     3196 *
     3197 * Part of the Settings API. Outputs a <div> for each error retrieved by get_settings_errors().
     3198 *
     3199 * This is called automatically after a settings page based on the Settings API is submitted.
     3200 * Errors should be added during the validation callback function for a setting defined in register_setting()
     3201 *
     3202 * The $sanitize option is passed into get_settings_errors() and will re-run the setting sanitization
     3203 * on its current value.
     3204 *
     3205 * The $hide_on_update option will cause errors to only show when the settings page is first loaded.
     3206 * if the user has already saved new values it will be hidden to avoid repeating messages already
     3207 * shown in the default error reporting after submission. This is useful to show general errors like missing
     3208 * settings when the user arrives at the settings page.
     3209 *
     3210 * @param string $setting Optional slug title of a specific setting who's errors you want.
     3211 * @param boolean $sanitize Whether to re-sanitize the setting value before returning errors.
     3212 * @param boolean $hide_on_update If set to true errors will not be shown if the settings page has already been submitted.
     3213 * @return <type>
     3214 */
     3215function settings_errors ( $setting = '', $sanitize = FALSE, $hide_on_update = FALSE ) {
     3216
     3217        if ($hide_on_update AND $_GET['updated']) return;
     3218       
     3219        $settings_errors = get_settings_errors( $setting, $sanitize );
     3220
     3221        if ( !is_array($settings_errors) ) return;
     3222
     3223        foreach ( $settings_errors as $key => $details ) {
     3224                $css_id = 'setting-error-' . $details['title'];
     3225                $css_class = $details['type'] . ' fade settings-error';
     3226                $output .= "<div id='$css_id' class='$css_class'> \n";
     3227                $output .= "<p><strong>{$details['message']}</strong></p>";
     3228                $output .= "</div> \n";
     3229        }
     3230        echo $output;
     3231}
     3232
     3233/**
    30813234 * {@internal Missing Short Description}}
    30823235 *
    30833236 * @since unknown
  • wp-includes/formatting.php

     
    23802380
    23812381        switch ($option) {
    23822382                case 'admin_email':
    2383                         $value = sanitize_email($value);
     2383                        if (!$value = sanitize_email($value))
     2384                                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'));
     2385                       
    23842386                        break;
    23852387
    23862388                case 'thumbnail_size_w':