MT API Руководство: Модульные отчёты

modular_reports.js - это библиотека, позволяющая создавать модульные отчёты
Модули — это самостоятельные блоки интерфейса, которые состоят из JS-скрипта и HTML-шаблона. Также в модуль можно включить дополнительные CSS и JS-файлы.

Преимущества использования модулей

Ускорение загрузки отчётов (загрузка по запросу).
Конфигурирование отчётов под требования клиентов (например, добавить инди-модули в дополнение к стандартным).

Принцип работы

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

Как создать модульный отчёт:

Модульный отчет имеет следующую структуру:

my_report
├──my_report.js
├── my_report.html
├── modules
│   └── my_module
│       ├── my_module.html
│       └── my_module.js
└── manifest.json

Метафайл модульного отчета выглядит следующим образом и может иметь нижеследующие поля:

{
  "uri": "stmobile://report/outletreports/myreport",
  ...
  "config": {
    "settingsKey": "myreport_open_modules",
    "modules": [
      {
        "name": "my_module",
        "position": 1,
        "uiName": "qsTr(My module)",
        "visibilityCheck": true,
        "reloadCheck": "self",
        "isDisabled": false
      }
    ]
  }
}

Обязательные параметры

name - Имя модуля (в этом примере - "my_module"). Должно быть таким же, как и имя папки с файлами модуля.
position - Определяет порядок сортировки. Чем меньше число, тем ближе к началу. Можно задавать дробные и отрицательные числа.
uiName - Название, которое будет отображено в интерфейсе. Можно указать строку или ключ для перевода через lng-файлы.

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

visibilityCheck - boolean. Нужна ли проверка на отображение модуля. Если задано true, при подключении будет запущена проверка, от результата которой зависит будет ли отображён модуль.
reloadCheck - "self" или "full". Нужна ли проверка на необходимость перезагрузки модуля при возврате в отчёт.
isDisabled - boolean. Если установлено значение true, модуль не будет загружен.

Подключение обработчика модульных отчётов

Для корректной работы модульности необходимо подключить обработчик и стили в основном HTML-файле отчёта:

<link type="text/css" rel="stylesheet" href="{{libPath}}/libs/modular_reports/modular_reports.css">
...
<script type="text/javascript" src="{{libPath}}/libs/modular_reports/modules_handler.js"></script>

Скрипт-обработчик необходимо подключать в конце HTML-файла до закрывающего тега </body>, чтобы исключить обращение скрипта к несуществующим элементам.
Внимание! для корректной работы необходимо подключение MTCHANNEL. Для более подробного описания см. раздел Взаимодействие HTML с Data-скриптом

Структура модуля

Модуль состоит из файлов my_module.js и my_module.html

Файл module_name.js имеет следующую структуру:

function getData () {
    return {
        /*Data to pass into HTML*/
    };
}

module.exports = {
    getData: getData
};

Обязательно необходимо экспортировать getData (а также и другие методы модулей, к которым будет необходим доступ из HTML-файла)

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

    var extensionsPath = api.warp.app.absolutePath("script").value,
        moduleCSS      = api.textfile.read(extensionsPath + "/modules/module_name/module_name.css");

Переменную moduleCSS необходимо сделать одним из свойств объекта, возвращаемого getData().

Подключение стиля производится следующим образом:

<style>
    {{moduleCSS|safe}}
</style>

Методы библиотеки modular_reports.js

loadModulesHTML(configKey)
Выполняет загрузку инициализацию всех модулей и раскрывает их при необходимости.

configKey - Обязательный параметр, строка, содержащая ключ, по которому происходит считывание "открытых" модулей из конфигурационного файла. Необходимо для раскрытия модулей при инциализации отчёта.

Возвращает HTML-код, который необходимо вставить в основной HTML-файл отчета следующим образом:
```
{{modules|safe}}
```
Пример вызова:
```
mapper.modules = loadModulesHTML("dashboard_open_modules");
```

getModule(moduleName)
Возвращает HTML-код с содержимым модуля

moduleName - Строка с названием модуля, содержимое которого надо загрузить.

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

callModuleFunction(args)
Служит для вызова какой-либо функции модуля из HTML-файла.

args - это объект следующего вида:

   {
       moduleName:   "my_module"   // Название модуля
       functionName: "my_function" // Имя вызываемой функции
       functionArgs: []            // Аргументы вызываемой функции
   }

modulesState([modules])
В случае вызова с параметром устанавливает состояние модулей в файле конфигурации. Иначе возвращает список модулей, которые необходимо раскрыть.

Методы обработчика модульности modules_handler.js

loadAllModules()
Восстанавливает сохраненное состояние модулей - загружает содержимое и раскрывает модули, открытые при последней работе с отчётом.

Должна вызываться следующим образом в основном HTML-файле отчёта:

$(function() {
    window.setTimeout(loadAllModules, 300);
})

300 - это таймаут для вызова в милисекундах. Необходимо для корректной подгрузки и работы обработчика модулей.

callModuleFunction(options, callback)
Служит для вызова какой-либо функции модуля в отдельном потоке.
Внимание! Не рекомендуется объявлять глобальные переменные в модульных отчётах, т.к. они доступны только в основном потоке.

options Объект, содержащий параметры вызова функции.

{
   moduleName:   "my_module",   // Название модуля
   functionName: "my_function", // Имя вызываемой функции
   functionArgs: []             // Аргументы вызываемой функции
}

callback Функция, вызываемая по окончанию работы метода модуля.

callMainThreadFunction(options, callback) Служит для вызова какой-либо функции модуля в основном потоке