settings_errors

Display settings errors registered by add_settings_error().

Description

settings_errors( (string) $setting = '', (constant) $sanitize = false, (bool) $hide_on_update = false ); 

Part of the Settings API. Outputs a div for each error retrieved by errors" title="get_settings_errors" class="code function">errors" title="get_settings_errors" class="code function">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 errors" title="get_settings_errors" class="code function">errors" title="get_settings_errors" class="code function">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.

Parameters (3)

0. $setting — Optional. (string) => ''
Slug title of a specific setting who's errors you want.
1. $sanitize — Optional. (constant) => false
Whether to re-sanitize the setting value before returning errors.
2. $hide_on_update — Optional. (bool) => false
If set to true errors will not be shown if the settings page has already been submitted.

Usage

  1. if ( !function_exists( 'settings_errors' ) ) { 
  2. require_once ABSPATH . '/wp-admin/includes/template.php'; 
  3.  
  4. // Optional slug title of a specific setting who's errors you want. 
  5. $setting = ''; 
  6.  
  7. // Whether to re-sanitize the setting value before returning errors. 
  8. $sanitize = false; 
  9.  
  10. // If set to true errors will not be shown if the settings page has 
  11. // already been submitted. 
  12. $hide_on_update = false; 
  13.  
  14. // NOTICE! Understand what this does before running. 
  15. $result = settings_errors($setting, $sanitize, $hide_on_update); 
  16.  

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/template.php  
  1. function settings_errors( $setting = '', $sanitize = false, $hide_on_update = false ) { 
  2.  
  3. if ( $hide_on_update && ! empty( $_GET['settings-updated'] ) ) 
  4. return; 
  5.  
  6. $settings_errors = get_settings_errors( $setting, $sanitize ); 
  7.  
  8. if ( empty( $settings_errors ) ) 
  9. return; 
  10.  
  11. $output = ''; 
  12. foreach ( $settings_errors as $key => $details ) { 
  13. $css_id = 'setting-error-' . $details['code']; 
  14. $css_class = $details['type'] . ' settings-error notice is-dismissible'; 
  15. $output .= "<div id='$css_id' class='$css_class'> \n"; 
  16. $output .= "<p><strong>{$details['message']}</strong></p>"; 
  17. $output .= "</div> \n"; 
  18. echo $output;