Функция settings_errors() в WordPress является частью API настроек и предназначена для отображения ошибок, зарегистрированных с помощью add_settings_error(). Она выводит HTML-код ошибок на экран, позволяя пользователям видеть, что пошло не так при сохранении настроек.
settings_errors( string $setting = '', bool $sanitize = false, bool $hide_on_update = false )
- $setting (строка, необязательный): Идентификатор конкретной настройки, ошибки которой вы хотите вывести. По умолчанию — пустая строка, что означает вывод всех зарегистрированных ошибок.
- $sanitize (логический, необязательный): Если установлен в
true, функция повторно очищает значение настройки перед возвращением ошибок. По умолчанию —false. - $hide_on_update (логический, необязательный): Если установлено в
true, ошибки не будут отображаться, если страница настроек уже была отправлена. Это полезно для отображения общих ошибок, когда пользователь возвращается на страницу настроек. По умолчанию —false.
Пример 1: Вывод ошибок для конкретной настройки
В этом примере мы выведем все сообщения об ошибках, зарегистрированные для настройки с идентификатором custom_setting_error.
/**
* Отображает все сообщения, зарегистрированные для 'custom_setting_error'
*/
function display_custom_admin_notices() {
settings_errors( 'custom_setting_error' );
}
add_action( 'admin_notices', 'display_custom_admin_notices' );
Этот код подключает функцию к хуку admin_notices, который автоматически вызывается при загрузке страниц в админке WordPress. Если при обработке настроек возникли ошибки, они будут отображены пользователю.
Пример 2: Использование параметров очистки и скрытия
Теперь мы рассмотрим пример, в котором будем использовать параметры $sanitize и $hide_on_update. Мы хотим, чтобы ошибки очищались и не отображались, если страница уже была отправлена.
/**
* Отображает ошибки настройки с параметрами очистки и скрытия
*/
function custom_admin_notices_with_sanitize() {
settings_errors( 'custom_setting_error', true, true );
}
add_action( 'admin_notices', 'custom_admin_notices_with_sanitize' );
В этом примере:
$settingустановлен наcustom_setting_error, что означает, что будут отображены только ошибки, связанные с этой настройкой.$sanitizeустановлен вtrue, чтобы перед отображением ошибок значение настройки было очищено.$hide_on_updateустановлен вtrue, чтобы скрыть сообщения, если пользователь уже отправил страницу настроек.
Как работает settings_errors()
Функция settings_errors() извлекает ошибки, зарегистрированные с помощью add_settings_error(), и выводит их на экран в виде HTML-блоков. Сообщения добавляются в процессе валидации данных, когда пользователь пытается сохранить настройки.
Ошибки регистрируются во время обработки данных на этапе валидации в функции, переданной в register_setting(). Например:
/**
* Валидация настройки
*/
function validate_custom_setting( $input ) {
if ( empty( $input ) ) {
add_settings_error( 'custom_setting_error', 'custom_setting_empty', 'Настройка не может быть пустой.', 'error' );
}
return $input;
}
Здесь, если пользователь оставит поле пустым, будет зарегистрирована ошибка, которую затем можно будет отобразить с помощью settings_errors().
Заключение
Функция settings_errors() является мощным инструментом для управления ошибками на страницах настроек в WordPress. Она позволяет разработчикам выводить сообщения об ошибках, помогая пользователям корректировать свои действия и обеспечивая лучший пользовательский опыт. Благодаря простоте использования и возможности кастомизации, settings_errors() — это необходимый компонент при разработке админских интерфейсов в WordPress.