Форматтеры

Форматтеры (formatters) определяют способ отображения значений атрибутов в ячейках колонок журнала. Каждый тип форматтера задаёт собственный внешний вид и поведение ячейки — от простого текста до цветных индикаторов, ссылок, дат и скриптовых вычислений. Форматтер задаётся в конфигурации колонки журнала в поле formatter.

Примечание

В форматтерах могут использоваться вычисляемые атрибуты.

Настройки

Перейти в раздел администрирования > Журналы > найти необходимый журнал > действие Редактировать. Перейти в Дополнительно.

Выберите форматтер из списка, заполните ключ-значение:

Типы

AssocFormatter / Ассоциация

Тип: assoc

Конфигурация:

Ключ

Значение

sourceId

Идентификатор ассоциации

openInBackground

Открыть в новой вкладке ECOS

openNewBrowserTab

Открыть в новой вкладке браузера

ActionFormatter / Действие

Тип: action

Конфигурация:

Ключ

Значение

type

<тип действия>

actionId

<id типа действия>

Предполагается в строке журнала наличие id или recordRef — ref записи, необходимый для выполнения действия.

Пример:

По клику на информацию в поле (1) в соседней вкладке Citeck открывать дашборд с данными документа (2):

../../../_images/action_formatter_example_1.png

Настройка форматтера:

../../../_images/action_formatter_example.png

где:

  • type — view

  • actionId — view-dashboard

BooleanFormatter / Логическое выражение

Тип: bool

Конфигурация:

Простой форматтер, который отдаёт «Да» или «Нет» в ячейке.

ColoredFormatter / Цвет

Тип: colored

Универсальный форматтер для отображения значений с цветовой индикацией.

Функции

  • Поддержка как предопределённых цветов (через классы CSS), так и пользовательских цветов HEX.

  • Использование идентификатора для сопоставления цветов и локализованного значения для отображения.

  • Возможность отображения цветного индикатора в качестве указателя или фона.

  • Если в showPointer установлено значение false, цвет фона отображается в виде закруглённого овала.

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

Параметры конфигурации

Параметр

Тип

По умолчанию

Описание

color

Object

{}

Сопоставление значений объектов с цветами.

showPointer

Boolean

false

Показывать ли цветной указатель. Если false, показывает закруглённый овальный фон.

defaultColor

String

'#FFFFFF'

Цвет по умолчанию для значений, не найденных в color. Может быть HEX или именованным цветом.

fn

String/Function

Скрипт или функция для определения цвета текста.
Предопределённые цвета

Форматтер поддерживает следующие предопределённые цвета:

  • green;

  • yellow;

  • pink;

  • red.

