Зміст циклу статей «Повне керівництво по налаштуванню WordPress API»:
У третій частині цієї серії статей, ми познайомилися з різними функціями для створення меню, які надає WordPress API. Якщо ви читали всі статті і виконували всі приклади, то знаєте, що ми вже створили сторінку налаштувань для нашої теми за допомогою функції add_theme_page.
Хоча створення меню і підменю не відноситься до Settings API, воно відіграє важливу роль у побудові функціональності плагінів і/або тим.
У цій статті, ми створимо нове меню в панелі управління WordPress, яке зробить опції нашої теми доступні скрізь, а не тільки з меню опцій «Зовнішній вигляд» (Appearance).
Примітка: стаття припускає, що ви вже знайомі з Settings API і опціями теми. Якщо ви початківець розробник, то рекомендується спочатку ознайомитись з попередніми статтями циклу.
Погляд на API
Так як ми вже познайомилися з усіма функціями, що стосуються пунктів меню в WordPress, нам не треба їх перераховувати. Замість цього, ми будемо розглядати конкретні практичні приклади, і говорити про те, як їх використовувати в реальній роботі.
До того, як розглянути приклади, давайте визначимося з тим, що ми збираємося робити далі:
- Створення меню верхнього рівня для опцій нашої теми;
- Додавання підменю для закладки «Опції відображення»;
- Додавання підменю для закладки «Опції соціальних мереж».
Для реалізації даного плану нам знадобиться дві функції:
- add_menu_page для створення меню верхнього рівня;
- add_submenu_page для створення підменю.
Ми дізнаємося про параметри, що приймаються кожною функцією та призначення їх використання в нашій темі.
Робота в даній статті заснована на цій версії шаблону Sandbox. Переконайтеся, що ваша версія збігається з нею.
Меню верхнього рівня
Насамперед, ми хочемо створити меню верхнього рівня. Цей пункт меню буде показаний відразу після пункту «Налаштування» (Settings) в адміністративній панелі WordPress і буде виконувати кілька завдань:
Функція приймає сім аргументів — перші п’ять обов’язкові, а два інші — ні:
- Page_title – текст, що відображається в заголовку вікна браузера;
- Menu_title – текст, що відображається у назві пункту меню;
- Capability – група користувачів, що мають доступ до даного меню;
- Menu_slug – унікальне значення, яке ідентифікує це меню. Необхідно для реєстрації підменю;
- Function_name – ім’я функції, що викликається при натисканні по пункту меню;
- Icon_url – шлях до іконки, які відображатимуться поряд з назвою меню;
- Position – розташування створюваного пункту меню по відношенню до вже наявних.
В нашій подальшій роботі ми зосередимося тільки на перших п’яти параметрах. Позиціонування меню буде розглянуто в кінці статті.
Спочатку, створимо виклик функції add_menu_page. Згідно WordPress Codex, пункт меню в адміністративну панель може бути доданий за допомогою хука admin_menu.
Раніше, ми вже писали функцію, яка додає пункт меню нашої теми у меню «вигляд» (Appearance). Якщо бути точним, то функція sandbox_example_theme_menu виглядала так:
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’);
У цьому коді функція реєструвалася за допомогою хука admin_menu. Завжди дуже важливо зберігати логіку в послідовності написання функцій.
Так як функція, зареєстрована за допомогою згаданого хука, вже є і надає схожий функціонал, то просто додамо наш новий пункт меню в цю функцію.
Додайте виклик функції add_menu_page прямо під викликом вище:
add_menu_page(
‘Тема Sandbox’, // Текст, що виводиться в заголовку браузера
‘Тема Sandbox’, // Текст, що виводиться в назві пункту меню
‘administrator’, // Група користувачів, що мають доступ до даного пункту меню
‘sandbox_theme_menu’, // Ідентифікатор, використовуваний для створення підменю
‘sandbox_theme_display’ // Callback-функція, яка використовується для виводу даного меню
);
Як бачите, ми зареєстрували меню, яке буде відображати текст «Тема Sandbox» в заголовку браузера і назві пункту меню. Ми дали доступ до цього меню тільки адміністраторам і присвоїли йому унікальний ID — sandbox_theme_parent_menu. Далі ми будемо використовувати це значення.
Важливо прояснити одну річ: ми визначили sandbox_theme_display як функцію, що викликається при натисканні на пункт меню. У третій частині ми використовували цю функцію (і модифікували її у п’ятої частини). Вона відповідальна за висновок нашої сторінки опцій з закладками.
Передаючи її ім’я функції add_menu_page, ми виводимо для пункту меню сторінку опцій за замовчуванням.
Тепер ми готові почати створення підменю, але спочатку давайте переконаємося, що ваші функції виглядають ось так:
function sandbox_example_theme_menu() {
add_theme_page(
‘Тема Sandbox’, // Текст в заголовку браузера
‘Тема Sandbox’, // Текст самого пункту меню в бічному меню WordPress
‘administrator’, // Групи користувачів, які мають доступ до даного меню
‘sandbox_theme_options’, // Унікальний ID — псевдонім – для даного пункту меню
‘sandbox_theme_display’ // Ім’я функції, що використовується для виводу пункту меню на екран
);
add_menu_page(
‘Тема Sandbox’, // Текст, що виводиться в заголовку браузера
‘Тема Sandbox’, // Текст, що виводиться в назві пункту меню
‘administrator’, // Група користувачів, що мають доступ до даного пункту меню
‘sandbox_theme_menu’, // Ідентифікатор, використовуваний для створення підменю
‘sandbox_theme_display’ // Callback-функція, яка використовується для виводу даного меню
);
} // Кінець функції sandbox_example_theme_menu
Додавання підменю
Процес додавання підменю дуже схожий на що використовується для меню, за винятком того, що підменю належить вже створеному пункту меню. Функції API для реєстрації підменю також аналогічні меню.
Функція приймає шість аргументів, обов’язковими з яких є перші п’ять, а решту — опціональний:
- Parent_slug – унікальний ідентифікатор батьківського пункту меню; у нашому випадку, sandbox_theme_menu;
- Page_title – текст, що відображається в заголовку вікна браузера, при активації даного підпункту меню;
- Menu_title – назва підпункту меню в адміністративній панелі;
- Capability – група користувачів, що мають доступ до даного пункту меню;
- Menu_slug – унікальний ID для цього підпункту;
- Function_name – функція, що викликається при активації цього підпункту.
Функція досить проста в роботі. Нам необхідно створити два підпункти меню – один для «Опцій відображення» і один для «Опцій соціальних мереж».
Опції відображення
Спочатку, давайте створимо підменю для опцій відображення. Додайте наступний блок коду прямо під викликом функції add_menu_page, який був визначений вище:
add_submenu_page(
‘sandbox_theme_menu’, // Унікальний ID пункту меню верхнього рівня, якому належить даний підпункт
‘Опції відображення’, // Текст, що виводиться в заголовку браузера
‘Опції відображення’, // Текст, що виводиться в назві пункту меню
‘administrator’, // Група користувачів, що мають доступ до даного пункту меню
‘sandbox_theme_display_options’, // Ідентифікатор, використовуваний для створення даного пункту всередині меню
‘sandbox_theme_display’ // Callback-функція, яка використовується для виводу даного меню
);
Всі параметри, що передаються функції повинні бути чітко визначено, за винятком function_name, переданого останнім. Зауважте, що це значення збігається зі значенням, указаним у виклику add_menu_page. Але різниця є, як ви вважаєте?
Група налаштувань «Опції відображення» є стандартною при вході в меню опцій, тому вона повинна відобразитися при активації меню верхнього рівня налаштувань нашої теми, а також вкладки «Параметри відображення».
Важлива особливість WordPress: після того, як ви додали перший підпункт меню, WordPress буде відображати ДВА підпункти меню верхнього рівня, один з яких дублює функції пункту меню верхнього рівня, а інший належить до створеного підпунктом.
Я звернув на це увагу, тому що бачив розробників, яких вводила в ступор ця особливість. Але це особливість саме WordPress, а не помилка у коді.
Опції соціальних мереж
Додавання пункту меню опцій для соціальних мереж, практично повністю аналогічно кроків для додавання пункту опцій відображення. Ми просто змінимо значення для заголовка, назви пункту меню і сторінки, що викликається при виборі пункту.
Спочатку здійснимо виклик функції add_submenu_page. Це буде виглядати так:
add_submenu_page(
‘sandbox_theme_menu’,
‘Опції соціальних мереж’,
‘Опції соціальних мереж’,
‘administrator’,
‘sandbox_theme_social_options’,
‘sandbox_theme_display’
);
Збережіть зміни, поновіть вікно адміністративної панелі і побачите підпункт «Опції соціальних мереж» доступний у меню «Тема Sandbox». Однак при кліці на цьому пункті показуються «Опції відображення».
Ми зіткнулися з невеликим випробуванням: нам потрібно вибрати закладку «Опції соціальних мереж» при кліці на відповідному підпункті.
Переробка функціоналу закладок
У нас кілька варіантів як прив’язати наш пункт підменю до закладки:
- Можна оголосити нову функцію, яка б виводила опції соціальних мереж. Це вимагає виконання деякої додаткової роботи по створенню нової функції, налаштування закладок таким чином, щоб не порушити зручність інтерфейсу, а також не допустити збільшення обсягу коду;
- Ми можемо змінити існуючу функцію sandbox_theme_display для прийому опціональних параметрів і потім використовувати анонімну функцію, викликавши add_submenu_page і передавши в неї параметри через цю анонімну функцію.
Обоє цих варіанта нам підходять. Однак, особисто я краще перероблю функцію, ніж буду збільшувати обсяг коду, тому далі буде розглянуто саме цей спосіб.
Переопределим функцію sandbox_theme_display. Передамо їй опціональний аргумент, який буде використовуватися для вказівки закладки, яку ми хочемо виділити. Знайдіть наступний шматок коду у файлі functions.php:
function sandbox_theme_display() {
/* Приклад створений спеціально для даної статті. */
} // Кінець функції sandbox_theme_display
Оновіть заголовок таким чином, щоб функція приймала один аргумент і повертала значення null, якщо цей аргумент не визначено:
function sandbox_theme_display( $active_tab = null ) {
/* Приклад створений спеціально для даної статті. */
} // Кінець функції sandbox_theme_display
Якщо ви новачок в PHP, то можете прочитати про аргументи за умовчанням тут.
З попередньої статті ви пам’ятаєте, що наша функція відображення зчитує встановлене значення рядка запиту. Ми хочемо залишити цей механізм робочим, але потрібно враховувати, що параметр може бути переданий також і в функцію.
Щоб виконати таку модифікацію, знайдіть наступний блок коду функції sandbox_theme_display:
$active_tab = isset( $_GET[ ‘tab’ ] ) ? $_GET[ ‘tab’ ] : ‘display_options’;
Даний код займається обробкою параметрів в рядку запиту. Щоб врахувати нові додаткові параметри, нам потрібен алгоритм, який спочатку перевіряє, чи заданий параметр рядка запиту; якщо ні, то перевіряє, чи заданий аргумент функції для відображення опцій соціальних мереж; якщо ні, то за замовчуванням воно покаже закладку «Опції відображення».
Змініть код вище, додавши в нього наступну умовну конструкцію:
if( isset( $_GET[ ‘tab’ ] ) ) {
$active_tab = $_GET[ ‘tab’ ];
} else if( $active_tab == ‘social_options’ ) {
$active_tab = ‘social_options’;
} else {
$active_tab = ‘display_options’;
} // Кінець конструкції if/else
Кінцева версія коду виглядає наступним чином:
function sandbox_theme_display( $active_tab = null ) {
?>
Опції теми Sandbox
Опції відображення
Опції соціальних мереж
Але це ще не все. Хоча ми налаштували висновок опцій соціальних мереж, але не викликали функцію з використанням аргументів. Для цього потрібно перевизначити функцію add_submenu_page. На даний момент функція виглядає так:
add_submenu_page(
‘sandbox_theme_menu’,
‘Опції соціальних мереж’,
‘Опції соціальних мереж’,
‘administrator’,
‘sandbox_theme_social_options’,
‘sandbox_theme_display’
);
Нам потрібно змінити параметри відображення і передати правильні значення висновок опцій соціальних мереж. Для цього створимо анонімну функцію:
add_submenu_page(
‘sandbox_theme_menu’,
‘Social Options’,
‘Social Options’,
‘administrator’,
‘sandbox_theme_social_options’,
create_function null, ‘sandbox_theme_display( «social_options» );’ )
);
Якщо ви новачок в PHP, то прочитайте про функції create_function, а також про анонімних функціях. Це дуже потужні інструменти, хоча їх розгляд виходить за рамки цієї статті.
Підсумковий вид функції sandbox_example_theme_menu виглядає так:
function sandbox_example_theme_menu() {
add_theme_page(
‘Тема Sandbox’, // Текст в заголовку браузера
‘Тема Sandbox’, // Текст самого пункту меню в бічному меню WordPress
‘administrator’, // Групи користувачів, які мають доступ до даного меню
‘sandbox_theme_options’, // Унікальний ID — псевдонім – для даного пункту меню
‘sandbox_theme_display’ // Ім’я функції, що використовується для виводу пункту меню на екран
);
add_menu_page(
‘Тема Sandbox’, // Текст, що виводиться в заголовку браузера
‘Тема Sandbox’, // Текст, що виводиться в назві пункту меню
‘administrator’, // Група користувачів, що мають доступ до даного пункту меню
‘sandbox_theme_menu’, // Ідентифікатор, використовуваний для створення підменю
‘sandbox_theme_display’ // Callback-функція, яка використовується для виводу даного меню
);
add_submenu_page(
‘sandbox_theme_menu’, // Унікальний ID пункту меню верхнього рівня, якому належить даний підпункт
‘Опції відображення’, // Текст, що виводиться в заголовку браузера
‘Опції відображення’, // Текст, що виводиться в назві пункту меню
‘administrator’, // Група користувачів, що мають доступ до даного пункту меню
‘sandbox_theme_display_options’, // Ідентифікатор, використовуваний для створення даного пункту всередині меню
‘sandbox_theme_display’ // Callback-функція, яка використовується для виводу даного меню
);
add_submenu_page(
‘sandbox_theme_menu’,
‘Опції соціальних мереж’,
‘Опції соціальних мереж’,
‘administrator’,
‘sandbox_theme_social_options’,
create_function null, ‘sandbox_theme_display( «social_options» );’ )
);
} // Кінець функції sandbox_example_theme_menu
add_action(‘admin_menu’, ‘sandbox_example_theme_menu’);
Висновок
На даний момент у нашої теми є підпункти для кожної закладки, доступні з меню верхнього рівня. Важливо зауважити, що існує безліч думок про те, як створювати меню в адміністративній панелі WordPress.
Добре спроектована система меню може поліпшити ваш продукт, але при неправильному підході вона також може заплутати користувача, змішавшись зі стандартними пунктами меню, або позиція ваших пунктів може бути заміщена іншими доповненнями.
Немає абсолютно правильного або абсолютно неправильного способу створення меню, просто треба бути уважним і обережним у розміщенні ваших пунктів. Якщо жодна з наявних в WordPress меню підходить за змістом, то розміщуйте підменю туди.
У наступній статті ми поговоримо про різні елементи введення, з допомогою яких можуть бути представлені опції в темі WordPress, а також як проводити валідацію і очищення даних до їх серіалізації (приміщення в базу даних).
Переклад статті «The Complete Guide To The WordPress Settings API, Part 6: Menu Pages» був підготовлений дружною командою проекту Сайтостроение від А до Я.
