На этом этапе мы узнали, почему API настроек имеет значение , мы узнали все о разделах, полях и настройках и даже настроили тему песочницы, которую мы используем для разработки функциональных возможностей при изучении API.
В этой статье мы рассмотрим, как мы можем взаимодействовать с системой меню WordPress. Важно отметить, что это на самом деле не является частью API настроек, но оно настолько тесно связано, что мы должны ознакомиться с тем, как его использовать.
Поскольку наши темы и / или плагины становятся все более сложными, нам необходимо знать все возможные способы их включения в панель управления WordPress. В этой статье мы рассмотрим различные функции меню WordPress, когда их использовать, когда их избегать, и ситуации, в которых каждая функция работает лучше всего.
Понимание типов меню
WordPress предоставляет четыре различных способа включения наших собственных меню. Ниже мы рассмотрим каждое меню, параметры, которые он принимает, и примеры кода, как их использовать в проектах. Мы стремимся выработать четкое понимание того, как работает API, поскольку оно может заложить основу для нашей будущей работы.
Меню верхнего уровня
Страницы меню относятся к пунктам меню, которые вы видите при первом входе в WordPress. То есть они являются доступными параметрами в левом меню, которые могут содержать список страниц подменю.
Чтобы ввести свою собственную страницу меню в панель управления WordPress, вы используете функцию add_menu_page .
Сейчас мы рассмотрим практический пример, но сначала давайте рассмотрим функцию — она принимает семь аргументов (пять обязательных, два необязательных):
- Название страницы относится к тексту, который появляется в верхней части окна браузера всякий раз, когда отображается страница меню верхнего уровня.
- Название меню — это текст, который отображается в реальном меню. Лучше держать это несколько коротким, иначе оно будет перенесено в пункт меню и будет немного отличаться от остальных пунктов меню.
- Возможность относится к тому, какие пользователи имеют доступ к меню. Это просто строковое значение, представляющее одну из доступных ролей .
- Menu Slug — это уникальный идентификатор, который вы предоставляете. Он определяет это меню в контексте WordPress, а также ссылается на страницу, которая отображает параметры, связанные с этим меню. Он также предоставляет хук, с помощью которого элементы подменю могут регистрироваться самостоятельно.
- Обратный вызов — это функция, которая определяет контент, отображаемый на странице, соответствующей этому меню. Это может быть встроенный HTML или ссылка на внешний файл.
- Значок URL — это путь к значку, который вы хотите отобразить рядом с пунктом меню в меню WordPress. Вы можете использовать один из существующих значков WordPress или использовать свой собственный. Этот аргумент не является обязательным.
- Позиция определяет позицию, в которой это меню будет находиться в списке пунктов меню WordPress. По умолчанию меню появляется в нижней части меню, но пользовательская позиция будет размещать ваше меню над (или под) любым из существующих пунктов меню WordPress.
Давайте посмотрим на пример. Найдите functions.php в песочнице настроек WordPress и добавьте следующие две функции:
|
1
2
3
4
5
6
|
function sandbox_create_menu_page() {
}
add_action(‘admin_menu’, ‘sandbox_create_menu_page’);
function sandbox_menu_page_display() {
}
|
Обратите внимание, что мы используем хук admin_menu для регистрации нашего пункта меню. Эта конкретная функция запускается сразу после того, как основное меню администрирования установлено, поэтому вы хотите зарегистрировать свое меню здесь, чтобы WordPress отображал его при отображении остальных меню.
Далее давайте настроим основной пункт меню. В соответствии со статьями ранее в этой серии мы планируем сделать следующее:
- Добавить новое меню в нижней части меню WordPress
- Мы дадим ему название нашей темы (то есть «Песочница»)
- Это будет доступно всем пользователям
- Это не будет включать в себя значок
Достаточно просто, правда? Давайте продолжим и добавим наше меню. Опять же, не просто скопируйте и вставьте этот код. Прочтите его, отметьте комментарии и убедитесь, что вы полностью понимаете, что мы делаем:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
|
function sandbox_create_menu_page() {
add_menu_page(
‘Sandbox Options’, // The title to be displayed on the corresponding page for this menu
‘Sandbox’, // The text to be displayed for this actual menu item
‘administrator’, // Which type of users can see this menu
‘sandbox’, // The unique ID — that is, the slug — for this menu item
‘sandbox_menu_page_display’,// The name of the function to call when rendering the menu for this page
»
);
} // end sandbox_create_menu_page
add_action(‘admin_menu’, ‘sandbox_create_menu_page’);
|
Теперь обновите меню администрирования WordPress, и вы должны увидеть новый пункт меню. Когда вы нажимаете на нее, вы должны увидеть пустую страницу.
Очевидно, это не очень функционально. Давайте заглушим функцию обратного вызова, которую мы определили ранее, чтобы отобразить что-то на экране:
|
01
02
03
04
05
06
07
08
09
10
11
|
function sandbox_menu_page_display() {
// Create a header in the default WordPress ‘wrap’ container
$html = ‘<div class=»wrap»>’;
$html .= ‘<h2>Sandbox</h2>’;
$html .= ‘</div>’;
// Send the markup to the browser
echo $html;
} // end sandbox_menu_page_display
|
Окончательная версия вашего кода должна выглядеть примерно так:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
/**
* Adds a new top-level menu to the bottom of the WordPress administration menu.
*/
function sandbox_create_menu_page() {
add_menu_page(
‘Sandbox Options’, // The title to be displayed on the corresponding page for this menu
‘Sandbox’, // The text to be displayed for this actual menu item
‘administrator’, // Which type of users can see this menu
‘sandbox’, // The unique ID — that is, the slug — for this menu item
‘sandbox_menu_page_display’,// The name of the function to call when rendering the menu for this page
»
);
} // end sandbox_create_menu_page
add_action(‘admin_menu’, ‘sandbox_create_menu_page’);
/**
* Renders the basic display of the menu page for the theme.
*/
function sandbox_menu_page_display() {
// Create a header in the default WordPress ‘wrap’ container
$html = ‘<div class=»wrap»>’;
$html .= ‘<h2>Sandbox</h2>’;
$html .= ‘</div>’;
// Send the markup to the browser
echo $html;
} // end sandbox_menu_page_display
|
Кроме того, как на самом деле использовать функцию add_menu_page, возможно, самый тонкий вывод заключается в том, что в WordPress каждый пункт меню имеет соответствующую страницу меню. Мы рассмотрим это более подробно на протяжении всей серии, но важно отметить, что сейчас мы начинаем исследовать каждый из различных типов меню.
Хотя это в значительной степени неполно, мы добавим к этому всю оставшуюся часть этой статьи и оставшуюся часть руководства.
Замечание о позиционировании: многие разработчики считают использование аргумента позиции плохим этикетом, поскольку он смешивает работу пользователя по умолчанию с WordPress. Кроме того, если вы определяете позицию, а другая тема, плагин или функция использует ту же позицию, один из пунктов меню может быть перезаписан.
Подменю
Подменю похожи на меню, за исключением того, что они принадлежат другому меню — у них есть родитель. Таким образом, очевидно, что вы не можете создать подменю без предварительного создания пункта меню. Конечно, как мы видели в прошлой статье , элементы подменю можно вводить в существующие пункты меню, а не только в пользовательские пункты меню.
В этой статье мы представим страницу подменю в нашем собственном пункте меню. Но прежде чем сделать это, давайте посмотрим на функцию add_submenu_page и параметры, которые она принимает:
- Parent Slug — это идентификатор родительского пункта меню, к которому будет относиться это подменю. В нашем случае мы будем использовать фрагмент меню, который мы определили выше.
- Заголовок страницы — это текст, который будет отображаться в заголовке браузера при отображении страницы.
- Название меню — это текст, который будет отображаться как фактический пункт меню в меню WordPress.
- Возможность, как и в родительском меню, относится к тому, какие типы пользователей имеют доступ к этому конкретному меню.
- Слаг меню — это уникальный идентификатор этого пункта меню. Это то, что используется для определения этого конкретного меню в контексте WordPress.
- Обратный вызов — это функция, которая используется для отображения страницы этого меню на экране.
Если вы хотите добавить пункт меню в одно из существующих меню, обратитесь к таблице в предыдущей статье .
Давайте начнем с регистрации подменю для существующего меню выше. Мы хотим сделать следующее:
- Зарегистрируйте подменю для добавления в только что созданное меню
- Будет отображаться текст «Опции»
- Это будет доступно всем пользователям
- Это не будет включать в себя значок
Проверьте следующий код — мы добавим его прямо под нашим вызовом add_menu_page:
|
1
2
3
4
5
6
7
8
|
add_submenu_page(
‘sandbox’, // Register this submenu with the menu defined above
‘Sandbox Options’, // The text to the display in the browser when this menu item is active
‘Options’, // The text for this menu item
‘administrator’, // Which type of users can see this menu
‘sandbox_options’, // The unique ID — the slug — for this menu item
‘sandbox_options_display’ // The function used to render the menu for this page to the screen
);
|
Не забудьте определить обратный вызов, даже если он пуст. То есть не забудьте добавить эту функцию в ваш файл (мы добавим еще немного):
|
1
2
|
function sandbox_options_display() {
} // end sandbox_options_display
|
Когда вы обновите свой браузер, вы должны увидеть два элемента подменю прямо под меню «Песочница». Обратите внимание, что WordPress самостоятельно создает элемент подменю — это элемент подменю, который соответствует пункту меню и определенной функции обратного вызова. Второй — это новая опция подменю, которую мы только что определили, хотя она не отображает контент.
Чтобы это исправить, давайте продолжим и представим основную страницу. Обновите функцию обратного вызова подменю, чтобы она выглядела следующим образом:
|
01
02
03
04
05
06
07
08
09
10
11
|
function sandbox_options_display() {
// Create a header in the default WordPress ‘wrap’ container
$html = ‘<div class=»wrap»>’;
$html .= ‘<h2>Sandbox Options</h2>’;
$html .= ‘</div>’;
// Send the markup to the browser
echo $html;
} // end sandbox_options_display
|
Обновите ваш браузер еще раз, и вы увидите основной заголовок страницы при выборе нового пункта подменю « Параметры» .
Хотя это и не требуется, обратите внимание, что на самом деле родительский элемент меню и пункт меню « Параметры» могут относиться к одному и тому же содержимому — просто обновите обратный вызов в функции ad_menu_page до функции sandbox_options_display которую мы только что определили.
Страницы плагинов
Если вы разрабатываете плагин для WordPress, то ваш продукт может взаимодействовать с платформой несколькими различными способами.
В частности, ваш плагин …
- Может работать в фоновом режиме и не требовать меню.
- Может использовать обе или одну из функций, упомянутых выше, для создания пользовательского меню
- Может включать себя в одно из существующих меню WordPress
Чтобы облегчить разработчикам плагинов включение их опций в существующие меню WordPress, WordPress API предлагает следующую функцию: add_plugins_page .
Но ждать. Если вы следовали приведенным выше примерам, то, вероятно, заметили, что между add_plugins_page и add_submenu_page, похоже, нет заметной разницы. Ты прав. add_plugins_page предлагает ту же функциональность, что и add_submenu_page, но есть два основных отличия:
- Плагин предоставляется специально для использования в разработке плагинов.
- Функция добавляет пункт меню плагинов непосредственно в меню плагинов WordPress.
Хотя вы, безусловно, можете использовать add_submenu_page для достижения той же цели, я всегда фанат использования функций, предназначенных для конкретного случая использования, даже если есть другая функция API, которая делает то же самое. Когда вы делаете это, вы показываете, что используете API в соответствии с намерениями разработчиков, и вы делаете свой код немного более сплоченным, поскольку ваша кодовая база более тесно связана с тем, как он взаимодействует с базовой платформой.
Разработка плагинов выходит за рамки данной серии, но это не совсем не имеет значения. Хотя в нашей Песочнице не будет никаких изменений, я хочу привести простой пример, показывающий, как использовать эту функцию.
Сначала давайте рассмотрим аргументы, которые принимает add_plugins_page:
- Заголовок страницы — это текст, который будет отображаться в заголовке браузера при отображении страницы параметров плагина.
- Название меню — это текст, который будет отображаться как пункт меню плагина в меню WordPress.
- Возможность, как и в родительском меню, относится к тому, какие типы пользователей имеют доступ к этому конкретному меню.
- Слаг меню — это уникальный идентификатор этого пункта меню. Это то, что он использовал для определения этого конкретного меню в контексте WordPress.
- Обратный вызов — это функция, которая используется для отображения страницы этого меню на экране.
Вот простой пример, который демонстрирует, как именно его использовать. Обратите внимание, что вы можете включить это в свой файл functions.php, но он не является частью темы «Песочница», над которой мы работаем, и вместо этого должен использоваться в контексте плагина.
Сначала настройте вызов функции API — обратите внимание, что для этого используется хук admin_menu:
|
01
02
03
04
05
06
07
08
09
10
11
12
|
function sandbox_example_plugin_menu() {
add_plugins_page(
‘Sandbox Plugin’, // The title to be displayed in the browser window for this page.
‘Sandbox Plugin’, // The text to be displayed for this menu item
‘administrator’, // Which type of users can see this menu item
‘sandbox_plugin_options’, // The unique ID — that is, the slug — for this menu item
‘sandbox_plugin_display’ // The name of the function to call when rendering the page for this menu
);
} // end sandbox_example_plugin_menu
add_action(‘admin_menu’, ‘sandbox_example_plugin_menu’);
|
Затем настройте функцию, которая будет отображать плагин:
|
01
02
03
04
05
06
07
08
09
10
11
12
|
function sandbox_plugin_display() {
// Create a header in the default WordPress ‘wrap’ container
$html = ‘<div class=»wrap»>’;
$html .= ‘<h2>Sandbox Plugin Options</h2>’;
$html .= ‘<p class=»description»>There are currently no options.
$html .= ‘</div>’;
// Send the markup to the browser
echo $html;
} // end sandbox_plugin_display
|
Обновите панель управления WordPress, наведите курсор мыши на меню плагинов, и вы должны заметить новый пункт меню. Неплохо, а?
Окончательная версия кода должна выглядеть так:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
/**
* This function introduces a single theme menu option into the WordPress ‘Plugins’
* menu.
*/
function sandbox_example_plugin_menu() {
add_plugins_page(
‘Sandbox Plugin’, // The title to be displayed in the browser window for this page.
‘Sandbox Plugin’, // The text to be displayed for this menu item
‘administrator’, // Which type of users can see this menu item
‘sandbox_plugin_options’, // The unique ID — that is, the slug — for this menu item
‘sandbox_plugin_display’ // The name of the function to call when rendering the page for this menu
);
} // end sandbox_example_theme_menu
add_action(‘admin_menu’, ‘sandbox_example_plugin_menu’);
/**
* Renders a simple page to display for the theme menu defined above.
*/
function sandbox_plugin_display() {
// Create a header in the default WordPress ‘wrap’ container
$html = ‘<div class=»wrap»>’;
$html .= ‘<h2>Sandbox Plugin Options</h2>’;
$html .= ‘<p class=»description»>There are currently no options.
$html .= ‘</div>’;
// Send the markup to the browser
echo $html;
} // end sandbox_plugin_display
|
Опять же, эта функция не будет частью нашей Песочницы, потому что она больше ориентирована на разработку плагинов; тем не менее, стоит обратить внимание на тех из вас, кто будет использовать API настроек в ваших усилиях по разработке плагинов.
Тематические страницы
Как и в случае с плагинами, WordPress предоставляет функцию API для представления меню специально для тем. Она очень похожа на функцию меню плагина в том, что она предоставляет еще один способ ввести подменю в существующие меню. Основное отличие состоит в том, что подменю добавляется в меню « Внешний вид» .
Как и в примере с плагином ранее в этой статье, мы посмотрим, как мы можем использовать эту функцию, но не будем включать ее в нашу тему песочницы. Это предназначено исключительно для демонстрации того, как использовать функцию на тот случай, если вы решите пойти по этому пути в своей личной работе.
Сначала мы рассмотрим аргументы, которые принимает add_theme_page . Вы заметите, что они похожи на те, которые требуются для меню плагинов, и очень похожи на функции подменю, которые мы описали ранее:
add_theme_page принимает следующие аргументы:
- Заголовок страницы — это текст, который будет отображаться в заголовке браузера при отображении страницы параметров темы.
- Название меню — это текст, который будет отображаться как пункт меню темы в меню WordPress.
- Возможность, как и в родительском меню, относится к тому, какие типы пользователей имеют доступ к этому конкретному меню.
- Слаг меню — это уникальный идентификатор этого пункта меню. Это то, что он использовал для определения этого конкретного меню в контексте WordPress.
- Обратный вызов — это функция, которая используется для отображения страницы этого меню на экране.
Как и с другими функциями, мы создадим несколько примеров функций, которые демонстрируют, как включить это в ваш проект. Обратите внимание, что вызов add_theme_page может быть добавлен в functions.php и, в отличие от вызовов add_plugin_page, должен находиться здесь при разработке вашей темы.
Во-первых, вызов для настройки пункта меню:
|
01
02
03
04
05
06
07
08
09
10
11
12
|
function sandbox_example_theme_menu() {
add_theme_page(
‘Sandbox Theme’, // The title to be displayed in the browser window for this page.
‘Sandbox Theme’, // The text to be displayed for this menu item
‘administrator’, // Which type of users can see this menu item
‘sandbox_theme_options’, // The unique ID — that is, the slug — for this menu item
‘sandbox_theme_display’ // The name of the function to call when rendering the page for this menu
);
} // end sandbox_example_theme_menu
add_action(‘admin_menu’, ‘sandbox_example_theme_menu’);
|
Далее мы настроим функцию для отображения страницы параметров:
|
01
02
03
04
05
06
07
08
09
10
11
12
|
function sandbox_theme_display() {
// Create a header in the default WordPress ‘wrap’ container
$html = ‘<div class=»wrap»>’;
$html .= ‘<h2>Sandbox Theme Options</h2>’;
$html .= ‘<p class=»description»>There are currently no options.
$html .= ‘</div>’;
// Send the markup to the browser
echo $html;
} // end sandbox_theme_display
|
Теперь обновите панель управления WordPress, наведите курсор мыши на меню « Внешний вид», и вы увидите новый пункт меню. Просто!
Окончательная версия кода должна выглядеть так:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
/**
* This function introduces a single theme menu option into the WordPress ‘Appearance’
* menu.
*/
function sandbox_example_theme_menu() {
add_theme_page(
‘Sandbox Theme’, // The title to be displayed in the browser window for this page.
‘Sandbox Theme’, // The text to be displayed for this menu item
‘administrator’, // Which type of users can see this menu item
‘sandbox_theme_options’, // The unique ID — that is, the slug — for this menu item
‘sandbox_theme_display’ // The name of the function to call when rendering the page for this menu
);
} // end sandbox_example_theme_menu
add_action(‘admin_menu’, ‘sandbox_example_theme_menu’);
/**
* Renders a simple page to display for the theme menu defined above.
*/
function sandbox_theme_display() {
// Create a header in the default WordPress ‘wrap’ container
$html = ‘<div class=»wrap»>’;
$html .= ‘<h2>Sandbox Theme Options</h2>’;
$html .= ‘<p class=»description»>There are currently no options.
$html .= ‘</div>’;
// Send the markup to the browser
echo $html;
} // end sandbox_theme_display
|
Для тех из вас, кто заинтересован в более продвинутой разработке темы, вы, вероятно, рассмотрели различные способы реализации нескольких опционных страниц для вашей темы.
С одной стороны, мы можем добавить несколько подменю в меню верхнего уровня, но есть альтернатива: навигация с вкладками. Это удобно, если вы хотите ввести опции в меню « Внешний вид» и не добавлять еще один пункт меню на панель управления WordPress. Мы обсудим это более подробно в следующей статье.
Когда использовать каждую функцию
Мы рассмотрели каждый из четырех основных способов представить наши собственные страницы опций в WordPress. Хотя эти функции не являются частью API настроек, их важно обсудить, поскольку они тесно связаны с ним.
Но знание этих функций — только половина. Как разработчик, отвечающий за интеграцию и организацию настроек, важно знать, когда использовать каждую из различных функций в соответствующем контексте.
Хотя не существует ответа «серебряной пули» на то, когда использовать каждую функцию, вот несколько рекомендаций, которые следует учитывать при работе с вашими пользовательскими функциями, плагинами и / или темами:
- Меню верхнего уровня могут быть добавлены, когда есть подменю, которое может быть логически сгруппировано с этими опциями. Это пригодится, когда у вас есть важная коллекция настроек, которые логически не вписываются ни в одно из существующих меню WordPress.
- Подменю всегда принадлежат меню верхнего уровня — либо пользовательского, либо уже существующего. Они всегда должны быть сгруппированы в меню верхнего уровня, которое наиболее логично. Если WordPress предлагает меню, которое может служить родительским для вашего подменю, используйте его; не загрязняйте меню избыточным меню верхнего уровня.
- Меню плагинов следует использовать, когда у вас есть простые одностраничные опции для вашего плагина. Если у вас есть несколько страниц параметров, рассмотрите возможность создания меню верхнего уровня или используйте навигацию с вкладками, которую мы рассмотрим в следующей статье.
- Меню тем следует использовать при разработке собственной темы, которая предлагает собственный набор пользовательских параметров. Если параметры могут жить на одной странице, рассмотрите возможность использования функции API WordPress. Если у вас есть больше вариантов, рассмотрите возможность использования навигации с вкладками. Обратите внимание, что многие разработчики тем часто поднимают свои параметры темы в меню верхнего уровня, и это тоже нормально.
Несколько слов о пользовательских меню: хотя WordPress дает нам возможность добавлять наши собственные меню верхнего уровня, добавлять в любое существующее меню и, как правило, дает нам возможность делать то, что мы хотим, с конфигурацией по умолчанию, часть сообщества не одобряет это. Они считают, что пользовательские функции не должны мешать определенным основным меню. Хотя в конечном итоге это зависит от вас, реализуйте свою работу с проницательностью — скорее всего, некоторые вещи, которые вы делаете, более важны, чем основные функции WordPress, поэтому не ставьте свою работу выше этого.
Что дальше?
В следующей статье мы собираемся применить немного из того, что мы узнали о меню, и начнем знакомство с опциональными страницами для нашей Песочницы.
Помимо добавления страниц меню, мы также рассмотрим навигацию по вкладкам и то, как мы можем реализовать ее для работы с нашими собственными страницами меню.
В то же время просмотрите предыдущие статьи этой серии и не забудьте проверить текущую версию WordPress Settings Sandbox на GitHub.
Связанные ресурсы
Мы рассмотрели немало ресурсов в этой статье. Вот краткое изложение всего, что мы использовали: