Зміст циклу статей «Повне керівництво по налаштуванню WordPress API»:

  • Повне керівництво по налаштуванню WordPress API, частина 1: вступ
  • Повне керівництво по налаштуванню WordPress API, частина 2: секції, поля та налаштування
  • Повне керівництво по налаштуванню WordPress API, частина 3: все про створення меню
  • Повне керівництво по налаштуванню WordPress API, частина 4: опції теми
  • Повне керівництво по налаштуванню WordPress API, частина 5: навігація закладочная
  • Повне керівництво по налаштуванню WordPress API, частина 6: сторінки меню
  • Повне керівництво по налаштуванню WordPress API, частина 7: валідація, очищення та елементи вводу
  • Повне керівництво по налаштуванню WordPress API, частина 8: валідація, очищення та елементи вводу
  • Після того, як ми зрозуміли, чому нам варто використовувати Settings API, вивчили способи створення секцій, полів і налаштувань, а також налаштували нашу тему Sandbox, можна приступати до розробки функціоналу і дослідженню API.

    У цій статті ми познайомимося із способами взаємодії з системою меню WordPress. Важливо зауважити, що система меню НЕ є частиною Settings API, але тісно з ним пов’язана. Тому нам слід з нею познайомитися.

    По мірі того, як наші теми і/або плагіни стають більш складними, необхідно знати про всі можливі способи їх показу в адміністративній панелі WordPress. У даній статті будуть показані різні функції меню WordPress та поради, коли їх використовувати, коли викликати і яку вибрати в тій чи іншій ситуації.

    Типи меню

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

    Меню верхнього рівня

    На сторінки з налаштуваннями є посилання в меню, яке ви бачите відразу при вході в WordPress. Це меню знаходиться ліворуч і включає в себе різні підпункти.

    Щоб створити в цьому меню посилання на свою власну сторінку, слід використовувати функцію add_menu_page.

    Скоро ми приступимо до практичного прикладу, але спершу давайте розглянемо цю функцію – вона приймає сім аргументів (п’ять обов’язкових, два опціональних):

    • Page Title – заголовок, що з’являється у верхній частині вікна браузера, коли активовано дане меню;
    • Menu Title – текст пункту меню. Зробіть його коротким і лаконічним, інакше воно не поміститься у вікні меню;
    • Capability – визначає, які користувачі можуть мати доступ до цього пункту меню;
    • Menu Slug – унікальний ідентифікатор пункту меню в WordPress. Також він потрібен для реєстрації в цьому пункті меню підпунктів;
    • Callback – функція, що виводить вміст сторінки, пов’язаної з цим пунктом меню. Це може бути HTML-рядок або посилання на зовнішній файл;
    • Icon URL – шлях до іконки, яка повинна відображатися поруч пунктом меню. Ви можете використовувати одну з наявних в WordPress іконок або вказати власну. Опціональний аргумент;
    • Position – визначає позицію, де цей пункт буде знаходитися в списку елементів меню. За замовчуванням, пункт меню з’являється знизу, але можна вказати позицію вище або нижче щодо наявних пунктів.

    Давайте розберемося з невеликим прикладом. Знайдіть файл functions.php і додайте в нього дві функції:

    function sandbox_create_menu_page() {
    }
    add_action(‘admin_menu’, ‘sandbox_create_menu_page’);
    function sandbox_menu_page_display() {
    }

    Ми використовували функцію admin_menu як хука, щоб зареєструвати наш пункт меню. Ця функція спрацьовує відразу після виведення меню, і WordPress виводить наш пункт меню серед всіх інших.

    Далі, налаштуємо наш пункт меню. За нашою традицією, прийнятою в попередніх статтях циклу, складемо план дій:

    • Додамо нове меню в нижню частину меню зліва в адміністративній панелі WordPress;
    • Задамо для нього ім’я в межах нашої теми;
    • Зробимо пункт меню доступним для всіх користувачів;
    • Створимо пункт меню БЕЗ іконки.

    Досить просто, чи не так? Отже, приступимо до створення меню. Ще раз раджу вам не просто копіювати і вставляти код з статті, а досконально розбиратися в тому, як він працює:

    /**
    * Додаємо нове меню верхнього рівня в нижню частину адміністративного меню WordPress.
    */
    function sandbox_create_menu_page() {
    add_menu_page(
    ‘Опції Sandbox’, // Текст заголовка для даного меню в браузері
    ‘Sandbox’, // Текст пункту меню
    ‘administrator’, // Користувачі, які можуть бачити цей пункт меню
    ‘sandbox’, // Унікальний ідентифікатор даного пункту меню
    ‘sandbox_menu_page_display’ // Ім’я функції, що викликається при відображенні меню
    );
    } // Кінець функції sandbox_create_menu_page
    add_action(‘admin_menu’, ‘sandbox_create_menu_page’);

    Тепер, поновіть ваш адміністративне меню в WordPress і побачите новий пункт. При натисканні на нього, з’явиться порожня сторінка.

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

    function sandbox_menu_page_display() {
    // Створення тега заголовка в стандартному контейнері «wrap»
    $html =’
    ‘;
    $html .= ‘

    Sandbox

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо розмітку на висновок в браузер
    echo $html;
    } // Кінець функції sandbox_menu_page_display

    В кінцевому підсумку, код повинен виглядати так:

    /**
    * Додаємо нове меню верхнього рівня в нижню частину адміністративного меню WordPress.
    */
    function sandbox_create_menu_page() {
    add_menu_page(
    ‘Опції Sandbox’, // який Відображається в браузері заголовок для даного меню
    ‘Sandbox’, // Текст пункту меню
    ‘administrator’, // Користувачі, які можуть бачити цей пункт меню
    ‘sandbox’, // Унікальний ідентифікатор даного пункту меню
    ‘sandbox_menu_page_display’ // Ім’я функції, що викликається при відображенні меню
    );
    } // Кінець функції sandbox_create_menu_page
    add_action(‘admin_menu’, ‘sandbox_create_menu_page’);
    function sandbox_menu_page_display() {
    // Створення тега заголовка в стандартному контейнері «wrap»
    $html =’
    ‘;
    $html .= ‘

    Sandbox

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо розмітку на висновок в браузер
    echo $html;
    } // Кінець функції sandbox_menu_page_display

    Крім усього іншого, слід зауважити, що функція add_menu_page зіставляє кожен пункт меню зі сторінкою меню. Ми розглянемо це питання докладніше трохи пізніше.

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

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

    Підменю

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

    Підменю можуть бути дочірніми по відношенню до вже наявних у WordPress пунктам меню, а не тільки по відношенню до створених вами.

    До того як почати розбирати код, давайте познайомимося з функцією add_submenu_page і параметрами, які вона приймає:

    • Parent Slug – вказує на ідентифікатор батьківського пункту меню, якому створюваний підпункт буде належати. У нашому випадку, ми будемо використовувати псевдонім, визначений вище;
    • Page Title – текст, що відображається в заголовку вікна браузера;
    • Menu Title – текст, який буде виведений в меню зліва;
    • Capability – група користувачів, що мають доступ до цього підпункту;
    • Menu Slug – унікальний ID цього підпункту меню, використовуваний для ідентифікації всередині WordPress;
    • Callback – функція, яка запускається при активації підпункту.

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

    Почнемо з реєстрації підпунктів у створеному нами раніше пункті меню. План наших дій:

    • Реєстрація підпункту меню, який ми будемо додавати;
    • Він повинен відображати текст «Опції»;
    • Він повинен бути доступним всім користувачам;
    • Він має бути БЕЗ іконки.

    Погляньте на нижченаведений код – ми додамо його прямо під функцією add_menu_page:

    add_submenu_page(
    ‘sandbox’, // Реєстрація підпункту під певним вище пунктом меню
    ‘Опції Sandbox’, // Текст заголовка браузера при активованому пункті меню
    ‘Опції’, // Текст для цього підпункту
    ‘administrator’, // Група користувачів, яким доступний цей підпункт
    ‘sandbox_options’, // Унікальний ID — псевдонім – для цього підпункту меню
    ‘sandbox_options_display’ // Функція, яка використовується для виведення вмісту цього пункту меню
    );

    Також, не забудьте визначити callbackфункцію – поки що вона порожня. Не забудьте додати в ваш файл з функціями:

    function sandbox_options_display() {
    } // кінець функції sandbox_options_display

    Коли ви поновіть вікно браузера, то побачите два підпункту меню «Sandbox». Зауважте, що WordPress створив новий пункт меню сам і прив’язав до нього певну нами callback-функції. Другий підпункт нічого не виводить при натисканні на нього.

    Щоб це виправити, давайте щось зробимо. Ми оновимо callbackфункцію так, щоб вона виглядала наступним чином:

    function sandbox_options_display() {
    // Створюємо заголовок в стандартному контейнері «wrap»
    $html =’
    ‘;
    $html .= ‘

    Опції Sandbox

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо створену розмітку браузеру
    echo $html;
    } // кінець функції sandbox_options_display

    Знову оновіть вікно браузера і побачите заголовок сторінки при натисканні на підпункт «Опції».

    Ви можете також зробити так, щоб батьківський пункт і підпункт «Опції» посилалися на одне і те ж вміст. Для цього, просто оновіть callback функцію в add_menu_page кодом функції sandbox_options_display.

    Сторінки плагінів

    Якщо ви розробляєте плагін для WordPress, то у вас є кілька способів розробки інтерфейсу.

    Ваш плагін може:

    • Працювати у фоновому режимі і не вимагати для себе створення пункту меню;
    • Використовувати одну або декілька функцій, наведених вище, щоб створити пункт меню для себе;
    • Може бути включений в один з пунктів меню.

    Щоб полегшити додавання опцій у існуючі меню, WordPress API пропонує наступну функцію: add_plugins_page.

    Але не поспішайте. Якщо ви уважно вивчали приклади вище, то ви напевно помітили, що суттєвої різниці між функціями add_plugins_page і add_submenu_page немає.

    Ви праві. Функція add_plugins_page надає ту ж функціональність, що і add_submenu_page, але є дві основні відмінності:

    • Друга функція призначена спеціально для розробки плагінів;
    • Вона додає пункт меню прямо в меню «Додатки».

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

    Якщо ви теж будете так робити, то ваш код буде більш універсальний і близький до того, який використовується в самому WordPress.

    Тема розробки плагінів виходить за рамки даного циклу статей, але почасти до неї відноситься. Хоча в самій темі Sandbox не було зроблено практично ніяких змін, я хочу на прикладі показати, як використовувати розглянуту функцію.

    Для початку наведу список аргументів, які приймає функція add_plugins_page:

    • Page Title – текст, що відображається в заголовку вікна браузера;
    • Menu Title – текст пункту меню;
    • Capability – група користувачів має доступ до цього пункту;
    • Menu Slug – унікальний ID для цього пункту;
    • Callback – функція, що відображає вміст сторінки опцій.

    Нижче дано простий приклад того, як використовується ця функція. Ви можете включити його в ваш файл functions.php але це НЕ є основним в даній статті. Використовуйте цей приклад розробки плагінів.

    Для початку, налаштуємо API-функцію – при цьому використовується хук admin_menu:

    function sandbox_example_plugin_menu() {
    add_plugins_page(
    ‘Плагін Sandbox’, // Текст, що відображається в заголовку вікна браузера.
    ‘Плагін Sandbox’, // Текст, що відображається у пункті меню
    ‘administrator’, // Група користувачів, що мають доступ до даного пункту меню
    ‘sandbox_plugin_options’, // Унікальний ID — псевдонім – для даного пункту
    ‘sandbox_plugin_display’ // Ім’я callback-функції
    );
    } // Кінець функції sandbox_example_plugin_menu
    add_action(‘admin_menu’, ‘sandbox_example_plugin_menu’);

    Далі, налаштуємо функцію, що відображає сторінку налаштувань для даного пункту меню:

    function sandbox_plugin_display() {
    // Створюємо заголовок в стандартному контейнері «wrap»
    $html =’
    ‘;
    $html .= ‘

    Опції плагіна Sandbox

    ‘;
    $html .= ‘

    Поки тут немає опцій. Це просто демонстрація.

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо html-розмітку браузеру
    echo $html;
    } // Кінець функції sandbox_plugin_display

    Оновіть вашу адміністративну панель WordPress, і в меню «Плагіни» ви побачите новий, створений вами підпункт. Непогано, правда?

    Підсумковий код повинен виглядати так:

    /**
    * Додавання одиночного підпункту в пункт меню «Плагіни»
    */
    function sandbox_example_plugin_menu() {
    add_plugins_page(
    ‘Плагін Sandbox’, // Текст, що відображається в заголовку вікна браузера.
    ‘Плагін Sandbox’, // Текст, що відображається у пункті меню
    ‘administrator’, // Група користувачів, що мають доступ до даного пункту меню
    ‘sandbox_plugin_options’, // Унікальний ID — псевдонім – для даного пункту
    ‘sandbox_plugin_display’ // Ім’я callback-функції
    );
    } // Кінець функції sandbox_example_plugin_menu
    add_action(‘admin_menu’, ‘sandbox_example_plugin_menu’);
    /**
    * Відображення простий сторінки налаштувань.
    */
    function sandbox_plugin_display() {
    // Створюємо заголовок в стандартному контейнері «wrap»
    $html =’
    ‘;
    $html .= ‘

    Опції плагіна Sandbox

    ‘;
    $html .= ‘

    Поки тут немає опцій. Це просто демонстрація.

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо html-розмітку браузеру
    echo $html;
    } // Кінець функції sandbox_plugin_display

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

    Тим сторінки

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

    Основна відмінність для створюваних цими функціями підпунктів те, що вони знаходяться в меню «вигляд» (Appearance).

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

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

    • Page Title – текст, що з’являється в заголовку браузера;
    • Menu Title – текст самого пункту меню в бічному меню WordPress;
    • Capability – групи користувачів, які мають доступ до даного пункту меню;
    • Menu Slug – унікальний ID для даного пункту меню. Використовується для його ідентифікації всередині WordPress;
    • Callback – функція, яка використовується для виводу пункту меню на екран.

    Як і у попередніх випадках, ми створимо кілька прикладів, які покажуть, як включити розглянуті функції в наш проект. Зауважте, що виклик функції add_theme_page не просто може бути доданий до файлу functions.php, а, на відміну від виклику add_plugin_page, повинен перебувати тут при розробці вашої теми.

    Для початку, налаштуємо наше меню:

    function sandbox_example_theme_menu() {
    add_theme_page(
    ‘Тема Sandbox’, // Текст в заголовку браузера
    ‘Тема Sandbox’, // Текст самого пункту меню в бічному меню WordPress
    ‘administrator’, // Групи користувачів, які мають доступ до даного меню
    ‘sandbox_theme_options’, // Унікальний ID -псевдонім – для даного пункту меню
    ‘sandbox_theme_display’ // Ім’я функції, що використовується для виводу пункту меню на екран
    );
    } // Кінець функції sandbox_example_theme_menu
    add_action(‘admin_menu’, ‘sandbox_example_theme_menu’);

    Далі, визначимо функцію, що виводить на екран вміст сторінки пункту меню:

    function sandbox_theme_display() {
    // Створимо тег заголовка в контейнері «wrap» у WordPress
    $html =’
    ‘;
    $html .= ‘

    Опції теми Sandbox

    ‘;
    $html .= ‘

    Поки тут немає опцій. Це просто демонстрація.

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо розмітку браузеру
    echo $html;
    } // Кінець функції sandbox_theme_display

    Тепер оновіть адміністративну панель WordPress, наведіть вказівник миші на меню «вигляд» (Appearance) і побачите наш новий пункт меню. Все просто!

    Кінцева версія коду повинна виглядати так:

    /**
    * Ця функція створює один пункт меню в меню «вигляд» (Appearance) у WordPress
    */
    function sandbox_example_theme_menu() {
    add_theme_page(
    ‘Тема Sandbox’, // Текст в заголовку браузера
    ‘Тема Sandbox’, // Текст самого пункту меню в бічному меню WordPress
    ‘administrator’, // Групи користувачів, які мають доступ до даного меню
    ‘sandbox_theme_options’, // Унікальний ID -псевдонім – для даного пункту меню
    ‘sandbox_theme_display’ // Ім’я функції, що використовується для виводу пункту меню на екран
    );
    } // Кінець функції sandbox_example_theme_menu
    add_action(‘admin_menu’, ‘sandbox_example_theme_menu’);
    /**
    * Виводить найпростішу сторінку для визначеного вище пункту меню.
    */
    function sandbox_theme_display() {
    // Створимо тег заголовка в контейнері «wrap» у WordPress
    $html =’
    ‘;
    $html .= ‘

    Опції теми Sandbox

    ‘;
    $html .= ‘

    Поки тут немає опцій. Це просто демонстрація.

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо розмітку браузеру
    echo $html;
    } // Кінець функції sandbox_theme_display

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

    З одного боку, ви можете включити кілька підменю в головне бічне меню, з іншого ж є альтернатива – вкладочная навігація або гармошка. Це дає можливість включати свої підпункти, наприклад, в меню «вигляд» (Appearance) не додаючи ще один пункт в меню в адміністративну панель WordPress.

    Ми обговоримо це більш детально в наступній статті.

    Коли яку функцію використовувати?

    Ми розглянули основні способи створення власних сторінок опцій WordPress. Хоча ці функції НЕ є частиною Settings API, вони важливі для розуміння, так як часто використовуються.

    Але знати ці функції тільки півсправи. Так як на розробника лягає відповідальність за інтеграцію та організацію налаштувань і важливо знати, коли використовувати ту або іншу функцію.

    Хоча на це питання немає однозначної відповіді, нижче наведені деякі рекомендації:

    • Меню верхнього рівня можна додати, коли є кілька підменю, які можуть бути логічно згруповані під цим меню. Цей варіант підходить, якщо у вас є група налаштувань, яка логічно може бути поміщена в одну з наявних в WordPress меню;
    • Підменю завжди належить меню верхнього рівня – небудь створеного, або наявному. Підменю групуються під меню верхнього рівня за логічним принципом. Якщо є можливість включити ваше підменю в одну з існуючих меню верхнього рівня, то так і робіть, – не варто захаращувати меню верхнього рівня зайвими пунктами;
    • Меню плагінів використовується, коли у вас є проста, одностраничная опція. Якщо ж таких кілька сторінок, то краще створити меню верхнього рівня, або використовувати закладний навігацію, яка буде розглядатися далі;
    • Меню тим використовується при розробці ваших власних тим і надає власний набір опцій. Якщо всі опції поміщаються на одній сторінці, використовуйте API-функцію WordPress. Якщо опцій більше – використовуйте закладний навігацію.
      Зауважимо, що багато розробники тим, часто виносять сторінки налаштувань в меню верхнього рівня.

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

    Але все залежить тільки від вас, так що вносите зміни з розумінням справи. Деякі речі, які ви робите, більш важливі, ніж збереження стандартної функціональності ядра WordPress. Тому нехай вас не бентежать вищенаведені думки.

    Що далі?

    У наступній статті, ми застосуємо частина знань, отриманих щодо сторінках меню, до нашої теми Sandbox.

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

    Якщо ви ще цього не зробили, то прочитайте попередні статті їх даного циклу статей та не забудьте звірити ваш код з контрольною версією на GitHub.

    Переклад статті «The Complete Guide To The WordPress Settings API, Part 3: All About Menus» був підготовлений дружною командою проекту Сайтостроение від А до Я.