Настройка отображения виджета для дашборда

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

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

По умолчанию виджет имеет высоту 272px. Данное значение можно изменить, подробнее об этом можно прочитать в разделе "Изменение значений по умолчанию для базовых свойств виджета".

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

ширина - 180px
высота - 132px.

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

widgetHeight - высота виджета в px;
widgetWidth - ширина виджета в px. Минимальное значение 360px.

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

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

Виджет не обязан уметь отображаться в минимальных размерах. Если у вашего виджета другие ограничения по размеру, их нужно настроить с помощью поля meta:

minWidth: number - минимальная ширина содержимого виджета в пикселях без учета боковых отступов
minHeight: number - минимальная высота содержимого виджета в пикселях без учета верхнего и нижнего отступов и заголовка

// TypeScript
{
   ...
   "meta": {
      "minWidth": 240,
      "minHeight": 360
   },
   ...
}

В случае если виджет будет меньше указанных вами минимальных размеров, будет показана соответствующая подсказка. При этом, размер прикладного содержимого виджета не будет уменьшен до реального размера виджета. Размер прикладного контента виджета всегда будет не меньше тех размеров, которые указаны в поле meta виджета.

Так же для виджета можно настроить макcимальную ширину, с помощью поля meta.maxWidth

// TypeScript
{
   ...
   "meta": {
      "maxWidth": 480
   },
   ...
}

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

Настройка режима высоты виджета

Для каждого виджета есть возможность настроить режим высоты. Есть три варианта режима высоты:

Фиксированная - высота равна высоте, настроенной в режиме редактирования, если контент не влезает, рисуются 3 точки.
По контенту - высота виджета подстраивается под высоту контента.
По контенту с ограничениями - максимальная высота равна высоте, настроенной в режиме редактирования, если контент не влезает, рисуется кнопка со стрелкой, при нажатии на которую контент виджета будет развернут.

По умолчанию у всех виджетов установлена фиксированная высота.

За режим высоты отвечает свойство heightMode, оно принимает следующие значения:

limited - фиксированная высота,
endlessScroll - высота по контенту,
expandable - высота по контенту с ограничениями.

Если установлен режим endlessScroll, то виджет может поддержать подгрузку данных по скроллу.

Настройка виджета с бесконечным скроллом

Есть виджеты, которые подгружают данные по скроллу, например виджет "Новости".

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

Если свойство heightMode принимает значение endlessScroll, значит виджет может работать в режиме бесконечного скрола, иначе виджет должен отобразить данные в соответствующем размере. Размер виджета будет передан в поле widgetHeight.

Обрезание контента виджета по высоте

При изменении высоты виджета в режиме конструирования контент виджета обрезается в соответствии с установленной высотой. Если контент виджета больше минимальной высоты в 2 блока, должна быть описана функция moreButtonClickCallback в поле meta. В этом случае в виджете средствами платформы отображается кнопка "Раскрыть". В обработчике moreButtonClickCallback нужно открыть окно, в котором отобразится полная информация, представленная в виджете.

moreButtonClickCallback: string- путь до функции, которая будет вызвана при клике на кнопку раскрытия при обрезании части контента виджета.

Принимает на вход:

id - идентификатор виджета,
props - настройки виджета,
opener - открывающий контрол.

// TypeScript
{
   ...
   "meta": {
      "moreButtonClickCallback": "HowEasy/callbacks/moreButtonClickCallback"
   },
   ...
}

Если у виджета установлена автовысота и загружены не все данные, для того, чтобы отобразилась кнопка "Раскрыть", необходимо описать функцию hasMoreCallback в поле meta. Функция должна вернуть true, если у виджета есть еще данные для отображения.

hasMoreCallback: string- путь до функции, которая будет вызвана, если у виджета установлена автовысота.

Принимает на вход:

props - настройки виджета.

// TypeScript
{
   ...
   "meta": {
      "hasMoreCallback": "HowEasy/callbacks/hasMoreCallback"
   },
   ...
}

Настройка отступов внутри виджета

Для настройки отступов внутри виджета дашборда в поле meta задайте опцию padding.

// TypeScript
{
   ...
   "meta": {
      "padding": {
         "left": "null",
         "right": "null",
         "top": "null",
         "bottom": "null"
      }
   },
   ...
}

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

Возможные варианты значения отступов: null, 3xs, 2xs, xs, s, st, m, l, xl, 2xl, 3xl; Каждый из вариантов соответствует значению платформенной css переменной --offset_<value>.

Настройка заголовка

Заголовок виджета располагается в верхней части виджета и отображается средствами платформы. Текст заголовка указывается в поле info.title.

// TypeScript
{
   ...
   "info": {
      "title": "Заголовок"
   },
   ...
}

Для настройки заголовка в поле meta задайте опции указанные ниже.

headerContentTemplate: string- шаблон, который будет отображаться справа от заголовка виджета.

// TypeScript
{
   ...
   "meta": {
      "headerContentTemplate": "HowEasy/templates/headerContentTemplate"
   },
   ...
}

headerVisible: boolean - флаг отображения заголовка: false - не показывать заголовок.

Скрывается не только текст заголовка, а целиком верхняя область заголовка виджета, при этом маркер не скрывается.

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

