Используем HightCharts в панели администратора WordPress

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

Что мы будем делать

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

Мы подготовим наш базовый плагин, добавим страницу для него в wp-admin, и затем подключим JavaScript-файл плагина только для этой страницы. Затем полученные нами данные мы передадим внешнему скрипту через wp_localize_script. В свою очередь, скрипт представит наши данные в графическом виде.

Мы планируем показать:

1. Самые популярные записи.
2. Топ пять рубрик по количеству постов.
3. Распределение записей по рубрикам.

HighCharts

Согласно сайту плагина:

«Highcharts – библиотека для составления диаграмм, написанная на чистом HTML5/JavaScript, предлагающая интуитивные, интерактивные диаграммы для вашего веб-сайта или веб-приложения. Highcharts в настоящее время поддерживает линии, сплайны, области, области-сплайны, столбцы, строки, круговые диаграммы и т.д.»

Скачать копию Highcharts можно с официального сайта.

Однако давайте для начала начнем работу с нашим плагином.

Подготавливаем наш плагин

Базовая настройка

Для начала мы создадим папку внутри wp-content/plugins под названием admin-charts. Внутри нее мы сделаем базовую структуру папок для нашего плагина.

Скопируем файл adminchart.js, полученный с официального сайта, в нашу папку js.

В корневой директории мы создадим файл index.php, внутри которого будет содержаться базовое объявление нашего плагина:

<?php
/*
Plugin Name: Admin Charts
Plugin URI: http://dev.imbilal.com/wpadmincharts
Description: JavaScript charts for WordPress admin. These charts show different statistics in the WordPress admin.
Version: 1.0
Author: Bilal Shahid
Author URI: http://www.imbilal.com
License: GPLv2 or later
*/
?>

Теперь переходим в WP-Admin – Plugins и видим, что наш плагин появился там, но пока он не способен функционировать.

Также мы добавим некоторые стили в admin_charts.css:

#admin_chart_form {
    margin: 30px 0;
}
 
#admin_chart_form label {
    display: inline-block;
    width: 250px;
}

Добавляем страницу плагина

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

<?php add_action( 'admin_menu', 'function_name' ); ?>

Мы добавим к нашему файлу index.php функцию chart_add_admin_page, после чего подцепим ее к данному действию:

add_action( 'admin_menu', 'chart_add_admin_page' );

Внутри функции chart_add_admin_page мы будем вызывать родную для WordPress функцию add_plugins_page:

function chart_add_admin_page() {
    add_plugins_page(
        'Charts For WordPress',
        'Admin Charts',
        'administrator',
        'admin-charts',
        'render_admin_charts_page'
    );
}

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

Теперь если вы активируете плагин и наведете мышкой на меню Plugins, то вы увидите новую страницу, которую мы добавили к нашему плагину.

Обработка контента на странице плагина

На данном этапе мы успешно добавили пустую страницу к нашему плагину. Пора сделать ее более функциональной путем вывода некоторого контента.

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

Под функцией chart_add_admin_page давайте добавим следующий код:

function render_admin_charts_page() {
    ?>
    <div class="wrap">
        <h2>Admin Charts</h2>
        <form action="#" method="post" name="admin_chart_form" id="admin_chart_form">
            <p>
                <label for="chart_data_type">What type of data do you want to show?</label>
                <select name="chart_data_type" id="chart_data_type">
                    <option value="chart_most_popular">Most Popular Post</option>
                </select>
            </p>
            <input type="submit" class="button-primary" value="Display Data" id="show_chart" name="show_chart" />
        </form>
        <div id="chart-stats" class="chart-container" style="width:900px; height:500px;"></div>
    </div>
    <?php
}
?>

Мы добавили простой HTML-код. Мы задали заголовок и форму внутри родного для WordPress CSS-класса wrap.

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

Теперь наша страница сформирована:

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

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

define( 'ROOT', plugin_dir_url( __FILE__ ) );

Теперь мы можем определить нашу функцию для регистрации скриптов и стилей:

add_action( 'admin_enqueue_scripts', 'chart_register_scripts' );
function chart_register_scripts() {
    wp_register_script(
        'highCharts',
        ROOT . 'js/highcharts.js',
        array( 'jquery' ),
        '3.0',
        true
    );
    wp_register_script(
        'adminCharts',
        ROOT . 'js/admin_charts.js',
        array( 'highCharts' ),
        '1.0',
        true
    );
    wp_register_style(
        'adminChartsStyles',
        ROOT . 'css/admin_chart.css'
    );
}

Сначала мы зарегистрировали скрипт HighCharts, скачанный нами ранее. Мы присвоили ему хэндл highCharts. В качестве следующего аргумента мы определили путь, по которому можно найти скрипт.

Затем мы передали массив скриптов, от которых зависит наш скрипт. В данном случае это jQuery, поскольку мы будем управлять DOM. Таким образом, нам не нужно думать о подключении jQuery, он будет подключаться автоматически всякий раз, когда мы подключаем скрипт highCharts.

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

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

По этой причине мы выполним проверку условия перед подключением наших скриптов:

add_action( 'admin_enqueue_scripts', 'chart_add_scripts' );
function chart_add_scripts( $hook ) {
 
    if ( 'plugins_page_admin-charts' == $hook ) {
 
        wp_enqueue_style( 'adminChartsStyles' );
        wp_enqueue_script( 'adminCharts' );
 
    }
}

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

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

Получение и вывод статистики

Мы хотим получить три типа данных:

1. Самые популярные записи (гистограмма)
2. Топ из пяти рубрик по количеству записей (гистограмма)
3. Разбиение записей по рубрикам (круговая диаграмма)

Самые популярные записи

Для представленного типа данных мы будем использовать класс WP_Query, позволяющий получить пять записей, которые имеют больше всего комментариев. Класс WP_Query очень удобен, когда нам нужно получить записи на базе различных критериев. Используя данный класс, мы можем выводить список записей любым желаемым образом. Запрос для получения записей с максимальным числом комментариев может иметь следующий вид:

$posts = new WP_Query(
    array(
        'post_type'      => 'post',
        'orderby'        => 'comment_count',
        'order'          => 'DESC',
        'posts_per_page' => 5
    )
);

Теперь у нас есть пять записей, которые обладают максимальным количеством комментариев и которые представлены в виде объектов внутри массива $posts. Вы можете всегда вызвать через echo переменную, которую вы хотите проверить.

Мы должны передать этот объект вместе с другими необходимыми данными в JS. Для этого мы сначала должны подготовить массив, который будет содержать тип данных, тип графика, который нам нужен, и сами записи, которые были отобраны через WP_Query.

$data = array(
    'data_type'  => 'chart_most_popular',
    'chart_type' => 'column',
    'post_data'  => $posts->posts
);

Мы можем передать переменную в JS через wp_localize_script:

wp_localize_script( 'adminCharts', 'data', $data );

Первый аргумент в вызове функции – это хэндл скрипта, которому мы должны передать данные. Мы зарегистрировали этот скрипт ранее. Второй аргумент – это название объекта, которое будет доступно для JS, и третий аргумент – это сами данные, которые мы должны передать. Финальный index.php будет иметь следующий вид:

<?php
/*
Plugin Name: Admin Charts
Plugin URI: http://dev.imbilal.com/wpadmincharts
Description: Javascript charts for wordpress admin. These charts graphically show different statistics in the wordpress admin.
Version: 1.0
Author: Bilal Shahid
Author URI: http://www.imbilal.com
License: GPLv2 or later
*/
 
/********************************* Adding some constants for later use *********************************/
define( 'ROOT', plugin_dir_url( __FILE__ ) );
 
/********************************* Adding the admin page for the plugin *********************************/
add_action( 'admin_menu', 'chart_add_admin_page' );
function chart_add_admin_page() {
    add_plugins_page(
        'Charts For WordPress',
        'Admin Charts',
        'administrator',
        'admin-charts',
        'render_admin_charts_page'
    );
}
 
function render_admin_charts_page() {
    ?>
    <div class="wrap">
        <h2>Admin Charts</h2>
        <form action="#" method="post" name="admin_chart_form" id="admin_chart_form">
            <p>
                <label for="chart_data_type">What type of data do you want to show?</label>
                <select name="chart_data_type" id="chart_data_type">
                    <option value="chart_most_popular" <?php selected_option('chart_most_popular'); ?>>Most Popular Post</option>
                </select>
            </p>
            <input type="submit" class="button-primary" value="Display Data" id="show_chart" name="show_chart">
        </form>
        <div id="chart-stats" class="chart-container" style="width:900px; height:500px;"></div>
    </div>
    <?php
}
 
