Создание модулей для дашборда (начиная с версии PrestaShop 1.6)

Опубликовано Опубликовано в рубрике prestashop, Руководство разработчика PrestaShop, Русская документация PrestaShop 1.6, Создание модулей PrestaShop

Создание модулей для дашборда (начиная с версии PrestaShop 1.6)

Версия 1.6 PrestaShop предлагает новую панель инструментов, в которой есть блоки контента, которые могут изменяться и добавляться.

Вы можете создавать свои собственные модули панели мониторинга доступные для всех, для загрузки или продажи на PrestaShop Addons.

Различия с основным модулем PrestaShop

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

Специфика

Имя

Модуль вашей панели должен иметь уникальное имя. В качестве условного обозначения модули панели мониторинга должны использовать префикс «dash»: «dashproduct», «dashactivity», «dashgoals» — это имена некоторых модулей панели управления по умолчанию

Метод конструктора

Что касается любого модуля PrestaShop, основной файл PHP должен содержать метод __construct() , который объявляет обычные переменные: namedisplayNameversion, etc.

Для правильного модуля панели мониторинга необходимы несколько новых переменных:

  • $this->push_filename: Каталог, в котором должны храниться данные.
  • $this->allow_push: Логическое значение, указывающее, должен ли ваш модуль вводить данные. или нет.
  • $this->push_time_limit: Количество секунд между двумя нажатиями.

Вот пример метода __construct() взятый из модуля Dashactivity:

public function __construct()
{
    $this->name = 'dashactivity';
    $this->displayName = 'Dashboard Activity';
    $this->tab = '';
    $this->version = '0.1';
    $this->author = 'PrestaShop';
    $this->push_filename = _PS_CACHE_DIR_.'push/activity';
    $this->allow_push = true;
    $this->push_time_limit = 180;
    parent::__construct();
}

Обратите внимание, что tab переменная пуста. Это не нужно сейчас, но может появиться в будущих версиях PrestaShop.

Метод install()

Что касается любого модуля PrestaShop, основной файл PHP должен содержать метод install() который объявляет обычные хуки, такие как displayBackOfficeHeader.

PrestaShop 1.6 реализует несколько новых хуков, предназначенных для модулей панели:

  • dashboardData: Как вы хотите, чтобы ваши данные обрабатывались.
  • dashboardZoneOne: Позволяет отображать ваш контент в левом столбце зоны панели
  • dashboardZoneTwo: Позволяет отображать ваш контент в центральном столбце зоны панели.

Вот пример метода install() взятый из модуля Dashproducts:

public function install()
{
    if (!parent::install()
        || !$this->registerHook('dashboardZoneTwo')
        || !$this->registerHook('dashboardData'))
        return false;
    return true;
}

Зоны дашборда

На панели управления есть две доступные зоны для ваших модулей:

  • Zone One: Левый столбец панели инструментов.
  • Zone Two: Центральный столбец приборной панели.

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

Правый столбец панели инструментов недоступен для модуля.

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

Каждый хук должен вызывать файл шаблона, чтобы отображать ваш контент.

Вот пример метода  hookDashboardZoneTwo() взятый из модуля Dashproducts:

public function hookDashboardZoneTwo($params)
{
    $this->context->smarty->assign(array(
        'date_from' => Tools::displayDate($params['date_from']),
        'date_to' => Tools::displayDate($params['date_to'])));
    return $this->display(__FILE__'dashboard_zone_two.tpl');
}

Шаблоны

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

Файл шаблона должен храниться в папке, специфичной для модуля: /modules/dashmyodule/views/templates/hook/dashboard_zone_two.tpl

Сам шаблон представляет собой классический шаблон PrestaShop с тегами Smarty в тегах HTML.
Как вы видели в методе hook, вы можете создавать новые метки Smarty, когда ваш модуль подключен к зоне. Например, этот код (типа как в модуле Dashactivity):

public function hookDashboardZoneOne($params)
{
    $this->context->smarty->assign(array_merge(array(
        'dashactivity_config_form' => $this->renderConfigForm(),
        'date_subtitle' => $this->l('(from %s to %s)'),
        'date_format' => $this->context->language->date_format_lite
    ), $this->getConfigFieldsValues()));
    return $this->display(__FILE__'dashboard_zone_one.tpl');
}

