# Источники данных задач (taskSource)
## Общие положения
Источники данных задач (**TaskSources**) используются для настройки контейнеров-синдикатов. Источник данных может объединять данные из нескольких категорий или использовать сложные условия отбора данных.
Вы можете выбрать один из существующих источников данных из выпадающего списка и отредактировать его. После внесения изменений нажмите кнопку **Сохранить**.
Источник данных задач может задаваться в одном из двух режимов: как **фильтр поиска** или как **смарт-фильтр**. Чтобы выбрать нужный режим, кликните мышью на левую или правую часть блока "**Фильтр задач**":
|Название|Описание|
|-|-|
|**Фильтр задач**||
|Фильтр поиском|Настройка параметров отбора задач. По ссылке "Открыть настройки поиска" открывается окно расширенного поиска: ⚠️ Параметры не сохраняются и при повторном открытии окна редактирования сбрасываются (становятся пустыми)!|
|Смарт-фильтр|Выбор готового смарт-фильтра из выпадающего меню (чтобы отредактировать выбранный фильтр, нажмите ) или создание нового (нажмите). Открывается обычное окно редактирования смартов.
⚠️ Смарт-фильтр не должен содержать сортировки (если это запрос на TSQL, он не должен содержать `ORDER BY`).
⚠️ В смарт-фильтре можно использовать параметр `@ContextId` (ID задачи) и `@CurrentSessionUserId` (Id текущего пользователя).
⚠️ Контроль прав запроса возлагается на системного администратора. Для контроля прав используйте процедуру `fn_UserTskPermissions()`|
|**Сортировка**||
|Поле|Название поля, по которому осуществляется сортировка задач|
|Смарт-выражение|Смарт-выражение, определяющее сортировку задач ⚠️ Смарт-выражение не должно содержать сортировки (если это запрос на TSQL, он не должен содержать `ORDER BY`)|
|Сортировать|Порядок сортировки (по возрастанию\по убыванию)|
|Выводить|Пустые записи (не содержащие значений) можно выводить в начале или в конце отсортированного списка|
## Создание taskSource с нуля
Источники данных задач создаются и редактируются в **админ-панели 1Ф**, а не в конфигурации МП. В МП они потом подключаются по `Id` контейнера или по `dataSourceUrl` в настройках плитки / кнопки.
Минимальная последовательность:
1. **Открыть админ-панель** → раздел **«Источники данных задач»** (`TaskSources`).
2. **Создать новый источник** — кнопка «Добавить источник» (или открыть существующий из выпадающего списка для редактирования).
3. **Указать название.** `Id` сгенерируется сам системой, он используется в МП для ссылки на этот таск-сорс.
4. **Задать фильтра задач** — задать «Смарт-фильтр» (см. таблицу «Фильтр задач» ниже).
5. **Задать сортировку** — поле или смарт-выражение, направление, поведение пустых значений (см. таблицу «Сортировка» ниже).
6. **Сохранить источник.** После сохранения он становится доступен в МП по `Id` (для контейнеров, например TaskSource67) или через `dataSourceUrl` публикации (для `CustomTaskSource`, который является отдельной публикацией на языке программирования Lua).
7. **Подключить в МП.** Чтобы пользователь увидел новый таск-сорс, нужно либо:
- добавить плитку `taskSourceDashboardItem` и указать в качестве Id, например, TaskSource67, где 67 - это номер сорса. Если же сорс является публикацией, то в качестве Id для плитку нужно указывать статичное CustomTaskSource, и задать значение для поля `dataSourceUrl`, где будет указан url(в относительном формате без домена),ведущим на этот источник;
- либо настроить `onTap` (например, на кнопке rbb) с `action = openTaskSource` и нужным `dataSourceUrl` или `Id`.
*Окно создания источника данных задач в админ-панели 1Ф.*
*Главное окно админ-панели TaskSources — параметры фильтра задач и сортировки.*
> ⚠️ Если у клиента стандартных возможностей фильтрации недостаточно — используйте `CustomTaskSource` через публикацию пакетов действий (см. раздел [CustomTaskSource](#customtasksource) ниже).
## Особенности использования
**Структура отдачи taskSource**
```
{tasks, categories, templates}
```
В `task` МП находит нужную категорию и далее находит нужный шаблон для отображения.
Кастомная ячейка рендерится в МП вертикально, где по вертикали задан в шаблоне порядок элементов (основных и доп. параметров). Это следует иметь в виду при настройке дин. шаблонов.
В `template` структура имеет вид:
```
{settings, sections > blocks > elements}
```
## Типовой и нетиповой дизайн
В источнике данных могут присутствовать задачи из разных категорий. Для каких-то категорий могут быть настроены свои шаблоны для вывода задачи в списке (**cell**), и эти шаблоны могут внешне отличаться друг от друга. В этом случае список задач в источнике данных может получиться внешне разнородным и плохо читаемым. Чтобы управлять этим, в шаблоне **taskSourceDashboardItem** есть параметр **cellStyle**, который может принимать значения **default** и **custom**.
- Если выбрано значение **default**, то для всех задач в списке будет применяться единый шаблон по умолчанию. Это сделает список однородным, но особенности отображения задач в разных категориях потеряются.
- Если выбрано значение **custom**, то для отображения каждой задачи будет использоваться шаблон **Cell**, указанный в ее категории, а если шаблон в категории не указан, то будет использоваться шаблон по умолчанию. Это сделает список разнородным, но позволит учесть особенности отображения разных задач.
## CustomTaskSource
Если для источника данных недостаточно стандартных возможностей платформы, определяющих поведение или внешний вид списка задач, можно использовать публикации пакетов действий.
В этом случае используется контейнер с Id равным **CustomTaskSource**. Для контейнера настраивается шаблон **taskSourceDashboardItem**. В параметре **cellStyle** шаблона указывается значение **custom**. В параметр **dataSourceUrl** записывается адрес вызова публикации (при необходимости задаются значения параметров). Публикация должна возвращать данные в формате JSON, соответствующие по структуре и наполнению динамическому шаблону. В этой публикации можно настроить и детализацию данных (drill-down) по нажатию на какое-то поле.
## Поведение при пустом результате
Если источник данных задач в момент отображения возвращает пустой список, поведение зависит от того, **где** этот источник используется:
### В полноэкранном списке задач
Показывается **глобальный плейсхолдер** — картинка из ключа `EmptyFeedPlaceholderURL` в `MobileAppSettings`. Если ключ не задан, отображается слово «Пусто».
### В плитке таск-сорса на дашборде
Поведение задаётся комбинацией ключей плитки `taskSourceDashboardItem`:
| Ключ | Что делает | Где задаётся |
|---|---|---|
| `emptyContentTitle` | Заголовок-заглушка, который отображается на плитке вместо счётчика, если список пустой. Например, `"Нет задач"`, `"Всё сделано"`. Если не задан — на плитке остаётся только заголовок без подсказки | На плитке `taskSourceDashboardItem` |
| `hideOnZeroCount` | `1` — скрыть плитку при пустом счётчике; `0` — оставить видимой с `emptyContentTitle` (или просто без бейджа) | На плитке |
| `tickerAlias` | Alias настроенного тикера для счётчика (без него сервер не считает значение для плитки таск-сорса) | На плитке |
**Связка с `tasksCounters`** в отдаче контейнера:
- Сервер в JSON-отдаче контейнера возвращает блок `data.tasksCounters` с числовыми значениями счётчиков (например, `overdueTasksCount`, `newTasksCount`).
- Для **синдиката** (`SubcatNNN`, `Feed` и т.п.) клиент берёт эти значения автоматически и показывает в бейдже плитки.
- Для **таск-сорса** (`TaskSourceNNN`, `CustomTaskSource`) `tasksCounters.allTasksCount` приходит как `null` — сервер не знает, какой именно тикер актуален для этой плитки. Поэтому требуется явный `tickerAlias` на плитке (см. [Ограничения при использовании на дэшборде](#ограничения-при-использовании-на-дэшборде) ниже).
## Ограничения при использовании на дэшборде
Когда источник данных задач размещается на дашборде в виде плитки (шаблон блока `taskSourceDashboardItem`), действуют ограничения по выводу счётчиков, отличные от обычного синдиката:
- **Актуальный счётчик задач на плитке не выводится.** Сервер не считает значение для плитки таск-сорса так же, как для синдиката. Чтобы на плитке появился числовой бейдж — настройте кастомный тикер и укажите его alias в ключе `tickerAlias` шаблона плитки. Без `tickerAlias` бейдж со счётчиком отображаться не будет.
- **При `hideOnZeroCount = 1`** плитка скрывается, если счётчик пуст или равен нулю. У плитки таск-сорса без настроенного `tickerAlias` счётчик всегда пуст, поэтому плитка не отобразится. Чтобы плитка была видна — либо отключите `hideOnZeroCount` (значение `0`), либо настройте `tickerAlias`.
Если задача — отображать актуальное число задач из таск-сорса на дашборде, требуется явно настроенный тикер. Без него используйте таск-сорс в полноэкранном режиме (через контейнер-синдикат).