Полное руководство по настройке WordPress API, часть 3: все о создании меню

2020-10-20

Содержание цикла статей "Полное руководство по настройке WordPress API":

Типы меню

После того, как мы поняли, почему нам стоит использовать 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 = '<div class="wrap">';  
        $html .= '<h2>Sandbox</h2>';  
    $html .= '</div>';  
      
    // Посылаем разметку на вывод в браузер  
    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 = '<div class="wrap">';  
        $html .= '<h2>Sandbox</h2>';  
    $html .= '</div>';  
      
    // Посылаем разметку на вывод в браузер  
    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 = '<div class="wrap">';
        $html .= '<h2>Опции Sandbox</h2>';  
    $html .= '</div>';
      
    // Посылаем созданную разметку браузеру  
    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 = '<div class="wrap">';
        $html .= '<h2>Опции плагина Sandbox</h2>';  
        $html .= '<p class="description">Пока тут нет опций. Это просто демонстрация.</p>';  
    $html .= '</div>';  
      
    // Посылаем 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 = '<div class="wrap">';
        $html .= '<h2>Опции плагина Sandbox</h2>';  
        $html .= '<p class="description">Пока тут нет опций. Это просто демонстрация.</p>';  
    $html .= '</div>';  
      
    // Посылаем 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 = '<div class="wrap">';  
        $html .= '<h2>Опции темы Sandbox</h2>';  
        $html .= '<p class="description">Пока тут нет опций. Это просто демонстрация.</p>';  
    $html .= '</div>';  
      
    // Посылаем разметку браузеру  
    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 = '<div class="wrap">';  
        $html .= '<h2>Опции темы Sandbox</h2>';  
        $html .= '<p class="description">Пока тут нет опций. Это просто демонстрация.</p>';  
    $html .= '</div>';  
      
    // Посылаем разметку браузеру  
    echo $html;  
      
} // Конец функции sandbox_theme_display

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

С одной стороны, вы можете включить несколько подменю в главное боковое меню, с другой же есть альтернатива – вкладочная навигация или гармошка. Это дает возможность включать свои подпункты, к примеру, в меню «Внешний вид» (Appearance) не добавляя еще один пункт в меню в административную панель WordPress.

Мы обсудим это более подробно в следующей статье.

Когда какую функцию использовать?

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

Но знать эти функции только полдела. Так как на разработчика ложится ответственность за интеграцию и организацию настроек и важно знать, когда использовать ту или иную функцию.

Хотя на этот вопрос нет однозначного ответа, ниже приведены некоторые рекомендации:

Меню верхнего уровня можно добавить, когда имеется несколько подменю, которые могут быть логически сгруппированы под этим меню. Этот вариант подходит, если у вас есть группа настроек, которая логически может быть помещена в одно из имеющихся в WordPress меню;
Подменю всегда принадлежит меню верхнего уровня – либо созданному, либо имеющемуся. Подменю группируются под меню верхнего уровня по логическому принципу. Если есть возможность включить ваше подменю в одно из существующих меню верхнего уровня, то так и поступайте – не стоит захламлять меню верхнего уровня лишними пунктами;
Меню плагинов используется, когда у вас есть простая, одностраничная опция. Если же таких страниц несколько, то лучше создать меню верхнего уровня или использовать закладочную навигацию, которая будет рассматриваться далее;
Меню тем используется при разработке ваших собственных тем и предоставляет собственный набор опций. Если все опции умещаются на одной странице, используйте API-функцию WordPress. Если опций больше – используйте закладочную навигацию.
Заметим, что многие разработчики тем, часто выносят страницы настроек в меню верхнего уровня.

Несколько слов о настраиваемых меню: хотя WordPress предоставляет возможность добавления собственных пунктов в уже существующие меню, часть сообщества WordPress-разработчиков этого не одобряет. Они считают, что пользовательские меню не должны смешиваться с пунктами меню ядра WordPress.

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

Что дальше?

В следующей статье, мы применим часть знаний, полученных о страницах меню, к нашей теме Sandbox.

В дополнение к добавлению страниц меню, мы также познакомимся с закладочной навигацией и способами её применения в нашей работе.

Если вы еще этого не сделали, то прочитайте предыдущие статьи их данного цикла статей и не забудьте сверить ваш код с контрольной версией на GitHub.