Для пользовательских цветов используйте формат HEX (например, «#FF0000»).

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

../../../_images/color_formatter_1.png

Функция должна вернуть строку с CSS-цветом (WebColor или HEX):

if (cell.disp.length > 2) return "red"

или:

if (cell.disp.length > 2) return "#FF0000"

Использование

Базовое использование с предопределёнными цветами

- id: priority
  name:
    ru: Приоритет
    en: Priority
  type: TEXT
  editor:
    type: select
  formatter:
    type: colored
    config:
      color:
        low: green
        medium: yellow
        high: pink
        urgent: red

Использование с цветами HEX

- id: priority
  name:
    ru: Приоритет
    en: Priority
  type: TEXT
  editor:
    type: select
  formatter:
    type: colored
    config:
      color:
        low: '#00FF00'
        medium: '#FFFF00'
        high: '#FF69B4'
        urgent: '#FF0000'

Использование с указателем на дисплее

- id: priority
  name:
    ru: Приоритет
    en: Priority
  type: TEXT
  editor:
    type: select
  formatter:
    type: colored
    config:
      color:
        low: green
        medium: yellow
        high: pink
        urgent: red
      showPointer: true

Использование с цветом по умолчанию

- id: priority
  name:
    ru: Приоритет
    en: Priority
  type: TEXT
  editor:
    type: select
  formatter:
    type: colored
    config:
      color:
        low: green
      defaultColor: '#CCCCCC'

Использование с именованным цветом по умолчанию

- id: priority
  name:
    ru: Приоритет
    en: Priority
  type: TEXT
  editor:
    type: select
  formatter:
    type: colored
    config:
      color:
        low: green
      defaultColor: 'red'

Форматирование цвета на основе скрипта

- id: priority
  name:
    ru: Приоритет
    en: Priority
  type: TEXT
  editor:
    type: select
  formatter:
    type: colored
    config:
      fn: 'if (cell.value > 2) return "#e2e2e2"'
      defaultColor: '#FFFFFF'

DateFormatter / Дата

Тип: date

Конфигурация:

Ключ

Значение

format

Временной формат (по умолчанию 'DD.MM.YYYY')

DateTimeFormatter / Дата и время

Тип: datetime

Конфигурация:

Ключ

Значение

format

Временной формат (по умолчанию 'DD.MM.YYYY HH:mm')

relative

Флаг, который будет отсчитывать время, которое прошло

DefaultFormatter / По умолчанию

Тип: default

Конфигурация:

Всегда отдаёт строковое значение, полученное из значения атрибута. Если ячейка имеет булево значение, то отдаёт «Да» или «Нет».

DurationFormatter / Продолжительность

Тип: duration

Конфигурация:

Ключ

Описание

showSeconds
При применении в журнале отображается запись в формате 1d 2h 30m 2s.
Возможные значения: true / false.
По умолчанию секунды отображаются — showSeconds = true.

maxAsHours
При применении в журнале продолжительность будет трансформироваться в часы, то есть 2d 3h 30m = 51h 30m.
Возможные значения: true / false.

Пример:

formatter:
  type: duration
  config:
    maxAsHours: true

FileNameFormatter / Имя файла

Тип: filename

Конфигурация:

Всегда отдаёт ссылку на документ вида:

<a href="${URL.DASHBOARD}?recordRef=${row.id}" target="_blank" rel="noopener noreferrer">
  <icon />
  { НАЗВАНИЕ ЯЧЕЙКИ}
</a>

HtmlFormatter / HTML

Тип: html

Конфигурация:

Ключ

Значение

html

Строка с HTML-кодом

LinkFormatter / Ссылка

Тип: link

Link форматтер используется для ячеек журнала с использованием полей (колонок) в качестве переменных.

Варианты конфигурации открытия ссылки по форматтеру

Список вариантов:

updateUrl {boolean}
openNewTab {boolean}
openNewBrowserTab {boolean}
reopenBrowserTab {boolean}
closeActiveTab {boolean}
openInBackground {boolean}
pushHistory {boolean}
replaceHistory {boolean} - default true, if updateUrl is true
rerenderPage {boolean} - needed to replace link in the router and start rerendering page

Ссылка по шаблону с использованием переменных

Добавлена возможность строить ссылки по шаблону с использованием переменных (атрибутов записи/полей журнала). Шаблон адреса ссылки задаётся в параметрах форматтера для столбца в конфигурации журнала (Форматтер для колонки).

Пример шаблона ссылки:

urlTemplate: "https://example.com/path?var1=${columnId1}&var2=${columnId2}"

где columnId1 и columnId2 — колонки журнала.

В качестве наименования ссылки используется значение ячейки. Если значения нет, то наименование = url.

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

Например:

Выбрать форматтер Ссылка (1) и указать:

  • ключ (2) — url,

  • значение (3) — ${$computed.url}.

../../../_images/link_formatter_1.png

Указать:

  • id (4) — url,

  • type (5) — value.

В конфигурации указать:

  • ключ (6) — value,

  • значение (7) — https://host/${?id}&${?disp}.

../../../_images/link_formatter_2.png

В журнале выглядит следующим образом:

../../../_images/link_formatter_3.png

По клику на наименование будет открываться ссылка.

NumberFormatter / Число

Тип: number

Конфигурация:

Ключ

Описание

mask

маска, где {value} — само число

locales
Какую локаль использовать для форматирования.
От неё зависит, как будут разделяться тысячи и дробные числа (точкой, запятой или пробелом). По умолчанию — текущая локаль.

maximumFractionDigits

сколько чисел после запятой

decimalSeparator

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

thousandSeparator

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

Пример:

mask: {value} руб.
locales: ru
maximumFractionDigits: 16
decimalSeparator: .
thousandSeparator: ,

Например:

Ключ

Описание

mask

{value} руб

maximumFractionDigits

2

decimalSeparator

.

thousandSeparator

_
../../../_images/number_formatter_1.png

ScriptFormatter / Скрипт

Тип: script

Конфигурация:

Ключ

Значение

fn
Тип: String
Тело функции. В любом месте скрипта можно использовать return.
В теле функции доступны следующие параметры:
_ — библиотека Lodash (https://lodash.com/docs/)
t — вспомогательная функция локализации. Принимает ключ и возвращает локализованное значение, либо сам ключ, если перевод отсутствует.
vars — переменные из конфигурации.
cell — значение текущей ячейки.
row — вся строка.
index — индекс значения в ячейке (для множественных значений).

Функция может возвращать значения разных типов:
Булево — заменяется на локализованное значение по ключу boolean.yes для true и boolean.no для false;
Число или Строка — результат отображается в ячейке;
Объект — воспринимается как конфигурация для следующего форматтера в формате {"type":"...", "config": {...}}.
Если в объекте есть cell, то значение оттуда используется как значение ячейки для следующего форматтера.
Если в объекте нет cell, то используется оригинальное значение ячейки.

vars
Тип: Object
Дополнительные переменные, которые могут понадобиться при выполнении скрипта.
Внутри скрипта к ним можно обращаться через vars.yourVariable, где yourVariable — это имя ключа в объекте vars.
Это полезно, например, когда нужно динамически подгрузить дополнительные данные через функционал форматтеров,
заменяющий все вхождения вида ${...} на соответствующие значения атрибутов.
Например, если указать vars: { currency: "${currencyAssoc.code!'unknown'}" }, то в скрипте через vars.currency
можно получить код валюты из ассоциации currencyAssoc.

Пример использования:

formatter:
  type: script
  config:
    vars:
      processingStatus: ${processingStatus}
    fn: return Citeck.messages.global[vars.processingStatus];

Если есть необходимость вызвать другой форматтер, например HtmlFormatter:

formatter:
  type: script
  config:
    fn: |
      const cellNum = _.parseInt(cell) || 0;
      let link = "";
      if (cellNum > 100000) {
        link = "https://duckduckgo.com/";
      } else if (cellNum > 1000) {
        link = "https://www.yahoo.com/";
      } else {
        link = "https://www.google.com/";
      }
      return {
        "type": "html",
        "config": {
          "html": "<a href='" + link + "' target='_blank'>" + link + "</a>"
        }
      };

WorkflowPriorityFormatter / Приоритет рабочего процесса

Тип: workflowPriority

to be updated