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

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

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

По умолчанию виджет имеет высоту 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
   },
   ...
}

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

Режимы для задания высоты виджета

В опции каждого виджета приходит свойство heightMode, определяющее режим для задания высоты виджетов.

Свойство может принимать следующие значения:

limited,
endlessScroll,
expandable.

Значение endlessScroll устанавливается в режиме просмотра, если виджет является последним в дашборде. Значение expandable устанавливается в режиме просмотра, если виджет находится в блоке из одной колонки и при этом не является последним в дашборде. В остальных случаях устанавливается значение limited.

Если heightMode имеет значение endlessScroll или expandable, виджету устанавливается автовысота.

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

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

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

Виджет с поддержкой бесконечного скрола может работать в 2 режимах:

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

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

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

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

Пример настройки виджета с бесконечным скроллом и с возможностью раскрытия на все содержимое контента:

<!-- WML -->
<div>
   <ws:if data="{{_options.heightMode === 'endlessScroll'}}">
      <Controls.list:View
         keyProperty="key"
         source="{{_source}}"
         navigation="{{_navigation}}">
      </Controls.list:View>
   </ws:if>
   <ws:else data="{{_options.heightMode === 'expandable'}}">
      <Controls.scroll:Container>
         <Controls.list:View
            keyProperty="key"
            source="{{_source}}">
         </Controls.list:View>
      </Controls.scroll:Container>
      <Controls.toggle:Separator bind:value="_expanderValue" on:valueChanged="_loadData()"/>
   </ws:else>
   <ws:else data="{{_options.heightMode === 'limited'}}">
      <Controls.scroll:Container>
         <Controls.list:View
            keyProperty="key"
            source="{{_source}}"
            navigation="{{_navigation}}">
         </Controls.list:View>
      </Controls.scroll:Container>
   </ws:else>
</div>

<!-- TypeScript -->
protected _source = new Memory({
   ...
});

protected _navigation = {
   source: 'position',
   view: 'infinity',
   sourceConfig: {
      field: 'key',
      position: null,
      direction: 'forward'
   }
};

protected _loadData(): void {
   // загружаем новые записи для списка
}

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

При изменении высоты виджета в режиме конструирования контент виджета обрезается в соответствии с установленной высотой. Если контент виджета больше минимальной высоты в 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 - высота виджета в пикселях. Подробнее про размеры виджета читайте в разделе "Настройка размера виджета".
layout: Dashboard/interface:ILayoutConfig - раскладка виджета. Определяет наличие маркера, фона и заголовка.
emptyHidden: boolean - определяет, должен ли скрываться виджет при отсутствии данных. Применяется только при указании поля meta.isEmptyCallback.
color: string - стиль виджета.

От указанного стиля виджета зависит цвет маркера и цвет фона виджета. Возможны 9 стилей виджета:

transparent
primary
brand
info
danger
success
warning
secondary
unaccented

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

height = 272
color = 'brand'
layout = {heading: true, marker: true, background: false}
emptyHidden = false

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

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

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

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

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

// TypeScript
{
   ...
   "propTypes": [{
       "name": "color",
       "defaultValue": "success"
   }, {
       "name": "layout",
       "defaultValue": {"heading": false, "marker": true, "background": true}
   }, {
       "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]
   },
   ...
}

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

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

Режимы для задания высоты виджета

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

Настройка виджета с возможностью раскрытия его на все содержимое контента

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

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

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

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

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

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

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

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

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