Настройка канбана с помощью шаблона

ℹ️ Настройка работает, начиная с 2.259 версии системы

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

1. Создание шаблона задач

В режиме администрирования перейдите к странице Шаблоны задач в разделе МП. Нажмите кнопку Создать.

В открывшемся окне задайте параметры:

• Контекст — Cell

• Тип — dynamic

• Категория — Категория, для которой создается шаблон

Имя шаблона, язык и описание могут иметь любое значение.

1. Настройка шаблона

Стандартное тело динамического шаблона — это JSON трехуровневой структуры: sections -> blocks -> elements.

Базовый вид шаблона:

{
 "contexts": [
   {
     "context": "kanban",
     "settings": {
       "templateClass": "kanban"
     },
     "sections": [
       {
         "settings": {},
         "blocks": [
           {
             "alias": "header",
             "elements": []
           },
           {
             "alias": "body",
             "elements": []
           },
           {
             "alias": "footer",
             "elements": []
           }
         ]
       }
     ]
   }
 ]
}

Шаблон канбана описывается в блоке Sections — он содержит только один элемент, соответствующий карточке канбана. В блоке задаются параметры blocks и settings.

showHeaderColors

Цветовое обозначение статусов в канбане по умолчанию соответствует цветам в настройках этих статусов. При этом завершающие статусы всегда имеют зеленый цвет, а отклоняющие — красный, для них смена цвета недоступна. Опционально можно отключить цветовое обозначение статусов в представлении категории Канбан — в таком случае все статусы будут окрашены в серый цвет. Сделать это можно с помощью параметра showHeaderColors, который указывается в секции contexts внутри settings.

Пример фрагмента:

