Перейти к основному содержимому
Версия: 7.0

Операторы фильтров и порядков формы

Операторы ORDER, FILTER, FILTERGROUP, FILTER PROPERTY (и их варианты ORDERS, FILTERS, FILTERGROUPS, FILTERS PROPERTY) - создание действий, которые применяют или читают текущие пользовательские фильтры и порядки элементов открытой формы.

Синтаксис​

ORDER            groupObjectId   [FROM expr]
FILTER           groupObjectId   [FROM expr]
FILTERGROUP      filterGroupId   [FROM expr]
FILTER PROPERTY  formPropertyId  [FROM expr]

ORDERS           groupObjectId   [TO propId]
FILTERS          groupObjectId   [TO propId]
FILTERGROUPS     filterGroupId   [TO propId]
FILTERS PROPERTY formPropertyId  [TO propId]

Описание​

Операторы работают с интерактивным представлением открытой формы и делятся на две группы:

  • операторы в единственном числе (ORDER, FILTER, FILTERGROUP, FILTER PROPERTY) применяют значение из блока FROM к элементу формы — те же порядки и фильтры, что может задать пользователь;
  • операторы во множественном числе (ORDERS, FILTERS, FILTERGROUPS, FILTERS PROPERTY) читают текущее значение элемента формы в свойство из блока TO.

Оператор в единственном числе применяет значение сразу: оператор во множественном числе дальше в том же действии читает уже новое значение, а форма показывает его вместе с остальными своими изменениями. События формы ORDERS, FILTERS, FILTERGROUPS и FILTERS PROPERTY он не вызывает: они возникают, когда порядки или фильтры меняет пользователь; события ORDER и FILTER группы объектов возникают при любом их изменении, в том числе и при этом.

Элемент формы задаётся его именем: groupObjectId — группа объектов (её порядки или фильтры), filterGroupId — группа фильтров, formPropertyId — свойство на форме (его фильтр).

Значение представлено в сериализованном виде, зависящем от элемента:

  • для порядков группы объектов (ORDER / ORDERS) — JSON: список порядков (имя свойства на форме, например number(o), и признак убывания);
  • для фильтров группы объектов (FILTER / FILTERS) — JSON: список условий фильтрации (имя свойства на форме, сравнение, отрицание, значение, объединение через OR);
  • для группы фильтров (FILTERGROUP / FILTERGROUPS) — INTEGER: номер активного фильтра в группе, начиная с 1, или 0, если активного фильтра нет, в том числе в группе NONULL; номер, не называющий фильтр группы, ничего не меняет;
  • для фильтра свойства (FILTER PROPERTY / FILTERS PROPERTY) — STRING: значение фильтра свойства.

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

Если у группы объектов нет пользовательских порядков или пользовательских фильтров, ORDERS и FILTERS записывают пустое значение JSON нулевой длины — не NULL и не []: проверка на NULL его не обнаруживает, а веб-клиент показывает его как пустую строку. ORDER и FILTER принимают все три одинаково: пустое значение, [] и NULL снимают пользовательские порядки или пользовательские фильтры группы объектов.

Указанный в элементе списка property должен быть именем свойства на форме. Иначе действие завершается с ошибкой. ORDER и FILTER пропускают элемент без property или с именем свойства, просмотр которого запрещён пользователю политикой безопасности, свойства другой группы объектов или свойства с опцией COLUMNS: колонку элемент списка не называет.

Поле compare условия фильтрации принимает один из знаков сравнения =, >, <, >=, <=, !=, _ (содержит) или @ (полнотекстовый поиск). Неизвестное сравнение завершает действие с ошибкой. Условие фильтрации без сравнения получает сравнение свойства по умолчанию.

Если блок FROM или TO не указан, по умолчанию используется соответствующее свойство системного модуля UserEvents (orders, filters, filterGroups, filtersProperty), через который эти операторы обычно и вызываются.

Параметры​

Примеры​

FORM orders
    OBJECTS o = Order
    PROPERTIES(o) number, date, customer

    FILTERGROUP amount
        FILTER 'Крупные' number(o) > 1000
        FILTER 'Мелкие' number(o) <= 1000
;

savedFilters = DATA JSON ();
currentOrders = DATA JSON ();

// сохранить текущие фильтры группы объектов o и позже применить их обратно;
// savedFilters получит JSON вида [{"property": "number(o)", "compare": ">", "negation": false, "value": "1000"}]
saveFilters ()  { FILTERS orders.o TO savedFilters; }
restoreFilters ()  { FILTER orders.o FROM savedFilters(); }

// прочитать текущий порядок группы объектов o;
// currentOrders получит JSON вида [{"property": "date(o)", "desc": true}, {"property": "number(o)", "desc": false}]
readOrders ()  { ORDERS orders.o TO currentOrders; }

// упорядочить группу объектов o по дате, сначала последние: JSON, заданный литералом, — сырой литерал
sortByDate ()  { ORDER orders.o FROM JSON(r'[{"property": "date(o)", "desc": true}]'); }

// оставить только заказы с номером больше 1000, тем же способом
filterLarge ()  { FILTER orders.o FROM JSON(r'[{"property": "number(o)", "compare": ">", "value": "1000"}]'); }

// активировать второй фильтр («Мелкие») в группе фильтров amount
showSmall ()  { FILTERGROUP orders.amount FROM 2; }

// отфильтровать свойство customer по значению 'Acme'
filterAcme ()  { FILTER PROPERTY orders.customer(o) FROM 'Acme'; }