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

Операторы 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: список порядков (имя свойства и признак убывания);
• для фильтров группы объектов (FILTER / FILTERS) — JSON: список условий фильтрации (имя свойства, сравнение, отрицание, значение, объединение через OR);
• для группы фильтров (FILTERGROUP / FILTERGROUPS) — INTEGER: номер активного фильтра в группе, начиная с 1, или 0, если активного фильтра нет, в том числе в группе NONULL; номер, не называющий фильтр группы, ничего не меняет;
• для фильтра свойства (FILTER PROPERTY / FILTERS PROPERTY) — STRING: значение фильтра свойства.

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

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

Параметры

• groupObjectId

  Идентификатор группы объектов на форме.

• filterGroupId

  Имя группы фильтров на форме, квалифицированное формой.

• formPropertyId

  Идентификатор свойства или действия на форме.

• expr

  Выражение, значение которого применяется к элементу формы. Его класс определяет вид сериализации (см. «Описание»). В обычном строковом литерале фигурные скобки выделяют идентификатор локализации, поэтому JSON, заданный литералом, записывается сырым строковым литералом r'...', который их сохраняет.

• propId

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

Примеры

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", "compare": ">", "negation": false, "value": "1000"}]
saveFilters ()  { FILTERS orders.o TO savedFilters; }
restoreFilters ()  { FILTER orders.o FROM savedFilters(); }

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

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

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

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

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