WordPress.org

Make WordPress Core

Changeset 13177


Ignore:
Timestamp:
02/17/10 17:50:42 (6 years ago)
Author:
ryan
Message:

Option validation error reporting. Props jeremyclarke. see #11474

Location:
trunk
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-admin/includes/template.php

    r13107 r13177  
    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) { 
     
    30033013 
    30043014/** 
    3005  * Add a new field to a settings page. 
     3015 * Add a new field to a section of a settings page 
     3016 * 
     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.  
    30063024 * 
    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 */ 
     
    30283048 
    30293049/** 
    3030  * {@internal Missing Short Description}} 
    3031  * 
    3032  * @since unknown 
    3033  * 
    3034  * @param unknown_type $page 
     3050 * Prints out all settings sections added to a particular settings page 
     3051 * 
     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 
     3058 * @since unknown 
     3059 * 
     3060 * @param string $page The slug name of the page whos settings sections you want to output 
    30353061 */ 
    30363062function do_settings_sections($page) { 
     
    30523078 
    30533079/** 
    3054  * {@internal Missing Short Description}} 
    3055  * 
    3056  * @since unknown 
    3057  * 
    3058  * @param unknown_type $page 
    3059  * @param unknown_type $section 
     3080 * Print out the settings fields for a particular settings section 
     3081 * 
     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 * 
     3088 * @since unknown 
     3089 * 
     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) { 
     
    30763108        echo '</tr>'; 
    30773109    } 
     3110} 
     3111 
     3112/** 
     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    if ( !isset($wp_settings_errors) ) 
     3136        $wp_settings_errors = array(); 
     3137 
     3138    $new_error = array( 
     3139        'setting' => $setting, 
     3140        'title' => $title, // @todo $title not defined. Use $id instead? 
     3141        'message' => $message, 
     3142        'type' => $type 
     3143    ); 
     3144    $wp_settings_errors[] = $new_error; 
     3145} 
     3146 
     3147/** 
     3148 * Fetch settings errors registered by add_settings_error() 
     3149 * 
     3150 * Checks the $wp_settings_errors array for any errors declared during the current 
     3151 * pageload and returns them. 
     3152 * 
     3153 * If changes were just submitted ($_GET['updated']) and settings errors were saved  
     3154 * to the 'settings_errors' transient then those errors will be returned instead. This 
     3155 * is used to pass errors back across pageloads. 
     3156 * 
     3157 * Use the $sanitize argument to manually re-sanitize the option before returning errors. 
     3158 * This is useful if you have errors or notices you want to show even when the user 
     3159 * hasn't submitted data (i.e. when they first load an options page, or in admin_notices action hook) 
     3160 * 
     3161 * @global array $wp_settings_errors Storage array of errors registered during this pageload 
     3162 * 
     3163 * @param string $setting Optional slug title of a specific setting who's errors you want. 
     3164 * @param boolean $sanitize Whether to re-sanitize the setting value before returning errors. 
     3165 * @return array Array of settings errors 
     3166 */ 
     3167function get_settings_errors( $setting = '', $sanitize = FALSE ) { 
     3168    global $wp_settings_errors; 
     3169 
     3170    // If $sanitize is true, manually re-run the sanitizisation for this option 
     3171    // This allows the $sanitize_callback from register_setting() to run, adding 
     3172    // any settings errors you want to show by default. 
     3173    if ( $sanitize ) 
     3174        sanitize_option( $setting, get_option($setting)); 
     3175 
     3176    // If settings were passed back from options.php then use them 
     3177    // Ignore transients if $sanitize is true, we dont' want the old values anyway 
     3178    if ( isset($_GET['updated']) && $_GET['updated'] && get_transient('settings_errors') ) { 
     3179        $settings_errors = get_transient('settings_errors'); 
     3180        delete_transient('settings_errors'); 
     3181    // Otherwise check global in case validation has been run on this pageload 
     3182    } elseif ( count( $wp_settings_errors ) ) { 
     3183        $settings_errors = $wp_settings_errors; 
     3184    } else { 
     3185        return; 
     3186    } 
     3187 
     3188    // Filter the results to those of a specific setting if one was set 
     3189    if ( $setting ) { 
     3190        foreach ( (array) $settings_errors as $key => $details ) 
     3191            if ( $setting != $details['setting'] ) 
     3192                unset( $settings_errors[$key] ); 
     3193    } 
     3194    return $settings_errors; 
     3195} 
     3196 
     3197/** 
     3198 * Display settings errors registered by add_settings_error() 
     3199 * 
     3200 * Part of the Settings API. Outputs a <div> for each error retrieved by get_settings_errors(). 
     3201 *  
     3202 * This is called automatically after a settings page based on the Settings API is submitted. 
     3203 * Errors should be added during the validation callback function for a setting defined in register_setting() 
     3204 * 
     3205 * The $sanitize option is passed into get_settings_errors() and will re-run the setting sanitization 
     3206 * on its current value. 
     3207 * 
     3208 * The $hide_on_update option will cause errors to only show when the settings page is first loaded. 
     3209 * if the user has already saved new values it will be hidden to avoid repeating messages already 
     3210 * shown in the default error reporting after submission. This is useful to show general errors like missing 
     3211 * settings when the user arrives at the settings page. 
     3212 * 
     3213 * @param string $setting Optional slug title of a specific setting who's errors you want. 
     3214 * @param boolean $sanitize Whether to re-sanitize the setting value before returning errors. 
     3215 * @param boolean $hide_on_update If set to true errors will not be shown if the settings page has already been submitted. 
     3216 * @return <type> 
     3217 */ 
     3218function settings_errors ( $setting = '', $sanitize = FALSE, $hide_on_update = FALSE ) { 
     3219 
     3220    if ($hide_on_update AND $_GET['updated']) return; 
     3221     
     3222    $settings_errors = get_settings_errors( $setting, $sanitize ); 
     3223 
     3224    if ( !is_array($settings_errors) ) return; 
     3225 
     3226    $output = ''; 
     3227    foreach ( $settings_errors as $key => $details ) { 
     3228        $css_id = 'setting-error-' . $details['title']; 
     3229        $css_class = $details['type'] . ' fade settings-error'; 
     3230        $output .= "<div id='$css_id' class='$css_class'> \n"; 
     3231        $output .= "<p><strong>{$details['message']}</strong></p>"; 
     3232        $output .= "</div> \n"; 
     3233    } 
     3234    echo $output; 
    30783235} 
    30793236 
  • trunk/wp-admin/options-head.php

    r12546 r13177  
    1111 
    1212wp_reset_vars(array('action', 'standalone', 'option_group_id')); 
     13 
     14settings_errors(); 
     15 
    1316?> 
    14  
    15 <?php if (isset($_GET['updated'])) : ?> 
    16 <div id="message" class="updated"><p><strong><?php _e('Settings saved.') ?></strong></p></div> 
    17 <?php endif; ?> 
  • trunk/wp-admin/options.php

    r12825 r13177  
    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 
     
    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' ]) ) { 
     
    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; 
  • trunk/wp-includes/formatting.php

    r13108 r13177  
    23812381    switch ($option) { 
    23822382        case 'admin_email': 
    2383             $value = sanitize_email($value); 
     2383            if ( !$value = sanitize_email($value) && function_exists('add_settings_error') ) 
     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 
Note: See TracChangeset for help on using the changeset viewer.