#7. Adding Admin Menus, JS, CSS

Latest Posts

Добавление административных меню

Вступление

Меню и Подменю

Функции  Админпанель

Admin Menu Functions

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

Sub-Menus

add_dashboard_page()

add_posts_page()

add_media_page()

add_pages_page()

add_comments_page()

add_theme_page()

add_plugins_page()

add_users_page()

add_management_page()

add_options_page()

Добавление JavaScript и CSS

Функции  регистрации script и style

Hooks

Front-End Hooks

Admin Hooks

Login Hooks

wp_register_script()

wp_enqueue_script()

wp_add_inline_script()

wp_register_style()

wp_enqueue_style()

wp_add_inline_style()

Расставляем приоритеты

Переопределение стандартных библиотек

Класс отвечающий за добавление JavaScript и CSS

Создать меню плагина

Подключить JS и CSS

Добавление административных меню

Добавление в административное меню

Настройка панели администратора WordPress

Добавляем пункты меню в админку wordpress

Функции  регистрации script и style

wp_enqueue_script

Cписок пунктов верхнего уровня меню и их примерного содержимого

Options — опции, доступные только администратору (смотрите Creating_Options_Pages). 
Manage — инструменты для управления постами, категориями, ссылками, изображениями и подобными вещами. 
Plugins — управление плагинами в целом (не настройки самих плагинов). 
Presentation — инструменты для управления графическим оформлением и содержимым панели. 
Write — содержит инструменты для написания постов и статей. 
Users — содержит инструменты для управления пользователями. 

Функции  Админпанели

Создадим базовый класс контроллер для создания пунктов меню (includes\controllers\admin\menu\StepByStepBaseAdminMenuController)

namespace includes\controllers\admin\menu;

abstract class StepByStepBaseAdminMenuController
{
   public function __construct(){
       /*
        * Регистрирует хук-событие. При регистрации указывается PHP функция,
        * которая сработает в момент события, которое вызывается с помощью do_action().
        */
       add_action(‘admin_menu’, array( &$this, ‘action’));
   }
   abstract public function action();
   abstract public function render();
   abstract public static function newInstance();
}

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

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

Добавляет пункт (страницу) верхнего уровня в меню админ-панели (в один ряд с постами, страницами, пользователями и т.д.).

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

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

Если вы видите ошибку «You do not have sufficient permissions to access this page.» при попытке зайти на страницу, это значит, что вы подключаете функцию слишком рано, подключаете функцию не на нужный хук. Нужно использовать хук admin_menu.

Список позиций для базовых пунктов меню:

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

Добавление меню для плагина Sub-Menus

После создания родительского пункта меню верхнего уровня или выбора его из существующих можно создать один или несколько пунктов подменю при помощи функции add_submenu_page.

add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function );

Добавляет дочернюю страницу (подраздел) указанного главного меню в админ-панели.

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

Нужно вызывать через один из хуков:

• user_admin_menu — админ-меню пользователя;
• network_admin_menu — админ-меню сети;
• admin_menu — обычное административное меню.

Создадим класс includes\controllers\admin\menu\StepByStepMainAdminSubMenuController который будет отвечать за добавление дочерней страницы  главному меню плагина.

<?php
namespace includes\controllers\admin\menu;
class StepByStepMainAdminSubMenuController extends StepByStepBaseAdminMenuController
{
   public function action()
   {
       // TODO: Implement action() method.
       $plugin_page = add_submenu_page(
           STEPBYSTEP_PlUGIN_TEXTDOMAIN,
           _x(
               ‘Sub Step By Step’,
               ‘admin menu page’ ,
               STEPBYSTEP_PlUGIN_TEXTDOMAIN
           ),
           _x(
               ‘Sub Step By Step’,
               ‘admin menu page’ ,
               STEPBYSTEP_PlUGIN_TEXTDOMAIN
           ),
           ‘manage_options’,
           ‘step_by_step_control_sub_menu’,
           array(&$this, ‘render’));
   }
   public function render()
   {
       // TODO: Implement render() method.
       _e(«Hello world sub menu», STEPBYSTEP_PlUGIN_TEXTDOMAIN);
   }
   public static function newInstance()
   {
       // TODO: Implement newInstance() method.
       $instance = new self;
       return $instance;
   }
}