/********************************* Adding necessary scripts/styles needed *********************************/
add_action( 'admin_enqueue_scripts', 'chart_register_scripts' );
function chart_register_scripts() {
    wp_register_script(
        'highCharts',
        ROOT . 'js/highcharts.js',
        array( 'jquery' ),
        '3.0',
        true
    );
    wp_register_script(
        'adminCharts',
        ROOT . 'js/admin_charts.js',
        array( 'highCharts' ),
        '1.0',
        true
    );
    wp_register_style(
        'adminChartsStyles',
        ROOT . 'css/admin_chart.css'
    );
}
 
add_action( 'admin_enqueue_scripts', 'chart_add_scripts' );
function chart_add_scripts( $hook ) {
    if ( 'plugins_page_admin-charts' == $hook ) {
 
        wp_enqueue_style( 'adminChartsStyles' );
        wp_enqueue_script( 'adminCharts' );
 
        // checking what type of data we are displaying
        if ( 'chart_most_popular' == $_POST['chart_data_type'] ) {
            $posts = new WP_Query(
                array(
                    'post_type'      => 'post',
                    'orderby'        => 'comment_count',
                    'order'          => 'DESC',
                    'posts_per_page' => 5
                )
            );
            $data = array(
                'data_type'  => 'chart_most_popular',
                'chart_type' => 'column',
                'post_data'  => $posts->posts
            );
            wp_localize_script( 'adminCharts', 'data', $data );
        }
    }
}
?>

Однако нам необходимо убедиться в том, что WP_Query и wp_localize_script вызываются только тогда, когда мы отправляем форму; поэтому мы вкладываем их в еще одно if-условие, которое будет проверять, отправлена ли форма:

if ( isset( $_POST['show_chart'] ) ) {
 
    if ( 'chart_most_popular' == $_POST['chart_data_type'] ) {
 
        $posts = new WP_Query(
            array(
                'post_type'      => 'post',
                'orderby'        => 'comment_count',
                'order'          => 'DESC',
                'posts_per_page' => 5
            )
        );
 
        $data = array(
            'data_type'  => 'chart_most_popular',
            'chart_type' => 'column',
            'post_data'  => $posts->posts
        );
 
        wp_localize_script( 'adminCharts', 'data', $data );
 
    }
 
}

Единственное, что нам нужно теперь сделать – это получить данные из JavaScript-файла и нарисовать диаграмму. Внутри файла js/admin_charts.js добавим следующий код:

(function($){
 
    if ( 'chart_most_popular' == data.data_type ) {
 
        var post_titles = [],
        post_comment_count = [];
 
        $( data.post_data ).each(function() {
 
            post_titles.push( this.post_title );
            post_comment_count.push( parseInt( this.comment_count ) );
 
        });
 
        $('#chart-stats').highcharts({
            chart: {
                type: data.chart_type
            },
            title: {
                text: 'Most Popular Posts (by number of comments)'
            },
            xAxis: {
                categories: post_titles
            },
            yAxis: {
                title: {
                    text: 'Number of Comments'
                }
            },
            series: [
                {
                    name: 'Comments Count',
                    data: post_comment_count
                }
            ]
        });
    }
}(jQuery));

Массив $data, который мы передали через index.php, превратится в объект внутри JavaScript. Мы можем работать с ним, как и с любым другим JS-объектом.

Поначалу мы проверяем получаемый тип данных:

if ( 'chart_most_popular' == data.data_type ) {

Затем мы инициализируем два пустых массива для заголовков записей и количества комментариев соответственно:

var post_titles    = [],
post_comment_count = [];

Наконец, мы пройдем через записи и получим их заголовки и количество комментариев в массивах, которые мы определили ранее:

$( data.post_data ).each(function() {
 
    post_titles.push( this.post_title );
    post_comment_count.push( parseInt( this.comment_count ) );
 
});

Теперь пришло время изобразить график, используя полученные данные. Для этого мы будем использовать HighCharts API:

$('#chart-stats').highcharts({
    chart: {
        type: data.chart_type
    },
    title: {
        text: 'Most Popular Posts (by number of comments)'
    },
    xAxis: {
        categories: post_titles
    },
    yAxis: {
        title: {
            text: 'Number of Comments'
        }
    },
    series: [
        {
            name: 'Comments Count',
            data: post_comment_count
        }
    ]
});

Переходим обратно к Plugins — Admin Charts и после выбора опции из выпадающего списка щелкаем по кнопке Отправить. Вы должны увидеть работающую гистограмму.

Вы можете вернуться обратно к вашим записям, добавить некоторые комментарии и затем посмотреть уже обновленную статистику:

Теперь мы добавим к плагину поддержку большего количества типов данных.

Топ пять рубрик по количеству записей

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

<select name="chart_data_type" id="chart_data_type">
    <option value="chart_most_popular">Most Popular Post</option>
    <option value="chart_top_cat">Top 5 Categories by Posts</option>
</select>

Теперь мы можем использовать родную для WordPress функцию get_categories и передать ей несколько аргументов:

$categories = get_categories(
    array(
        'orderby' => 'count',
        'order'   => 'desc'
    )
);

Затем мы получаем наши данные тем же способом, как мы делали это раньше:

$data = array(
    'data_type'  => 'chart_top_cat',
    'chart_type' => 'column',
    'post_data'  => $categories
);

Итоговый код будет выглядеть следующим образом:

if ( 'chart_cat_break' == $_POST['chart_data_type'] ) {
 
    $categories = get_categories(
        array(
            'orderby' => 'count',
            'order' => 'desc'
        )
    );
 
    $data = array(
        'data_type'  => 'chart_cat_breakup',
        'chart_type' => 'pie',
        'post_data'  => $categories
    );
 
    wp_localize_script( 'adminCharts', 'data', $data );
 
}

В admin_charts.js вставим следующий код после условия if:

else if ( 'cart_top_cat' == data.data_type ) {
 
    var cat_titles = [],
    cat_count = [];
 
    $( data.post_data ).each(function() {
 
        cat_titles.push( this.name );
        cat_count.push( parseInt( this.count ) );
 
    });
 
    $('#chart-stats').highcharts({
        chart: {
            type: data.chart_type
        },
        title: {
            text: 'Top 5 Categories by Posts'
        },
        xAxis: {
            categories: cat_titles
        },
        yAxis: {
            title: {
                text: 'Number of Posts'
            },
            tickInterval: 5
        },
        series: [
            {
                name: 'Post Count',
                data: cat_count
            }
        ]
    });
}

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

Распределение записей по рубрикам

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

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

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

if ( 'chart_cat_breakup' == $_POST['chart_data_type'] ) {
    $categories = get_categories(
        array(
            'orderby' => 'count',
            'order'   => 'desc'
        )
    );
    $data = array(
        'data_type'  => 'chart_cat_breakup',
        'chart_type' => 'pie',
        'post_data'  => $categories
    );
    wp_localize_script( 'adminCharts', 'data', $data );
}

Вывести на экран круговую диаграмму достаточно просто. В admin_charts.js добавим следующий код после существующего условия else-if:

else if ( 'chart_cat_breakup' == data.data_type ) {
    var number_posts  = [];
    $( data.post_data ).each(function() {
        number_posts.push( [ this.name, parseInt( this.count ) ] );
    });
    $('#chart-stats').highcharts({
        title: {
            text: 'Breakup of Categories by Number of Posts'
        },
        tooltip: {
            pointFormat: 'Number {series.name}: <b>{point.y}</b><br>{series.name} Share: <b>{point.percentage:.1f}%</b>'
        },
        series: [{
            type: 'pie',
            name: 'Posts',
            data: number_posts
        }]
    });
}

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

Добавим следующий код в index.php после функции render_admin_charts_page:

function selected_option( $option ) {
    if ( $otpion == $_POST['chart_data_type'] ) {
        echo 'selected="selected"';
    }
}

Затем следует вызов функции внутри каждой из выбранных нами опций:

<select name="chart_data_type" id="chart_data_type">
    <option value="chart_most_popular" <?php selected_option( 'chart_most_popular' ); ?>>Most Popular Post</option>
    <option value="chart_top_cat" <?php selected_option( 'chart_top_cat' ); ?>>Top 5 Categories by Posts</option>
    <option value="chart_cat_breakup" <?php selected_option( 'chart_cat_breakup' ); ?>>Breakup of Categories by Posts</option>
</select>

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