Представления

Представления в Tessa являются источником табличных данных, которые могут использоваться для автодополнения, для выпадающих списков, для справочников с поиском, группировкой и постраничным отображением, для отчётов с выгрузкой в html или csv и др. Редактирование, отладка, предпросмотр и настройка прав для представлений выполняются на вкладке Представления.

Настройки представления

Добавим представление, используя кнопку "+" -> Представление на верхней панели (справа от кнопки обновления).

Для созданного представления укажем:

• Алиас - уникальный алиас представления, посредством которого к представлению возможно обращение как из расширений, так и для связи с ссылочными контролами, такими как Reference. Назовём представление AbDocumentTypes;

• Имя - отображаемое имя представления по умолчанию, используется как имя узла по умолчанию в дереве рабочего места (отображаемого в TessaClient), а также при импорте/экспорте представлений. Непосредственное значение этого свойства не выводится пользователю, но бывает полезно указать поясняющее название для удобства работы с представлением. Например, “Document types”;

• Группа - это группа, используемая для группировки представлений в редакторе. Не выводится пользователю, поэтому может быть любой. Укажем Ab, чтобы группировка была такой же, как в схеме данных и в типах карточек.

Нажмём кнопку Сохранить всё, чтобы сохранить представление.

Представление – источник табличных данных, и обычно оно задаётся шаблонизируемым SQL-запросом к БД. Поэтому представление может возвращать любые данные или справочники (причём не только с карточками, но и с таблицей-перечислением, как в нашем случае), а также отчёты (такие как отчёты КИД по завершённым заданиям, которые объединяют множества таблиц и используют агрегатные функции для определения количества заданий, сгруппированного по каждому сотруднику или департаменту).

Рассмотрим другие настройки представления, которые задаются в многострочных полях ввода:

• Метаданные – метаинформация с указанием параметров пейджинга (постраничного отображения), названий выводимых колонок, сортировок, параметров фильтрации, сабсетов (группировок) и ссылок (т.е. описаний, на какие сущности ссылается каждая строка таблицы; например, строка может ссылаться как на документ, так и на контрагента, указанного в этом документе). Подробное описание синтаксиса есть в руководстве разработчика и руководстве администратора;

• Запрос – шаблонизируемый SQL с запросом SELECT. Шаблонизируемость позволяет системе изменять запрос в зависимости от того, какие параметры, группировки и сортировки выбраны. Например, добавлять в выражение ORDER BY имя колонки, для которой выполняется сортировка;

• Описание – это произвольное текстовое описание представления, т.е. комментарий. Система никак не использует значение этого поля.

Метаинформация представления и шаблонизируемый запрос

Укажем следующие значения в полях Метаданные и Запрос:

Перейдите во вкладку `Редактор JSON` и вставьте следующий код:

{
  "Alias": "AbDocumentTypes",
  "Appearance": null,
  "Appearances": null,
  "AutoSelectFirstRow": true,
  "AutoWidthRowLimit": null,
  "Caption": "Document Types",
  "CollapseGroups": false,
  "Columns": [
    {
      "Alias": "DocTypeID",
      "Appearance": null,
      "CalendarIDColumn": null,
      "CalendarOverdueFormat": null,
      "CalendarQuantsColumn": null,
      "Caption": null,
      "Condition": null,
      "DisableGrouping": false,
      "HasTag": false,
      "Hidden": true,
      "InvisibleByDefault": false,
      "Localizable": false,
      "MaxLength": null,
      "PlannedColumn": null,
      "SortBy": null,
      "SortByFormat": null,
      "TreatValueAsUtc": false,
      "Type": "$AbDocumentTypes.ID"
    },
    {
      "Alias": "DocTypeName",
      "Appearance": null,
      "CalendarIDColumn": null,
      "CalendarOverdueFormat": null,
      "CalendarQuantsColumn": null,
      "Caption": "Name",
      "Condition": null,
      "DisableGrouping": false,
      "HasTag": false,
      "Hidden": false,
      "InvisibleByDefault": false,
      "Localizable": false,
      "MaxLength": null,
      "PlannedColumn": null,
      "SortBy": "t.Name",
      "SortByFormat": null,
      "TreatValueAsUtc": false,
      "Type": "$AbDocumentTypes.Name"
    }
  ],
  "ConnectionAlias": null,
  "DefaultSortColumns": [
    {
      "Alias": "DocTypeName",
      "SortDirection": "Ascending"
    }
  ],
  "EnableAutoWidth": false,
  "ExportDataPageLimit": null,
  "Extensions": null,
  "FormatVersion::int": 3,
  "GroupingColumn": null,
  "MultiSelect": false,
  "Overrides": null,
  "PageLimit": null,
  "Paging": "No",
  "Parameters": [
    {
      "Alias": "Name",
      "AllowedOperands": null,
      "AutoCompleteInfo": null,
      "AutoCompleteMapping": null,
      "Caption": "Name",
      "Condition": null,
      "DateTimeType": null,
      "DisallowedOperands": null,
      "DropDownInfo": null,
      "EmptyStringIsNotNull": false,
      "Hidden": false,
      "HideAutoCompleteButton": false,
      "IgnoreCase": true,
      "Multiple": true,
      "RefSection": null,
      "TreatValueAsUtc": false,
      "Type": "$AbDocumentTypes.Name"
    }
  ],
  "QuickSearchParam": null,
  "References": [
    {
      "CardType": null,
      "CardTypeColumn": null,
      "ColPrefix": "DocType",
      "Condition": null,
      "DisplayValueColumn": "DocTypeName",
      "IsCard": false,
      "OpenOnDoubleClick": false,
      "RefSection": [
        {
          "::single_type": "str"
        },
        "AbDocumentTypes"
      ]
    }
  ],
  "RowCountSubset": null,
  "RowCounterVisible": false,
  "SelectionMode": "Row",
  "Subsets": null,
  "TagsPosition": "None",
  "TreatAsSingleQuery": false,
  "TreeGroup": null,
  "TreeGroupDisplayValue": null,
  "TreeGroupId": null,
  "TreeGroupParentId": null,
  "TreeId": null,
  "TreeParentId": null
}

select
    t.ID as DocTypeID,
    t.Name as DocTypeName
from AbDocumentTypes t with(nolock)
where 1=1
    #param(Name, t.Name)
order by #order_by

Рассмотрим вкладку Метаданные:

• В поле Alias указан алиас представления, т.е. имя, которое используется при выборе представления в узле рабочего места, в элементе управления “Представление” и т. д.

• Поля Appearance и Appearances позволяют определить внешний вид представления (подробнее см. в документации разработчика).

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

• Значение AutoWidthRowLimit позволяет определить максимальное количество строк в наборе данных, при котором будет работать автоматический расчет ширины столбцов.

• Поле Caption задает отображаемое имя или заголовок представления.

• Выставленный флаг CollapseGroups указывает на то, что все группировки таблицы будут свернуты при открытии представления.