Вызовем класс StepByStepMainAdminSubMenuController в классе StepByStepLoader в методе admin
/**
    * Метод срабатывает когда вы находитесь в Административной панеле. Загрузка классов для Административной панели.
    */
   public function admin(){
       StepByStepMainAdminSubMenuController::newInstance();
   }

add_dashboard_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = »)

add_posts_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = »)

— добавить дочернюю страницу меню в меню Media

add_media_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = »)

— добавить дочернюю страницу меню в меню Pages

add_pages_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = »)

— добавить дочернюю страницу меню в меню Comments

add_comments_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = »)

— добавляет подменю в меню «внешний вид» (Appearance) в админ-панели

add_theme_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = »)

— добавить дочернюю страницу меню в меню Tools

add_management_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = »)

— добавить дочернюю страницу (подменю) в меню админ-панели «Параметры» (Settings)

add_options_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = »)

Добавление JavaScript и CSS

Функции  регистрации script и style

Hooks

Front-End Hooks

• wp_enqueue_scripts
• wp_print_scripts
• wp_print_styles

Admin Hooks

• admin_enqueue_scripts
• admin_print_scripts
• admin_print_styles

Login Hooks

• login_enqueue_scripts — функцию нужно подключать через хуки, потому что вызов функции за пределами хуков, может создать проблемы:

1. wp_enqueue_scripts, если нужно вызвать функцию в лицевой части сайта (фронт-энде).
2. admin_enqueue_scripts, чтобы вызвать в административной части.
3. login_enqueue_scripts — для страницы авторизации.

Чтобы зарегистрировать скрипт который уже есть в WP, вам нужно сначала его удалить, с помощью функции wp_deregister_script(), а затем снова зарегистрировать с нужными параметрами.

Вызов любой из трех функций регистрации скриптов: wp_deregister_script(),  wp_register_script() или wp_enqueue_script() создает класс WP_Scripts и определяет глобальную переменную $wp_scripts. До этого WordPress ничего не знает об этом классе и не использует его, т.е. не происходит регистрация никаких скриптов из таблицы ниже

wp_register_script( $handle, $src, $deps, $ver, $in_footer );

$in_footer (логический). Где выводить скрипт: в head или footer. Обычно скрипты располагаются в head части. Если этот параметр будет равен true скрипт будет добавлен в конец body тега, для этого тема должна содержать функцию wp_footer() перед закрывающим тегом </body>.
По умолчанию: false

wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer );

Правильно подключает скрипт (JavaScript файл) на страницу.

wp_enqueue_script() добавляет скрипт, только если он еще не был добавлен и другие скрипты от которых он зависит зарегистрированы. Зависимые скрипты добавляются автоматически.

Функция обычно вызываться во время следующих событий (вешаться на хуки):

1. wp_enqueue_scripts — для внешней части сайта;
2. admin_enqueue_scripts — для админ-панели;
3. login_enqueue_scripts  — для страницы входа.

Шаблон использования:

add_action( ‘wp_enqueue_scripts’, ‘my_scripts_method’ );
function my_scripts_method(){
wp_enqueue_script( ‘newscript’, get_template_directory_uri() . ‘/js/custom_script.js’); }

wp_add_inline_script() — добавляет дополнительный javascript код к уже зарегистрированному скрипту.

JS добавляется прямо в html документ, после основного (указанного) скрипта.

Код скрипта указывается в параметре $data. Если на один обработчик (название) добавлено несколько скриптов, то ни будут выведены в порядке их добавления, в едином блоке <script>.

Использовать wp_add_inline_script() нужно после того как основной скрипт добавлен в очередь на вывод, но еще не был выведен на экран. Т.е. если скрипт добавлен и уже выведен на экран использование wp_add_inline_script() ничего не выведет.
Аналогичная функция есть и для стилей: wp_add_inline_style()
Используется в:  wp_localize_jquery_ui_datepicker(). Работает на основе: wp_scripts(). Хуков нет.

Пример

Подключим JS код после файла JS:
add_action(‘wp_enqueue_scripts’, function(){
wp_enqueue_script(‘my_scripts’, get_stylesheet_directory_uri() .’/my_scripts.js’ );
// добавим произвольный код
wp_add_inline_script(‘my_scripts’, ‘alert(«Привет!»);’);  });

/* Получим в HTML коде
<script type=’text/javascript’ src=’http://site.ru/wp-content/themes/mytheme/my_scripts.js’></script>
<script type=’text/javascript’>
alert(«Привет!»); </script>
*/

wp_register_style() — регистрирует CSS файл в WordPress. После регистрации файл можно добавить в html документ с помощью функции wp_enqueue_style(). Нужно использовать эту функцию, чтобы правильно подключить CSS файлы в WordPress. Для скриптов такой функцией является wp_register_script(). Эта функция только регистрирует файл, чтобы он был подключен и выведен, его нужно добавить в очередь с помощью wp_enqueue_style(). Файл будет добавлен в <head> часть документа.

Пример

class my_plugin {
function __construct() {
// регистрируем стили
add_action( ‘wp_enqueue_scripts’, array( $this, ‘register_plugin_styles’ ) ); }
// регистрируем файл стилей и добавляем его в очередь
public function register_plugin_styles() {
wp_register_style( ‘my-plugin’, plugins_url( ‘my-plugin/css/plugin.css’ ) );
wp_enqueue_style( ‘my-plugin’ ); } }

wp_enqueue_style()

Правильно добавляет файл CSS стилей. Регистрирует файл стилей, если он еще не был зарегистрирован.

Если файл стилей был предварительно зарегистрирован через wp_register_style(), то его можно добавить в очередь, указав название (идентификатор) в первом параметре $handle.

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

Добавленный в очередь файл стилей выводится в <head> части документа.

С версии 3.3. wp_enqueue_style() можно вызывать в середине документа. В этом случае файл будет выведен в подвале, перед тегом </body> (где вызывается wp_footer()).

wp_enqueue_style() как и wp_enqueue_script() принято вызывать во время событий: wp_enqueue_scripts и admin_enqueue_scripts.
Используйте wp_style_add_data() чтобы добавить условия подключения стилей.
Чтобы вставить в текст сами CSS стили, а не файл стилей, используйте wp_add_inline_style()

Пример

// правильный способ подключить стили и скрипты
add_action( ‘wp_enqueue_scripts’, ‘theme_name_scripts’ );
function theme_name_scripts() {
wp_enqueue_style( ‘style-name’, get_stylesheet_uri() );
wp_enqueue_script( ‘script-name’, get_template_directory_uri() . ‘/js/example.js’, array(), ‘1.0.0’, true ); }

wp_add_inline_style()

Добавляет дополнительный блок CSS стилей. CSS добавляются прямо в html документ, после основных (указанных) стилей.

Работает, когда стили к которым прикрепляется дополнительный блок уже были добавлены в очередь. В параметре $data нужно сами стили CSS, пр.: ‘.container{ width:50%; }’.

Если более одного блока CSS стилей добавлено к одинаковому файлу стилей (параметр $handle), то блоки будут выведены в порядке их добавления, т.е. более поздний блок будет «перебивать», при совпадении, стили предыдущего блока.

Для добавления внешних файлов CSS стилей, используйте wp_enqueue_style().
Хуков нет.

Пример

function my_styles_method() {
wp_enqueue_style(‘custom-style’, get_template_directory_uri() . ‘/css/custom_script.css’);
$color = get_theme_mod( ‘my-custom-color’ ); // #FF0000
$custom_css = «.mycolor{ background: {$color}; }»;
wp_add_inline_style( ‘custom-style’, $custom_css ); }
add_action( ‘wp_enqueue_scripts’, ‘my_styles_method’ );

Расставляем приоритеты

add_action( $tag, $function_to_add, $priority, $accepted_args );

Обратите внимание, что часто используются только параметры $tag и $function_to_add. Параметр $priority по умолчанию равен 10, а параметр $accepted_args — 1. Если мы хотим, чтобы наши скрипты или стили были вызваны раньше, мы просто уменьшаем значение $priority.

Класс отвечающий за добавление JavaScript и CSS

Теперь когда мы рассмотрели как подключать  JavaScript и CSS сделаем класс ответственный за их подключение в плагине.

includes\common\StepByStepLoaderScript

<?php

namespace includes\common;

class StepByStepLoaderScript {}

Добавим методы на действия которые отвечают за загрузку JavaScript и CSS.

namespace includes\common;

class StepByStepLoaderScript
{
   private static $instance = null;
   private function __construct(){
       // Проверяем в админке мы или нет
       if ( is_admin() ) {
           add_action(‘admin_enqueue_scripts’, array(&$this, ‘loadScriptAdmin’ ) );
           add_action(‘admin_head’, array(&$this, ‘loadHeadScriptAdmin’));
       } else {
           add_action( ‘wp_enqueue_scripts’, array(&$this, ‘loadScriptSite’ ) );
           add_action(‘wp_head’, array(&$this, ‘loadHeadScriptSite’));
           add_action( ‘wp_footer’, array(&$this, ‘loadFooterScriptSite’)); } }
   public static function getInstance(){
       if ( null == self::$instance ) {
           self::$instance = new self;   }
       return self::$instance;   }
   public function loadScriptAdmin($hook){}
   public function loadHeadScriptAdmin(){}
   public function loadScriptSite($hook){}
   public function loadHeadScriptSite(){}
   public function loadFooterScriptSite(){}
}

Добавим JavaScript в админпанель

Добавим JavaScript в админпанель. Для этого в методе loadScriptAdmin($hook) пропишем следующее.

Регистрирует файл скрипта, чтобы в дальнейшем подключать его используя функцию wp_enqueue_script()

wp_register_script(
           STEPBYSTEP_PlUGIN_SLUG.’-AdminMain’, //$handle
           STEPBYSTEP_PlUGIN_URL.’assets/admin/js/StepByStepAdminMain.js’, //$src
           array(
               ‘jquery’
           ), //$deps
           STEPBYSTEP_PlUGIN_VERSION, //$ver
           true //$$in_footer );

/**
        * Добавляет скрипт, только если он еще не был добавлен и другие скрипты от которых он зависит зарегистрированы.
        * Зависимые скрипты добавляются автоматически.
        */
       wp_enqueue_script(STEPBYSTEP_PlUGIN_SLUG.’-AdminMain’);

Создадим assets/admin/js/StepByStepAdminMain.js.

jQuery(function($) {
$(document).ready(function(){
alert(«Hello world.»);
}); });

Вызовем класс includes\common\StepByStepLoaderScript в классе  includes\common\StepByStepLoader в методе all.

StepByStepLoaderScript::getInstance();

Зайдем в админ панель и обновим сайт

Добавим CSS в админпанель

Для этого в методе loadScriptAdmin($hook) пропишем следующее.

wp_register_style(
           STEPBYSTEP_PlUGIN_SLUG.’-AdminMain’, //$handle
           STEPBYSTEP_PlUGIN_URL.’assets/admin/css/StepByStepAdminMain.css’, // $src
           array(), //$deps,
           STEPBYSTEP_PlUGIN_VERSION // $ver );

Создадим assets/admin/js/StepByStepAdminMain.css.

Передача переменных php в JavaScript

public function loadHeadScriptAdmin(){
       ?><script type=»text/javascript»>
               var stepByStepAjaxUrl;
               stepByStepAjaxUrl  = ‘<?php echo STEPBYSTEP_PlUGIN_AJAX_URL; ?>’;
           </script><?php }