{
 "contexts": [
   {
     "context": "kanban",
     "settings": {
       "templateClass": "kanban",
      "showHeaderColors": false
     }\...

Пример отображения статусов в канбане, когда showHeaderColors не задан или принимает значение true:

Пример отображения статусов в канбане, когда showHeaderColors принимает значение false:

Секция Blocks

В Blocks задаются блоки внутри карточки канбана:

• header и footer — Блоки с предопределенным видом, который можно конфигурировать внутри массива elements.

• body — Динамический блок, в котором можно отображать значения ДП или системных полей задачи. ДП выводятся в карточке, только если в них есть значение.

Каждый блок содержит параметры:

• alias — Определяет тип блока (header, body, footer).

• elements — Описывает элементы внутри блока.

Элементы для блоков с типом header и footer:

Элемент с источником данных из системного параметра:

{
   "type": "mainParam",
   "dataKey": "taskId",
   "alias": "cardIdentifier",
   "viewMode": "valueOnly",
   "settings": {
       "prefix": "\#"
   }
}

Элемент с источником данных из ДП:

{
 "type": "extparam",
 "alias": "headerCounter",
 "dataKey": 12872,
 "settings": {
   "color": "default",
   "emphasis": "container"
 }
}

Описание параметров блоков:

Параметр

Описание

type

Тип источника данных

mainParam

Системный параметр

extparam

ДП

dataKey

Для ДП ("type":"extparam") в dataKey указывается ID ДП.

Для системных параметров задачи ("type":"mainParam") dataKey может принимать следующие значения:

taskText

Текст задачи

taskId

Номер задачи

priority

Приоритет

state

Статус

dueDate

Срок

performers

Исполнители

owner

Заказчик

alias (для header)

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

title

Заголовок — текст задачи

headerCounter

Индикатор с количеством задач. В секции можно задать параметры:

• color — Цвет счетчика. Возможные значения:

• primary

• accent

• info

• success

• warning

• fav

• danger

• error

• default

• blackWhite

• emphasis — Акцент счетчика. Возможные значения:

• accent

• container

Пример фрагмента:

 "alias": "headerCounter",
                 "dataKey": 12872,
                 "settings": {
                   "color": "default",
                   "emphasis": "container"
                 }

subtitle

Подзаголовок, вторая строка

mainTag

Главный тег.  В секции можно задать параметр:

• color — Цвет счетчика. Возможные значения:

• primary

• accent

• info

• success

• warning

• fav

• danger

• error

• default

• blackWhite

tags

Теги задачи. Приходят в viewTags задачи. Для другого источника данных пока не работает

headerDate

Дата заголовка. Выполняет функцию отображения срока

cover

Обложка карточки канбана. В секции settings для данного alias можно задать параметры:

• showEmptyCover — Показать пустую обложку. Обязательный параметр, должно быть указано true.

• ratioWH — Соотношение сторон изображения. Доступные значения:

• 16:9

• 1:1

Пример фрагмента:

"alias": "cover",
        "settings": {
             "ratioWH": "16:9",
             "showEmptyCover": true
                     }

alias (для footer)

Возможные значения:

avatar

Аватар карточки задачи. В dataKey необходимо передать ID ДП с типом "Файл", в котором хранится аватар.

Пример фрагмента:

{
            "alias": "footer",
            "elements": \
              {
                "type": "extparam",
                "dataKey": 14089,
                "alias": "avatar"
              }
            \
          }

priority

Приоритет. Для отображения можно передать dataKey: priority, либо для кастомного поля в settings передать поле valueMapper (см. пример)

Пример фрагмента:

{
 "type": "mainParam",
 "dataKey": "priority",
 "alias": "priority",
 "viewMode": "valueOnly",
 "settings": {
   "valueMapper": {
     "0": "low",
     "3": "high"
   }
 }
}

users

Пользователи. Например, исполнители задачи или значение в ДП "Выбор пользователей". Для отображения в параметр viewMode элемента необходимо передать значение table.

cardIdentifier

Текстовое или числовое значение. В settings можно передать поле prefix, который добавит префикс к значению.

totalSubtasks

Общее количество подзадач.

Пример фрагмента:

{
  "type": "mainParam",
  "dataKey": "totalSubtasks",
  "alias": "totalSubtasks"
}

Может использоваться для отображения значения из ДП с типом Число — в таком случае alias остается без изменений, в параметре type должно быть задано значение extparam, а в dataKey указан ID нужного ДП.

Пример фрагмента (ДП Число):

{
  "type": "extparam",
  "dataKey": 1234,
  "alias": "totalSubtasks"
}

activeSubtasks

Число активных подзадач.

Пример фрагмента:

{
  "type": "mainParam",
  "dataKey": "activeSubtasks",
  "alias": "activeSubtasks"
}

Может использоваться для отображения значения из ДП с типом Число — в таком случае alias остается без изменений, в параметре type должно быть задано значение extparam, а в dataKey указан ID нужного ДП.

Пример фрагмента (ДП Число):

{
  "type": "extparam",
  "dataKey": 1234,
  "alias": "activeSubtasks"
}

viewMode

Параметр вида. Для отображения пользователей необходимо передать значение table, для остальных типов данных можно не передавать.

settings

Является параметром, который необходимо описать для определенных полей.

Например, если мы хотим чтобы перед номером задачи в footer отображался символ #, то в settings элемента нужно передать параметр prefix со значением префикса (в нашем случае #). Ниже будут описаны возможные settings для каждого элемента.

Элементы для блока с типом body

Элемент с источником данных из системного параметра:

{
 "type": "mainParam",
 "dataKey": "owner",
 "viewMode": "table"
}

Элемент с источником данных из ДП:

{
 "type": "extparam",
 "name": "Клиентский срок",
 "viewMode": "icon",
 "dataKey": 12187,
 "settings": {
   "icon": "myicons-825"
 }
}

Описание параметров блоков:

Параметр

Описание

type

Тип источника данных

mainParam

Системный параметр

extparam

ДП

name

Название поля. Если значение не задано, по умолчанию будет отображаться в зависимости от типа источника данных: название ДП или название системного поля.

dataKey

Для ДП ("type":"extparam") в dataKey указывается ID ДП.

Для системных параметров задачи ("type":"mainParam") dataKey может принимать следующие значения:

taskText

Текст задачи

taskId

Номер задачи

priority

Приоритет

state

Статус

dueDate

Срок

performers

Исполнители

owner

Заказчик

viewMode

Параметр вида. В отличие от header и footer, для блока body viewMode является обязательным параметром. Возможные значения:

normal

Названия параметров отображаются строкой выше значений

compact

Названия параметров отображаются слева от их значений. Является значением по умолчанию, если не передать другой viewMode.

Параметры отображаются без названий

Параметры в карточке не отображаются

Используется для отображения пользователей. В settings можно передать "showUserStatus": true чтобы отобразить статус пользователя "как в ленте"

icon

Вместо названия параметра отображается иконка слева. Необходимо передать icon в settings элемента.

Вместо значений ДП с типом "Выбор нескольких задач из категории" (Multilookup) передавать иконки задач.

Опционально иконки могут быть окрашены в соответствии с цветом выбранных в ДП задач, для этого необходимо передать showColor в settings элемента.

tags

Значения ДП "Lookup" и "Выбор нескольких задач из категории" (Multilookup) в виде тегов. Опционально в карточке можно отображать иконки задач-значений ДП с соответствующим цветом, для этого необходимо передать showIcon и showColor в settings элемента.

   "type": "extparam",
   name": "Компании",
   "viewMode": "tags",
   "dataKey": 2570,
   "settings": {
        "showIcon": true,
        "showColor": true
               }

settings

Параметр, который необходимо описать для определенных полей.

icon

При viewMode: icon задается иконка из списка иконок. Список доступных иконок можно найти по адресу: https://Адрес_1Формы/spa/content-icons

truncate

Обрезка текстовых значений полей и заголовков.

Возможные значения: true (обрезать, текст при достижении максимально доступного значения обрезается троеточием) / false (не обрезать, текст отображается полностью с переносом на следующую строку).

По умолчанию true.

showUserStatus

Отображение статуса пользователей в viewMode: table для полей с выбором пользователей.

Возможные значения: true (отображать) / false (не отображать).

По умолчанию false.

showIcon

Признак отображения иконки задачи, выбранной в ДП, при viewMode: tags

showColor

Признак отображения цвета задачи, выбранной в ДП, при viewMode: tags. При использовании в leftBorder значение true переключает режим на автоматическое определение цвета по значению поля: для dataKey: "priority" — системный цвет приоритета (поддерживаются все 5 уровней), для Lookup-полей — цвет самого значения (taskColor), если он задан. В этом режиме dynamicSettings/valueMapper не используется.

Секция Settings

В Settings содержатся настройки карточки канбана. Из параметров доступны leftBorder , groupings , aggregations и sortings.

leftBorder отвечает за левую обводку карточки.

Пример:

"leftBorder": {
         "type": "mainParam",
         "dataKey": "priority",
         "alias": "leftBorder",
         "dynamicSettings": {
           "0": {
             "color": "var(\--base-info)"
           },
           "3": {
             "color": "var(\--base-danger)"
           }
         }
       }

Если для элемента leftBorder задано settings.showColor: true, цвет левой полоски определяется автоматически по цвету значения задачи, а не по ручному dynamicSettings. Для системного поля priority это включает все 5 уровней приоритета: критичный, высокий, обычный, низкий и самый низкий. Для Lookup-полей при включённом showColor используется цвет самого значения (taskColor). Ручной dynamicSettings нужен только если требуется явно задать собственное сопоставление значений и цветов.

Пример минимальной настройки leftBorder с автоматическими цветами приоритета:

"leftBorder": { "type": "mainParam", "dataKey": "priority", "alias": "leftBorder", "settings": { "showColor": true } }

groupings позволяет задать список доступных группировок. Элементы в groupings имеют схожий вид с элементами в sections. Для указания группировки по умолчанию, которая будет отображаться для пользователей при переходе в Канбан, в "settings" параметр "isDefault" должен принимать значение "true".

Пример:

"groupings": [
         {
           "type": "mainParam",
           "dataKey": "performers",
           "name": "Исполнители",
           "settings": {
             "isDefault": true
           }

Если не указывать группировку, в выпадающем списке по умолчанию отображаются системные параметры: Исполнители, Заказчик, Срок, Дата создания, Дата изменения.

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

Параметр

Описание

column

ID ДП в формате ExtParam{ExtParamID}

 "column": "ExtParam12872"

name

Имя ДП

postfix

Текст, который добавляется после вычисленного значения

separator

Символ-разделитель, который используется между агрегациями

operation

sum

Сумма

avg

Среднее значение

max

Максимальное значение

min

Минимальное значение

Пример:

"aggregations": \
        {
          "column": "ExtParam12872",
          "name": "Efforts(сумма)",
          "postfix": "сум",
          "separator": "/",
          "operation": "sum"
        },
        {
          "column": "ExtParam12872",
          "name": "Efforts(среднее)",
          "postfix": "ср",
          "operation": "avg"
        }
     \

sortings задаёт сортировку карточек (порядок отображения) внутри каждой колонки. Эта настройка применяется ко всему представлению канбана и используется, когда требуется показывать наверху более приоритетные или срочные задачи, например просроченные, задачи с высоким приоритетом или карточки с заполненным значением определённого поля.

Сортировка задаётся на уровне конфигурации канбана, без пользовательского переключателя в интерфейсе. Такой вариант подходит для сценариев, где канбан настраивается администратором один раз и далее используется сотрудниками в фиксированном виде.

Поддерживаются два типа полей для сортировки:

1. Системные поля задачи — например срок, дата создания, приоритет.
2. Дополнительные параметры категории.

Для одного канбана можно задать несколько правил сортировки последовательно. В этом случае второе правило применяется к карточкам, равным по первому, третье — к карточкам, равным по первым двум, и т.д. Это позволяет, например, сначала поднимать вверх карточки с более высоким приоритетом, а затем внутри них сортировать задачи по сроку.

Типовые сценарии:

1. Сначала показать задачи с наибольшим приоритетом, затем — с ближайшим сроком.
2. Поднять вверх карточки, у которых заполнен определённый Lookup-параметр.
3. Отсортировать карточки по числовому ДП, например по количеству дней ожидания.

Важно учитывать следующие особенности:

1. Сортировка действует внутри колонки, а не меняет порядок самих колонок.
2. Если сортировка не задана, канбан использует стандартный порядок, возвращаемый источником данных.
3. Если настройка сортировки не выбрана, параметр сортировки не должен передаваться в запрос получения данных.
4. При настроенной сортировке перетаскивание карточек внутри колонки для пользователя недоступно — карточка возвращается на исходную позицию. Это позволяет сохранить заданный порядок без возможности случайного изменения.

В settings каждого элемента нужно передать direction и опционально isDefault.

"sortings": [
  {
    "type": "mainParam",
    "dataKey": "order",
    "name": "Порядок",
    "settings": {
      "direction": "desc"
    }
  },
  {
    "type": "mainParam",
    "dataKey": "createdTask",
    "name": "Дата создания",
    "settings": {
      "direction": "asc"
    }
  },
  {
    "type": "extParam",
    "dataKey": 76690,
    "name": "Фича",
    "settings": {
      "isDefault": true,
      "direction": "desc"
    }
  },
  {
    "type": "extParam",
    "dataKey": 2570,
    "name": "Компании",
    "settings": {
      "isDefault": true,
      "direction": "desc"
    }
  },
  {
    "type": "mainParam",
    "dataKey": "taskText",
    "name": "По алфавиту",
    "settings": {
      "direction": "asc"
    }
  }
]

Сохраните созданный шаблон.

Фильтрация по параметру

Канбан может быть построен не только по основному маршруту, но и по значениям параметра с типом Lookup поле. Любой из настроенных в категории параметров выбирается в меню Статус. Задать порядок колонок в канбане можно с помощью настройки определенного Lookup поля Колонка сортировки. Если настройка для параметра не задана, то по умолчанию колонки выводятся по алфавиту.

1. Настройка шаблонизации в категории

В настройках категории в блоке Формы перейдите к настройкам шаблонизации.

Выберите в списке созданный шаблон. Задайте для него следующие настройки:

• В колонке Клиент выберите значение all

• Активируйте опцию Активность правила

Пример настроенного шаблона

Шаблон задач:

{
 "contexts": [
   {
     "context": "kanban",
     "settings": {
       "templateClass": "kanban",
       "showHeaderColors": false,
       "leftBorder": {
         "type": "mainParam",
         "dataKey": "priority",
         "alias": "leftBorder",
         "dynamicSettings": {
           "0": {
             "color": "var(\--base-info)"
           },
           "3": {
             "color": "var(\--base-danger)"
           }
         }
       }
     },
     "sections": [
       {
         "blocks": [
           {
             "alias": "header",
             "elements": \
               {
                 "type": "mainParam",
                 "dataKey": "taskText",
                 "alias": "title"
               },
               {
                 "type": "mainParam",
                 "dataKey": "tags",
                 "alias": "tags"
               },
               {
                 "type": "extparam",
                 "name": "Efforts",
                 "alias": "headerCounter",
                 "dataKey": 12872,
                 "settings": {
                   "color": "default",
                   "emphasis": "container"
                 }
               }
             \
           },
           {
             "alias": "body",
             "elements": \
               {
                 "type": "mainParam",
                 "dataKey": "owner",
                 "viewMode": "table"
               },
               {
                 "type": "extparam",
                 "name": "Клиентский срок",
                 "viewMode": "icon",
                 "dataKey": 12187,
                 "settings": {
                   "icon": "myicons-825"
                 }
               },
               {
                 "type": "extparam",
                 "name": "Сборка",
                 "viewMode": "icon",
                 "dataKey": 7500,
                 "settings": {
                   "icon": "arrow-circle-login"
                 }
               }
             \
           },
           {
             "alias": "footer",
             "elements": \
               {
                 "type": "mainParam",
                 "dataKey": "performers",
                 "alias": "users",
                 "viewMode": "table"
               },
               {
                 "type": "mainParam",
                 "dataKey": "taskId",
                 "alias": "cardIdentifier",
                 "viewMode": "valueOnly",
                 "settings": {
                   "prefix": "\#"
                 }
               }
             \
           }
         ]
       }
     ]
   }
 ]
}