Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Theme Development
Code

Повна Інструкція по WordPress Settings API, Частина 2: Розділи, Поля і Налаштування

by
Difficulty:BeginnerLength:LongLanguages:
This post is part of a series called The Complete Guide to the WordPress Settings API.
The WordPress Settings API, Part 1: What It Is, Why It Matters
The WordPress Settings API, Part 3: All About Menus

Ukrainian (українська мова) translation by Alexander Kompanets (you can also view the original English article)

Коли доходить до розробки Тем та Плагінів WordPress, існує багато різноманітних шляхів, якими розробники створюють свої меню, параметри та функції перевірок.  Справа в тому, що насправді існує тільки один спосіб зробити це правильно в рамках WordPress:  Settings API.

Ця серія націлена стати повним довідником, як скористатися перевагою WordPress Settings API, щоб ви мали єдине місце, де зібрані рекомендації з правильної розробки ваших тем і плагінів.

В першій статті в цій серії ми широко роздивились Settings API і чому це важливо. Тут ми збираємося почати занурення в API і дізнатись, як скористатися перевагами всього того, що він пропонує.

Ми поглянемо на основоположну одиницю параметрів WordPress - розділи, поля та налаштування - і як включити їх в рідну панель управління WordPress.


У Розділах, Полях та Налаштуваннях

Перед тим, як ми перейдемо до написання будь-якого коду, важливо зрозуміти три основні складові WordPress Settings API.

  1. Поля - це самостійні параметри, що з'являються на сторінках меню. Поля відповідають дійсним елементам на екрані. Тобто, поле управляється текстовим полем, радіо перемикачем, прапорцем, і т. д. Поля представляють значення, що зберігається в базі даних WordPress.
  2. Розділи - це логічне згрупування полів. Кожного разу, коли ви працюєте із декількома полями, швидше за все ви збираєтеся згрупувати споріднені параметри разом - Розділи представляють таке групування. Крім того, якщо ваша робота включає в себе декілька сторінок адміністрування, кожен розділ часто відповідає своїй окремій сторінці меню (хоча, ви можете додати їх до існуючих розділів).
  3. Налаштування реєструються після того, як ви визначили обидва Поля та Розділи. Думайте про Налаштування як про поєднання Полів і Розділів, до якого вони належать.

Зараз не хвилюйтеся, якщо вам до цих пір щось незрозуміло, про будь-який з основних компонентів. Ми збираємося глибоко поглянути на кожен компонент, поряд зі зразком вихідного коду, який зв'яже все до купи.


Пісочниця для Наших Налаштувань

Для того, щоб розпочати програмування із Settings API, давайте встановимо основну тему, яка зможе бути використана у цій статті та серії, що залишається. Весь вихідний код також доступний на GitHub.

У вашій локальній установці WordPress перейдіть в каталог "themes", створіть новий, пустий каталог і назвіть його "WordPress-Settings-Sandbox". Додайте наступні три файли:

  • style.css – Це таблиця стилів для теми. Вона включає в себе всю мета-інформацію теми. WordPress потребує її
  • index.php – Це стандартний шаблон теми. На початку він може бути порожнім. WordPress потребує його
  • functions.php – Тут ми будемо робити більшість своєї роботи. Його ми будемо заповнювати на шляху всієї нашої інструкції.

Додайте наступний код до style.css:

Далі, додайте наступний код до index.php:

Зверніть увагу, що вищезазначена розмітка надзвичайно проста і я не рекомендую використовувати її як основу для розробки тем. Вона приведена спеціально для цієї серії статей і просто є засобом, за допомогою якого ми будемо зчитувати значення з Settings API.

На екрані адміністрування Теми, оновіть сторінку і ви маєте побачити нову тему Sandbox, що з'явилась. Давайте, активуйте її.

Theme Selection

На даний час ми готові почати.


Наш перший набір Параметрів

Помітьте, в згаданому вище шаблоні index ми визначили три конкретних області вмісту: заголовок, зміст і нижній колонтитул. Використовуючи Settings API, давайте створимо "Загальний" розділ, що містить три поля, кожний з яких відповідає одному з особливих областей змісту, що ми щойно визначили.

Перед написанням коду, я завжди вважаю корисним перерахувати те, що мені потрібно зробити. В цьому випадку, ми повинні зробити наступне:

  • Визначити розділ, що буде використано для групування кожного поля
  • Додати три поля - одне для кожної області вмісту - до розділу, що визначений вище
  • Зареєструвати налаштування за допомогою WordPress API.

Для того, щоб уникнути будь-яких масивних блоків коду і щоб переконатися, що ми охоплюємо всі наші основи, ми будемо брати кожен із зазначених пунктів один за одним.

Створення розділу

