Подробно про страницы настроек WordPress

Давно уже меня просили написать пост про создание страниц настроек с использованием Settings API, но всё никак не доходили до него руки. Ну что же, вот и дошли.

Прежде всего не забывайте, страницы настроек и настройки темы в Theme Customizer – две разные вещи. Если вы хотите знать, чем они отличаются и заодно научиться добавлять опции в Theme Customizer, то рекомендую этот урок.

Кроме того, свои приколы по добавлению страниц настроек есть у WooCommerce – об этом тоже на сайте отдельный урок.

Обычно, в похожих уроках авторы любят рассматривать все функции по отдельности — в таких случаях их ну очень неудобно копировать и можно запутаться что к чему. Поэтому в конце урока я решил предоставить вам полностью готовый к использованию код — просто вставьте его сами знаете, куда, и страница настроек сразу появится у вас в админке. Ну а потом вы уже сможете отредактировать в ней поля, либо добавить свои собственные.

Ну, а если вам хочется разобраться в этом вместе со мной по шагам, то погнали!

1. Создание страницы в админке для новых опций сайта

Хорошая новость – вы можете разместить вашу страницу настроек абсолютно где угодно в меню в админке – это может быть как элемент меню верхнего уровня, так и вложенный в уже существующий элемент меню, например в «Инструменты» или в «Настройки».

Рассмотрим оба случая!

Для этого можно воспользоваться функцией add_menu_page() и только ей. Про неё следует помнить, что она должны находиться внутри хука admin_menu , иначе у вас просто возникнут проблемки.

Если у вас возникают вопросы по параметрам функции, то они все у меня описаны в документации функции add_menu_page().

При вставке этого кода, надеюсь, вы знаете, куда, у вас появится меню в админке и даже отдельная страница для него:

Но вполне возможно, что для добавления своей страницы настроек вы не хотите перегружать админку новыми элементами, поэтому вы можете захотеть добавить свою страницу настроек в уже какой-то существующий пункт меню – логичнее всего конечно же в «Настройки».

Для этого вы можете воспользоваться функцией add_submenu_page(), либо какой-либо из альтернативных функций, в зависимости от того, куда будете добавлять вложенный пункт меню.

Пробуем видоизменить код выше:

2. Подготовка страницы настроек под Settings API

Теперь, вместо того, чтобы выводить «привет» в нашей колбэк-функции, мы добавим в неё следующее:

В этом коде я использовал функции:

– возвращает заголовок страницы, взятый из параметров, которые мы передали в add_menu_page(). – для вывода скрытых полей страницы настроек, – эта функция непосредственно выводит секции и поля настроек, – для вывода кнопки сохранения настроек.

После обновления кода, страница примет вид:

Если на этом моменте вам уже стало страшно, то возможно стоит рассмотреть возможность создания страниц настроек при помощи плагина Carbon Fields. Урок об этом тоже есть!

3. Добавляем поле

Для добавления поля нам понадобится целых… 5 функций! 🙃

– она зарегистрирует нашу опцию,
1. любая функция очистки значения поля перед сохранением в базу данных, например я буду использовать функцию absint(), – добавит секцию (и подзаголовок, если нужно) на страницу настроек, – добавит поле,
2. любая кастомная функция для вывода HTML-поля.

На самом деле может показаться, что очень жёстко, но давайте попробуем!

Все эти функции весело отправляются в хук admin_init .

printf() и sprintf() это две PHP-функции, которые очень часто используются в разработке на WordPress. Вы можете почитать о них в PHP-документации. Например в примере выше мы видим первый параметр, который представляет собой строку-шаблон, в ней все вхождения %s и %d будут заменены на следующие параметры функции в соответствующем порядке, где %s должно представлять собой строковое значение, а %d – целое число. Кроме того, я добавил очистку absint(), потому что мы также должны исключить отрицательные числа.

Если в предыдущем коде вы сделаете несколько изменений, а именно:

То наша опция слайдера появится в Настройки > Медиафайлы:

Также вы можете воспользоваться и другими идентификаторами стандартных страниц настроек:

• general – Общие,
• writing – Написание,
• reading – Чтение,
• discussion – Обсуждение,
• media – Медиафайлы,
• permalink – Постоянные ссылки;

4. Уведомление о сохранении

Последний шаг – при нажатии на кнопку «Сохранить изменения» неплохо бы сообщить об этом пользователю!

Получаем совсем красоту в итоге:

5. Валидация полей

Также не могу не рассказать вам про то, как настроить валидацию полей. Для этого нам понадобится использовать две функции settings_errors() для вывода ошибок и add_settings_error() для добавления ошибки. Обе эти функции привязаны к друг к другу при помощи первого параметра-идентификатора, который должен совпадать, например settings_errors( 'hey-error' ) и add_settings_error( 'hey-error', . ) . Попробуем это реализовать!

Прежде всего подготовим в нашем коде место для вывода ошибок. Для этого я возьму код из второй части урока и добавлю там функцию settings_errors() непосредственно в то место, где я хочу вывести ошибки! Например:

Здесь мы возвращаемся к функции register_setting() из третьего шага, в котором мы регистрировали опцию настроек:

Меняем название функции очистки (у меня это absint()) на любую кастомную функцию, которую мы сейчас и создадим: