add_settings_error() WP 3.0
Регистрирует сообщение о проверке опции, чтобы позднее показать это сообщение пользователю. Обычно такое сообщение - это ошибка проверки данных.
Функция является частью API настроек.
Используйте, чтобы вывести сообщение пользователю, что проверка значение опции не была пройдена например, при: ошибки проверки поля или если не заполнено обязательное поле и т.д.
По умолчанию сообщение выводятся автоматически для всех подстраниц в разделе "Настройки". Но если изменение опций выводятся на других страницах, которые регистрируются функциями: add_menu_page() или add_submenu_page(), то сообщения об обновлении опций или ошибке, не будут показаны автоматически.
Чтобы их показать, нужно просто добавить в код вывода страницы настроек функцию settings_errors(), обычно её нужно добавлять сразу после вывода заголовка страницы:
<h2>Заголовок страницы настроек</h2> <?php settings_errors(); ?>
add_settings_error() обычно используется внутри функции проверки значений опции: см. параметр $sanitize_callback
в register_setting().
Хуков нет.
Возвращает
Ничего не возвращает.
Использование
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; }