Работа с данными во front-end модулях Creatio реализована с помощью высокоуровневого класса EntitySchemaQuery, который предназначен для построения запросов на выборку из базы данных.
Особенности класса EntitySchemaQuery:
- Запрос на выборку данных EntitySchemaQuery строится c учетом прав доступа текущего пользователя.
- Механизм кэширования позволяет оптимизировать выполнение операций за счет обращения к кэшированным результатам запроса без дополнительного обращения к базе данных.
Алгоритм работы с данными во front-end модулях Creatio:
- Cоздайте экземпляр класса EntitySchemaQuery.
- Укажите корневую схему.
- Сформируйте путь к колонке корневой схемы для добавления колонки в запрос.
- Создайте экземпляры фильтров.
- Добавьте фильтры в запрос.
- Отфильтруйте результаты запроса.
Сформировать пути к колонкам относительно корневой схемы
Основой механизма построения запроса EntitySchemaQuery является корневая схема. Корневая схема — таблица базы данных, относительно которой строятся пути к колонкам в запросе, в том числе к колонкам присоединяемых таблиц. Для использования в запросе колонки из произвольной таблицы необходимо корректно задать путь к этой колонке.
Сформировать путь к колонке по прямым связям
Шаблон формирования пути к колонке по прямым связям ИмяСправочнойКолонки.
Например, есть корневая схема [City] из справочной колонкой [Country], которая через колонку Id связана со справочной схемой [Country].
Путь к колонке c наименованием страны, которой принадлежит город по прямым связям Country.Name. Здесь:
- Country — имя справочной колонки корневой схемы [City] (ссылается на схему [Country]).
- Name — имя колонки из справочной схемы [Country].
Сформировать путь к колонке по обратным связям
Шаблон формирования пути к колонке по обратным связям [ИмяПрисоединяемойСхемы:
Путь к колонке с именем контакта, который добавил город по обратным связям [Contact:Id:CreatedBy].Name. Здесь:
- Contact — имя присоединяемой схемы.
- Id — имя колонки схемы [Contact] для установки связи присоединяемой схемы.
- CreatedBy — имя справочной колонки схемы [City] для установки связи текущей схемы.
- Name — значение справочной колонки схемы [City].
Если в качестве колонки для связи у текущей схемы выступает колонка [Id], то ее можно не указывать: [ИмяПрисоединяемойСхемы:
Добавить колонки в запрос
Колонка запроса EntitySchemaQuery представляет собой экземпляр класса Terrasoft.EntityQueryColumn. В свойствах экземпляра колонки необходимо указать основные характеристики:
- Заголовок.
- Значение для отображения.
- Признаки использования.
- Порядок и позицию сортировки.
Для добавления колонок в запрос предназначен метод addColumn(), который возвращает экземпляр добавленной в запрос колонки. Имя колонки относительно корневой схемы в методах addColumn() формируется согласно правилам, описанным в статье Сформировать пути к колонкам корневой схемы. Разновидности метода addColumn() позволяют добавлять в запрос колонки с различными параметрами и представлены в таблице ниже.
Тип колонки | Метод |
---|---|
Колонка по заданному пути относительно корневой схемы | addColumn(column, columnAlias) |
Экземпляр класса колонки запроса | |
Колонка — параметр | addParameterColumn(paramValue, paramDataType, columnAlias) |
Колонка — функция | addFunctionColumn(columnPath, functionType, columnAlias) |
Колонка — агрегирующая функция | addAggregationSchemaColumnFunctionColumn(columnPath, aggregationType, columnAlias) |
Получить результат запроса
Результат выполнения запроса EntitySchemaQuery — коллекция сущностей Creatio. Каждый экземпляр коллекции — строка набора данных, возвращаемого запросом.
Способы получения результатов запроса:
- Вызов метода getEntity() для получения конкретной строки набора данных по заданному первичному ключу.
- Вызов метода getEntityCollection() для получения всего результирующего набора данных.
Управлять фильтрами в запросе
Фильтр — набор условий, применяемых при отображении данных запроса. В терминах SQL фильтр представляет собой отдельный предикат (условие) оператора WHERE.
Для создания простого фильтра в EntitySchemaQuery используется метод createFilter(), который возвращает созданный объект фильтра Terrasoft.CompareFilter. В EntitySchemaQuery реализованы методы создания фильтров специального вида.
Экземпляр EntitySchemaQuery имеет свойство filters, которое представляет собой коллекцию фильтров данного запроса (экземпляр класса Terrasoft.FilterGroup). Экземпляр класса Terrasoft.FilterGroup представляет собой коллекцию элементов Terrasoft.BaseFilter.
Алгоритм добавления фильтра в запрос:
- Создайте экземпляр фильтра для данного запроса (метод createFilter(), методы создания фильтров специального вида).
- Добавьте созданный экземпляр фильтра в коллекцию фильтров запроса (метод add() коллекции).
По умолчанию фильтры, добавляемые в коллекцию filters, объединяются между собой логической операцией AND. Свойство logicalOperation коллекции filters позволяет указать логическую операцию, которой необходимо объединять фильтры. Свойство logicalOperation принимает значения перечисления Terrasoft.core.enums.LogicalOperatorType (AND — И, OR — ИЛИ).
В запросах EntitySchemaQuery реализована возможность управления фильтрами, участвующими в построении результирующего набора данных. Каждый элемент коллекции filters имеет свойство isEnabled, которое определяет, участвует ли данный элемент в построении результирующего запроса (true — участвует, false — не участвует). Аналогичное свойство isEnabled также определено для коллекции filters. Установив это свойство в false, можно отключить фильтрацию для запроса, при этом коллекция фильтров запроса останется неизменной. Таким образом, изначально сформировав коллекцию фильтров запроса, в дальнейшем можно использовать различные комбинации, не внося изменений в саму коллекцию.
Формирование путей колонок в фильтрах EntitySchemaQuery осуществляется в соответствии с общими правилами формирования путей к колонкам относительно корневой схемы.
Путь к колонке корневой схемы
- Корневая схема: [Contact].
- Колонка с адресом контакта: Address.
Путь к колонке схемы по прямым связям
- Корневая схема: [Contact].
- Колонка с названием контрагента: Account.Name.
- Колонка с именем основного контакта у контрагента: Account.PrimaryContact.Name.
Путь к колонке схемы по обратным связям
- Корневая схема: [Contact].
- Колонка с именем контакта, который добавил город: [Contact:Id:CreatedBy].Name.
Класс EntitySchemaQuery предназначен для построения запросов на выборку из базы данных.
Методы
Прерывает выполнение запроса.
Создает и добавляет в коллекцию колонок запроса экземпляр функциональной колонки Terrasoft.FunctionQueryColumn с заданным типом AGGREGATION.
{String} column |
Путь колонки для добавления (указывается относительно rootSchema). |
{Terrasoft. |
Тип используемой агрегирующей функции. Возможные значения (Terrasoft.AggregationType)
Cреднее значение всех элементов. Количество всех элементов. Максимальное значение среди всех элементов. Минимальное значение среди всех элементов. Тип агрегирующей функции не определен. Сумма значений всех элементов. |
{String} column |
Псевдоним колонки (необязательный параметр). |
{Terrasoft. |
Область применения агрегирующей функции. Возможные значения (Terrasoft.AggregationEvalType)
Область применения агрегирующей функции не определена. Применяется для всех элементов. Применяется к уникальным значениям. |
Создает и добавляет в коллекцию колонок запроса экземпляр колонки Terrasoft.EntityQueryColumn.
{String/ |
Путь колонки для добавления (указывается относительно rootSchema) или экземпляр колонки запроса Terrasoft.BaseQueryColumn. |
{String} column |
Псевдоним колонки (необязательный параметр). |
{Object} config | Конфигурационный объект колонки запроса. |
Создает и добавляет в коллекцию колонок запроса экземпляр колонки-функции Terrasoft.FunctionQueryColumn с типом DATE_PART.
{String} column |
Путь колонки для добавления (указывается относительно rootSchema). |
{Terrasoft. |
Часть даты, используемая в качестве значения Возможные значения (Terrasoft.DatePartType)
Пустое значение. День. Неделя. Месяц. Год. День недели. Час. Минута. |
{String} column |
Псевдоним колонки (необязательный параметр). |
Создает и добавляет в коллекцию колонок запроса экземпляр колонки-функции Terrasoft.FunctionQueryColumn с типом MACROS, который требует параметризации. Например, следующие N дней, 3-й квартал года, и т. д.
{Terrasoft. |
Тип макроса колонки. |
{Number/ |
Вспомогательная переменная для макроса (необязательный параметр). |
{String} column |
Псевдоним колонки (необязательный параметр). |
Создает и добавляет в коллекцию колонок запроса экземпляр колонки-функции Terrasoft.FunctionQueryColumn.
{String} column |
Путь колонки для добавления (указывается относительно rootSchema). |
{Terrasoft. |
Тип функции. Возможные значения (Terrasoft.FunctionType)
Тип функционального выражения не определен. Подстановка по макросу. Агрегирующая функция. Часть даты. Размер значения в байтах. Используется для бинарных данных. |
{String} columnAlias | Псевдоним колонки (необязательный параметр). |
Создает и добавляет в коллекцию колонок запроса экземпляр колонки-функции Terrasoft.FunctionQueryColumn с типом MACROS, который не требует параметризации (например, текущий месяц, текущий пользователь, первичная колонка, и т. д.).
{Terrasoft. |
Тип макроса колонки. Возможные значения (Terrasoft.QueryMacrosType)
Тип макроса не определен. Текущий пользователь. Контакт текущего пользователя. Вчера. Сегодня. Завтра. Предыдущая неделя. Текущая неделя. Следующая неделя. Предыдущий месяц. Текущий месяц. Следующий месяц. Предыдущий квартал. Текущий квартал. Следующий квартал. Предыдущее полугодие. Текущее полугодие. Следующее полугодие. Предыдущий год. Текущий год. Предыдущий час. Текущий час. Следующий час. Следующий год. Следующие N дней. Требует параметризации. Предыдущие N дней. Требует параметризации. Следующие N часов. Требует параметризации. Предыдущие N часов. Требует параметризации. Первичная колонка. Первичная колонка для отображения. Первичная колонка для отображения изображения. |
{String} column |
Псевдоним колонки (необязательный параметр). |
Создает и добавляет в коллекцию колонок запроса экземпляр колонки-параметра Terrasoft.ParameterQueryColumn.
{Mixed} param |
Значение параметра. Значение должно соответствовать типу данных. |
{Terrasoft. |
Тип данных параметра. |
{String} column |
Псевдоним колонки (необязательный параметр). |
Создает экземпляр Between-фильтра.
{Terrasoft. |
Выражение, проверяемое в фильтре. |
{Terrasoft. |
Начальное выражение диапазона фильтрации. |
{Terrasoft. |
Конечное выражение диапазона фильтрации. |
Создает экземпляр Between-фильтра для проверки попадания колонки в заданный диапазон.
{String} column |
Путь к проверяемой колонке относительно корневой схемы rootSchema. |
{Mixed} less |
Начальное значение фильтра. |
{Mixed} greater |
Конечное значение фильтра. |
{Terrasoft. |
Тип данных параметра. |
Создает экземпляр Compare-фильтра для сравнения колонки с заданным значением.
{Terrasoft. |
Тип операции сравнения. |
{String} column |
Путь к проверяемой колонке относительно корневой схемы rootSchema. |
{Mixed} param |
Значение параметра. |
{Terrasoft. |
Тип данных параметра. |
Создает экземпляр In-фильтра для проверки совпадения значения заданной колонки со значением одного из параметров.
{String} column |
Путь к проверяемой колонке относительно корневой схемы rootSchema. |
{Array} param |
Массив значений параметров. |
{Terrasoft. |
Тип данных параметра. |
Создает экземпляр IsNull-фильтра для проверки заданной колонки.
{String} column |
Путь к проверяемой колонке относительно корневой схемы rootSchema. |
Создает экземпляр IsNull-фильтра для проверки заданной колонки.
{String} column |
Путь к проверяемой колонке относительно корневой схемы rootSchema. |
Создает экземпляр Compare-фильтра.
{Terrasoft. |
Тип операции сравнения. |
{Terrasoft. |
Выражение, проверяемое в фильтре. |
{Terrasoft. |
Выражение фильтрации. |
Создает экземпляр Exists-фильтра для сравнения типа [Существует по заданному условию] и устанавливает в качестве проверяемого значения выражение колонки, расположенной по заданному пути.
{String} column |
Путь к колонке, для выражения которой строится фильтр. |
Создает экземпляр фильтра класса Terrasoft.CompareFilter для сравнения значений двух колонок.
{Terrasoft. |
Тип операции сравнения. |
{String} left |
Путь к проверяемой колонке относительно корневой схемы rootSchema. |
{String} right |
Путь к колонке-фильтру относительно корневой схемы rootSchema. |
Создает экземпляр группы фильтров.
Создает экземпляр In-фильтра.
{Terrasoft. |
Выражение, проверяемое в фильтре. |
{Terrasoft. |
Массив выражений, которые будут сравниваться с leftExpression. |
Создает экземпляр IsNull-фильтра.
{Terrasoft. |
Выражение, которое проверяется по условию IS NOT NULL. |
Создает экземпляр IsNull-фильтра.
{Terrasoft. |
Выражение, которое проверяется по условию IS NULL. |
Создает экземпляр Exists-фильтра для сравнения типа [Не существует по заданному условию] и устанавливает в качестве проверяемого значения выражение колонки, расположенной по заданному пути.
{String} column |
Путь к колонке, для выражения которой строится фильтр. |
Создает объект фильтра для сравнения первичной колонки для отображения со значением параметра.
{Terrasoft. |
Тип сравнения. |
{Mixed} param |
Значение параметра. |
{Terrasoft. |
Тип данных параметра. |
Удаляет экземпляр объекта. Если экземпляр уже удален, запишет в консоль сообщение об ошибке. Вызывает виртуальный метод onDestroy для переопределения в подклассах.
Включает фильтрацию по первичному ключу.
{String/ |
Значение первичного ключа. |
Записывает сообщение об ошибке в журнал сообщений.
{String} message | Сообщение об ошибке, которое будет записано в журнал сообщений. |
Запрос на выполнение запроса на сервере.
{Function} callback | Функция, которая будет вызвана при получении ответа от сервера. |
{Object} scope | Контекст, в котором будет вызвана функция callback. |
Возвращает объект с дополнительной информацией для сериализации.
Возвращает экземпляр сущности по заданному первичному ключу primaryColumnValue. После получения данных вызывает функцию callback в контексте scope.
{String/ |
Значение первичного ключа. |
{Function} callback | Функция, которая будет вызвана при получении ответа от сервера. |
{Object} scope | Контекст, в котором будет вызвана функция callback. |
Возвращает коллекцию экземпляров сущности, представляющих результаты выполнения текущего запроса. После получения данных вызывает функцию callback в контексте scope.
{Function} callback | Функция, которая будет вызвана при получении ответа от сервера. |
{Object} scope | Контекст, в котором будет вызвана функция callback. |
Возвращает информацию о типе элемента.
Записывает сообщение в журнал сообщений.
{String| |
Сообщение, будет записано в журнал сообщений. |
{Terrasoft. |
Тип журнала сообщений callback (необязательный параметр). По умолчанию console.log. Возможные значения заданы перечислением Terrasoft.core.enums.LogMessageType. |
Удаляет все подписки на события и уничтожает объект.
Сериализует объект в json.
{String} serialization |
Результат в json. |
Задает имя свойства объекту, если он не пустой или не является функцией.
{Object} serializable |
Сериализуемый объект. |
{String} property |
Имя свойства. |
Записывает предупреждающее сообщение в журнал сообщений.
{String} message | Сообщение, будет записано в журнал сообщений. |
Класс DataManager
Класс DataManager — синглтон, который доступен через глобальный объект Terrasoft. Данный класс предоставляет хранилище dataStore. В хранилище может быть загружено содержимое одной или нескольких таблиц базы данных.
Каждая запись коллекции представляет запись из соответствующей таблицы в базе данных.
Свойства
Хранилище коллекций данных.
Имя класса записи. Содержит значение Terrasoft.DataManagerItem.
Методы
Если dataStore не содержит коллекцию данных с именем config.entitySchemaName, то метод формирует и выполняет запрос в базу данных, затем возвращает полученные данные, иначе возвращает коллекцию данных из dataStore.
{Object} config |
Конфигурационный объект. Свойства конфигурационного объекта
Имя схемы. Условия. |
{Function} callback | Функция обратного вызова. |
{Object} scope | Контекст выполнения функции обратного вызова. |
Создает новую запись типа config.entitySchemaName со значениями колонок config.columnValues.
{Object} config |
Конфигурационный объект. Свойства конфигурационного объекта
Имя схемы. Значения колонок записи. |
{Function} callback | Функция обратного вызова. |
{Object} scope | Контекст выполнения функции обратного вызова. |
Добавляет запись item в коллекцию данных схемы.
{Terrasoft. |
Добавляемая запись. |
Возвращает запись из коллекции данных схемы с именем entitySchemaName и с идентификатором id.
{String} entity |
Название коллекции данных. |
{String} id | Идентификатор записи. |
Устанавливает признак isDeleted для записи item, при фиксации изменений запись будет удалена из базы данных.
{Terrasoft. |
Удаляемая запись. |
Удаляет запись из коллекции данных схемы.
{Terrasoft. |
Удаляемая запись. |
Обновляет запись со значением первичной колонки config.primaryColumnValue значениями из config.columnValues.
{Object} config |
Конфигурационный объект. Свойства конфигурационного объекта
Имя схемы. Значение первичной колонки. Значения колонок. |
{Function} callback | Функция обратного вызова. |
{Object} scope | Контекст выполнения функции обратного вызова. |
Отменяет изменения для записи item, сделанные в текущей сессии работы с DataManager.
{Terrasoft. |
Запись, по которой будут отменены изменения. |
Выполняет сохранение в базу данных коллекций данных схем, указанных в config.entitySchemaNames.
{Object} config |
Конфигурационный объект. Свойства конфигурационного объекта
Имя схемы, сохранение которой необходимо выполнить. Если свойство не заполнено, сохранение выполняется для всех схем. |
{Function} callback | Функция обратного вызова. |
{Object} scope | Контекст выполнения функции обратного вызова. |
Класс DataManagerItem
Методы
Устанавливает новое значение columnValue для колонки с именем columnName.
{String} column |
Название колонки. |
{String} column |
Значение колонки. |
Возвращает значение колонки с именем columnName.
{String} column |
Название колонки. |
Возвращает значения всех колонок записи.
Устанавливает признак isDeleted для записи.
Отменяет изменения для записи, сделанные в текущей сессии работы с DataManager.
Фиксирует изменения в базе данных.
{Function} callback | Функция обратного вызова. |
{Object} scope | Контекст выполнения функции обратного вызова. |
Возвращает признак того, что запись новая.
Возвращает признак того, что запись была изменена.