Этот код объявляет три новых тега:

  • dashactivity_config_form: отображает содержимое модуля renderConfigForm() методом.
  • date_subtitle: Отображает локализованную строку («from %s to %s»).
  • date_format: Отображает дату в «легком» формате (day.month.year).

Оттуда вы можете вызывать эти теги непосредственно в шаблоне. Например, {$dashactivity_config_form} отображает форму в renderConfigForm().

Поток данных

Пункт наличия модуля панели мониторинга — показывать полезный контент вашему пользователю. Когда приборная панель загружается впервые, и каждый раз, когда вы меняете настройку времени (в верхней части панели управления), PrestaShop запускает вызов dashboardData хука для загрузки данных через запросы Ajax.

Чтобы перехватить код dashboardData хука, вы должны создать hookDashboardData() метод, который должен содержать SQL-запросы, необходимые для ваших данных. Затем этот метод должен возвращать массив стандартных типов данных, каждый из которых содержит массив значений в этом типе данных.

For instance, here is the hookDashboardData() method from Dashproduct:

public function hookDashboardData($params)
{
    $table_recent_orders $this->getTableRecentOrders();
    $table_best_sellers $this->getTableBestSellers($params['date_from'], $params['date_to']);
    $table_most_viewed $this->getTableMostViewed($params['date_from'], $params['date_to']);
    $table_top_10_most_search $this->getTableTop10MostSearch($params['date_from'], $params['date_to']);
    return array(
        'data_table' => array(
            'table_recent_orders' => $table_recent_orders,
            'table_best_sellers' => $table_best_sellers,
            'table_most_viewed' => $table_most_viewed,
            'table_top_10_most_search' => $table_top_10_most_search,
        )
    );
}

Building hookDashboardData()

Your hookDashboardData() method can be as simple or complex as is necessary for your dashboard module. See for instance the way the Dashactivity module implements it: https://github.com/PrestaShop/PrestaShop/blob/c7fe91a0a9e02ca21183cc1c09e3e565d4de7265/modules/dashactivity/dashactivity.php#L95 The important thing is that it should return the various values as an array of arrays, with the data types as the root arrays.

See for instance the bottom of Dashactity’s hookDashboardData() method:

return array(
    'data_value' => array(
        'pending_orders' => $pending_orders,
        'return_exchanges' => $return_exchanges,
        // etc.
    ),
    'data_trends' => array(
        'orders_trends' => array('way' => 'down''value' => 0.42),
    ),
    'data_list_small' => array(
        'dash_traffic_source' => $this->getReferer($params['date_from'], $params['date_to']),
    ),
    'data_chart' => array(
        'dash_trends_chart1' => $this->getChartTrafficSource($params['date_from'], $params['date_to']),
    ),
);

PrestaShop извлекает эти данные с использованием запроса Ajax в формате JSON:

{"dashactivity":{
  "data_value":{"pending_orders":"0","return_exchanges":"0"},
  "data_trends":{"orders_trends":{"way":"down","value":0.42}},
  "data_list_small":{"dash_traffic_source":{"Direct link":0}},
  "data_chart":{"dash_trends_chart1":{"chart_type":"pie_chart_trends","data":[{"key":"Direct link","y":0}]}}}
}

Обратите внимание, что вы должны установить значения в массиве, соответствующие типу данных:

  • Массивы значений должны находиться в data_value array
  • Все массивы Trends должны находиться в data_trends array
  • etc.

Типы данных

Существует 4 типа данных, которые могут использовать ваш модуль:

  • Value: a single value, which can have any data type (string, number, boolean, etc.)
  • Trends: a specific type, available as an array two values:
    • ‘way’: either ‘up’ or ‘down’, depending on the trend
    • ‘value’: the difference between the past and current value.
  • List Small: an array of values.
  • Chart: an array of two values:
    • ‘chart_type’: the type of chart to be used (ie.: ‘pie_chart_trends’).
    • ‘data’: an array of arrays:
      • key: the data key.
      • y: the data value.

Именование и получение отображаемых значений

Ключ для каждого значения очень важен, так как PrestaShop обновит отображение вашего модуля: с помощью JavaScript панель инструментов найдет тег HTML, соответствующий значению, и обновит его содержимое.
Например, этот код в Dashactivity’s файле dashboard_zone_one.tpl :