• В массиве Columns описываются колонки, возвращаемые в запросе SELECT:

  • Alias – это алиас колонки, т.е. то имя колонки, которое возвращает SELECT в SQL-запросе;

  • Appearance позволяет определить внешний вид ячейки столбца.

  • Caption - определяет имя колонки, выводимое пользователю в заголовке. Для колонки DocTypeName с названием типа документа у колонки устанавливается заголовок Name;

  • Type – тип данных в ячейке;

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

  • MaxLength - максимальное количество символов в ячейке (подробнее см. в документации разработчика);

  • SortBy - содержит список колонок с возможностью указания порядка сортировки, который в сформированном запросе будет подставлен на место плейсхолдера #order_by при сортировке по колонке (причём направление сортировки ASC или DESC при необходимости добавляется системой автоматически);

  • SortByFormat – это шаблон кастомного SQL-выражения, которое может быть подставлено в запросе на место плейсхолдера #order_by при сортировке по колонке;

  • HasTag - признак отображения тегов в ячейке (подробнее см. в документации разработчика);

  • Hidden - определяет видимость колонки. Для колонки DocTypeID мы указываем Hidden: true, чтобы эта колонка не отображалась в таблице, которая выводится пользователю;

  • Признак TreatValueAsUtc используется для колонок с типами DateTime и DatetTime2 и определяет, что значение должно быть представлено в формате UTC;

  • Localizable - определяет признак того, что значение колонки должны быть локализовано при выводе в пользовательском интерфейсе;

  • DisableGrouping - определяет запрет группировки таблицы по данной колонке;

  • InvisibleByDefault - признак того, что колонка скрыта в пользовательском интерфейсе по умолчанию, но её видимость можно изменить с помощью пользовательских настроек (по умолчанию колонка видна).

  • CalendarIDColumn, CalendarOverdueFormat, CalendarQuantsColumn, PlannedColumn используются для настройки колонки с указанием ссылки на кванты календаря (подробнее см. в документации разработчика).

• В поле ConnectionAlias можно указать алиас строки подключения к БД из конфигурационного файла для случая, если выборку в представлении нужно сделать из базы данных, отличной от заданной по умолчанию.

• В массиве DefaultSortColumns настраиваются колонки, сортировка по которым выполняется по умолчанию (т.е. при открытии узла с представлением или при выборе из выпадающего списка):

  • Alias – алиасы колонок;

  • SortDirection - направление сортировки для колонки (Ascending - по возрастанию, Descending - по убыванию);

• Флаг EnableAutoWidth определяет, будет ли автоматически рассчитываться ширина столбцов в представлении.

• В поле ExportDataPageLimit можно задать число строк, которое представление будет возвращать при экспорте данных в режиме пейджинга (по умолчанию 1000).

• Массив Extensions содержит информацию о расширениях представления (подробнее см. в документации разработчика).

• В поле FormatVersion указана версия JSON-формата представления.

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

• Флаг MultiSelect определяет возможность множественного выбора строк в таблице.

• Массив Overrides содержит информацию о перегрузках основных настроек представления (подробнее см. в документации разработчика).

• Поле PageLimit позволяет задать число строк, которое будет возвращать представление в режиме постраничного вывода (по умолчанию 20).

• Массив Parameters описывает параметры поиска (фильтрации) представления:

  • Alias – алиас параметра, который используется для шаблонизации запроса, а также для указания, каким образом будет выполняться фильтрация при вводе текста в ссылочный контрол Reference с автодополнением;

  • В полях AllowedOperands и DisallowedOperands можно задать разрешенные и запрещенные типы фильтрации по данному параметру. Могут иметь следующие значения: Between, Contains, NotContains, StartWith, EndWith, Equality, NonEquality, GreatOrEquals, GreatThan, LessOrEquals, LessThan, IsNull, IsNotNull, IsTrue, IsFalse.;

    Note

    Параметры типов фильтрации с отрицательной коннотацией, такие как “Не содержит” (NotContains) и “Не равен” (NonEquality), в запросах к представлениям объединяются логическим оператором “И”, а параметры остальных типов — логическим оператором “ИЛИ”.

  • Caption – название параметра, выводимое пользователю в диалоге выбора параметров фильтрации;

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

  • AutoCompleteInfo, AutoCompleteMapping, HideAutoCompleteButton, DropDownInfo, RefSection - настройки автокомплита и выпадающего списка (подробнее см. в документации разработчика);

  • Флаг Hidden, при его указании, позволяет скрыть параметр для выбора пользователем. Это позволяет по-прежнему использовать параметр для фильтрации из контрола, или для связи представлений master-detail, или для вызова представлений из расширений и др.;

  • Флаг IgnoreCase определяет, учитывается ли при фильтрации регистр символов. Не используется с MS SQL Server;

  • Флаг Multiple определяет, можно ли добавить в параметр несколько значений, связанных через “или”. Если параметр отображается пользователю (т.е. не скрыт через Hidden), то пользователь может задать несколько значений, например, “Name равен Incoming ИЛИ Name равен Outgoing”;

  • Флаг Mandatory определяет, является ли параметр обязательным, если флаг установлен, то такой параметр всегда должен передаваться в запросе к представлению;

  • Признак TreatValueAsUtc используется для параметров с типами DateTime и DatetTime2 и определяет, что значение должно быть представлено в формате UTC;

  • Type – тип данных параметра.

