Статьи

API настроек WordPress, часть 6: страницы меню

Январь 4, 2019

В третьей части этой серии мы рассмотрели различные функции меню, которые предоставляет API WordPress. Если вы следили за этим, то знаете, что мы уже настроили страницу настроек для нашей темы с помощью функции add_theme_page . Хотя введение меню и подменю явно не является частью API настроек, они играют роль в создании пользовательских функций, плагинов и / или тем.

В этой статье мы собираемся представить новое меню на панели инструментов WordPress, которое сделает наши параметры темы доступными не в разделе «Внешний вид», а в других местах.

Прежде чем начать: в этой статье предполагается, что вы знакомы с настройками API и параметрами темы. Если вы начинающий или даже промежуточный разработчик WordPress, я настоятельно рекомендую ознакомиться с остальной частью серии, прежде чем углубляться в этот пост.

Посмотрите на API

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

Прежде чем мы рассмотрим каждую функцию, давайте подробно рассмотрим, что мы планируем выполнить на следующем этапе этой серии:

  • Введите меню верхнего уровня для наших опций темы
  • Добавьте элемент подменю, который будет ссылаться на вкладку «Параметры отображения»
  • Добавьте элемент подменю, который будет ссылаться на вкладку «Социальные параметры»

Относительно просто, верно? Для этого мы воспользуемся следующими двумя функциями:

  • add_menu_page который используется для представления пунктов меню верхнего уровня
  • add_submenu_page который используется для введения пунктов подменю в меню верхнего уровня.

Мы рассмотрим параметры и использование каждой функции по мере их реализации в нашей теме.

Обратите внимание, что оставшаяся часть этой статьи основана на этой версии изолированной программной среды WordPress . Если вы следуете вместе с хранилищем, обязательно проверьте его.

Меню верхнего уровня

Первое, что мы хотим сделать, это ввести меню верхнего уровня. Это меню появится непосредственно под меню «Настройки» в панели управления WordPress и будет служить двум целям. Меню должно:

  1. Выставьте параметры темы на панель управления WordPress.
  2. Показать страницу параметров по умолчанию для параметров темы

Функция принимает следующие семь аргументов, первые пять обязательны, последние два — нет:

  1. page_title — это текст, который будет отображаться в строке заголовка браузера.
  2. menu_title — текст, который будет отображаться для пункта меню
  3. capability относится к роли, которую пользователь должен иметь для доступа к этому меню
  4. menu_slug — это уникальное значение, которое идентифицирует это меню. Также подменю регистрируются в этом меню.
  5. function_name которое вызывается при нажатии меню для отображения страницы параметров.
  6. icon_url — это путь к значку, который вы хотите отобразить рядом с вашим пунктом меню.
  7. position — это то место, куда следует добавить меню по отношению к другим меню в панели управления WordPress.

В нашей работе мы сосредоточимся только на первых пяти параметрах. Я обсуждаю расположение меню в заключении этой статьи.

Для начала нам нужно ввести вызов функции add_menu_page . Согласно Кодексу WordPress, меню администрирования могут быть добавлены с помощью admin_menu . Ранее в этой серии мы написали функцию, которая добавляет параметры нашей темы в меню «Внешний вид». В частности, мы написали sandbox_example_theme_menu :

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 this menu’s page
    );
 
} // end sandbox_example_theme_menu
add_action( ‘admin_menu’, ‘sandbox_example_theme_menu’ );

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

Добавьте следующий вызов в add_menu_page прямо под вызовом выше:

1
2
3
4
5
6
7
add_menu_page(
    ‘Sandbox Theme’, // The value used to populate the browser’s title bar when the menu page is active
    ‘Sandbox Theme’, // The text of the menu in the administrator’s sidebar
    ‘administrator’, // What roles are able to access the menu
    ‘sandbox_theme_menu’, // The ID used to bind submenu items to this menu
    ‘sandbox_theme_display’ // The callback function used to render this menu
);

Как видите, мы регистрируем меню, в котором будет отображаться «Тема песочницы» как в строке заголовка браузера, так и в пункте меню. Мы открываем меню только для администраторов, и мы дали меню уникальный идентификатор » sandbox_theme_parent_menu «. Мы будем повторно использовать этот параметр в следующем разделе.

Есть одна важная вещь, которую нам нужно уточнить: обратите внимание, что мы передали « sandbox_theme_display » как функцию, которая будет вызываться при нажатии на этот пункт меню. Напомним, что в части 3 мы ввели эту функцию (и уточнили ее в части 5 ). В частности, он отвечает за отображение нашей страницы настроек темы с вкладками.

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