<span class="data_value size_l">
    <span id="pending_orders"></span>
</span>

…Привязана к JSON pending_orders значению через код JavaScript PrestaShop – который вы сами установили в PHP-коде для вашего hookDashboardData() метода.

Поэтому вы должны обратить внимание на то, как вы называете ваши HTML-элементы и ваш ключ данных, так как между ними существует четкая корреляция между PrestaShop.

Ваши собственные типы данных

Помимо стандартных по умолчанию, вы можете создать свой собственный тип данных! Например, вы можете иметь потребность в типе данных Slider. Таким образом, вы возвращаете код:

return array(
    'data_boolean' => array(
        'is_enabled' => getModuleState(),
        'must_auto_reload' => $auto_reload,
        // etc.
    ),
);

Что даст вам следующий ответ данных JSON:

{"dashmymodule":{
  "data_boolean":{"is_enabled":true,"must_auto_reload":false},
}

По умолчанию типы данных загружаются и помещаются определенными функциями JavaScript. Чтобы данные ваших пользовательских типов данных были загружены и правильно размещены, вы должны добавить свою собственную функцию JavaScript, которая вызывается автоматически, когда hookDashboardData() отправляет свой JSON обратно.

Эта функция JavaScript должна быть в вашем собственном .js файле, который вы должны добавить в заголовок темы, используя $this->context->controller->addjs('js/mymethods.js', 'all'); метод.

Он должен принять эту простую форму:

function data_boolean(widget_name, data)
{
    // Here, the code that takes the data array sent by hookDashboardData, and handles their display in the right location.
}

Чтобы получить пример таких методов JavaScript, проверьте их для data_valuedata_trends и другой тип данных по умолчанию в файле https://github.com/PrestaShop/PrestaShop/blob/e71094283395b092ccd0b0a0bb0a0fdfe25cbabc/js/admin-dashboard.js#L112.

Конфигурационная форма

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

Чтобы объявить форму конфигурации, вам просто нужно:

  1. Объявите функцию PHP, которая будет отображать эту форму.
  2. Назначьте эту функцию тегу Smarty.
  3. Вызовите этот ярлык Smarty в шаблоне.

Вот как это делает модуль Dashactivity.

1 — Объявление:

public function renderConfigForm()
{
        $fields_form array(
                'form' => array(
                        'id_form' => 'step_carrier_general',
                        'input' => array(),
                        'submit' => array(
                                'title' => $this->l(' Save '),
                                'class' => 'btn btn-default submit_dash_config',
                                'reset' => array(
                                        'title' => $this->l('Cancel'),
                                        'class' => 'btn btn-default cancel_dash_config',
                                )
                        )
                ),
        );
                
        $sub_widget array(
                array('label' => $this->l('Show Pending'), 'config_name' => 'DASHACTIVITY_SHOW_PENDING'),
                array('label' => $this->l('Show Notifications'), 'config_name' => 'DASHACTIVITY_SHOW_NOTIFICATION'),
                array('label' => $this->l('Show Clients'), 'config_name' => 'DASHACTIVITY_SHOW_CUSTOMERS'),
                array('label' => $this->l('Show Newsletters'), 'config_name' => 'DASHACTIVITY_SHOW_NEWSLETTER'),
                array('label' => $this->l('Show Traffic'), 'config_name' => 'DASHACTIVITY_SHOW_TRAFFIC'),
        );
        
// etc.
}

Для полного renderConfigForm() кода, смотри https://github.com/PrestaShop/PrestaShop/blob/c7fe91a0a9e02ca21183cc1c09e3e565d4de7265/modules/dashactivity/dashactivity.php#L297.

2 — Assignation to a Smarty tag:

public function hookDashboardZoneOne($params)
{
$this->context->smarty->assign(array_merge(array(
        'dashactivity_config_form' => $this->renderConfigForm(),
    ), $this->getConfigFieldsValues()));
    return $this->display(__FILE__'dashboard_zone_one.tpl');
}

3 — Использование в шаблоне:

<section id="dashactivity_config" class="dash_config hide">
    <header><i class="icon-wrench"></i> {l s='Configuration' mod='dashactivity'}</header>
    {$dashactivity_config_form}
</section>

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