Скрипт фильтрации значений параметра

Категория скрипта "Фильтрация значений параметров событий".

Кроме значений произвольного справочника

Описание скрипта

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

Место настройки скрипта

Форма добавления параметра пользовательского действия по событию, см. Добавление пользовательской кнопки.

Структура скрипта

Формально скрипт состоит из двух частей:

Часть 1, вычисляемая в интерфейсе администратора (form == null). Возвращается список кодов параметров, от которых зависит данный параметр.

def PARAMS_FOR_UPDATE_ON_FORMS = ['paramCode1', 'paramCode2', ...]
// Обязательная проверка! Даже если фильтрующих параметров нет.
if (form == null)
{
return PARAMS_FOR_UPDATE_ON_FORMS
}

Часть 2, вычисляемая в интерфейсе оператора (в момент открытия формы). Возвращается список объектов, которые будут отображаться в списке.

return utils.find('class$type',['paramCode1':'value1']...);

Если скрипт фильтрации должен вернуть все объекты (более 500), то вместо конструкции типа:

return utils.find('class$type',[:])

рекомендуется использовать конструкцию, которая значительно сократит время формирования списка объектов:

return api.filtration.disableFiltration()

Когда выполняется скрипт

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

Результат выполнения скрипта

В интерфейсе администратора скрипт возвращает:

  • Коллекцию (список) кодов параметров, от которых зависят возможные значения фильтруемого параметра. Условие выполнения скрипта form==null.
  • пустой список [] — если значение фильтруемого параметра не зависит ни от одного из параметров объекта.

В интерфейсе оператора скрипт возвращает:

  • Коллекцию (список) объектов, доступных для выбора.

    Один объект — если скрипт используется для фильтрации значений параметра типа "Ссылка на бизнес-объект".

    Коллекцию ClassFqn, или коллекцию строк, представляющих собой ClassFqn, или список объектов — если скрипт используется для фильтрации значений параметра типа "Набор типов класса".

  • пусто — если отсутствуют доступные для выбора значения.

Переменные и их значения

Глобальные переменные:

  • user — пользователь, инициализировавший событие. Является объектом класса "Сотрудник" (employee). Если событие инициализировал суперпользователь, то user=null.
  • ip — ip-адрес рабочего места пользователя user. Если действие выполняется автоматически системой (а не пользователем), то переменная не определяется.
  • appVersion — версия приложения.
  • api — используется для обращения к методам api, например api.utils, api.ldap, api.timing, см. Методы API;
  • modules — используется для обращения к скриптовому модулю и конкретному методу, определенному в нем, с помощью конструкции: modules.{код модуля}.{имя метода}({параметры метода}...), см. Скрипт текста модуля;
  • logger — используется для отладки скриптов и позволяет вывести в лог на указанный уровень переданную строку, см. Оформление и отладка скриптов.
  • utils — синоним api.utils.

Переменные контекста, доступные в скрипте фильтрации значений параметра:

  • attrCode — код параметра, для которого производится фильтрация значений.

  • cardObject — объект, из карточки которого было инициировано действие. Если действие инициировано НЕ из карточки объекта, то cardObject = null.

    Переменную cardObject использовать не рекомендуется.

  • form — значения полей формы, на которой присутствует параметр с признаком "Фильтрация значений при редактировании", в том числе текущее значение данного параметра (представление объекта на клиенте).

  • list — все объекты списка. Количество объектов коллекции ограничивается 1000. Переменная доступна, если событие вызвано из списка объектов.

    Метод limitExceeded() возвращает:

    • true, если лимит превышен и часть объектов списка не попали в данную коллекцию.
    • false, если в коллекции 1000 и меньше объектов.
  • permittedFqns — список разрешенных типов объектов. В ссылочных параметрах типа "Ссылка на бизнес-объект" и "Набор ссылок на бизнес-объекты" можно ограничить список возможных значений по типам (свойство параметра "Типы объектов"). В этом случае целесообразно использование переменной permittedFqns. Переменная хранит "ClassFqn" для типов, выбранных в поле "Тип", и позволяет фильтровать объекты только указанных типов, что повышает производительность системы. Если выбран класс, то переменная хранит пустую коллекцию. Если переменная не используется, то ограничения по типам не нарушаются.
  • source — способ вызова события: OBJECT_LIST из списка объектов и OBJECT_CARD из карточки объекта.

  • subjects — объекты, выбранные в списке объектов (если событие вызвано из списка объектов), или текущий объект (если событие вызвано из карточки объекта).

    Переменная содержит только те объекты, относительно которых у текущего пользователя есть право на выполняемое действие. Если прав нет, то subjects = null

    Переменная доступна, если действие выполняется как массовая операция в списке;

  • subject — содержит в себе произвольный объект из коллекции subjects (если событие вызвано из списка объектов), или текущий объект (если событие вызвано из карточки объекта). Если у текущего пользователя нет права на выполняемое действие, то subject = null.

Контекстные переменные: list, subject, subjects, cardObject, source недоступны при выполнении скрипта в интерфейсе администратора (при открытии формы добавления или редактирования контента со встроенным приложением, для которого запрашиваются дополнительные параметры).

Особенности скрипта

  • К значениям параметров следует обращаться через form.код_параметра.
  • В PARAMS_FOR_UPDATE_ON_FORMS необходимо указывать существующий код параметра, иначе при сохранении скрипта возникнет ошибка.
  • Не рекомендуется использовать атрибуты, помещенные в контент, который может быть скрыт, т.к. скрипт не пересчитывает значение, если атрибут скрывается.

