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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "Alias": "AbDocumentTypes",
  "Appearance": null,
  "Appearances": null,
  "AutoWidthRowLimit": null,
  "Caption": "Document Types",
  "Columns": [
    {
      "Alias": "DocTypeID",
      "Appearance": null,
      "Caption": null,
      "Condition": null,
      "DisableGrouping": false,
      "HasTag": false,
      "Hidden": true,
      "Localizable": false,
      "MaxLength": null,
      "SortBy": null,
      "TreatValueAsUtc": false,
      "Type": "$AbDocumentTypes.ID"
    },
    {
      "Alias": "DocTypeName",
      "Appearance": null,
      "Caption": "Name",
      "Condition": null,
      "DisableGrouping": false,
      "HasTag": false,
      "Hidden": false,
      "Localizable": false,
      "MaxLength": null,
      "SortBy": "t.Name",
      "TreatValueAsUtc": false,
      "Type": "$AbDocumentTypes.Name"
    }
  ],
  "ConnectionAlias": null,
  "DefaultSortColumns": [
    {
      "Alias": "DocTypeName",
      "SortDirection": "Ascending"
    }
  ],
  "EnableAutoWidth": false,
  "ExportDataPageLimit": null,
  "Extensions": null,
  "GroupingColumn": null,
  "MultiSelect": false,
  "Overrides": null,
  "PageLimit": null,
  "Paging": "No",
  "Parameters": [
    {
      "Alias": "Name",
      "AllowedOperands": null,
      "AutoCompleteInfo": null,
      "Caption": "Name",
      "Condition": null,
      "DisallowedOperands": null,
      "DropDownInfo": null,
      "Hidden": false,
      "HideAutoCompleteButton": false,
      "Multiple": true,
      "RefSection": null,
      "SourceViews": 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"
      ]
    }
  ],
  "RowCounterVisible": false,
  "RowCountSubset": null,
  "SelectionMode": "Row",
  "Subsets": null,
  "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

Рассмотрим поле Метаданные:

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

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

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

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

  • SortBy – это выражение, которое подставляется в запрос на месте плейсхолдера #order_by при сортировке по этому представлению (причём направление сортировки asc или desc добавляется системой автоматически);

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

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

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

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

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

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

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

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

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

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

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

    Example

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

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

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

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

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

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

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

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

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

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

Ниже в группе Сортировка указываются названия колонок, для которых возможна сортировка (для нас это 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” в это поле;

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

  

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

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

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

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

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