• В поле Paging определяется режим разбиения результатов выборки на страницы (пейджинга). Допустимые значения: No (пейджинг отключен), Always (пейджинг включен), Optional (режим пейджинга зависит от настроек узла рабочего места).

• Значение поля QuickSearchParam содержит алиас параметра для быстрого поиска.

• Массив References позволяет указать системе, что в каждой строке представления содержится ссылка на некоторую сущность системы. В нашем случае это ссылка на тип документа, который указан в свойстве RefSection. В одной строке может быть несколько ссылок, так, в строке в представлении “ActionHistory” для логов аудита предоставляются ссылки как на карточку, с которой произведено действие (открытие, удаление и т.п.), так и на запись в логе аудита, которую можно открыть по двойному клику;

  • CardType – поле, в котором можно указать алиас типа карточки;

  • CardTypeColunm – поле, в котором можно указать алиас колонки, где хранится алиас типа карточки;

  • ColPrefix – префикс алиасов колонок, которые входят в ссылку. Система считает, что все колонки, алиасы которых начинаются на эту строку, входят в ссылку, а значит, например, могут записываться в карточку при выборе в контроле Reference. Для нашего представления – это колонка DocTypeID с числовым идентификатором типа документа и колонка DocTypeName с именем типа;

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

  • RefSection – список таблиц, на которые ссылается эта ссылка. Это свойство используется при выборе значений через кнопку с троеточием в ссылочных контролах Reference;

    Example

    Например, ссылочная колонка “AbDocuments.Type” в схеме данных в свойстве “Referenced table” ссылается на таблицу AbDocumentTypes, поэтому контрол Reference, связанный с этой колонкой, по кнопке с троеточием откроет диалог с выбором всех представлений, у которых в RefSection присутствует эта таблица AbDocumentTypes. Ниже мы увидим пример использования такой возможности.

  • DisplayValueColumn – алиас колонки, которая считается отображаемым значением для ссылки. Обычно это свойство используется только для определения названий карточек, открываемых по ссылке (название отображается в заголовке вкладки), если для карточки явно не была определена функция Digest, формирующая название по другим полям карточки;

  • IsCard – признак того, что ссылка ссылается на карточку. В рассматриваемом случае это не карточка, а строка таблицы-перечисления, поэтому указываем “false”;

  • OpenOnDoubleClick – признак того, что карточка будет открыта при двойном клике по строке представления. Поскольку тип документа – это не карточка, то указываем значение “false”.

• В поле RowCountSubset можно указать подмножество, используемое для получения количества элементов в запросе.

• Флаг RowCounterVisible указывает, будет ли отображен счетчик строк.

• В поле SelectionMode задается режим выделения табличных данных: Row (строка) или Cell (ячейка).

• Массив Subsets содержит информацию о подмножествах представления (подробнее см. в документации разработчика).

• В поле TagsPosition задается режим отображения тегов в представлении: No (теги не отображаются), Top (над строкой), Bottom (под строкой), InColumn (в отдельной ячейке).

• Флаг TreatAsSingleQuery определяет режим выполнения SQL-запроса. Если флаг выставлен, то запрос будет выполняться без дополнительной компиляции.