Примеры скрипта

1. Скрипт фильтрации простого раскрывающегося списка объектов (не дерева):

//ПАРАМЕТРЫ------------------------------------------------------------
//список кодов параметров объекта, от которых зависит фильтрация,
//необходимо для обновления фильтруемого списка выбора на форме при изменении этих параметров.
def PARAMS_FOR_UPDATE_ON_FORMS = ['metaClass'];
//ОСНОВНОЙ БЛОК--------------------------------------------------------
// Если form = null, нужно вернуть список кодов параметров, от которых зависит фильтруемый параметр
if(null == form)
{
return PARAMS_FOR_UPDATE_ON_FORMS
}
// возвращаем без фильтрации список отделов
objects = api.utils.find("ou", [:])
return objects
}

2. Скрипт фильтрации раскрывающегося списка объектов в виде дерева. Скрипт возвращает все объекты класса test, у которых title совпадает с значением параметра title на форме:

//ПАРАМЕТРЫ------------------------------------------------------------
//список кодов параметров объекта, от которых зависит фильтрация,
//необходимо для обновления фильтруемого списка выбора на форме при изменении этих параметров.
def PARAMS_FOR_UPDATE_ON_FORMS = ['title'];
//ОСНОВНОЙ БЛОК--------------------------------------------------------
if(null == form)
{
return PARAMS_FOR_UPDATE_ON_FORMS
}
def objects = []
objects = utils.find('test', ['title': form.title])
return objects

3. Скрипт фильтрации раскрывающегося списка объектов в виде дерева. Скрипт возвращает все вложенные в ou$1234 отделы:

//ПАРАМЕТРЫ------------------------------------------------------------
//список кодов параметров объекта, от которых зависит фильтрация,
//необходимо для обновления фильтруемого списка выбора  на форме при изменении этих параметров.
def PARAMS_FOR_UPDATE_ON_FORMS = [];
//UUID отдела, вложенные отделы в который, необходимо получить
def PARENT_OU_UUID = 'ou$1234'; 
//ОСНОВНОЙ БЛОК--------------------------------------------------------
if(null == form)
{
return PARAMS_FOR_UPDATE_ON_FORMS
}
def objects = []
objects = api.ou.listNestedOUs(PARENT_OU_UUID)
return objects

4. Скрипт фильтрации агрегирующих параметров:

if (form == null)
{
// возвращаем пустой список кодов параметров, от которых зависит фильтрация
return [] 
}
return [
//значением параметра можно выбрать только сотрудника, в рамках его отдела и команд, в которых он является участником
'employee$2241',
//значением параметра можно выбрать только команду
'team$2104',
//значением параметра можно выбрать только отдел
'ou$1901',
//значением  параметра можно выбрать сотрудников — участников команды
['team$2107': ['employee$2213', 'employee$2214']],
//значением  параметра можно выбрать сотрудников отдела
['ou$1902': ['employee$2203', 'employee$2209']]
]

Для значений произвольного справочника

Описание скрипта

Скрипт фильтрации определяет список возможных значений произвольного справочника.

Скрипт учитывает скрипт вычисления элементов произвольного справочника.

Когда выполняется скрипт

  • При открытии формы заполнения параметров действия по событию, на которой расположен параметр.
  • При открытии формы добавления или редактирования контента со встроенным приложением, для которого запрашиваются дополнительные параметры.

Результат выполнения скрипта

В интерфейсе пользователя скрипт возвращает ассоциативный список "ключ–значение" (ключ и значение имеют тип "строка") ИЛИ пустое значение, если отсутствуют доступные для выбора значения.

Переменные и их значения

Дополнительные переменные контекста, доступные в скрипте фильтрации значений произвольного справочника:

  • form — значения полей формы, на которой присутствует параметр "Элемент произвольного справочника" с признаком "Фильтрация значений при редактировании", в том числе текущее значение данного параметра (представление объекта на клиенте).
  • attrCode — код параметра, для которого производится фильтрация значений.
  • subject — ссылка на объект, к которому применяется действие.
  • subjects — набор ссылок на объекты, к которым применяется действие. Переменная доступна, если действие выполняется как массовая операция в списке.
  • cardObject — объект, из карточки которого было инициировано событие. Переменная доступна, если событие вызвано из карточки объекта;
  • list — содержит ассоциативный список, который возвращает скрипт вычисления элементов произвольного справочника этого параметра.
  • source — способ вызова события: OBJECT_LIST из списка объектов и OBJECT_CARD из карточки объекта.

Контекстные переменные: list, subject, subjects, cardObject, source недоступны при выполнении скрипта в интерфейсе администратора (при открытии формы добавления или редактирования контента со встроенным приложением, для которого запрашиваются дополнительные параметры).

Особенности скрипта

  • Вместо метода api.filtration.disableFiltration() следует использовать контекстную переменную list

Примеры скрипта

//ПАРАМЕТРЫ------------------------------------------------------------
//список кодов параметров объекта, от которых зависит фильтрация,
//необходимо для обновления фильтруемого селекта на форме при изменении этих параметров.
def PARAMS_FOR_UPDATE_ON_FORMS = ['metaClass'];
//ОСНОВНОЙ БЛОК--------------------------------------------------------
// Если form = null, то нужно вернуть список кодов параметров, от которых зависит фильтруемый параметр
if(null == form)
{
   return PARAMS_FOR_UPDATE_ON_FORMS
}
dictionary = [:]
for (ou in api.metainfo.getTypes('ou')) {
   dictionary.put(ou.code, ou.title)
}
return dictionary