Работа с дашбордами

Введение

Дашборд - это страница с некоторыми показателями и панелями с выводом таблиц, графиков и диаграмм.

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

Смотреть пример вывода Дашборда на демостенде

Также посмотрите пошаговое руководство по созданию дашборда

Управление дашбордами

Создание дашборда

<div class="as-dashboard" data-code="code1" data-animated="1"></div>

2. В меню "Компоненты" в разделе "Дашборды" создать элемент с указанным кодом code1. Указать правильные права для users, roles (указываем через запятую и без пробелов).

3. Создать дополнительные панели в дашборде (ссылка в таблице Панели).

4. Для панели указываем код (задает название хранимых процедур), Колонка (1-12  как часть разметки Bootstrap - сколько занимает колонка). Тип (table, bar, line), Html (если указано, то данная разметка будет выводиться в панели).  Height - в px, % или auto - высота панели. 

5. Создаем необходимые хранимые процедуры. Для счетчиков это хранимая процедура вида dashboard_{dashboardCode}_getCounters, для табличных данных (тип table) - это dashboard_{dashboardCode}_{panelCode}_getPanelTable, для bar и подобных графиков - это dashboard_{dashboardCode}_{panelCode}_GetPanelChart

Процедура GetCounters - настройка показателей дашборда

CREATE PROCEDURE [dbo].[dashboard_forAdmin_getCounters]
       @username nvarchar(128),
       @parameters ExtendedDictionaryParameter readonly  -- необязательный параметр, в нем хранится фильтр значение key=filter
AS
BEGIN
-- select 1 4 верхних показателя
SELECT
        /*Выходной результат - это 4 строки в указанном формате
          На входе - username */
	'Falcon' Title,
	'Falcon 2. Документация' Tooltip,
	'fa fa-cogs' Icon,
	'2.0' Number,
	'' AdditionalNumber,
	'Документация разработчика' DownTitle,
	'DownLink' DownLink -- нижняя ссылка выводится если указан DownTitle,
        2000 AnimateDuration,
        '' Makeup

-- select 2  Названия панелей в дашборде
SELECT 'Название1' panel1, -- код панели
       'Название2' panel2

-- SELECT 3 Dashboard settings
select '' Title, '' Subtitle, '' Makeup, 'radio' FilterType

-- SELECT 4 Значения для фильтров
select value,text from (
  select '' Value, 'День' text, 1 ord
  union
  select 'week' Value, 'Неделя' text, 2 ord
  union
  select 'month' Value, 'Месяц' text, 3 ord
  union
  select 'quarter' Value, 'Квартал' text, 4 ord
  union
  select 'year' Value, 'Год' text, 5 ord
) t1
order by ord


END

• username - текущий пользователь
• parameters - необязательный параметр, коллекция элементов(Key, Value). В ней передается langID, falconGuid и filter. 

• Title - заголовок 
• Tooltip - подсказка к показателю
• Icon - иконка (например, fa fa-cube)
• Number - главный показатель (может быть и текстом)
• AdditionaNumber - дополнительный номер (например, значение за прошлую неделю)
• DownTitle, Downlink - текст и ссылка нижнего блока в показателе
• AnimateDuration - если больше 0, то при выводе будет анимация от 0 до Number за указанное число миллисекунд
• Color - задает цвет счетчика - danger,warning, success и т.д. (если не заданы - то идут цвета по умолчанию).
• Makeup - кастомная разметка для параметра. Если пустая - то используется стандартный показатель. Использует параметры {title}, {tooltip}, {icon}, {number}, {additionalNumber}, {downTitle}, {downLink}, {color}. Пример: 

<div class="col-12 col-md-2">{title}<br>{number}</div>

SELECT 2 возвращает названия панелей (если их надо сделать динамическими).

SELECT 3 задает настройки дашборда: 

• title - подменяет название дашборда
• subtitle - задает описание дашборда
• filterType - radio или select. Задает формат вывода фильтра справа (значения фильтра устанавливаются в SELECT 4)
• makeup - позволяет задать кастом разметку, в которой можно использовать следующие параметры: 
  • {title} - заменяется на заголовок дашборда
  • {subtitle} - заменяется на подпись к дашборду
  • {counters} - заменяется на панель счетчиков
  • {panels} - заменяется на структуру панелей дашборда
  • {counter1}, {counter2} и т.д. - заменяется соответствующим счетчиком с таким номером
  • {panelABC}, {panelXYZ} - заменяется панелью с соответствующим кодом (ABC, ZYZ в примере)

Пример кастом дашборда на демостенде - https://demo.web-automation.ru/list/watch/panel-upravleniya-s-kastom-razmetkoy---89

SELECT 4 возвращает значения фильтра (text,value). Фильтр выводится справа вверху 

Процедура GetPanelTable - вывод таблицы в панели

Данная процедура используется для типов table и apexchart (диаграммы Apex - о них будет сказано ниже). 

Для вывода таблицы просто указываем в SELECT 1 данные таблицы (названия столбцов будут отражены в названии колонок выводимой таблицы в панели).

CREATE PROCEDURE [dbo].[dashboard_forAdmin_panel1_getPanelTable]
	@username nvarchar(128) -- на входе username
AS
BEGIN
      -- На выходе любая таблица с полями (выведется как таблица на панели)
      SELECT isnull(name,'') as name,
             isnull(code,'') as code
      FROM as_trace
      ORDER BY id
END

Процедура GetPanelChart (bar и похожие типы) - вывод диаграммы в панели