Для того, щоб знайти наш «Загальний» розділ параметрів, ми необхідно буде використати функцію add_settings_section із Settings API. Згідно Кодексу WordPress, add_settings_section потребує три аргументи:

  • ID – Це унікальний ідентифікатор цього конкретного розділу. Зверніть увагу, що це значення, яке буде використовуватись для реєстрації кожного поля в межах цього розділу. Ви можете назвати його як завгодно, проте я рекомендую, щоб ви зробили його таким, щоб можна було прочитати.
  • Title – Це значення буде відображатися у верхній частині сторінки в панелі налаштувань WordPress, коли користувачі працюють з вашими параметрами.
  • Callback – Це ім'я функції, яку ми визначимо для генерування тексту на екрані для функції. Вона може використовуватись для різноманітного функціоналу. У найпростішому випадку її можна використати для надання набору інструкцій або опису для вашої сторінки параметрів.
  • Page – Це значення, що використовується для сповіщення WordPress, на якій саме сторінці мають відображатися ваші параметри. У наступній статті ми будемо використовувати його, щоб додати параметри до наших власних веб-сторінок. Тепер ми будемо додавати його для існуючої сторінки Загальні Параметри.

Разом з тим давайте продовжимо і визначимо наш розділ. Погляньте на наступний коментований код. Ми добавимо це до нашого файлу functions.php.

Слово про фрагменти коду в цій серії: не треба просто копіювати і вставляти цей код. Знайдіть час, щоб прочитати кожен рядок, побачити, як аргументи відповідають кожній функції API, що ми охоплюємо та слідкуйте відповідним коментарям, щоб переконатися, що ви звикли до того, що ми робимо:

Має сенс? Взагалі-то кажучи, здається, що не дуже, але перейдіть до меню Налаштування і натисніть на Загальні. Прокрутіть в кінець сторінки, і ви повинні побачити ваш новий розділ параметрів.

General Settings

Ви можете додати цей розділ до будь-яких сторінок в меню Налаштування. У наведеному вище прикладі ми вже пройшли "Загальні", як останній параметр у add_settings_section, але якщо ви хотіли б додати його до іншої сторінки, ви можете передати її заголовок. Ось посилання для кожної зі сторінок Налаштування та відповідної клавіші:

  • Загальне, "general"
  • Написання, "writing"
  • Читання, "reading"
  • Обговорення, "discussion"
  • Медіа, "media"
  • Приватність, "privacy"
  • Постійні посилання, "permalink"

Додавання Полів

Тепер, коли ми визначили розділ, ми можемо представити кілька налаштувань. Нагадаємо, що в нашому шаблоні index ми визначили три конкретних елемента контейнера: заголовок, зміст і нижній колонтитул.

Хоча ми будемо представляти більше параметрів протягом усієї цієї серії, сьогодні ми збираємося представити спосіб перемикання видимості кожного з наведених вище елементів.

Так само, як ми це зробили з розділом налаштувань, я хотів би перерахувати те, що саме нам потрібно зробити перед тим, як написати будь-який код. З тих пір, як ми збираємося переключати кожну з областей змісту...

  • Нам потрібно мати три налаштування - по одному для кожної області змісту
  • Оскільки ми перемикаємо видимість, ми можемо використовувати прапорець в якості нашого елементу інтерфейсу

Зараз ми готові представити перше поле налаштування. Щоб це зробити, ми використаємо функцію add_settings_field Ця функція приймає шість параметрів (чотири обов'язкових, два необов'язкових). Вони наступні:

  • ID – ID самого поля. Він використовуватиметься для збереження та отримання значення по всій темі. Я рекомендую назвати його чимось значимим для поліпшення читаності вашого коду.
  • Title – Це значення відносить заголовок до поля параметрів на сторінці адміністрування. Воно має бути зрозумілим, так як буде прочитане кінцевими користувачами.
  • Callback – Це назва функції, яка використовується для надання фактичного елементу інтерфейсу, з яким будуть взаємодіяти користувачі.
  • Page – Подібно до секції, що ми виклали, цей параметр визначає, на якій сторінці повинен знаходитися цей параметр. Якщо ви лише представляєте один єдиний параметр, ви можете додати його до існуючої сторінки, а не до розділу, який ви визначили.
  • Section – Це відноситься до розділу, що ви створили за допомогою функції add_settings_section. Це значення - це ID, що ви визначили, коли створювали розділ. Цей параметр не обов'язковий.
  • Arguments – Це масив аргументів, що передаються в функцію зворотнього виклику. Це корисно, якщо присутня додаткова інформація, яку ви хочете включити до представлення вашого елементу параметра. Цей параметр не обов'язковий.

З урахуванням наведеного, давайте пройдемо і визначимо наше перше поле налаштування. Зокрема, ми будемо представляти параметр для перемикання видимості заголовка.

По-перше, ми зробимо виклик add_settings_field одразу після виклику функції add_settings_section у функції ініціалізації, що ми писали в першій частині уроку. Продивіться кожний рядок і коментар для кожного з параметрів:

Далі ми визначимо зворотній виклик, що відноситься до згаданої вище функції . Цей зворотній виклик використовується для візуалізації прапорцю і опису на сторінці адміністрування:

Що стосується прапорця, зверніть увагу на коментарі, але не сильно турбуйтеся про деякі атрибути, які ви не впізнаєте (наприклад, виклик функції checked()). Пізніше в цій серії ми збираємося подивитися на кожний елемент вводу та їх відповідні допоміжні функції.

