# Дашборды — паттерны настройки

Паттерны настройки дашбордов (порталов) в 1Форме: создание порталов, режимы верстки (Dashboard/CSS Grid/Flex/Board), права доступа, типы виджетов, настройка источников данных, подсказки и легенды виджетов, таблица с Drill Down.

## 1. Создание дашбордов

Дашборд (портал) — пространство с виджетами, аналог рабочего стола. Стартовая страница системы — главный портал, открывается по клику на логотип.

![Пример дашборда с виджетами-графиками разных типов: линейный, столбчатый, секторный, воронка продаж, спидометр](https://help.1forma.ru/help-images/portal/portal_widgets.png)

Создание: Администрирование - Пользовательский интерфейс - Порталы - Добавить портал - ввести название - Ок.

**Режимы верстки**

| Режим | Когда использовать |
|-------|--------------------|
| **Dashboard** | Основной режим. Сетка с виджетами, перетаскивание, изменение размеров. Наибольшее число типов виджетов |
| **CSS Grid** | Адаптивная сетка: блоки разных размеров, комбинирование нескольких стратегий на одной странице. Единственный режим, где работают «Навигация» и «Мини-опрос» |
| **Flex** | Устаревший режим. Адаптивная верстка контейнерами; для новых порталов не используется — его задачи решает CSS Grid |
| **Board** | Секции, группы, вкладки, несколько страниц. Собран поверх Dashboard: каждая секция — встроенный Dashboard-портал. Ссылки в верхней части портала |

Переключение: кнопка "Дизайнер" - выбрать режим - Сохранить.

**Виджеты, добавленные в одном режиме, после смены на другой не отображаются.**

**Дизайнер Dashboard**

Сетка + панель настроек справа. Добавление виджета через "+", перемещение перетаскиванием, изменение размеров за нижний край.

**Дизайнер CSS Grid**

Адаптивная сетка из блоков разного размера. Блоки размещаются в ячейках сетки, размер и положение задаются перетаскиванием. Доступны все типы виджетов, включая «Навигацию» и «Мини-опрос», которые в Dashboard не отображаются.

**Дизайнер Flex (устаревший)**

Контейнерная верстка. Основной элемент — родительский контейнер с дочерними. Управление через контекстное меню (ПКМ): добавить контейнер, настройка, удалить. Добавление виджетов из списка блоков ("+"). Режим сохранён для уже созданных порталов; для новых страниц используйте CSS Grid.

**Дизайнер Board**

Древовидная структура: Портал - Группы - Секции. Группа объединяет секции во вкладки. Секция — отдельный дашборд. Поддерживает ссылки на другие страницы/порталы в верхней части.

**Права доступа на портал и добавление в избранное**

Кнопка "Доступ" в меню портала - указать группы пользователей. Администраторы видят портал в конструкторе даже без доступа.

Добавление в "Избранное": кнопка "Добавить в избранное" - указать группы, для которых ссылка добавится в блок "Избранное".

**Доступ к секциям Board (вкладкам).** У каждой секции Board — свой отдельный дашборд с собственными правами доступа, независимыми от общего доступа к порталу. Если содержимое дашборда одной из секций недоступно (например, нет прав на него) — при переходе на соответствующую вкладку вместо содержимого показывается «Нет доступа». Переключение на остальные вкладки продолжает работать как обычно.

## 3. Типы виджетов (дизайнер Dashboard)

Доступные типы виджетов в дизайнере Dashboard:

| Тип | Назначение |
|-----|-----------|
| **Блок поиска задач** | Задачи из категории/произвольного источника. Список или карточки. Новости, объявления, встречи |
| **Список задач** | Задачи текущего пользователя: на сегодня, активные, просроченные, на подписи и др. |
| **Таблица** | Сводная информация из SP. Поддержка Drill Down |
| **График (диаграмма)** | Столбчатая, круговая, линейный и др. |
| **Меню** | Набор кнопок с настраиваемыми действиями (открытие отчёта, задачи) |
| **Контакты** | Список контактов с чатом, звонками, календарной занятостью |
| **Кнопка-тикер** | Блок со счётчиком, ссылкой, иконкой и кнопкой создания задачи |
| **Баннер-кнопка** | Баннер со ссылкой на объект, визуальные эффекты |
| **Счётчики** | До 6 счётчиков, прямые/обратные метрики, %, штуки. Источник — smart |
| **Диаграмма Ганта** | Временная шкала задач с цветом по статусу |
| **Smart HTML** | Произвольный HTML + Mustache + SMART/T-SQL |
| **Календарь** | Информация с привязкой к дате/периоду, шаблон как Smart HTML |
| **Степпер** | Пошаговый алгоритм с интерактивным выбором шага |

### График (диаграмма): значения подсказки и цвет сегмента

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

Цвет сегмента, возвращённый хранимой процедурой источника данных, применяется к диаграмме независимо от числа серий в наборе данных — и при одной серии, и при нескольких.

Цвет сегмента принимается, если задан как HEX (`#RGB` / `#RRGGBB`), `rgb`/`rgba`, `hsl`/`hsla`, простая CSS-переменная (`var(--имя)`) или безопасное именованное имя цвета. Значение в другом формате заменяется на чёрный (`#000000`) — если сегменты неожиданно стали чёрными, проверьте формат заданного цвета.

## 4. Настройка виджетов — общие паттерны

**Права доступа виджета**

Поле "Доступен для групп" — обязательно включать Administrators (облегчает диагностику).

**Источники данных**

- **Блок поиска задач**: категория или smart-фильтр в "Дополнительных настройках"
- **Список задач**: встроенные источники (задачи на сегодня, активные, просроченные и т.д.)
- **Контакты**: smart-выражение для выборки пользователей
- **Таблица, Кнопка-тикер, Счётчики**: smart/T-SQL
- **График**: SQL-объект (процедура/view/таблица) или смарт-запрос — по сериям, взаимоисключающе для всего графика

**Smart-фильтр для виджета "Блок поиска задач"**

Дополнительные настройки - Фильтр задач - переключить на smart-фильтр - "+".

Усечение времени до даты при сравнении сроков — иначе сравнение будет с точностью до секунды.

**Виджет "Меню" — кнопки**

Добавление через "Дополнительные настройки" или кнопку "Добавить" в редакторе дашборда. Для каждой кнопки:

- "Текст ссылки" — отображаемый текст
- "Ссылка" — **относительная** (без домена, от первого `/`)

**Использовать относительные ссылки**, чтобы настройки работали на любой площадке. Пример: `/spa/report/72`, `/spa/tasks/<номер>`.

Динамическая ссылка — smart-выражение, формирующее URL вида `/spa/tasks/<номер задачи>`.

**Виджет "Контакты" — пример smart для выборки по группе**

```sql
SELECT u.userid
FROM Users u WITH (NOLOCK)
JOIN usergroups g WITH (NOLOCK)
  ON g.userid = u.userid
 AND g.groupid = 935   -- ID группы
```

**Виджет "Счётчики" — конфигурация**

- До 6 счётчиков в одном виджете
- Значения через smart-выражения
- Поддержка прямых и обратных метрик; параметр «Тип значения» с двумя вариантами (Проценты / Штуки).
- Параметр «Тип числа» — формат отображения значения: Числовой, Денежный (всегда два знака после запятой) или Процентный.
- Заголовок может содержать ссылку на объект

## 5. Подсказка и легенда виджета

Начиная с версии 2.268.334 у всех виджетов портала появились дополнительные элементы оформления.

**Подсказка**

Рядом с заголовком виджета отображается значок (i). При нажатии на него открывается карточка задачи 1Форма, заданной в настройках виджета — она служит контекстной справкой. Если связанная задача является пространством, она открывается как пространство, иначе — как обычная модальная карточка. Чтобы задать подсказку, в настройках виджета укажите номер задачи 1Форма. Если задача не существует или у пользователя к ней нет доступа, значок не отображается. Опция с динамическим выбором задачи через смарт-выражение для подсказки не предусмотрена — поле `HintSmartId` в схеме БД отсутствует, в отличие от легенды.

**Легенда**

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

- **Фиксированный текст** — введите текст с Markdown-разметкой в дополнительных настройках виджета.
- **Динамическая через смарт-выражение** — настройте смарт-выражение (SmartScript), которое возвращает текст с разметкой. Легенда будет обновляться в зависимости от данных и контекста пользователя.

Если не задан ни фиксированный текст, ни смарт-выражение, блок легенды не отображается. Подсказка и легенда доступны для всех типов виджетов.

### Безопасность HTML в легенде и индикаторах

Если легенда виджета или индикатор в ячейке таблицы содержат HTML-разметку (в том числе из SmartScript), перед показом она очищается: базовое форматирование и платформенные иконки (`mat-icon`) сохраняются, а скрипты и небезопасные теги удаляются. Настраивайте оформление встроенными средствами виджета; если легенда или индикатор перестали отображаться, проверьте, не используется ли в разметке удалённый тег.

## 6. Виджет "Таблица" с Drill Down

**Источник данных — хранимая процедура**

Виджет "Таблица" получает данные из **хранимых процедур SQL**.

Обязательные входные параметры SP:

| Параметр | Тип | Назначение |
|----------|-----|-----------|
| `@XmlParam` | XML | Параметры фильтрации (из виджета) |
| `@DrilldownField` | varchar | Колонка, по которой запрошена детализация |
| `@DrillDownParams` | varchar | Параметры детализации |
| `@UserID` | int | Текущий пользователь |

**Фильтры виджета**

Настройки фильтрации - Создать фильтр - Добавить параметр (тип "Период", "Выпадающий список" и др.). Параметр задаётся на латинице — по нему обращение в SP.

Парсинг параметров в SP:

```sql
-- Получить параметры из XML
EXEC crm_repGetParams @XmlParam, @Params OUTPUT

-- Извлечь период
SELECT @startDate = [From], @endDate = [To]
FROM @Params
WHERE Name = 'periodFilter'
```

**Логика Drill Down в одной SP**

```sql
IF @DrillDownField = '' OR @DrillDownField IS NULL
BEGIN
    -- Основная таблица
    SELECT ...
END
ELSE
BEGIN
    -- Детализация: парсим @DrillDownParams
    -- Определяем колонку по @DrillDownField
    SELECT ...
END
```

Параметры Drill Down извлекаются из `@DrillDownParams` в табличную переменную `@DrillParams`, доступ по ключу (колонка `Name`).

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

1. Дополнительные настройки виджета - ввести имя SP
2. Отобразятся колонки — проставить галки "Отображать", задать "Имя" на русском
3. Для Drill Down: указать SP и "Колонку для функции Drill Down"
4. Для каждого столбца с Drill Down — настроить колонки детализированной таблицы (шестерёнка в колонке "Детализация")


### Экспорт данных

Виджет «Таблица» позволяет выгрузить отображаемые данные. Значения фильтров и параметры детализации (drill-down) кодируются в адрес выгрузки, поэтому фильтры со спецсимволами (`&`, `=`, пробелы и др.) экспортируются корректно. Объём выгрузки определяется правами текущего пользователя и настроенными фильтрами — экспорт не открывает данные в обход прав.

### 6.1. Автовысота таблицы

В дополнительных настройках виджета «Таблица» (блок «Таблица») доступны два флага автовысоты.

| Флаг | Поведение |
|------|-----------|
| **Автовысота таблицы** | Отключает внутренний скролл таблицы: высота грида подстраивается под количество строк (ag-grid `domLayout: autoHeight`) — сколько данных, столько и отображается. Если рядом на портале более высокий виджет, место под короткой таблицей остаётся пустым. |
| **Автовысота дриллдауна** | При проваливании в детализацию (Drill Down) высота пересчитывается под новый контент. Если флаг выключен — высота фиксируется по исходной таблице, а при большем объёме данных появляется внутренний скролл. |

Без «Автовысоты таблицы» виджет работает как раньше — с фиксированной высотой по сетке портала и внутренним скроллом. Настройки относятся к виджету «Таблица» (ag-grid) на портале.