• Значения полей TreeGroup, TreeGroupDisplayValue, TreeGroupId, TreeGroupParentId, TreeId, TreeParentId определяют свойства древовидной группировки представления (подробнее см. в документации разработчика).

Множественная передача параметров из master-представления в detail-представление

Для связки master-detail представлений множественная передача параметров будет работать, если:

• у master-представления настроен множественный выбор строк (флаг метаданных представления MultiSelect);
• у master-представления указан режим выбора “Строка”;
• у detail-представления замапленный параметр поддерживает множественную передачу значений (флаг метаданных параметра представления Multiple).

Если вышеуказанные условия не соблюдены, передаётся только один параметр.

Note

Множественная передача параметров не работает, если у master-представления установлен режим выбора “Ячейка”.

Отладка представления

В поле Запрос мы записали SQL-запрос с плейсхолдерами #param для подстановки параметра фильтрации Name и #order_by для сортировки по колонке DocTypeName. Посмотрим, каким будет сгенерирован запрос на вкладке Отладка, переключиться на которую можно в правом верхнем углу окна.

Кнопка на верхней панели (Сформировать текст запроса) генерирует текст для запроса, используя шаблонизацию текста в поле Запрос, Кнопка Выполнить запрос и отобразить данные выполняет запрос и выводит его результаты в таблице ниже Результат выполнения запроса. Справа указываются параметры фильтрации, передаваемые в запрос, причём некоторые из них являются системными:

• Name – это наш параметр фильтрации по имени типа. Именно этот параметр должен использоваться при вводе данных в контроле Reference;

• Текущий сотрудник – это системный параметр с идентификатором текущего пользователя. Используя его, можно, например, в представлении “My tasks” (мои задания) выводить только задания текущего пользователя;

• Locale – имя культуры (языка) текущего пользователя. Строка “ru” соответствует русскому языку. С помощью этого параметра можно локализовать значения в результате запроса Запрос.

• Форматирование дат и чисел – имя настроек форматирования для текущего пользователя (обратитесь к разделу Форматирование дат и чисел). Строка “ru” соответствует форматированию в соответствии с российскими стандартами. С помощью этого параметра можно форматировать дату, время и числа в результате запроса Запрос.

Ниже в группе Сортировка указываются названия колонок, для которых возможна сортировка (для нас это DocTypeName с именем типа документа) и направление сортировки (по возрастанию, по убыванию, или отсутствует для колонки). Т.к. по умолчанию в метаинформации #view была указана колонка DocTypeName с направлением сортировки по возрастанию, то именно эти значения были выбраны.

В сгенерированном SQL-запросе видно, что плейсхолдер #order_by был заменён на “t.Name asc”, где “t.Name” - значение свойства SortBy в метаинформации #column для колонки DocTypeName. Таким образом, в SQL сортировка будет выполняться для поля AbDocumentTypes.Name по возрастанию.

Укажем слева в параметре Name значение In для оператора сравнения начинается с кликнем по имени параметра. Ещё раз нажмём на кнопку генерации и выполнения запроса.

Результаты такого же запроса, но с оператором содержит, будут выведены в выпадающем списке контрола с автодополнением, когда пользователь начнёт вводить in для ввода типа документа (ввод выполняется без учёта регистра символов, т.е. для значений параметра in или IN результат будет одинаковым). Будут выведены все строки, которые содержат значение “in”:

Параметр #param(Name, t.Name) указывает, что при вводе параметра с алиасом Name (алиас задаётся в метаинформации #param, в нашем случае алиас и отображаемое имя одинаковы) значение этого параметра будет сравниваться с полем t.Name. Для выбранного значения параметра плейсхолдер #param был заменён на AND ((t.Name like ('%' + @NAME_1+'%'))), и, если подставить значение параметра, то это будет AND t.Name like '%in%', т.е. поле AbDocumentTypes.Name должно содержать подстроку in.

