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

Правила: формы

Правила форм​

  1. Чтобы разместить несколько объектов в одной таблице сразу, ассистенту СЛЕДУЕТ объединить их в одну группу объектов с помощью скобок.

  2. В секции FORM ... ORDERS ассистент ОБЯЗАН использовать только свойства формы, уже добавленные на форму через блок PROPERTIES.

    В ORDERS ассистент ОБЯЗАН указывать одно из:

    • имя свойства формы с его параметрами, если явный алиас не задан
    • явный алиас свойства формы, если такой алиас был указан

    Сырые выражения, объекты или свойства, не добавленные на форму, НЕ ДОЛЖНЫ помещаться в ORDERS.

  3. Ассистент НЕ ДОЛЖЕН использовать INPUT внутри действий, добавленных непосредственно на форму через PROPERTIES, если это действие не используется в обработчике ON CHANGE: значение встроенного класса вводится в редакторе свойства, изменение которого обрабатывается, поэтому вне обработчика изменения его негде отобразить. Исключение — значения файлов и цветов: они вводятся отдельным диалогом, и их МОЖНО запрашивать из любого действия формы.

    Чтобы запросить значения из кнопки, ассистенту СЛЕДУЕТ либо разместить вводимые свойства на самой форме (первичные свойства, в том числе локальные, в панели) и прочитать их в действии, либо открыть диалоговую форму, возвращающую введённые значения (DIALOG с объектами, помеченными INPUT).

  4. Ассистент НЕ ДОЛЖЕН выводить на форму внутренние идентификаторы объектов, в том числе через свойства, значениями которых являются объекты: значение-объект отображается его внутренним идентификатором — числом, ничего не говорящим пользователю.

    Вместо них ДОЛЖНЫ выводиться осмысленные примитивные или производные примитивные / текстовые свойства.

    Самый частый случай — связь со статическим объектом класса-перечисления (status = DATA Status (Project)): заголовок статического объекта платформа сама НЕ подставляет. На форму выводится композиция заголовка — captionStatus 'Статус' = caption(status(p)): запись через композицию уходит в связь, а не в заголовок статического объекта (см. правило 7), и при небольшом числе вариантов, как у перечислений, веб-клиент показывает её элементом выбора (группа кнопок / список / выпадающий список — по числу вариантов и длине заголовков).

  5. Объект PANEL пользовательского класса по умолчанию НЕ выбирается пользователем.

    Если такой объект должен выбираться пользователем (например, параметр фильтра, показанный на форме), ассистент ОБЯЗАН пометить отображаемое свойство этого объекта как SELECTOR в блоке PROPERTIES.

    Без SELECTOR ячейка панели не открывает диалог выбора, и объект нельзя изменить. Ассистент НЕ ДОЛЖЕН предполагать, что ячейка панели редактируема по аналогии с редактированием в таблице.

  6. В блоке PROPERTIES формы стиль параметров у свойства или действия, добавляемого на форму, ДОЛЖЕН соответствовать заголовку блока:

    • С заголовком с общими параметрами PROPERTIES(p1, ..., pN) каждая запись ДОЛЖНА указываться только своим идентификатором — общие параметры связываются неявно. Запись propName(p1, ..., pN) после идентификатора — это ошибка разбора.
    • Без заголовка с общими параметрами (просто PROPERTIES) каждая запись ДОЛЖНА нести явные скобки, например propName(t) с параметрами, либо propName() / actionName() для свойств и действий без параметров. Скобки ОБЯЗАТЕЛЬНЫ, даже когда параметров нет — пустые скобки всё равно ДОЛЖНЫ быть записаны. Голое имя без скобок — это ошибка разбора.

    Ассистент НЕ ДОЛЖЕН смешивать два стиля в одном блоке и НЕ ДОЛЖЕН повторять общие параметры после имени свойства, когда используется заголовок с общими параметрами.

    Это правило применяется только к записи, добавляемой на форму. Списки аргументов внутри опций вроде ON CHANGE actionName(...), READONLYIF expr, BACKGROUND expr и т. д. — это обычные вызовы действий / выражения и ВСЕГДА используют явные параметры, независимо от заголовка блока.

    Записи, чьё выражение несёт запятую, не заключённую в собственные скобки, нужна форма, которую принимает этот блок: без заголовка общих параметров её пишут как алиас = (выражение), потому что голое (выражение) — parse error; с PROPERTIES(o) запись остаётся использованием свойства и после алиас =, выражение там не принимается вовсе, и единственное средство — именованное свойство, добавленное по идентификатору.

  7. Обработка изменения CHANGE по умолчанию у свойства, показанного на форме, выводится не из вида его выражения, а из пути записи: изменяемыми являются первичные свойства, оператор выбора и композиции изменяемых свойств — запись передаётся через композицию в нижележащее изменяемое свойство. Путь записи не виден в месте использования, поэтому ассистент НЕ ДОЛЖЕН предполагать, что вычисляемое на вид свойство нередактируемо.

    Внешне похожие записи при этом редактируются по-разному:

    • композиция через объектную связь (name(customer(o))) — пользователю предлагается выбрать связанный объект, и записывается связь (customer(o)); это обычный способ ввода;
    • атрибут самого объекта строки (name(c)) — введённое значение записывается на месте, то есть объект переименовывается;
    • свойство статического объекта (caption(st)) — запись уходит в хранимый заголовок статического объекта и живёт до очередной синхронизации базы данных с кодом (обычно при старте сервера), которая возвращает заголовок из кода.

    Каждое свойство, показываемое только для чтения, ДОЛЖНО быть явно помечено READONLY — во всех контекстах формы: не только в таблицах списочных форм, но и в панелях, диалогах, дашбордах и графиках. Когда только для чтения показывается весь блок, СЛЕДУЕТ помечать блок целиком (PROPERTIES(o) READONLY ...), а не каждую запись; пометка у отдельной записи остаётся для блоков, где часть записей предназначена для ввода. В контекстах просмотра и выбора каждая запись явно помечается READONLY, кроме записей, сознательно предназначенных для ввода. Явная пометка заодно документирует намерение для читателя кода.

Правила потока управления (WAIT, NOWAIT)​

  1. Если не задана ни одна опция, платформа выбирает режим сама: оператор работает синхронно, когда форма открывается в модальном месте, когда модальна форма, из которой его открывают, или когда текущая сессия может использоваться дальше, — и асинхронно в остальных случаях.

    Поэтому два одинаково выглядящих вызова могут вести себя по-разному. Там, где код после вызова зависит от того, что форма закрыта, или, наоборот, должен выполниться не дожидаясь, ассистент ОБЯЗАН сказать это явно — через WAIT или NOWAIT у SHOW, единственного оператора, синтаксис которого их принимает.

    У DIALOG такой опции нет: он синхронен, когда его результат используется, и отдан той же эвристике в остальных случаях. Когда диалог должен блокировать, ассистент добивается этого тем, что использует возвращаемое им значение.