Зміст циклу статей «Повне керівництво по налаштуванню WordPress API»:
Коли справа доходить до розробки тем і плагінів (Themes & Plugins) під WordPress, то розробник стикається з тим, що є багато різних способів створити меню, параметри і функціональність для перевірки введених даних.
Але заковика в тому, що в дійсності є тільки один по-справжньому правильний спосіб зробити це в WordPress – він полягає у використанні Settings API (API налаштувань).
Дана серія статей якраз націлена на створення повноцінного гіда, який би розкривав всі переваги використання WordPress Settings API. Таким чином, виходить цілісне керівництво по правильній розробці тем і плагінів.
У першій статті цього циклу, ми оглядово познайомилися з Settings API і розібралися, чому це важливо. У цій же статті, ми збираємося зануритися в API і дізнатися, як отримати максимальну користь з наданих їм можливостей.
Ми дізнаємося про основні одиницях WordPress – секціях (sections), поля (fields) і налаштування (settings) – а також про те, як включити їх в панель управління WordPress (Dashboard).
Секції, поля та налаштування
До того, як писати якийсь код, було б розумно розібратися з трьома основними компонентами WordPress Settings API:
- Поля – індивідуальні опції, що з’являються на сторінках меню. Поле-це мінімальна одиниця. Поля можуть бути представлені текстовими полями (text box), радіокнопками (radio button), чекбоксами (checkbox) і так далі. Значення полів зберігаються в базі даних WordPress;
- Секції – логічно згруповані поля. Коли ви працюєте з великою кількістю полів, то дуже допомагає групування полів за спільною ознакою. Секції якраз її і надають. Більш того, якщо ваш продукт включає в себе багато сторінок налаштувань, то кожна секція може представляти собою посилання на окрему сторінку або вкладку;
- Налаштування – реєструються після визначення полів і секцій. Налаштування є комбінацією полів і секцій, які в них входять.
Не турбуйтеся, якщо ви все ще не зрозуміли що, по суті, являють собою перелічені вище основні компоненти. Далі ми розглянемо кожну складову і наведемо приклад вихідного коду, який реалізує дану функціональність.
Пісочниці (Sandbox) для наших налаштувань
Щоб почати боротьбу зі звіром по імені Settings API, давайте налаштуємо стандартну тему, яка буде використовуватися в цій і подальших статтях циклу. Весь вихідний код, зрозуміло, буде викладений на загальний огляд.
Перейдіть до папки themes вашої локально встановленої копії WordPress, і створіть нову порожню директорію з ім’ям WordPress-Settings-Sandbox (sandbox по-англійськи – пісочниця, тобто це місце, де безпечно можна грати з налаштуваннями, звідси і така назва).
У ній слід створити такі файли:
- style.css – файл стилів для нашої теми. Включає в себе мета-інформацію для нашої теми. Це обов’язковий файл для WordPress;
- index.php – стандартний шаблон для нашої теми. Поки що залишимо його порожнім. Обов’язковий файл WordPress;
- functions.php – в цьому файлі ми будемо виробляти основну частину роботи. Ми будемо заповнювати його в міру просування по циклу статей.
Додайте наступний код у файл style.css:
/*
Theme Name: Пісочниця для створюваних налаштувань WordPress
Theme URI: Ваш URI-адресу
Description: Найпростіша тема для демонстрації WordPress Settings API.
Author: Ваше ім’я
Author URI: Адресу вашого веб-сайту
Версія: 0.1
License: Текст файл ліцензії, за якою поширюється даний продукт
Copyright 2013 Ваше ім’я (ваша email-адреса)
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, версії 2, as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
Далі, додайте наступні рядки в файл index.php:
Повноцінний гід по Settings API | Тема Sandbox
Заголовок Sandbox
Тут вміст теми.
© Всі права захищені.
Зауважте, що розмітка, представлена вище, надзвичайно проста і її не рекомендується використовувати в якості основи для розробки своїх тем. Вона створена спеціально для цієї серії статей і призначена для вивчення Settings API.
Оновіть сторінку налаштувань теми в панелі керування, і ви побачите, що з’явилася нова тема під назвою «Sandbox». Активуйте її.
Тепер можна починати.
Перші кроки у створенні опцій
Зверніть увагу, що для індексного шаблону, представленого вище, ми визначили три специфічних області вмісту: заголовок — header, вміст – content і підвал (футер) — footer. Використовуючи Settings API, давайте створимо секцію «Загальні», що включає в себе три поля, кожне з яких відноситься до одного з визначених вище контейнерів.
Але перш, перерахуємо порядок наших дій. Він такий:
- Визначення секції, яка буде використовуватися для групування полів;
- Додавання трьох полів – по одному для кожного контейнера – в секцію, визначену вище;
- Реєстрація налаштувань за допомогою WordPress API.
Щоб уникнути громіздкого коду і переконатися, що ми врахували всі правила, ми будемо робити все по кроках.
Створення секції
Щоб знайти нашу секцію опцій «Загальні», нам треба використовувати функцію add_settings_section з Settings API. Згідно WordPress Codex, функція add_settings_section вимагає три аргументи:
- ID – унікальний ідентифікатор визначається секції. Це значення, яке буде використовуватися для реєстрації кожного поля усередині секції. Можете визначити цей ідентифікатор за своїм розсудом, але я рекомендую робити ім’я осмисленим для зручності читання коду;
- Title – значення, яке буде відображатися вгорі адміністративної панелі WordPress, коли користувачі будуть працювати з цією опцією;
- Callback – ім’я функції, яка буде виводити вміст сторінки на екран опцій. Це може бути використане для різних цілей. У найпростішому випадку, для надання набору інструкцій або описів на вашій сторінці опцій;
- Page – це значення використовується для того, щоб повідомити WordPress, на якій сторінці потрібно відобразити ваші опції. В наступних статтях циклу, ми будемо використовувати це для того, щоб додати опції на створені вами сторінки. А зараз, як ми додамо їх на існуючу сторінку «Загальні налаштування» (General Options).
Після цього, йдемо далі і визначаємо нашу секцію. Уважно прочитайте коментарі до нижченаведеним кодом. Ми додамо його в наш файл functions.php.
Трохи про код, представленому в статтях: не варто просто копіювати і вставляти його. Приділіть час його прочитання, подивіться які аргументи записані в представлених API-функції, а також ознайомтеся з коментарями, щоб переконатися, що ви всі добре зрозуміли:
Виберіть, які секції ви хочете показувати на сторінці.
‘;
} // Кінець функції sandbox_general_options_callback
?>
Звичайно, зараз там немає на що дивитися, але перейдіть в меню «Налаштування» (Settings) і перейдіть на вкладку «Загальні» (General). Прокрутіть сторінку вниз і побачите нову, створену нами секцію опцій.
Ви можете додати цю секцію на будь-яку сторінку в меню «Налаштування» (Settings). У прикладі вище, ми передали параметр general останнім у функцію add_settings_section, але при бажанні, ви можете вставити туди заголовок будь-якої іншої сторінки. Ось список сторінок в меню «Налаштування» (Settings) і відповідне їм унікальне ім’я:
- Загальні (General), «general»;
- Написання (Writing), «writing»;
- Читання (Reading), «reading»;
- Обговорення (Discussion), «discussion»;
- Медіафайли (Media), «media»;
- Приватність (Privacy), «privacy»;
- Постійні посилання (Permalinks), «permalink».
Додавання полів
Тепер, коли наша секція визначена, можна додати кілька опцій. Як ви пам’ятаєте, в нашому індексному файлі ми визначили три специфічних контейнера: header, content і footer.
Далі, у наступних статтях циклу опцій буде більше, а поки що ми створимо перемикач видимості кожної із зазначених секцій.
Аналогічно тому, як ми робили перед реалізацією секції, зараз ми перерахуємо кроки, необхідні для створення перемикача видимості контейнерів з вмістом:
- Спочатку визначимо три опції – по одній для кожного контейнера;
- Потім, як елемент інтерфейсу для перемикача ми використовуємо чекбокс (checkbox).
Зараз саме час познайомити вас з першим полем. Але для його додавання нам потрібно розглянути функцію add_settings_field. Вона приймає шість параметрів (чотири обов’язкових, два – немає):
- ID – ідентифікатор поля. Буде використовуватися, щоб отримувати та зберігати значення, отримані з теми. Рекомендується назвати осмисленим ім’ям для спрощення читання коду;
- Title – назва поля, яке буде відображатися на сторінці опцій в адміністративній панелі. Воно повинно бути зрозумілим, щоб бути легко зрозумілим користувачами;
- Callback – ім’я функції, що використовується для виводу;
- Page – вказує, на якій сторінці потрібно відобразити дану опцію. Можна додати як на одну з наявних, так і на свою власну сторінку;
- Section – посилання на секцію, яку ви створили з допомогою функції add_settings_section. Це значення збігається з ID, який ви визначили при створенні секції. Параметр опціональний;
- Arguments – Масив аргументів, що передається у функцію виклику. Це корисно, якщо є додаткова інформація, яку ви хочете включити до виведення вашого елемента інтерфейсу. Параметр опціональний.
Тепер, давайте визначимо наше перше поле. Його призначенням буде, як згадувалося вище, перемикання видимості контейнерів в шаблоні.
Ми викличемо функцію add_settings_field нижче функції add_settings_section всередині функції ініціалізації, яку ми створили вище. Виглядає це так:
// Далі, ми створимо поле для перемикання видимості контейнерів в шаблоні
add_settings_field(
‘show_header’, // Ідентифікатор, використовуваний для ідентифікації поля всередині теми
‘Контейнер header’, // Мітка ліворуч від елемента інтерфейсу
‘sandbox_toggle_header_callback’, // Ім’я функції, відповідальної за виведення елемента інтерфейсу
‘general’, // Сторінка, на яку буде виведена опція
‘general_settings_section’, // Ім’я секції, якій належить полі
array( // Масив-аргументів, що передається callback-функції. В нашому випадку просто опис.
‘Ввімкніть цю опцію, щоб відобразити контейнер header.’
)
);
Далі, визначаємо callback-функції для вищенаведеної функції. Вона використовується для виведення чекбокса і опису в адміністративній панелі:
/* ———————————————————————— *
* callback-функції для полів
* ————————————————————————
*/
/**
* Ця функція виводить елемент інтерфейсу для зміни видимості контейнера header.
*
* Вона отримує масив аргументів, в якому першим йде опис,
* що буде відображено після чекбокса.
*/
function sandbox_toggle_header_callback($args) {
// Зауважте, що ідентифікатор і ім’я атрибута елемента повинні збігатися із зазначеними у функції add_settings_field
$html = «;
// Беремо перший елемент масиву і додаємо його до мітки чекбокса
$html .= » . $args[0] . «;
echo $html;
} // кінець функції sandbox_toggle_header_callback
Зверніть увагу на коментарі і не турбуйтеся, що деякі атрибути вам незрозумілі (наприклад, виклик функції checked). Пізніше, в наступних статтях, ми повернемося до кожного елемента вводу, так і до використовується допоміжним функціям.
Отже, до теперішнього моменту ваш файл functions.php повинен виглядати так:
Виберіть, які секції ви хочете показувати на сторінці.
‘;
} // Кінець функції sandbox_general_options_callback
/* ———————————————————————— *
* Callback-функції для полів
* ————————————————————————
*/
/*
* Ця функція виводить елемент інтерфейсу для зміни видимості контейнера header.
* Вона отримує масив аргументів, в якому першим йде опис, яке буде відображено після чекбокса.
*/
function sandbox_toggle_header_callback($args) {
//Ідентифікатор і ім’я атрибута елемента повинні збігатися із зазначеними у функції add_settings_field
$html = «;
// Беремо перший елемент масиву і додаємо його до мітки чекбокса
$html .= » . $args[0] . «;
echo $html;
} // Кінець функції sandbox_toggle_header_callback
?>
Оновіть сторінку «Загальні налаштування» (General Settings). Ви побачите чекбокс з міткою «Контейнер header» та з описом поруч.
На жаль, це значення поки не зберігається в базі даних.
Реєстрація наших налаштувань
Щоб зберегти значення наших полів в базі даних, нам потрібно зареєструвати їх в WordPress. Зробити це досить просто – потрібно просто використовувати функцію register_setting. Вона приймає три аргументи (два обов’язкових, один опціональний):
Option Group ім’я групи опцій. Це може бути як група, пропонована WordPress, так і ID, який ми визначили при створенні власної секції. Обов’язковий;
Option Name – ID реєстрованого поля. У нашому випадку, ми реєструємо одне поле, але якщо б ми реєстрували кілька, то треба було б викликати цю функцію для кожного поля окремо. Обов’язковий;
Callback – ім’я функції, яка буде викликана перед збереженням у базу даних. Цей аргумент виходить за рамки даного циклу статей, проте ближче до кінця серії ми його трохи торкнемося. Опціональний Аргумент.
Давайте зареєструємо налаштування, яку ми тільки що створили. Погляньте на код, представлений нижче. Додайте його прямо після виклику функції add_settings_field в секції ініціалізації, яку ми визначили раніше. Це один з найбільш простих фрагментів (уривків коду) у статті:
// Реєструємо поля у WordPress
register_setting(
‘general’,
‘show_header’
);
Спробуйте – натисніть спочатку на чекбокс, а потім на кнопку «Зберегти зміни» і побачите, як при оновленні сторінки, стан чекбокса збереглося.
Досить легко, вірно?
Додавання решти двох опцій
Нам все ще потрібно додати опції для перемикання видимості контейнерів content і footer. Вони будуть аналогічні функціям для контейнера header.
Спочатку, давайте визначимо поле для управління відображенням контейнера content. Для цього спочатку викличемо функцію add_settings_field:
add_settings_field(
‘show_content’,
‘Контейнер content’,
‘sandbox_toggle_content_callback’,
‘general’,
‘general_settings_section’,
array(
‘Ввімкніть цю опцію, щоб відобразити контейнер content.’
)
);
Тепер визначимо callback-функції:
function sandbox_toggle_content_callback($args) {
$html = «;
$html .= » . $args[0] . «;
echo $html;
} // Кінець функції sandbox_toggle_content_callback
Далі, визначимо поле для відображення контейнера footer:
add_settings_field(
‘show_footer’,
‘Контейнер footer’,
‘sandbox_toggle_footer_callback’,
‘general’,
‘general_settings_section’,
array(
‘Ввімкніть цю опцію, щоб відобразити контейнер footer.’
)
);
Створимо callbackфункцію для цього поля:
function sandbox_toggle_footer_callback($args) {
$html = «;
$html .= » . $args[0] . «;
echo $html;
} // Кінець функції sandbox_toggle_footer_callback
Нарешті, зареєструємо два нових поля в WordPress. Два виклику цих функцій слід помістити нижче функції ініціалізації, яка була визначена раніше.
register_setting(
‘general’,
‘show_content’
);
register_setting(
‘general’,
‘show_footer’
);
Фінальна версія файлу functions.php повинна виглядати так:
Виберіть, які секції ви хочете показувати на сторінці.
‘;
} // Кінець функції sandbox_general_options_callback
/* ———————————————————————— *
* Callback-функції для полів
* ————————————————————————
*/
/*
* Ця функція виводить елемент інтерфейсу для зміни видимості контейнера header.
* Вона отримує масив аргументів, в якому першим йде опис, яке буде відображено після чекбокса.
*/
function sandbox_toggle_header_callback($args) {
//Ідентифікатор і ім’я атрибута елемента повинні збігатися із зазначеними у функції add_settings_field
$html = «;
// Беремо перший елемент масиву і додаємо його до мітки чекбокса
$html .= » . $args[0] . «;
echo $html;
} // Кінець функції sandbox_toggle_header_callback
function sandbox_toggle_content_callback($args) {
$html = «;
$html .= » . $args[0] . «;
echo $html;
} // Кінець функції sandbox_toggle_content_callback
function sandbox_toggle_footer_callback($args) {
$html = «;
$html .= » . $args[0] . «;
echo $html;
} // Кінець функції sandbox_toggle_footer_callback
?>
Тепер поновіть сторінку «Загальні налаштування» (General Settings) і ви побачите три повноцінно працюють чекбокса.
Використання API в темі
Яка користь від опцій, якщо ми не можемо їх використовувати в нашій темі або плагіні? Нам потрібно мати можливість зчитувати значення для управління нашими опціями.
Щоб це зробити, нам потрібно використовувати функцію get_option. Ця функція приймає два аргументи (один обов’язковий і один опціональний):
- Option ID – ідентифікатор поля, для якого ви намагаєтеся отримати значення. Обов’язковий Аргумент;
- Default Option – значення, яке буде передано, якщо функція поверне null (наприклад, у випадку, якщо опція не знайдено в базі даних). Опціональний Аргумент.
Для початку, давайте спробуємо перемкнути видимість контейнера header. У файлі index.php, створеному раніше, знайдіть код містить параметр id зі значенням header. Ось він:
Заголовок Sandbox
Далі, зробимо виклик функції get_option з використанням умовної конструкції if. Якщо умова дорівнює true (це у випадку, якщо опція була відзначена на сторінці «Основні налаштування» (General Settings)), то елемент буде відображений; в іншому випадку – він виводитися не буде.
Заголовок Sandbox
Після цього, знову зайдіть на сторінку «Загальні налаштування» (General Settings), і встановіть опцію для приховування контейнера header і поновіть сторінку в браузері. Контейнер header видно не буде.
Далі, просто повторюємо цей процес для двох, що залишилися контейнерів. Нам необхідно обернути контейнери content і footer умовними конструкціями, які будуть порівнювати результат роботи функції get_option.
Погляньте:
Тут вміст теми.
© Всі права захищені.
Відвідайте сторінку «Загальні налаштування» (General Settings), відмітьте всі три чекбокса і поновіть сторінку в браузері. Відображенням кожного контейнера тепер можна управляти окремо.
Далі, сторінки меню
На сьогодні досить! Ми розглянули всі функції, необхідні для створення нових секцій, полів і параметрів в WordPress. Звичайно, є ще дуже багато всього, що потрібно обговорити.
У наступній статті циклу, ми розберемося, як додати власні меню і сторінки в панель управління WordPress.
Переклад статті «The Complete Guide To The WordPress Settings API, Part 2: Sections, Fields, and Settings» був підготовлений дружною командою проекту Сайтостроение від А до Я.