Если вы скрыли свой заголовок, вы обязаны добавить к себе верстку стандартный заголовк с помощью использования компонента Dashboard.dashboard:Heading.

Dashboard.dashboard:Heading - компонент заголовка, который необходимо разместить в прикладном контенте виджета, не имеет опций. Все необходимые настройки в заголовок передаются через контекст автоматически.

// TypeScript
{
   ...
   "meta": {
      "headerVisible": false
   },
   ...
}

getTitleCallback: string - путь до функции, которая вернет заголовок виджета. Принимает на вход загруженные данные виджета. Возвращает заголовок виджета. Применяется в случае, когда заголовок виджета зависит от его настроек.

// TypeScript
{
   ...
   "meta": {
      "getTitleCallback": "HowEasy/callbacks/getTitleCallback"
   },
   ...
}

headerClickCallback: string - путь до функции, которая будет вызвана при клике на заголовок виджета. Используется для перехода по ссылке, открытия окна и т.д.

// TypeScript
{
   ...
   "meta": {
      "headerClickCallback": "HowEasy/callbacks/headerClickCallback"
   },
   ...
}

Принимает на вход:

id - идентификатор виджета,
props - настройки виджета,
opener - открывающий контрол.

Настройка пустого состояния

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

Если пользователь выберет "Скрывать виджет, если в нем нет данных" и функция isEmptyCallback вернёт true, то в режиме просмотра виджет будет скрыт, а в режиме конструирования будет отображен с шаблоном designtimeConfig. isEmptyCallback указать в поле meta.

isEmptyCallback: string - путь до функции, которая будет вызвана при проверке пустоты данных для виджета. Функция должна быть синхронная и возвращать true или false в зависимости от наличия данных в виджете для отображения.

Принимает на вход:

загруженные данные виджета
props - настройки виджета

// TypeScript
{
   ...
   "meta": {
      "isEmptyCallback": "HowEasy/callbacks/isEmptyCallback"
   },
   ...
}

Настройка возможности обработки клика в режиме конструирования

По умолчанию виджеты дашборда в режиме конструирования некликабельны. Для того, чтобы сделать виджет кликабельным, нужно установить в поле meta.interactiveInDesigntime значение true.

interactiveInDesigntime: boolean - признак того, что виджет кликабелен в режиме конструирования.

// TypeScript
{
   ...
   "meta": {
      "interactiveInDesigntime": true
   },
   ...
}

Базовые свойства виджета

У всех виджетов для дашборда есть базовые свойства:

height: number - высота виджета в пикселях. Подробнее про размеры виджета читайте в разделе "Настройка размера виджета".
emptyHidden: boolean - определяет, должен ли скрываться виджет при отсутствии данных. Применяется только при указании поля meta.isEmptyCallback.
headingVisible: boolean - определяет видимость заголовка виджета.
heightMode: Dashboard/interface:IHeightMode - определяет режим высоты виджета.
colors: Dashboard/interface:IColorsConfig - определяет цвет фона и маркера виджета.

Возможны 9 цветов фона виджета:

default
transparent
primary
brand
info
danger
success
warning
unaccented

и 8 цветов маркера:

transparent
primary
brand
info
danger
success
warning
unaccented

У всех базовых свойств есть значения по умолчанию:

height = 272
emptyHidden = false
headingVisible = true
colors = {marker: "brand", background: "default"}
heightMode = "limited"

Значения базовых свойств приходят в опции виджета вместе со значениями прикладных свойств. Название опции соответствует названию свойства. Если для виджето свойство не настроено, то будете передано значение по умолчанию.

Базовые свойства виджета редактируются с помощью PropertyGrid вместе с прикладными свойствами:

Изменение значений по умолчанию для базовых свойств виджета

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

Пример изменения свойств по умолчанию:

// TypeScript
{
   ...
   "propTypes": [{
       "name": "colors",
       "defaultValue": {
         "marker": "success",
         "background": "success"
       }
   }, {
       "name": "headingVisible",
       "defaultValue": false
   }, {
       "name": "height",
       "defaultValue": 276
   }, {
       "name": "emptyHidden",
       "defaultValue": true
   }]
   ...
}

Настройка фона виджета

Фон виджета настраивается с помощью стандартного диалога редактирования в редакторе дашбордов.

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

Пример использования css переменной --widget_background-color:

.myClass {
   ...
   background: linear-gradient(to top, var(--widget_background-color), transparent);
}

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

Скрытие категорий уведомлений при отображении виджета

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

Для настройки вам нужно в поле meta настроить поле hiddenNoticeCategories.

Список соответствия идентификаторов и названий категорий уведомлений можно посмотреть здесь.

// TypeScript
{
   ...
   "meta": {
      "hiddenNoticeCategories": [19, 23]
   },
   ...
}

Настройка отображения виджета для дашборда

Настройка размера виджета

Настройка режима высоты виджета

Настройка виджета с бесконечным скроллом

Обрезание контента виджета по высоте

Настройка отступов внутри виджета

Настройка заголовка

Настройка пустого состояния

Настройка возможности обработки клика в режиме конструирования

Базовые свойства виджета

Изменение значений по умолчанию для базовых свойств виджета

Настройка фона виджета

Скрытие категорий уведомлений при отображении виджета