Предпросмотр представления

Теперь переключимся на режим “Просмотр” (справа от “Отладка”). Этот режим позволяет увидеть, каким образом представление будет отображаться для пользователя в дереве рабочего места.

Кнопка фильтра (слева от кнопки обновления) открывает диалог фильтрации, где пользователь может выбрать фильтрацию по отображаемым параметрам (для которых не указано Hidden: true в метаинформации #param).

После выбора значения текущие параметры фильтрации будут отображаться в области над представлением.

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

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

Для представления осталось настроить последнюю важную деталь: список ролей, для которых представление доступно. Если представление недоступно для пользователя, то он не может получить его данные любым из способов (при вводе в контроле поле будет отображаться с красной рамкой, кнопка выпадающего списка работать не будет, а через троеточие или в дереве рабочего места в главном окне узел с представлением не будет отображён). Т.е. недоступное по правам представление для приложения TessaClient идентично отсутствующему представлению.

По умолчанию список ролей пуст, и представление доступно только для администраторов, т.к. администраторам доступны абсолютно все представления в системе. Чтобы представление с типами документов было доступно всем сотрудникам, добавим роль Все сотрудники (в которую входят все сотрудники), начав вводить это поле, а потом нажав два раза [Enter] для его добавления в список.

Связь представления со ссылочным контролом

Теперь сохраним представление и вернёмся в редактор типа карточки AbDocument.

Свяжем представление с контролом для ввода типа документа, указав его свойства:

• Алиас представления – алиас представления, из которого будут получены данные при вводе в текстовое поле. У нас это “AbDocumentTypes”. Если значение не указано, то в поле нельзя будет ввести данные посимвольно с автодополнением, но можно будет выбрать представление другим способом (из выпадающего списка или по кнопке с троеточием);

• Алиас параметра – алиас параметра, в который будет передана строка, которую пользователь начал вводить в поле для ввода. Причём строка передаётся в параметр с оператором содержит. У нас это параметр Name. Если пользователь ввёл букву “o”, то в параметр с алиасом Name в представлении с алиасом AbDocumentTypes будет передано значение “содержит ‘o’“. После этого SQL представления выполняется, возвращает две строки “Incoming” и “Outgoing”, которые и выводятся в выпадающем списке;

  

• Алиас представления выпадающего списка – алиас представления, используемого для отображения данных по кнопке выпадающего списка со стрелкой “вниз”. При этом в представление не передаются параметры (если это не указано явно в настройках маппинга представления, о чём подробнее можно узнать в руководстве администратора). Выпадающий список обычно имеет смысл только для небольших справочников, таких как наш справочник типов документов. Поэтому запишем значение “AbDocumentTypes” в это поле;

• Выпадающий список – флаг, который включает режим выпадающего списка. С отключённым флагом кнопка со стрелкой вниз отображаться не будет независимо от значения свойства Алиас представления выпадающего списка. Обычно и включают этот флаг, и задают алиас представления;

  

• Разрешить открывать ссылки – флаг, разрешающий открытие карточки по двойному клику по значению в поле (или через контекстное меню на введённом значении). Карточка открывается по идентификатору, указанному во внешнем ключе колонки, с которой связан контрол. Поскольку тип документа – это не карточка, то снимем этот флаг.

Свойства контрола будут выглядеть следующим образом:

Если в форме нажать на кнопку троеточия, то будет выведено такое предупреждение:

Это означает, что или нет ни одного представления, доступного по правам доступа (по списку ролей), или в системе нет подходящих представлений, размещённых в рабочих местах. Можно скрыть кнопку троеточия, поставив флаг Скрывать кнопку выбора, т.к. для такого небольшого по размерам справочника нет смысла организовывать сложный выбор из различных представлений с фильтрацией.

Но мы рассмотрим, как добавить представление в рабочее место, чтобы оно отображалось при нажатии кнопки с троеточием.