Обработка события сохранения объекта на клиенте

В клиентских обработчиках событий нажатия на кнопки сохранения, расположенных на Web-форме редактирования, перед отправкой постбэка и сохранением объекта выполняется проверка редактируемых данных в технологическом коде (валидаторы контролов, AjaxGroupEdit).

Стандартный процесс проверки редактируемых данных может быть расширен за счет добавления обработчиков событий с помощью функции $.icsEditForm.attachEventHandler. Возможно добавление обработчиков следующих событий:

Событие	Описание
onCheckStarts	Инициируется перед началом проверки редактируемых данных в технологическом коде. В обработчике данного события возможно отменить последующее сохранение редактируемых данных или инициировать выполнение асинхронных операций, которые должны завершиться до выполнения проверкиредактируемых данных в технологическом коде (за счет передачи Deferred-объектов через параметр обработчика данного события в технологический обработчик события сохранения объекта).
onCheckStopped	Инициируется в случае отмены сохранения данных в обработчике события onCheckStarts.
onCheckSucceed	Инициируется в случае успешного выполнения проверки редактируемых данных в технологическом коде.
onCheckFailed	Инициируется в случае неуспешного выполнения проверки редактируемых данных в технологическом коде или в случае перевода в состояние “отменено” хотя бы одного из Deferred-объектов, созданных в обработчике события onCheckStarts.
onCheckProgress	Инициируется в случае получения уведомлений о прогрессе от одного из Deferred-объектов, созданных в обработчике события onCheckStarts.

Методы $.icsEditForm.attachEventHandler и $.icsEditForm.attachOnceEventHandler

Методы $.icsEditForm.attachEventHandler и $.icsEditForm.attachOnceEventHandler предназначены для регистрации обработчиков событий формы редактирования. Разница между ними в том, что $.icsEditForm.attachEventHandler регистрирует обработчик, который будет выполняться всегда, при возникновении соответствующего события, а $.icsEditForm.attachOnceEventHandler регистрирует обработчик, который будет выполнен однократно.

Оба метода принимают два параметра:

Параметр	Описание
handler	Функция-обработчик события.
eventName	Имя события. Если не указано, то регистрируется обработчик события onCheckStarts.

Обработчики событий

Все обработчики событий, принимают объект, в качестве аргумента. Этот объект содержит как минимум одно свойство: saveOptions - параметры, с которыми был вызван метод сохранения. По этим параметрам можно отличить был ли метод сохранения вызван из технологического кода (например по нажатию на кнопку сохранения), или из прикладного.

Аргумент обработчиков событий onCheckStarts и onCheckSucceed содержит еще два свойства (stop и deferreds):

Свойство	Описание
saveOptions	Параметры, с которыми был вызван метод сохранения.
stop	Логическое свойство, которое позволяет отменить дальнейшую логику сохранения, в случае установки значения true.
deferreds	Массив Deferred-объектов для возможности выполнения асинхронных операций до выполнения проверки редактируемых данных в технологическом коде. Обработчик события сохранения объекта, определенный в технологическом коде, выполнится только в том случае, если все Deferred-объекты, добавленные в данный массив, перейдут в состояние “выполнено” (т.е. будет вызван метод resolve() для каждого их них). В случае перевода хотя бы одного такого Deferred-объекта в состояние “отменено” проверка редактируемых данных в технологическом коде и последующее инициирование процесса сохранения объекта выполнено не будет, но будет выполнен обработчик события onCheckFailed.

Пример добавления дополнительной логики при сохранении объекта

$(function() {
    // Регистрация пользовательского обработчика события onCheckStarts.
    // Внимание! Пользовательские проверки, зарегистрированные в качестве обработчиков события  выполняются до технологических проверок.
    $.icsEditForm.attachEventHandler(function(p) {
        var d1 = $.Deferred();
        p.deferreds.push(d1);
        // Функция $.ics.dialog.confirm - асинхронная.
        // Технологический обработчик сохранения объекта будет приостановлен до тех пор, пока объект d1 не перейдет в состояние "выполнено" или "отменено".
        $.ics.dialog.confirm({
            message: 'Данные изменены. Сохранить изменения?',
            callback: function (res) {
                if (!res) {
                    // В этом случае выполнится проверка редактируемых данных в технологическом коде и последующее сохранение объекта в случае успешного завершения проверки.
                    d1.reject();
                } else {
                    // В этом случае выполнится обработчик события onCheckFailed, определенный ниже.
                    d1.resolve();
                }
            }
        });
    });
    // Выполнение действий в случае перевода объекта d1 в состояние "отменено" или в случае возникновения ошибок при проверке данных в технологическом коде.
    $.icsEditForm.attachEventHandler(function (p) {
        // ...
    }, 'onCheckFailed');
});

Методы save и saveAndClose

У jQuery-плагина jquery.icsEditForm есть публичные методы save и saveAndClose, которые предназначены соответственно для сохранения формы редактирования, и сохранения с последующим закрытием страницы.

Оба метода принимают объект с опциями в качестве параметра.

Опция	Описание	Значение по умолчанию
showSaveWaitingWindow	Флаг, показывающий нужно ли отображать модальное окно со спиннером, во время ожидания сохранения формы.	true
saveWaitingWindow	Объект с настройками модального окна ожидания
saveWaitingWindow.width	Ширина модального окна ожидания	310
saveWaitingWindow.height	Высота модального окна ожидания	110
saveWaitingWindow.title	Заголовок модального окна ожидания	‘Подождите, пожалуйста’
saveWaitingWindow.contentSelector	CSS-селектор для элемента разметки с содержанием модального окна ожидания	‘#hiddenContent’
postBackEventTarget	Значение, которое попадет в form.EVENTTARGET.value при вызове submit() формы	Значение атрибута ‘name’ технологической кнопки ‘Сохранить’ (для метода ‘save’), или кнопки ‘Сохранить и закрыть’ (для метода ‘saveAndClose’)
postBackEventArgument	Значение, которое попадет в form.EVENTARGUMENT.value при вызове submit() формы	”

Пример использования метода save и обработки событий формы

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

$(function() {
        var customSaveBtn = $('#<%= CustomSaveBtn.ClientID %>');
        var customSaveBtnId = customSaveBtn.attr('id');
        var messageColorDropDown = $("#<%= MessageColorDropDown.ClientID %>");
        var pageForm = $('#pageForm');
        // Обрабатываем событие, сигнализирующее о начале сохранения формы.
        // Делаем дополнительную прикладную проверку (она будет выполнена до технологических проверок).
        // Внимание! Если нужно выполнить прикладные проверки после технологических, то можно абсолютно аналогичным образом обрабатывать событие 'onCheckSucceed'.
        $.icsEditForm.attachEventHandler(function (e) {
            if (e.saveOptions.postBackEventTarget !== customSaveBtnId) {
                // Не выполняем обработку, если метод 'save' был вызван по нажатию технологической, а не прикладной кнопки сохранения.
                return;
            }
            var selectedColor = $('option:selected', messageColorDropDown).val();
            if (selectedColor === '') {
                alert('Форма не прошла дополнительную прикладную проверку. Не выбран цвет сообщения.');
                // Прерываем дальнейшее сохранение.
                e.stop = true;
                return;
            }
        }, 'onCheckStarts');
        $.icsEditForm.attachEventHandler(function (e) {
            alert('Форма не прошла проверку. Возможно не заполнены обязательные поля.');
        }, 'onCheckFailed');
        // Обрабатываем клик по прикладной кнопке на форме редактирования.
        customSaveBtn.on('click', function () {
            // Вызываем метод сохранения формы, чтобы инициировать прикладные и технологические проверки.
            // В случае успешного завершения всех проверок, будет сделан postpack, при котором
            // postBackEventTarget будет доступен через Request.Form['__EVENTTARGET'],
            // postBackEventArgument будет доступен через Request.Form['__EVENTARGUMENT'].
            // Внимание! Сохранение объекта данных не произойдет, если postBackEventTarget не совпадает с атрибутом 'name',
            // технологической кнопки 'Сохранить' или 'Сохранить и закрыть'.
            pageForm.icsEditForm('save', {
                showSaveWaitingWindow: false,
                postBackEventTarget: customSaveBtn.attr('id'),
                postBackEventArgument: ''
            });
            return false;
        });
    });