Добавление элемента меню в панель управления WordPress: функция add_menu_page() – WP 1.5.0

# Функция ADD_MENU_PAGE() │ WP 1.5.0

Функция add_menu_page() добавляет основной элемент меню в панель управления WordPress (рядом с такими элементами, как Записи, Страницы, Пользователи и т. д.).

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

Если вам нужно добавить подпункт в меню, используйте функцию add_submenu_page().

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

## Примечания

1. Эта функция принимает параметр «capability» (право доступа), который используется для определения, должен ли отображаться элемент меню. Это право доступа также применяется для проверки доступа к странице меню.

2. Если вы используете API настроек для сохранения данных и хотите, чтобы эта функциональность работала для пользователей с правами ниже администратора, вам нужно изменить разрешения с помощью хука option_page_capability_{$option_group}. Здесь $option_group — это то же самое, что и $menu_slug.

   Пример того, как разрешить пользователям с правами редактора изменять настройки:

   ```php
   add_action( 'admin_menu', 'register_my_page' );
   add_filter( 'option_page_capability_my_page_slug', 'my_page_capability' );

   // Добавить новый элемент меню для редакторов
   function register_my_page(){
       add_menu_page( 'Мой заголовок страницы', 'Моя страница', 'edit_others_posts', 'my_page_slug', 'my_page_function', plugins_url( 'myplugin/images/icon.png' ), 6 );
   }

   // Изменить права доступа
   function my_page_capability( $capability ) {
       return 'edit_others_posts';
   }

Возврат

Строка. Возвращает суффикс хука для страницы.

Использование

add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position );

• $page_title (string) (обязательный): Текст, который будет отображаться в тегах <title> на странице при выборе пункта меню.
• $menu_title (string) (обязательный): Текст, используемый для самого меню.
• $capability (string) (обязательный): Права доступа, необходимые для отображения этого меню пользователю. Список ролей и прав.
• $menu_slug (string) (обязательный): Уникальное имя для ссылки на это меню, должны включать только строчные буквы, цифры, дефисы и символы подчеркивания.

Если параметр $function не указан, вам нужно указать имя PHP-файла (относительно каталога плагина) в этом параметре. Этот файл будет отвечать за вывод содержимого страницы данного элемента меню. Вы также можете указать произвольную ссылку (URL), в этом случае при нажатии на элемент меню вы перейдете по указанному URL.

• $function (callable): Функция, которая будет вызываться для вывода содержимого этой страницы. Этот параметр является необязательным. Если он не указан, WordPress ожидает, что PHP-файл из параметра $menu_slug сгенерирует страницу админ меню.

Существует несколько вариантов указания этого параметра:

1. Если функция является методом класса:
   • array( $this, 'function_name' )
   • или статически:
   • array( __CLASS__, 'function_name' ).
2. Имя функции как строка.

По умолчанию: ''

• $icon_url (string): URL-адрес иконки, которая будет использоваться для этого элемента меню.

  • Если вы хотите использовать пользовательскую иконку, укажите URL иконки, например: plugin_dir_url( __FILE__ ) .'plugin-icon.png'. Размер иконки должен быть не более 20x20 пикселей.
  • Если вы хотите использовать специальные иконки dashicons, выберите одну из списка dashicons и используйте ее название, например: dashicons-dashboard.
  • Важно: начиная с WP 6.0 только форматы SVG могут быть указаны этим способом (png, jpg не сработают).

• $position (int): Число, определяющее позицию элемента меню. Чем большее число, тем ниже будет элемент меню. Очень важно! Если два элемента используют одно и то же число, один из элементов может быть перезаписан, и только один из двух элементов будет показан. Чтобы избежать такой конфликта, можно использовать дробные числа вместо целых: 63.3 вместо 63. Используйте кавычки: "63.3".

По умолчанию элемент меню будет добавлен в конец списка.

Структура меню:

• 2 – Панель управления
• 4 – Разделитель
• 5 – Записи
• 10 – Медиа
• 15 – Ссылки
• 20 – Страницы
• 25 – Комментарии
• 59 – Разделитель
• 60 – Внешний вид
• 65 – Плагины
• 70 – Пользователи
• 75 – Инструменты
• 80 – Настройки
• 99 – Разделитель

По умолчанию: null

Примеры

Пример 1: Добавление элемента меню, если он еще не добавлен

Для того чтобы убедиться, что элемент меню еще не добавлен, вы можете использовать глобальную переменную $admin_page_hooks:

global $admin_page_hooks;

if( isset($admin_page_hooks['menu_slug']) ){
    add_submenu_page( ... );
} else {
    add_menu_page( ..., ..., ..., 'menu_slug' );
    add_submenu_page( ... );
}

Пример 2: Настройки темы

Этот пример показывает, как добавить страницу настроек темы в главное меню панели управления WordPress.

add_action('admin_menu', function(){
    add_menu_page( 'Дополнительные настройки сайта', 'Дополнительные настройки', 'manage_options', 'site-options', 'add_my_setting', '', 4 );
});

function add_my_setting(){
    ?>
    

        


        parent_base !== 'options-general' )
            settings_errors('option_name');
        ?>

        

            
        
    
    

add_action( 'admin_menu', 'register_my_custom_menu_page' );
function register_my_custom_menu_page(){
    add_menu_page(
        'Заголовок пользовательского меню', 'Пользовательское меню', 'manage_options', 'myplugin/myplugin-admin.php', '', plugins_url( 'myplugin/images/icon.png' ), 6
    );
}

add_action( 'admin_menu', 'register_my_custom_menu_page' );
function register_my_custom_menu_page(){
    add_menu_page(
        'Заголовок пользовательского меню', 'Пользовательское меню', 'manage_options', 'custompage', 'my_custom_menu_page', plugins_url( 'myplugin/images/icon.png' ), 6
    );
}

function my_custom_menu_page(){
    echo "Некоторый код страницы.";
}

function is_admin_menu_item_exists( $handle, $sub = false ){
    if( !is_admin() || (defined('DOING_AJAX') && DOING_AJAX) )
        return false;

    global $menu, $submenu;

    $check_menu = $sub ? $submenu : $menu;

    if( empty($check_menu) )
        return false;

    foreach( $check_menu as $k => $item ){
        if( $sub ){
            foreach( $item as $sm ){
              if( $handle == $sm[2] )
                return true;
            }
        }
        elseif( $handle == $item[2] )
            return true;
    }

    return false;
}

add_action( 'admin_menu', 'change_menu' );

function change_menu() {

    $post_id  = 393;
    $url_edit = get_edit_post_link( $post_id );

    if ( $url_edit ) {
        add_menu_page( '', 'Моя статья', 'edit_posts', $url_edit, '', '', 5 );
    }
}