CREATE PROCEDURE [dbo].[dashboard_forAdmin_panel2_getPanelChart]
	@username nvarchar(128) -- текущий пользователь
	@filter nvarchar(128) = '' --  необязательный параметр выбранного фильтра
AS
BEGIN
      SELECT 'bar' type, -- определяющий тип при выводе графика
             'График 1' title,
             260 width,
             260 height

      /*На выходе 2 select
        Первый - настройки диаграммы(1 строка)
        Второй - данные для графика*/

      SELECT code Title,
             count(*) Value,
             '' Color
      FROM as_trace
      GROUP BY code
END

Процедура GetPanelChart (для line) - вывод графика в панели дашборда

Можно указать несколько графиков на 1 панели.

CREATE PROCEDURE [dbo].[dashboard_forAdmin_panel2_getPanelChart]
	@username nvarchar(128) -- текущий пользователь
	@filter nvarchar(128)='' --  необязательный параметр выбранного фильтра
AS
BEGIN
      -- на выходе 2 запроса select
      SELECT 'line' type, -- определяющий тип при выводе графика
             'График 1' title,
             260 width,
             260 height,
             '2,35,45,23' CommaLabels -- это метрик по оси абсцисс (ось Х)

      /*На выходе 2 select
        Первый - настройки диаграммы(1 строка)
        Второй - данные для графика*/

      SELECT 'График 1' title,
             '1,4,5,12' Value,
             '' Color -- если цвет не установлен, то будет использовано случайное значение
      UNION
      SELECT 'График 1' title,
             '12,4,2,48' Value,
             '' Color

END

Примечание

1. Можно кешировать результаты панели, для этого укажите значение больше 0 в поле панели Кеширование в минутах.
2. Если необходима дополнительная нетиповая функциональность на дашбордах, это можно сделать через дополнительную разметку в поле панели HTML. 
3. Вы можете указать в сниппете data-hideDigits='1' и data-hidePanels='1' для того, чтобы не выводить Показатели и Панели на странице. 
4. В панели в HTML можно вставлять формы, таблицы и панели-подсказки (flashLabel).
5. У вас есть возможность отключать панели - для этого необходимо установить у панели галку Отключено. 
6. Если панель одна, то она выводится на всю ширину (без разбиения на 2 столбца). 
7. В разметку панелей дашборда можно включать сниппеты других компонентов - т.е. выводить в панелях Таблицы, Формы, Ресурсы, Метрики и т.д.
8. Для таблиц можно изменять вывод ячеек как для таблиц, т.е. использовать префиксы color_, backcolor_, icon_, barPercent_, barClass_.
9. Нечетко отображаются на больших экранах графики? Необходимо в SQL панели дашборда в SELECT 1 установить достаточно большие значения ширины и высоты
10. Можно добавить JS коллбек после загрузки дашборда в виде as.dashboard.callbacks.{dashboardCode}_getItems в коде страницы.

$(function(){
     as.dashboard.callback.forAdmin_getItems = function(data){
        console.log('clGet',data)
     }
});

Тип панели progress

Прогресс в процентах по элементам. Запрос панели возвращает модель из Title, Value (именно в таком порядке).
Value - это число от 0 до 100 (лучше целое). 

Тип панели apexchart

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

В процедуре getpanelTable выводим  JSON настройки в SELECT 1 в параметре apexChartOptions

Пример: 

CREATE PROCEDURE [dbo].[dashboard_forAdmin_p1_getPanelTable] 
@username nvarchar(128)
AS
BEGIN
	select '{
      "chart": {
        "type": "line"
      },
      "series": [{
        "name": "Выручка",
        "data":   [30,40,35,50,49,60,70,91,125],
        "color": "#afa"
      },
      {
        "name": "Затраты",
        "data":  [20,10,15,40,29,50,20,15,45],
        "color": "#faa"
      }],
      "xaxis": {
        "categories": [1991,1992,1993,1994,1995,1996,1997, 1998,1999]
      }
    }' apexChartOptions
END

Как вывести в дашборде существующую таблицу, форму или произвольную разметку? 

• Указываем в разметке поля HTML сниппет таблицы. 
• Реализуем таблицу как обычно (про работу с таблицами читаем здесь). 
• Аналогично можно вывести и другие компоненты, например Ресурсы, Чат и т.д.

Как настроить фильтр для дашборда

1. Добавляем параметр @parameters ExtendedDictionaryParameter readonly  в процедуру GetCounter и извлекаем значение фильтра: 

declare @filter nvarchar(128) = ''
select @filter = Value from @parameters where [Key] = 'filter'

2. В SELECT 3 прописываем filterType = radio или select (select по умолчанию)

3. В SELECT 4 прописываем возможные  значения фильтра

select value,text from (
  select '' Value, 'День' text, 1 ord
  union
  select 'week' Value, 'Неделя' text, 2 ord
  union
  select 'month' Value, 'Месяц' text, 3 ord
  union
  select 'quarter' Value, 'Квартал' text, 4 ord
  union
  select 'year' Value, 'Год' text, 5 ord
) t1
order by ord

4. В хранимых процедурах для панелей (GetPanelChart и GetPanelTable) передается необязательный параметр @filter (строка). 

5. Если планируется использовать внутри компоненты через кастом HTML в панели, то его можно получить через переменную {filter}. 

<div class="as-table" data-code="table1" data-itemid="{filter}"></div>

Примечание: 

• ВАЖНО. Первый элемент в фильтре, который должен идти по умолчанию должен иметь Value=''. В этом случае он будет считаться выбранным по умолчанию при первой загрузке.
• Для улучшения вывода фильтра (он выводится справа сверху) используйте title / subtitle дашборда.

Пример дашборда с фильтром на демостенде