Функция up.submit

Функция up.submit является одной из ключевых утилит в библиотеке Unpoly для управления отправкой форм через AJAX с полной поддержкой прогрессивного улучшения. Она позволяет перехватывать стандартное поведение HTML-форм, отправлять данные на сервер асинхронно и обновлять определённые части страницы без полной перезагрузки.

Основной синтаксис

up.submit(form, options)
  • form — объект формы (<form>), либо селектор, либо элемент DOM.
  • options — объект с настройками отправки.

Простейший пример:

up.submit('#login-form');

В этом случае Unpoly автоматически отправит форму на URL из атрибута action методом, указанным в method (GET или POST), и обновит целевой контейнер, если он задан через up-target.

Параметры options

Объект options предоставляет гибкий контроль над поведением отправки формы.

  • url — строка, переопределяющая action формы.
  • method — HTTP-метод (get, post, put, delete). Если не указан, берётся из form.method.
  • target — селектор или элемент, который будет обновлён после успешного ответа.
  • fragment — CSS-селектор для извлечения части ответа. Полезно для частичной замены содержимого.
  • params — дополнительные параметры, передаваемые вместе с данными формы. Можно использовать объект вида { key: value }.
  • force — если true, форма будет отправлена даже при наличии ошибки валидации HTML.
  • scroll — логика прокрутки после обновления (false, 'top', 'target').
  • cache — управление кэшированием запроса (true, false, 'reload').

Пример с параметрами:

up.submit('#signup-form', {
  url: '/users',
  method: 'post',
  target: '#main-content',
  params: { referrer: 'landing-page' },
  scroll: 'top'
});

События, связанные с up.submit

Unpoly предоставляет богатый набор событий для управления жизненным циклом отправки формы:

  1. up:form:submit — триггерится до отправки формы. Позволяет предотвратить отправку через event.preventDefault().
  2. up:request:loading — срабатывает при начале запроса.
  3. up:request:success — вызывается при успешном завершении запроса.
  4. up:request:error — вызывается при ошибке сервера.
  5. up:request:complete — выполняется после любого завершения запроса, независимо от успеха или ошибки.

Пример обработки событий:

up.on('up:form:submit', '#login-form', event => {
  console.log('Форма готова к отправке');
});

up.on('up:request:success', event => {
  console.log('Ответ успешно получен', event.responseText);
});

Отправка с дополнительными данными

up.submit позволяет расширять данные формы без изменения HTML. Для этого используется опция params или можно модифицировать FormData перед отправкой:

const form = document.querySelector('#profile-form');
up.submit(form, {
  params: { token: 'abc123' }
});

Если нужно работать напрямую с FormData:

const formData = new FormData(form);
formData.append('extra_field', 'value');

up.submit(form, { params: formData });

Асинхронные функции и промисы

up.submit возвращает промис, что позволяет использовать современный синтаксис async/await:

async function submitProfile() {
  try {
    const response = await up.submit('#profile-form');
    console.log('Данные успешно отправлены', response);
  } catch (error) {
    console.error('Ошибка при отправке формы', error);
  }
}

Частичная замена контента

С помощью опций target и fragment можно обновлять только нужный элемент страницы.

Пример:

up.submit('#comment-form', {
  target: '#comments',
  fragment: '.latest-comment'
});

В этом случае из ответа сервера будет извлечён элемент с классом .latest-comment и заменит содержимое контейнера #comments.

Принудительная отправка и обход валидации

По умолчанию HTML-валидация блокирует отправку формы при нарушении правил (required, pattern). Чтобы обойти проверку, используется опция force: true:

up.submit('#contact-form', { force: true });

Это полезно для сценариев, где валидация реализована на стороне сервера или через кастомный JavaScript.

Совместимость с прогрессивным улучшением

up.submit интегрируется с Unpoly так, чтобы формы оставались функциональными даже без Jav * aScript:

  • Без Unpoly форма будет отправляться обычным способом.
  • С Unpoly форма превращается в AJAX-запрос с обновлением указанных элементов.
  • Все события Unpoly работают только при активной библиотеке.

Настройка глобального поведения

Unpoly позволяет задавать глобальные опции для всех форм через up.fragment.config и up.on('up:form:submit'). Например, можно глобально прокручивать страницу к верхней части после каждой отправки формы:

up.on('up:form:submit', event => {
  event.target.dataset.upScroll = 'top';
});

Особенности работы с CSRF

При интеграции с фреймворками вроде Rails или Django, up.submit автоматически добавляет токены CSRF в заголовки запроса, если они указаны в <meta> тегах. Это делает использование Unpoly безопасным без дополнительной настройки.

Вывод

Функция up.submit является мощным инструментом для асинхронной работы с формами в Unpoly. Она сочетает простоту вызова, гибкость конфигурации, поддержку событий и совместимость с прогрессивным улучшением, обеспечивая чистую и отзывчивую работу веб-приложений. Ее использование позволяет минимизировать перезагрузки страниц, управлять частичной заменой контента и интегрировать кастомные сценарии отправки и обработки данных.

Оглавление