Наразі ваш файл functions.php повинен виглядати так:

Тепер оновіть сторінку Загальні Параметри. Ви маєте побачити ваш прапорець із міткою "Header" та описом поруч прапорця.

First Option

На жаль, вона поки що фактично не зберігає значення в базу даних.

Реєстрування Наших Налаштувань

Для того, щоб наші поля для реально збереглися до бази даних, ми повинні зареєструвати їх за допомогою WordPress. Зробити це відносно легко - нам лише необхідно використати перевагу функції register_setting.

Ця функція приймає три аргументи (два обов'язкових, один необов'язковий):

  • Option Group – Це насправді ім'я групи параметрів. Це може бути як існуюча група параметрів, представлена WordPress, або ID, що ми визначили, коли створювали свій власний розділ налаштувань. Цей параметр обов'язковий.
  • Option Name – Це ID поля, яке ми реєструємо. У нашому випадку ми реєструємо лише одне поле, але якщо б ми реєстрували декілька полів, ми повинні були б визивати цю функцію для кожного поля, що ми реєструємо. За мить ми подивимося на це більш ретельно. Цей аргумент є обов'язковим.
  • Callback – Цей аргумент вимагає ім'я функції, що буде визвана перед збереженням даних до бази даних. Цей аргумент виходить за рамки цієї статті, але ми будемо використовувати його до закінчення серії. Цей аргумент не є обов'язковим.

Тепер давайте зареєструємо параметр, який ми тільки-но створили. Погляньте на код нижче. Додайте цей рядок коду безпосередньо під визовом add_settings_field у функції ініціалізації, котру ми визначили раніше у статті. Це можливо найлегший з усіх фрагментів, яким ви будете слідувати у цій статті:

Спробуйте - перевірте прапорець, клацніть 'Save Changes' та зверніть увагу, що коли сторінка оновлюється, параметр змінився. Зніміть прапорець, збережіть і дивіться, як він збережеться.

Saved Option

Досить просто, правда?

Додаємо Останні Два Параметри

Нам все ще потрібно представити параметри для перемикання видимості області вмісту та області нижнього колонтитулу. Це робиться майже так само, як ми налаштували опцію для перемикання заголовку.

По-перше, давайте визначимо поле для показу змісту. Це буде йти під першим визовом add_settings_field:

Та давайте встановимо функцію зворотнього виклику:

Далі, давайте встановимо поле для показу нижнього колонтитулу:

І, також, встановимо зворотній виклик для цього поля:

Нарешті, давайте зареєструємо ці два нові поля з WordPress. Ці два виклики функцій йдуть до низу функції ініціалізації, що ми визначили раніше у статті.

Остаточна версія functions.php має виглядати наступним чином:

Теперь оновіть сторінку Загальні Налаштування і помітьте, що ви маєте всі три повністю функціональні прапорці.

Final Options

Читання API

Що хорошого у налаштуваннях, якщо ми не можемо скористатися ними у нашій темі або нашому плагіні? Ми повинні мати можливість зчитувати значення для того, щоб правильно керувати нашими новими параметрами.

Щоб це робити, нам потрібно використовувати функцію get_option. Ця функція приймає два аргументи (один обов'язковий, один необов'язковий):

  • Option ID – Цей аргумент є ID поля для значення, що ви намагаєтесь отримати. Аргумент є обов'язковим.
  • Default Option – Це значення функція поверне, якщо функція повертає пусте значення (таке, як у випадку, якщо параметр не знайдено у базі даних). Цей аргумент не обов'язковий.

Спочатку, давайте спробуємо перемикнути видимість заголовку. У шаблоні index, котрий ми створили раніше у цій статті, знайдіть елемент з ID header. Він має виглядати ось так:

Потім, давайте зробимо виклик get_option у контексті умови. Якщо умова має значення істина (тобто, параметр було вибрано на сторінці Загальні Налаштування), то елемент буде відображено; в іншому випадку елемент не відображатиметься.

Після цього перейдіть до сторінки Загальні Параметри, оберіть налаштування приховати елемент заголовка та оновіть вашу домашню сторінку. Елемент заголовку більше не повинен відображатися.

Тепер просто існує необхідність повторити процес також для елемента зміст і нижній колонтитул. Нам необхідно обернути елементи вмісту та колонтитула з умовами, яки обчислять результат визову get_option.

Погляньте:

Поверніться до сторінки Загальні Параметри, увімкніть кожен прапорець та оновіть сторінку теми. Ваші елементи сторінки мають кожен перемикатися незалежно один від одного.


Наступне, Сторінки Меню

Це все поки-що! Ми оглянули усі функції, необхідні для впровадження нових розділів, полів та параметрів у WordPress. Звісно, що ще є багато чого, що необхідно розглянути. 

У наступній статті ми поглянемо на те, як додати власні елементи меню до меню WordPress, і як ми можемо представити наші власні сторінки до панелі налаштувань WordPress.


Пов'язані ресурси

Ми розглянули багато матеріалу в цій статті. Ось посилання на все те, що ми використовували протягом всієї цієї статті.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.