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

В клиентских обработчиках событий нажатия на кнопки сохранения, расположенных на 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;
        });
    });