steelmorgan/form-patterns

Form module patterns (client-server interaction)

Key principle: Minimize the number and size of server calls. Each &НаСервере call is a network round-trip plus serialization of the full form context.

---

Rule 1: Directive hierarchy — prefer context-free calls

Preference order (from best to worst)

1. &НаКлиентеНаСервереБезКонтекста  — чистые вычисления, обе среды
2. &НаСервереБезКонтекста            — обращение к БД, без контекста формы
3. &НаСервере                        — нужен доступ к реквизитам формы
4. &НаКлиенте                        — интерактивная логика (диалоги, навигация)

Decision rule

Нужно ли обращаться к базе данных?
├── Нет → &НаКлиенте или &НаКлиентеНаСервереБезКонтекста
└── Да →
    Нужен ли доступ к реквизитам формы?
    ├── Нет → &НаСервереБезКонтекста (передаём только параметры)
    └── Да → &НаСервере (передаётся весь контекст)

// Чистое вычисление — обе среды
&НаКлиентеНаСервереБезКонтекста
Функция РассчитатьСумму(Количество, Цена, СтавкаНДС)
    СуммаБезНДС = Количество * Цена;
    СуммаНДС = СуммаБезНДС * СтавкаНДС / 100;
    Возврат СуммаБезНДС + СуммаНДС;
КонецФункции

// Нужны данные из БД, но НЕ нужны реквизиты формы
&НаСервереБезКонтекста
Функция ПолучитьДанныеНоменклатуры(НоменклатураСсылка)
    Возврат ОбщегоНазначения.ЗначенияРеквизитовОбъекта(
        НоменклатураСсылка,
        "Наименование, ЕдиницаИзмерения, СтавкаНДС, Цена");
КонецФункции

// Нужен доступ к реквизитам формы
&НаСервере
Процедура ПересчитатьИтогиНаСервере()
    Объект.СуммаДокумента = Объект.Товары.Итог("Сумма");
    Объект.СуммаНДС = Объект.Товары.Итог("СуммаНДС");
КонецПроцедуры

---

Rule 2: Minimize server calls — batch data

Each server call takes ~100 ms (serialization + round-trip + deserialization). Three calls equal 300 ms of delay. One call that returns all data equals 100 ms.

&НаКлиенте
Процедура КонтрагентПриИзменении(Элемент)
    ДанныеЗаполнения = ПолучитьДанныеЗаполненияПоКонтрагенту(Объект.Контрагент, Объект.Дата);

    Объект.Договор = ДанныеЗаполнения.Договор;
    Объект.Организация = ДанныеЗаполнения.Организация;
    Объект.Валюта = ДанныеЗаполнения.Валюта;
    КурсВалюты = ДанныеЗаполнения.Курс;
КонецПроцедуры

&НаСервереБезКонтекста
Функция ПолучитьДанныеЗаполненияПоКонтрагенту(КонтрагентСсылка, ДатаДокумента)

    Результат = Новый Структура;

    РеквизитыКонтрагента = ОбщегоНазначения.ЗначенияРеквизитовОбъекта(
        КонтрагентСсылка, "ДоговорПоУмолчанию, ОсновнаяОрганизация");

    Результат.Вставить("Договор", РеквизитыКонтрагента.ДоговорПоУмолчанию);
    Результат.Вставить("Организация", РеквизитыКонтрагента.ОсновнаяОрганизация);

    Если ЗначениеЗаполнено(РеквизитыКонтрагента.ДоговорПоУмолчанию) Тогда
        ВалютаДоговора = ОбщегоНазначения.ЗначениеРеквизитаОбъекта(
            РеквизитыКонтрагента.ДоговорПоУмолчанию, "ВалютаВзаиморасчетов");
        Результат.Вставить("Валюта", ВалютаДоговора);
        Результат.Вставить("Курс", РаботаСКурсамиВалют.ПолучитьКурсВалюты(ВалютаДоговора, ДатаДокумента));
    Иначе
        Результат.Вставить("Валюта", Неопределено);
        Результат.Вставить("Курс", 1);
    КонецЕсли;

    Возврат Результат;

КонецФункции

---

Rule 3: ДанныеФормыВЗначение / ЗначениеВДанныеФормы

On the server, form data is not a real object but ДанныеФормы*. You must convert it to call object module methods.

| Scenario | Does conversion need to happen? | |----------|------------------------------| | Reading form attributes | No - Объект.Реквизит works directly | | Calling object module methods | Yes | | Passing the object to a common module | Yes - common modules work with real objects |

&НаСервере
Процедура ЗаполнитьПоУмолчаниюНаСервере()
    ДокументОбъект = РеквизитФормыВЗначение("Объект");
    ДокументОбъект.ЗаполнитьТоварыПоУмолчанию();
    // ОБЯЗАТЕЛЬНО: преобразовать обратно, иначе изменения не отразятся на форме!
    ЗначениеВРеквизитФормы(ДокументОбъект, "Объект");
КонецПроцедуры

Common mistake - forgetting ЗначениеВРеквизитФормы

// ПЛОХО: изменения потеряны!
&НаСервере
Процедура ЗаполнитьНаСервере()
    ДокументОбъект = РеквизитФормыВЗначение("Объект");
    ДокументОбъект.ЗаполнитьТаблицу();
    // ЗАБЫЛИ: ЗначениеВРеквизитФормы(ДокументОбъект, "Объект");
КонецПроцедуры

---

Rule 4: Form event handlers — order and purpose

Event order when opening a form

1. ПриСозданииНаСервере     — форма создаётся на сервере, данные загружены
2. ПриОткрытии              — форма отобразилась на клиенте

Event order during saving

1. ПередЗаписьюНаКлиенте    — клиент: можно отменить (Отказ = Истина)
2. ПередЗаписьюНаСервере     — сервер: последняя проверка
3. ПриЗаписиНаСервере        — сервер: в той же транзакции
4. ПослеЗаписиНаСервере      — сервер: обновление формы
5. ПослеЗаписи               — клиент: оповещение

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
    Если Параметры.Свойство("ЗначенияЗаполнения") Тогда
        ЗаполнитьЗначенияСвойств(Объект, Параметры.ЗначенияЗаполнения);
    КонецЕсли;
    Элементы.ГруппаСклад.Видимость = (Объект.ВидОперации <>
        Перечисления.ВидыОпераций.Услуга);
    ОбновитьСписокВыбораДоговоров();
КонецПроцедуры

// ПередЗаписьюНаКлиенте — проверки, требующие подтверждения пользователя
&НаКлиенте
Процедура ПередЗаписью(Отказ, ПараметрыЗаписи)
    Если Объект.СуммаДокумента > 1000000 Тогда
        Если Не ПараметрыЗаписи.Свойство("ПодтверждениеСуммы") Тогда
            Отказ = Истина;
            ПоказатьВопрос(
                Новый ОписаниеОповещения("ПослеПодтвержденияСуммы", ЭтотОбъект, ПараметрыЗаписи),
                НСтр("ru = 'Сумма документа превышает 1 000 000. Продолжить?'"),
                РежимДиалогаВопрос.ДаНет);
        КонецЕсли;
    КонецЕсли;
КонецПроцедуры

// ПослеЗаписи — оповещения на клиенте
&НаКлиенте
Процедура ПослеЗаписи(ПараметрыЗаписи)
    Оповестить("Запись_РеализацияТоваровУслуг",
        Новый Структура("Ссылка", Объект.Ссылка), ЭтотОбъект);
КонецПроцедуры

---

Rule 5: Dynamic lists — setup and optimization

A dynamic list automatically provides pagination, search, and sorting.

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
    // Отборы через КомпоновкаДанных (пользователь сможет изменять)
    ОбщегоНазначенияКлиентСервер.УстановитьЭлементОтбораДинамическогоСписка(
        СписокДокументов,
        "Организация",
        Организация,
        ВидСравненияКомпоновкиДанных.Равно,
        ,
        ЗначениеЗаполнено(Организация));
КонецПроцедуры

Custom query for a dynamic list

СписокДокументов.ПроизвольныйЗапрос = Истина;
СписокДокументов.ТекстЗапроса =
"ВЫБРАТЬ
|   Реализация.Ссылка,
|   Реализация.Дата,
|   Реализация.Номер,
|   Реализация.Контрагент,
|   Реализация.СуммаДокумента,
|   ЕСТЬNULL(Задолженность.СуммаОстаток, 0) КАК ОстатокЗадолженности
|ИЗ
|   Документ.РеализацияТоваровУслуг КАК Реализация
|       ЛЕВОЕ СОЕДИНЕНИЕ РегистрНакопления.ВзаиморасчетыСКонтрагентами.Остатки КАК Задолженность
|       ПО Реализация.Контрагент = Задолженность.Контрагент
|           И Реализация.Договор = Задолженность.Договор
|{ГДЕ
|   Реализация.Дата >= &ДатаНачала}";

Rules: do not load the entire dataset; apply filters via КомпоновкаДанных instead of WHERE; do not use УПОРЯДОЧИТЬ ПО in a custom query.

---

Rule 6: Conditional formatting — programmatic configuration

&НаСервере
Процедура УстановитьУсловноеОформление()

    УсловноеОформление.Элементы.Очистить();

    ЭлементУО = УсловноеОформление.Элементы.Добавить();

    ЭлементОтбора = ЭлементУО.Отбор.Элементы.Добавить(Тип("ЭлементОтбораКомпоновкиДанных"));
    ЭлементОтбора.ЛевоеЗначение = Новый ПолеКомпоновкиДанных("ДатаОплаты");
    ЭлементОтбора.ВидСравнения = ВидСравненияКомпоновкиДанных.Меньше;
    ЭлементОтбора.ПравоеЗначение = ТекущаяДатаСеанса();
    ЭлементОтбора.Использование = Истина;

    ЭлементОтбора2 = ЭлементУО.Отбор.Элементы.Добавить(Тип("ЭлементОтбораКомпоновкиДанных"));
    ЭлементОтбора2.ЛевоеЗначение = Новый ПолеКомпоновкиДанных("Оплачен");
    ЭлементОтбора2.ВидСравнения = ВидСравненияКомпоновкиДанных.Равно;
    ЭлементОтбора2.ПравоеЗначение = Ложь;
    ЭлементОтбора2.Использование = Истина;

    ЭлементУО.Оформление.УстановитьЗначениеПараметра("ЦветФона", WebЦвета.МисттиРоуз);

    ПолеОформления = ЭлементУО.Поля.Элементы.Добавить();
    ПолеОформления.Поле = Новый ПолеКомпоновкиДанных("СписокДокументов");

КонецПроцедуры

---

Rule 7: Asynchronous dialogs instead of modal

Modal calls (Предупреждение(), Вопрос()) are forbidden in the web client. Use ОписаниеОповещения instead.

ITS standard: “Restrictions on the use of modal methods.”

&НаКлиенте
Процедура УдалитьСтрокуТоваров(Команда)
    Если Элементы.Товары.ТекущаяСтрока = Неопределено Тогда
        Возврат;
    КонецЕсли;

    ПоказатьВопрос(
        Новый ОписаниеОповещения("ПослеПодтвержденияУдаления", ЭтотОбъект),
        НСтр("ru = 'Удалить выбранную строку?'"),
        РежимДиалогаВопрос.ДаНет,
        ,
        КодВозвратаДиалога.Нет);
КонецПроцедуры

&НаКлиенте
Процедура ПослеПодтвержденияУдаления(Результат, ДополнительныеПараметры) Экспорт
    Если Результат = КодВозвратаДиалога.Да Тогда
        Объект.Товары.Удалить(Элементы.Товары.ТекущаяСтрока);
    КонецЕсли;
КонецПроцедуры

---

Rule 8: Opening forms and handling the result

&НаКлиенте
Процедура ОткрытьФормуПодбораТоваров(Команда)

    ПараметрыФормы = Новый Структура;
    ПараметрыФормы.Вставить("Организация", Объект.Организация);
    ПараметрыФормы.Вставить("Склад", Объект.Склад);
    ПараметрыФормы.Вставить("Дата", Объект.Дата);
    ПараметрыФормы.Вставить("МножественныйВыбор", Истина);

    ОткрытьФорму("Обработка.ПодборТоваров.Форма",
        ПараметрыФормы,
        ЭтотОбъект,
        ,,,
        Новый ОписаниеОповещения("ПослеПодбораТоваров", ЭтотОбъект));

КонецПроцедуры

&НаКлиенте
Процедура ПослеПодбораТоваров(РезультатПодбора, ДополнительныеПараметры) Экспорт
    Если РезультатПодбора = Неопределено Тогда
        Возврат;
    КонецЕсли;

    Для Каждого ДанныеТовара Из РезультатПодбора Цикл
        НоваяСтрока = Объект.Товары.Добавить();
        ЗаполнитьЗначенияСвойств(НоваяСтрока, ДанныеТовара);
    КонецЦикла;

    Модифицированность = Истина;
КонецПроцедуры

---

Rule 9: Visibility control — group changes

All visibility/accessibility changes should be done in a single server call to avoid interface flickering.

&НаСервере
Процедура УправлениеВидимостью()
    ЭтоУслуга = Объект.ВидОперации = Перечисления.ВидыОпераций.Услуга;

    Элементы.Склад.Видимость = НЕ ЭтоУслуга;
    Элементы.ТоварыКоличество.Видимость = НЕ ЭтоУслуга;
    Элементы.ТоварыЕдиницаИзмерения.Видимость = НЕ ЭтоУслуга;
    Элементы.ГруппаДоставка.Видимость = НЕ ЭтоУслуга;

    Элементы.Контрагент.ТолькоПросмотр = Объект.Проведен;
КонецПроцедуры

&НаКлиенте
Процедура ВидОперацииПриИзменении(Элемент)
    УправлениеВидимостью(); // Один серверный вызов для всех изменений
КонецПроцедуры

---

Rule 10: Tabular parts — recalc on the client when possible

// Изменение количества — пересчёт суммы на клиенте
&НаКлиенте
Процедура ТоварыКоличествоПриИзменении(Элемент)
    ТекущаяСтрока = Элементы.Товары.ТекущиеДанные;
    ТекущаяСтрока.Сумма = РассчитатьСумму(
        ТекущаяСтрока.Количество, ТекущаяСтрока.Цена, ТекущаяСтрока.СтавкаНДС);
КонецПроцедуры

// Изменение номенклатуры — нужен сервер для получения данных
&НаКлиенте
Процедура ТоварыНоменклатураПриИзменении(Элемент)
    ТекущаяСтрока = Элементы.Товары.ТекущиеДанные;
    ДанныеНоменклатуры = ПолучитьДанныеНоменклатуры(ТекущаяСтрока.Номенклатура);

    ТекущаяСтрока.ЕдиницаИзмерения = ДанныеНоменклатуры.ЕдиницаИзмерения;
    ТекущаяСтрока.Цена = ДанныеНоменклатуры.Цена;
    ТекущаяСтрока.СтавкаНДС = ДанныеНоменклатуры.СтавкаНДС;
    ТекущаяСтрока.Сумма = РассчитатьСумму(
        ТекущаяСтрока.Количество, ТекущаяСтрока.Цена, ТекущаяСтрока.СтавкаНДС);
КонецПроцедуры

---

Rule 11: Notifications between forms

// Форма документа — после записи
&НаКлиенте
Процедура ПослеЗаписи(ПараметрыЗаписи)
    Оповестить("Запись_РеализацияТоваровУслуг",
        Новый Структура("Ссылка, Проведен", Объект.Ссылка, Объект.Проведен),
        ЭтотОбъект);
КонецПроцедуры

// Форма списка — обработка оповещения
&НаКлиенте
Процедура ОбработкаОповещения(ИмяСобытия, Параметр, Источник)
    Если ИмяСобытия = "Запись_РеализацияТоваровУслуг" Тогда
        Элементы.Список.Обновить();
    КонецЕсли;
КонецПроцедуры

---

Rule 12: Data types passed between client and server

Types passed freely

Primitives (Строка, Число, Дата, Булево), References, Enumerations, Структура, Соответствие, Массив, ФиксированныеКоллекции, ХранилищеЗначения.

Types NOT passed (server-only)

| Type | Alternative | |-----|-------------| | ТаблицаЗначений | ДанныеФормыКоллекция (через реквизиты формы) | | ДеревоЗначений | ДанныеФормыДерево (через реквизиты формы) | | ОбъектМетаданных | Передавать ИмяМетаданных (строку) | | Запрос, РезультатЗапроса | Передавать результат (структура/массив) |

---

depends_on: []