На этом этапе мы готовы начать добавлять подменю, но прежде чем двигаться вперед, убедитесь, что ваша функция выглядит именно так:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
function sandbox_example_theme_menu() {
 
    add_theme_page(
        ‘Sandbox Theme’,
        ‘Sandbox Theme’,
        ‘administrator’,
        ‘sandbox_theme_options’,
        ‘sandbox_theme_display’
    );
     
    add_menu_page(
        ‘Sandbox Theme’,
        ‘Sandbox Theme’,
        ‘administrator’,
        ‘sandbox_theme_menu’,
        ‘sandbox_theme_display’
    );
 
} // end sandbox_example_theme_menu

Добавить подменю

Подменю очень похоже на меню, за исключением того, что они «принадлежат» существующему меню. API для регистрации подменю также относительно похож. Функция принимает шесть аргументов, первые пять обязательны, а последний необязателен:

  1. parent_slug ссылается на уникальный идентификатор родительского пункта меню. В нашем случае » sandbox_theme_menu «.
  2. page_title — это текст, который будет отображаться на панели инструментов браузера, когда этот элемент подменю активен.
  3. menu_title — текст для этого фактического элемента подменю на панели инструментов.
  4. capability — это роль, которую пользователь должен иметь для доступа к этому пункту меню
  5. menu_slug — уникальный идентификатор для этого конкретного пункта меню
  6. function_name которое вызывается при нажатии на меню для отображения страницы параметров

Функция проста. У нас есть два пункта меню — один для «Параметры отображения» и один для «Социальные параметры».

Показать варианты

Сначала давайте введем элемент подменю для отображения параметров. Добавьте следующий блок кода непосредственно под вызовом add_menu_page который мы определили выше:

1
2
3
4
5
6
7
8
add_submenu_page(
    ‘sandbox_theme_menu’, // The ID of the top-level menu page to which this submenu item belongs
    ‘Display Options’, // The value used to populate the browser’s title bar when the menu page is active
    ‘Display Options’, // The label of this submenu item displayed in the menu
    ‘administrator’, // What roles are able to access this submenu item
    ‘sandbox_theme_display_options’, // The ID used to represent this submenu item
    ‘sandbox_theme_display’ // The callback function used to render the options for this submenu item
);

Каждый из приведенных выше параметров должен быть понятен, за исключением имени функции, которое мы передали в качестве последнего аргумента. Обратите внимание, что это то же имя функции, которое мы add_menu_page вызове add_menu_page . Но это имеет смысл, верно? В конце концов, «Параметры отображения» — это вкладка по умолчанию, которая отображается при выборе параметров темы, поэтому имеет смысл, чтобы ее отображали при выборе меню верхнего уровня и при выборе пункта меню «Параметры отображения». ,

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

Социальные параметры

Добавление пункта меню для параметров социальных сетей практически аналогично добавлению пункта меню для параметров отображения. Конечно, мы просто хотим изменить значения для строки заголовка, пункта меню и страницы, которая отображается при выборе меню. Во-первых, давайте add_submenu_page наш вызов функции add_submenu_page . Это должно выглядеть так:

1
2
3
4
5
6
7
8
add_submenu_page(
    ‘sandbox_theme’,
    ‘Social Options’,
    ‘Social Options’,
    ‘administrator’,
    ‘sandbox_theme_social_options’,
    ‘sandbox_theme_display’
);

Сохраните ваш код, обновите панель управления, и вы должны увидеть пункт меню «Social Options», теперь доступный в меню «Sandbox Theme»; однако обратите внимание, что при щелчке по новому элементу подменю отображаются только «Параметры отображения». Так как мы передали « sandbox_theme_display » в качестве имени функции, это то, что мы должны ожидать, верно? Итак, теперь перед нами стоит небольшая проблема: как выбрать вкладку «Социальные параметры» при нажатии на элемент подменю?

Рефакторинг функциональности нашей вкладки

Для привязки нового элемента подменю к соответствующей вкладке на странице параметров темы у нас есть несколько вариантов:

  • Мы можем определить новую функцию, которая предоставляет социальные параметры. Это потребовало бы, чтобы мы проделали дополнительную работу по внедрению новой функции, настройке функциональности вкладок, чтобы мы не нарушали работу существующей страницы, и дублированию небольшого количества кода.
  • Мы можем реорганизовать существующую функцию sandbox_theme_display чтобы принять необязательный параметр, а затем использовать анонимную функцию в вызове add_submenu_page чтобы передать ей параметр.

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

Во-первых, давайте начнем рефакторинг нашей функции sandbox_theme_display . Давайте примем необязательный аргумент, который будет использоваться для указания того, какую вкладку мы хотим выбрать. Найдите следующую подпись в вашем файле functions.php :

