Функция up.follow

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

Синтаксис и параметры

up.follow(url, options)
  • url — строка с адресом ресурса, на который необходимо перейти.
  • options — объект с настройками запроса и поведения, который может содержать следующие свойства:
  1. target: CSS-селектор или DOM-элемент, куда будет загружен контент. Эквивалент атрибута up-target.
  2. method: HTTP-метод запроса ('GET' или 'POST'). По умолчанию 'GET'.
  3. params: объект с параметрами запроса. Может быть простым объектом { key: value } или FormData.
  4. cache: булевое значение, включающее или отключающее кэширование. По умолчанию true.
  5. scroll: задаёт поведение скролла после загрузки (true — скролл к верху target, false — оставить текущую позицию, селектор — скролл к указанному элементу).
  6. history: определяет работу с историей браузера. Можно передать 'replace', 'push' или false.
  7. focus: элемент, на который будет установлен фокус после загрузки (CSS-селектор или DOM-элемент).

Примеры использования

Загрузка страницы в конкретный контейнер:

up.follow('/users', { target: '#main-content' });

В этом примере контент страницы /users будет загружен в элемент с id main-content без перезагрузки всей страницы. История браузера автоматически обновится.

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

up.follow('/search', {
  method: 'POST',
  params: { query: 'Unpoly', page: 1 },
  target: '#results'
});

Это позволяет инициировать поиск, не привязываясь к форме в DOM. Данные передаются через AJAX-запрос, и результаты отображаются в указанном контейнере.

Обновление контента с управлением историей:

up.follow('/profile', {
  target: '#profile-section',
  history: 'replace'
});

Использование history: 'replace' заменяет текущую запись в истории, что предотвращает создание лишнего шага при навигации назад.

Асинхронное управление результатами

Функция up.follow возвращает объект Promise, который позволяет реагировать на успешное выполнение запроса или ошибки:

up.follow('/notifications', { target: '#notif' })
  .then(response => {
    console.log('Контент успешно загружен', response);
  })
  .catch(error => {
    console.error('Ошибка при загрузке контента', error);
  });
  • response содержит объект с полями request и response, которые предоставляют доступ к деталям запроса и ответа.
  • error срабатывает при сетевых ошибках или если сервер вернул статус 4xx/5xx, в зависимости от настроек up.fail.

Взаимодействие с атрибутами HTML

up.follow полностью совместим с атрибутами Unpoly:

  • up-target — указание контейнера, куда будет загружен контент.
  • up-method — выбор метода запроса (GET или POST).
  • up-params — дополнительные параметры для передачи на сервер.

Программный вызов up.follow позволяет обойтись без явного использования атрибутов, сохраняя гибкость и повторное использование логики на стороне JavaScript.

Продвинутые сценарии

  1. Условная навигация: выполнение перехода только при определённых условиях:
if (user.isLoggedIn) {
  up.follow('/dashboard', { target: '#content' });
}
  1. Комбинирование с анимацией: использование CSS-переходов или сторонних библиотек для плавного обновления контента после загрузки:
up.follow('/comments', { target: '#comments' })
  .then(() => {
    $('#comments').fadeIn();
  });
  1. Динамическое формирование параметров: параметры запроса могут формироваться на основе состояния страницы:
const params = {
  filter: document.querySelector('#filter').value,
  sort: document.querySelector('#sort').value
};

up.follow('/products', { target: '#product-list', params });

Важные особенности

  • up.follow следует тем же правилам кэширования и оптимизации, что и стандартные ссылки Unpoly.
  • Если указанный target отсутствует на странице, запрос всё равно выполняется, но контент может быть не вставлен.
  • Методы GET и POST автоматически учитывают params и корректно формируют тело запроса.
  • Использование функции упрощает модульное тестирование, так как запросы и переходы можно инициировать программно без клика по элементам DOM.

Функция up.follow является ядром динамической навигации в Unpoly, обеспечивая мощный и гибкий способ управления асинхронным обновлением контента и интеграции с существующей структурой страницы.

Оглавление