add_settings_error()
Реєструє повідомлення про перевірку опції, щоб пізніше показати це повідомлення користувачу. Зазвичай таке повідомлення – це помилка перевірки даних.
Функція є частиною API налаштувань .
Використовуйте, щоб вивести повідомлення користувачу, що перевірка значення опції не була пройдена, наприклад, при: помилки перевірки поля або якщо не заповнене обов’язкове поле і т.д.
За промовчанням повідомлення автоматично відображаються для всіх підсторінок у розділі “Параметри”. Але якщо зміни опцій виводяться на інших сторінках, які реєструються функціями: add_submenu_page() , то повідомлення про оновлення опцій або помилку не будуть показані автоматично.
Щоб їх показати, потрібно просто додати код виведення сторінки налаштувань функцію settings_errors() , зазвичай її потрібно додавати відразу після виведення заголовка сторінки:
<h2>Заголовок сторінки налаштувань</h2> <?php settings_errors(); ?>
add_settings_error() зазвичай використовується всередині функції перевірки значень опції: див. параметр $sanitize_callback в register_setting() .
Хуків немає.
Повертає
null. Нічого не вертає.
Використання
add_settings_error( $setting, $code, $message, $type );
-
$setting
(рядок) (обов’язковий) -
Назва опції, до якої належить поточна помилка. Ідентифікатор, який повинен збігатися з параметром $setting
settings_errors( $setting )або
get_settings_errors( $setting ). -
$code
(рядок) (обов’язковий) -
Ідентифікатор, назва помилки. Використовується як частина id атрибут HTML тега. Префікс
setting-error-буде доданий до назви та id атрибуту тега , що обертає повідомлення html
<div id="">. -
$message
(рядок) (обов’язковий) -
Відформатований текст повідомлення на екрані. Текст буде обернутий на
<div>теги
<p>. -
$type
(рядок) -
Якого типу це повідомлення:
errorабо
updated. Вказане тут значення буде додано до класу тега, що обертає
<div>. Щоб вказати кілька класів розділіть їх комами.
За замовчуванням: ‘error’
Приклади
#1 Збереження значення опції або виведення повідомлення про помилку
Припустимо, що ми зареєстрували опцію функцією register_setting() , в параметрі $sanitize_callback вказали функцію перевірки: sanitize_opt() .
Нижче приклад цієї функції, в якій реєструється повідомлення про перевірку та збереження значення опції:
function sanitize_opt( $value ) {
$option_name = 'my_option'; // Назва опції
$message = 'Дані успішно оновлені.';
$type = 'updated';
if( empty($value) ) {
$type = 'error';
$message = 'Поле хххх не може бути порожнім';
}
if( is_numeric($value) ){
$type = 'error';
$message = 'Поле хххх не може бути числом';
}
// Очистимо опцію
$ Value = sanitize_text_field ($ Value);
add_settings_error( $option_name, 'settings_updated', $message, $type );
if( $type === 'error' )
return get_option ($ option_name);
else
return $value;
}Функція перевірки sanitize_opt() повинна завжди повертати значення опції для збереження його в БД і WordPress сам збереже значення, що повернулося в опцію. Але що робити, якщо перевірка деяких опцій не була пройдена і потрібно зареєструвати помилку, щоб побачив її користувач, але не потрібно оновлювати значення опції в БД? У цьому випадку функція sanitize_opt() повинна повернути оригінальне значення опції. Справа в тому, що скасувати роботу оновлення опції ніяк не вийде, тому щоб не оновлювати опцію, ми можемо повернути вихідне значення опції, такий свого роду хак, який дозволяє досягти потрібного результату.
#2 Реєстрація помилок під час перевірки значень опції
Припустимо, ми створили сторінку налаштувань з двома полями форми: input і checkbox (дивіться другий приклад на сторінці API налаштувань ). Тепер нам потрібно перевірити значення цих полів і якщо вони не відповідають нормам, зареєструвати помилки, які WordPress при збереженні виведе автоматично:
/**
* функція перевірки значень опцій та реєстрації помилок, якщо потрібно!
* передбачається що ми реєстрували опцію так:
* register_setting( 'primer_group', 'primer_option', 'primer_options_check');
*/
function primer_options_check( $data ) {
$option_name = 'my_option'; // Назва опції
// перевіряємо поле input
$message = $type = null;
if ( empty( $data['input'] ) ) {
$type = 'error';
$message = 'Поле "Назва опції" не може бути порожнім';
}
elseif( preg_match( '~[0-9]~', $data['input'] ) ){
$ data['input'] = null;
$type = 'error';
$message = 'Поле "Назва опції" не може містити цифри';
}
if( $message ){
add_settings_error( 'primer_input', 'input', $message, $type );
}
// перевіряємо поле checkbox
$message = $type = null;
if( empty( $data['checkbox'] ) ){
$type = 'error';
$message = 'Чекбокс слід зазначити!';
}
if( $message ){
add_settings_error( 'primer_checkbox', 'checkbox', $message, $type );
}
if( $type === 'error' )
return get_option ($ option_name);
else
return $data;
}
нотатки
- Global. Масив. $wp_settings_errors Storage array of errors затриманий протягом цієї pageload
список змін
| З версії 3.0.0 | Введено. |
| З версії 5.3.0 | Added warning and info як можливі значення для $type . |
add settings error WP 6.0.2
function add_settings_error( $setting, $code, $message, $type = 'error' ) {
global $wp_settings_errors;
$wp_settings_errors[] = array(
'setting' => $setting,
'code' => $code,
'message' => $message,
'type' => $type,
);
}