1
2
3
function sandbox_theme_display() {
    /* Consolidated for this part of the article.
} // end sandbox_theme_display

Обновите подпись так, чтобы она принимала один аргумент и устанавливала его в нуль, когда он не определен:

1
2
3
function sandbox_theme_display( $active_tab = null ) {
    /* Consolidated for this part of the article.
} // end sandbox_theme_display

Если вы новичок в PHP, вы можете прочитать об аргументах по умолчанию на этой странице .

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

1
$active_tab = isset( $_GET[ ‘tab’ ] ) ?

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

1
2
3
4
5
6
7
if( isset( $_GET[ ‘tab’ ] ) ) {
    $active_tab = $_GET[ ‘tab’ ];
} else if( $active_tab == ‘social_options’ ) {
    $active_tab = ‘social_options’;
} else {
    $active_tab = ‘display_options’;
} // end if/else

Окончательная версия функции должна выглядеть так:

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
33
34
35
36
37
38
39
40
41
function sandbox_theme_display( $active_tab = » ) {
?>
    <!— Create a header in the default WordPress ‘wrap’ container —>
    <div class=»wrap»>
     
        <div id=»icon-themes» class=»icon32″></div>
        <h2>Sandbox Theme Options</h2>
        <?php settings_errors();
         
        <?php if( isset( $_GET[ ‘tab’ ] ) ) {
            $active_tab = $_GET[ ‘tab’ ];
        } else if( $active_tab == ‘social_options’ ) {
            $active_tab = ‘social_options’;
        } else {
            $active_tab = ‘display_options’;
        } // end if/else ?>
         
        <h2 class=»nav-tab-wrapper»>
            <a href=»?page=sandbox_theme_options&tab=display_options» class=»nav-tab <?php echo $active_tab == ‘display_options’ ? ‘nav-tab-active’ : »; ?>»>Display Options</a>
            <a href=»?page=sandbox_theme_options&tab=social_options» class=»nav-tab <?php echo $active_tab == ‘social_options’ ? ‘nav-tab-active’ : »; ?>»>Social Options</a>
        </h2>
         
        <form method=»post» action=»options.php»>
            <?php
             
                if( $active_tab == ‘display_options’ ) {
                    settings_fields( ‘sandbox_theme_display_options’ );
                    do_settings_sections( ‘sandbox_theme_display_options’ );
                } else {
                    settings_fields( ‘sandbox_theme_social_options’ );
                    do_settings_sections( ‘sandbox_theme_social_options’ );
                } // end if/else
                 
                submit_button();
             
            ?>
        </form>
         
    </div><!— /.wrap —>
<?php
} // end sandbox_theme_display

Мы еще не закончили. Хотя мы проделали необходимую работу для отображения социальных параметров, если был передан соответствующий параметр, на самом деле мы не вызывали функцию с помощью параметра. Для этого нам нужно провести рефакторинг функции add_submenu_page сверху. В настоящее время вызов функции выглядит следующим образом:

1
2
3
4
5
6
7
8
add_submenu_page(
    ‘sandbox_theme’,
    ‘Social Options’,
    ‘Social Options’,
    ‘administrator’,
    ‘sandbox_theme_social_options’,
    ‘sandbox_theme_display’
);

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

1
2
3
4
5
6
7
8
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 должна выглядеть следующим образом:

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
33
34
35
36
37
38
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 this menu’s page
    );
     
    add_menu_page(
        ‘Sandbox Theme’, // The value used to populate the browser’s title bar when the menu page is active
        ‘Sandbox Theme’, // The text of the menu in the administrator’s sidebar
        ‘administrator’, // What roles are able to access the menu
        ‘sandbox_theme_menu’, // The ID used to bind submenu items to this menu
        ‘sandbox_theme_display’ // The callback function used to render this menu
    );
     
    add_submenu_page(
        ‘sandbox_theme_menu’, // The ID of the top-level menu page to which this submenu item belongs
        ‘Display Options’, // The value used to populate the browser’s title bar when the menu page is active
        ‘Display Options’, // The label of this submenu item displayed in the menu
        ‘administrator’, // What roles are able to access this submenu item
        ‘sandbox_theme_display_options’, // The ID used to represent this submenu item
        ‘sandbox_theme_display’ // The callback function used to render the options for this submenu item
    );
     
    add_submenu_page(
        ‘sandbox_theme_menu’,
        ‘Social Options’,
        ‘Social Options’,
        ‘administrator’,
        ‘sandbox_theme_social_options’,
        create_function( null, ‘sandbox_theme_display( «social_options» );’ )
    );
 
} // end sandbox_example_theme_menu
add_action( ‘admin_menu’, ‘sandbox_example_theme_menu’ );

Вывод

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

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

Связанные источники

35
Share: