X-Up заголовки

Unpoly — это фронтенд-библиотека для создания интерактивных веб-приложений без полной перезагрузки страниц. Она использует концепцию progressive enhancement, позволяя добавлять AJAX-подгрузку, анимации и обновление фрагментов страницы поверх стандартного HTML, сохраняя при этом базовую функциональность для браузеров без JavaScript.

Ключевым понятием является up-target — область страницы, которая обновляется при выполнении действия (клик по ссылке, отправка формы). Библиотека автоматически обрабатывает ссылки и формы, подгружая новые фрагменты HTML и вставляя их в указанный контейнер.

Работа с целями (Targets)

Unpoly использует CSS-селекторы для указания целевых областей обновления. Атрибуты up-target и up-swap позволяют управлять тем, как контент будет вставляться в DOM.

Пример:

<div id="content">
  Старый контент
</div>

<a href="/новый-контент" up-target="#content" up-swap="replace">Загрузить</a>

  • up-target="#content" — указывает контейнер, который будет обновлен.

  • up-swap="replace" — определяет стратегию замены контента:

    • replace — заменяет содержимое полностью;
    • before — вставляет перед текущим содержимым;
    • after — вставляет после;
    • outer — заменяет сам контейнер;
    • delete — удаляет целевой элемент.

Обработка ссылок и форм

Unpoly автоматически перехватывает клики по ссылкам и отправку форм с атрибутами up-target или up-submit.

Ссылки:

<a href="/страница" up-target="#main" up-transition="fade">Перейти</a>
  • up-transition="fade" — добавляет плавную анимацию при обновлении контента.

Формы:

<form action="/создать" method="post" up-target="#list" up-swap="append">
  <input type="text" name="name">
  <button type="submit">Добавить</button>
</form>
  • up-swap="append" — добавляет новый элемент в конец списка.

Unpoly также поддерживает AJAX-валидацию форм, автоматически подставляя ошибки на страницу без перезагрузки.

Навигация и история

Библиотека интегрируется с history API, обеспечивая корректное поведение кнопок «Назад» и «Вперед». Каждый AJAX-запрос может обновлять URL с помощью up-target и up-history.

<a href="/новая-страница" up-target="#content" up-history="push">Перейти</a>
  • up-history="push" — добавляет запись в историю браузера.
  • up-history="replace" — заменяет текущую запись.

При этом Unpoly отслеживает состояния страницы, включая формы и скролл, и корректно их восстанавливает.

События и хуки

Unpoly предоставляет богатый набор событий, позволяющих интегрировать собственную логику при обновлении страницы.

Основные события:

  • up:click — срабатывает при клике по ссылке, перехваченному Unpoly;
  • up:before-request — перед отправкой AJAX-запроса;
  • up:success — после успешного обновления целевого элемента;
  • up:fragment-updated — после вставки нового фрагмента в DOM;
  • up:layer-closed — при закрытии всплывающего слоя (modal).

Пример подписки:

up.on('up:fragment-updated', function(event) {
  console.log('Фрагмент обновлен:', event.target);
});

События позволяют динамически инициализировать JS-плагины на новых элементах страницы.

Модальные окна и слои

Unpoly поддерживает слои (layers) — плавающие контейнеры поверх страницы, аналог модальных окон.

<a href="/профиль" up-target="body" up-layer="true">Открыть профиль</a>
  • up-layer="true" — открывает ссылку во всплывающем слое.
  • up-layer можно использовать с up-transition для анимации появления.

Слои могут быть вложенными, а закрытие происходит по нажатию на фоновую область или вызову up.layer.close().

Фильтрация и обновление фрагментов

Unpoly позволяет обновлять только определённые фрагменты страницы с помощью селекторов up-fragment и up-keep.

<div id="menu" up-keep>
  Меню остаётся без изменений
</div>

<div id="main" up-fragment>
  Основной контент обновляется
</div>
  • up-keep — предотвращает замену содержимого при обновлении родительского контейнера;
  • up-fragment — явно указывает, что этот элемент может быть обновлён.

Такой подход облегчает управление сложной структурой страниц и предотвращает нежелательную потерю состояния элементов.

Кэширование и оптимизация

Unpoly имеет встроенные механизмы кэширования фрагментов. Если один и тот же URL загружается повторно, библиотека может использовать закэшированный HTML вместо запроса к серверу.

Атрибуты кэширования:

  • up-cache="true" — сохраняет содержимое для последующих загрузок;
  • up-cache="false" — отключает кэширование для конкретного фрагмента.

Кэширование повышает производительность, особенно на страницах с повторяющимися компонентами, такими как списки или вкладки.

Анимации и переходы

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

  • fade — постепенное появление/исчезновение;
  • slide-up / slide-down — вертикальное смещение;
  • cross-fade — одновременная смена старого и нового контента.

Применение анимаций осуществляется через up-transition:

<a href="/новый-контент" up-target="#content" up-transition="slide-down">Сменить</a>

Анимации работают как с целыми слоями, так и с отдельными фрагментами.

Интеграция с сервером

Unpoly не навязывает формат данных. На сервер можно возвращать обычный HTML, фрагменты, JSON или ошибки валидации. Для корректной работы нужно:

  1. Отделять обновляемые фрагменты с помощью CSS-селекторов.
  2. Использовать HTTP-коды: 200 для успешного обновления, 422 для ошибок форм.
  3. Поддерживать правильные ссылки и формы с атрибутами up-target и up-swap.

Unpoly также поддерживает REST-подход, позволяя легко комбинировать AJAX-запросы с традиционными страницами.

Расширение функционала

Unpoly можно расширять через плагины или собственные обработчики событий. Доступ к внутреннему API позволяет:

  • программно открывать или закрывать слои: up.layer.open(url) / up.layer.close(layer);
  • динамически обновлять целевые области: up.replace('#content', html);
  • контролировать историю и состояние страницы: up.history.push(url).

Такой подход обеспечивает полную гибкость при построении интерактивных приложений без перегрузки серверной логики.

Оглавление