esrc.js — серверные интерактивные интерфейсы без SPA
esrc.js — небольшой runtime Esora для progressive enhancement. Он позволяет описать HTTP-запрос и место обновления прямо в HTML-атрибутах. Браузер продолжает работать с обычными ссылками и формами, а при загруженном JavaScript отправляет запрос асинхронно и заменяет только нужный фрагмент страницы.
Это не замена полноценному frontend-приложению. esrc.js подходит, когда состояние в основном находится на сервере: формы, фильтры, пагинация, удаление строк, inline-редактирование, навигация по документации и небольшие интерактивные компоненты.
Когда использовать
Используйте esrc.js, если:
- сервер уже умеет отрисовывать HTML-фрагменты;
- после действия нужно обновить один блок, а не весь документ;
- состояние должно оставаться на сервере;
- не хочется добавлять SPA-роутер и отдельный frontend-state;
- нужна рабочая страница даже при отключённом JavaScript.
Используйте обычный JavaScript или полноценный frontend, если компонент имеет сложное локальное состояние, drag-and-drop, большой граф редактора, offline-режим или десятки независимых клиентских состояний.
Модальные окна и alert
После подключения esrc.js доступен независимый runtime window.esora. Он не требует
дополнительных зависимостей и поддерживает role="dialog", aria-modal, восстановление
фокуса, ловушку Tab и закрытие по Escape.
JavaScript API
// Alert: Promise завершается после нажатия OK.
await esora.alert('Профиль сохранён', { type: 'success', title: 'Готово' });
// Confirm: Promise возвращает true для Yes и false для No, Escape или backdrop.
const allowed = await esora.confirm('Удалить запись?', {
type: 'warning',
title: 'Подтвердите действие',
okLabel: 'Yes',
cancelLabel: 'No',
});
// Произвольный HTML. Возвращаемый объект содержит element, result, close() и focus().
const modal = esora.modal({
type: 'info',
title: 'Детали',
html: true,
content: '<p><strong>HTML-контент</strong> из доверенного источника.</p>',
buttons: { Close: null },
});
await modal.result;
Поддерживаемые типы: info, success, warning, error. По умолчанию alert и
confirm вставляют сообщение как текст (html: false). Для modal HTML разрешён
явно; не передавайте в него непроверенный пользовательский ввод.
Data-атрибуты
<button type="button"
data-esora-alert="Синхронизация завершена"
data-esora-alert-type="success"
data-esora-title="Успешно">
Показать alert
</button>
<button type="button"
data-esora-confirm="Удалить черновик?"
data-esora-alert-type="warning">
Удалить
</button>
<button type="button"
data-esora-modal="#help-modal"
data-esora-title="Справка"
data-esora-alert-type="info">
Открыть modal
</button>
<template id="help-modal"><p>Произвольный HTML из шаблона.</p></template>
Для data-esora-modal значение, начинающееся с #, трактуется как селектор элемента;
его innerHTML копируется в modal. Остальные значения трактуются как HTML-строка.
После esrc-swap runtime повторно сканирует вставленный фрагмент, поэтому новые
data-атрибуты работают без ручной инициализации.
data-esrc-confirm использует esora.confirm, если runtime подключён. При отсутствии
этого API сохраняется обратная совместимость с нативным window.confirm.
Установка и подключение
1. Опубликовать runtime
В проекте Esora выполните:
php bin/console assets:publish
Команда публикует esrc.js в public/assets/js/esrc.js. После изменения исходников ассетов в production повторите публикацию.
2. Подключить runtime в layout
Подключите скрипт после HTML-разметки или с атрибутом defer:
<body>
<!-- страница и элементы с data-esrc-* -->
<script src="/assets/js/esrc.js"></script>
</body>
Runtime автоматически сканирует DOM после DOMContentLoaded. Повторный вызов esrc.scan() безопасен: уже привязанные элементы повторно не подписываются.
3. Добавить endpoint
Контроллер должен вернуть HTML, который можно вставить в target:
use Esora\Http\ResponseFactory;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
public function ping(ServerRequestInterface $request): ResponseInterface
{
return ResponseFactory::html(
'<span class="status status--ok">Сервер отвечает</span>'
);
}
Маршрут:
$router->get('/api/ping', [StatusController::class, 'ping']);
Для HTML-ответа используйте ResponseFactory::html(). Runtime получает тело ответа как текст и передаёт его в выбранную swap-стратегию.
Первый пример: GET и innerHTML
<button
type="button"
data-esrc-get="/api/ping"
data-esrc-target="#ping-result"
>
Проверить соединение
</button>
<div id="ping-result" aria-live="polite">
Проверка ещё не выполнялась.
</div>
Что произойдёт:
- runtime найдёт
data-esrc-get; - для
buttonпо умолчанию выберет событиеclick; - отправит
GET /api/ping; - возьмёт ответ сервера;
- установит его как
innerHTMLэлемента#ping-result.
data-esrc-target — CSS-селектор. Если target не найден, запрос всё равно отправится, но визуально результат никуда не попадёт. Поэтому ID или селектор target нужно проверять особенно внимательно.
Атрибуты запросов
HTTP-метод и URL
Используйте один атрибут метода на элементе:
<button data-esrc-get="/users/42">Загрузить</button>
<form data-esrc-post="/users">...</form>
<button data-esrc-put="/users/42">Сохранить</button>
<button data-esrc-delete="/users/42">Удалить</button>
Поддерживаются:
data-esrc-get→GET;data-esrc-post→POST;data-esrc-put→PUT;data-esrc-delete→DELETE.
Runtime использует URL как есть. Query string можно указать прямо в атрибуте:
<button data-esrc-get="/reports?period=week" data-esrc-target="#report">
За неделю
</button>
Target
<div id="result"></div>
<button
data-esrc-get="/fragment"
data-esrc-target="#result"
>
Обновить
</button>
Кроме обычного CSS-селектора, поддерживаются два относительных варианта:
<!-- target — ближайшая карточка с классом .card -->
<button data-esrc-get="/status" data-esrc-target="closest .card">
Обновить карточку
</button>
<!-- target — элемент #content внутри текущего элемента -->
<div data-esrc-get="/status" data-esrc-target="find #content">
<div id="content"></div>
</div>
Если data-esrc-target не указан, target-ом считается сам элемент, инициировавший запрос. Для кнопок обычно лучше указывать отдельный target, иначе ответ заменит содержимое самой кнопки.
Swap-стратегии
По умолчанию используется innerHTML:
<button
data-esrc-get="/cart"
data-esrc-target="#cart"
data-esrc-swap="innerHTML"
>
Обновить корзину
</button>
Доступные значения:
innerHTML— заменяет содержимое target.outerHTML— заменяет сам target новым HTML.beforebegin— вставляет HTML перед target.afterbegin— вставляет HTML в начало target.beforeend— добавляет HTML в конец списка.afterend— вставляет HTML после target.none— выполняет запрос, но не меняет DOM.
Примеры:
<!-- Ответ становится новым содержимым списка -->
<div id="notifications"></div>
<button data-esrc-get="/notifications" data-esrc-target="#notifications">
Обновить уведомления
</button>
<!-- Ответ добавляется новой строкой в конец списка -->
<ul id="messages">
<li>Старое сообщение</li>
</ul>
<button
data-esrc-get="/messages/latest"
data-esrc-target="#messages"
data-esrc-swap="beforeend"
>
Загрузить ещё
</button>
После вставки runtime снова сканирует добавленный DOM. Поэтому элементы с data-esrc-*, пришедшие в HTML-ответе, начинают работать без ручной инициализации.
Формы и отправка данных
Для формы runtime по умолчанию использует событие submit и сериализует поля через FormData.
POST-форма
<form
data-esrc-post="/profile"
data-esrc-target="#profile-result"
>
<label>
Имя
<input name="name" required>
</label>
<label>
Email
<input name="email" type="email" required>
</label>
<button type="submit">Сохранить</button>
</form>
<div id="profile-result" aria-live="polite"></div>
Контроллер получает данные через PSR-7 request:
public function update(ServerRequestInterface $request): ResponseInterface
{
$body = $request->getParsedBody();
$data = is_array($body) ? $body : [];
$name = htmlspecialchars((string) ($data['name'] ?? ''), ENT_QUOTES, 'UTF-8');
return ResponseFactory::html(
'<p class="notice">Профиль сохранён: ' . $name . '</p>'
);
}
Для GET-формы поля превращаются в query-параметры:
<form data-esrc-get="/search" data-esrc-target="#results">
<input name="q" placeholder="Поиск">
<select name="status">
<option value="open">Открытые</option>
<option value="closed">Закрытые</option>
</select>
<button type="submit">Найти</button>
</form>
В результате runtime отправит запрос вида /search?q=...&status=open.
Передача дополнительных полей через include
Если инициатором является не форма, поля можно подключить через data-esrc-include:
<input id="filter" name="q" value="esora">
<select id="sort" name="sort">
<option value="newest">Сначала новые</option>
<option value="oldest">Сначала старые</option>
</select>
<button
data-esrc-get="/articles"
data-esrc-include="#filter, #sort"
data-esrc-target="#articles"
>
Применить фильтр
</button>
<div id="articles"></div>
Runtime соберёт элементы из CSS-селектора, возьмёт их name и value, а для GET добавит их в query string. Для POST/PUT/DELETE эти поля войдут в FormData.
События и пользовательские сценарии
Изменить trigger
Для кнопок и ссылок default trigger — click, для форм — submit, для input, select и textarea — change. Явное событие задаётся так:
<select
name="category"
data-esrc-get="/products"
data-esrc-trigger="change"
data-esrc-target="#products"
>
<option value="books">Книги</option>
<option value="tools">Инструменты</option>
</select>
data-esrc-trigger поддерживает события click, submit, change, input и специальное load.
Загрузка блока при открытии страницы
<section
data-esrc-get="/dashboard/summary"
data-esrc-trigger="load"
data-esrc-target="this"
>
Загружаем сводку…
</section>
При load запрос запускается сразу после инициализации runtime. Не используйте этот режим для большого количества блоков без необходимости: каждый блок создаёт отдельный запрос.
Ссылка без полной перезагрузки
Обычная ссылка сохраняет fallback-навигацию:
<a
href="/docs/database"
data-esrc-get="/docs/database"
data-esrc-target="article.doc"
data-esrc-push-url="true"
>
База данных
</a>
С включённым runtime HTML-ответ заменит только article.doc, а history.pushState() добавит новый URL. Без JavaScript браузер перейдёт по href как обычно.
Индикаторы и подтверждение действия
Индикатор загрузки
Укажите CSS-селектор элемента, которому во время запроса добавляется класс esrc-loading:
<span id="spinner" hidden>Загрузка…</span>
<button
data-esrc-post="/export"
data-esrc-target="#export-result"
data-esrc-indicator="#spinner"
>
Запустить экспорт
</button>
CSS может управлять отображением:
#spinner { display: none; }
#spinner.esrc-loading { display: inline; }
На элементе, который отправляет запрос, во время выполнения также появляется класс esrc-requesting.
Подтверждение опасного действия
<button
data-esrc-delete="/projects/42"
data-esrc-target="closest .project-row"
data-esrc-swap="outerHTML"
data-esrc-confirm="Удалить проект без возможности восстановления?"
>
Удалить
</button>
Перед запросом runtime вызовет стандартный window.confirm(). При отмене запрос не отправляется.
CSRF и изменяющие запросы
GET, HEAD и OPTIONS считаются безопасными методами и не требуют CSRF-заголовка от esrc.js. Для POST, PUT и DELETE runtime читает cookie nqphp_csrf и, если токен найден, отправляет его как X-CSRF-Token.
Пример серверного middleware с формой:
<form data-esrc-post="/settings" data-esrc-target="#result">
<input type="hidden" name="_token" value="<?= htmlspecialchars($csrfToken) ?>">
<input name="timezone" value="UTC">
<button>Сохранить</button>
</form>
На стороне приложения CSRF middleware также может проверить токен из _token или заголовка. Если сервер вернул 419, проверьте:
- middleware добавляет CSRF-cookie на страницу;
- форма содержит актуальный
_token, если приложение использует поле формы; - cookie доступна текущему домену;
- запрос отправляется на тот же origin;
- в DevTools Network присутствует
X-CSRF-Token.
Не отключайте CSRF только ради работы демо. Исключение endpoint из проверки оправдано только для осознанно публичного, безопасного API.
Lifecycle и события JavaScript
Для каждого запроса lifecycle выглядит так:
- пользователь вызывает trigger;
- runtime определяет method, URL, target и swap;
- добавляется
Accept: text/html, application/xhtml+xml; - добавляется
X-NQPHP-Request: true; - для изменяющего метода добавляется CSRF-заголовок, если токен найден;
- отправляется
fetch(); - срабатывает
nq:beforeRequest; - ответ вставляется в target;
- при наличии
data-esrc-push-url="true"обновляется history; - срабатывает
nq:afterRequest.
Можно отменить запрос в nq:beforeRequest:
<script>
document.addEventListener('nq:beforeRequest', (event) => {
const { element } = event.detail;
if (element.matches('[data-requires-online]') && !navigator.onLine) {
event.preventDefault();
document.querySelector('#result').textContent = 'Нет соединения.';
}
});
</script>
Отслеживание успешного ответа:
<script>
document.addEventListener('nq:afterRequest', (event) => {
const { status, element, responseText } = event.detail;
console.log('esrc request completed', {
status,
url: element.getAttribute('data-esrc-get')
|| element.getAttribute('data-esrc-post'),
responseText,
});
});
</script>
Ошибки доступны через nq:error:
<script>
document.addEventListener('nq:error', (event) => {
const { status, responseText, error } = event.detail;
console.error('esrc request failed', { status, responseText, error });
});
</script>
nq:error срабатывает для HTTP-ответа с кодом не из диапазона 2xx, а также для сетевой ошибки. Сам runtime всё равно получает текст ответа и применяет swap; если нужно особое поведение для 422 или 419, обработайте событие и выберите подходящую разметку ответа.
Ответы сервера и безопасность HTML
Обычно endpoint для esrc возвращает HTML-фрагмент:
return ResponseFactory::html(
'<div class="alert">Операция выполнена.</div>'
);
Значения пользователя обязательно экранируйте до вставки в HTML:
$name = htmlspecialchars(
(string) ($data['name'] ?? ''),
ENT_QUOTES,
'UTF-8'
);
return ResponseFactory::html('<p>Привет, ' . $name . '</p>');
Не вставляйте непроверенный пользовательский HTML. innerHTML, outerHTML и остальные swap-стратегии вставляют ответ как HTML. Если endpoint возвращает JSON, esrc.js не преобразует его в объект и не форматирует автоматически — верните HTML-фрагмент либо подпишитесь на nq:afterRequest и обработайте responseText самостоятельно.
Динамические элементы и повторное сканирование
Ответ может содержать новый управляемый элемент:
return ResponseFactory::html(<<<'HTML'
<button data-esrc-get="/tasks/next" data-esrc-target="#tasks">
Показать ещё
</button>
HTML);
После innerHTML, beforeend, afterbegin и других swap-операций runtime вызывает внутренний scan для добавленного DOM. В большинстве случаев дополнительный код не нужен. Если разметка добавлена сторонним скриптом напрямую, вызовите:
<script>
window.esrc?.scan();
</script>
Полный пример: список задач
Маршруты
$router->get('/tasks', [TaskController::class, 'index']);
$router->post('/tasks', [TaskController::class, 'store']);
$router->delete('/tasks/{id}', [TaskController::class, 'destroy']);
Контроллер
public function store(ServerRequestInterface $request): ResponseInterface
{
$body = $request->getParsedBody();
$title = is_array($body) ? trim((string) ($body['title'] ?? '')) : '';
if ($title === '') {
return ResponseFactory::html(
'<p class="alert alert--error">Введите название задачи.</p>',
422
);
}
// Сохранение через модель или Query Builder.
$safeTitle = htmlspecialchars($title, ENT_QUOTES, 'UTF-8');
return ResponseFactory::html(
'<li class="task"><span>' . $safeTitle . '</span>'
. '<button data-esrc-delete="/tasks/1" '
. 'data-esrc-target="closest .task" '
. 'data-esrc-swap="outerHTML" '
. 'data-esrc-confirm="Удалить задачу?">Удалить</button></li>'
);
}
Шаблон
<form data-esrc-post="/tasks" data-esrc-target="#task-result">
<input name="title" placeholder="Название задачи">
<button type="submit">Добавить</button>
</form>
<div id="task-result"></div>
<ul id="tasks">
<li class="task">
Разобрать документацию
<button
data-esrc-delete="/tasks/1"
data-esrc-target="closest .task"
data-esrc-swap="outerHTML"
data-esrc-confirm="Удалить задачу?"
>
Удалить
</button>
</li>
</ul>
В production вместо фиксированного ID используйте ID созданной записи и экранируйте каждое значение, пришедшее из базы данных.
Диагностика
Нажатие ничего не делает
Проверьте:
- загружен ли
/assets/js/esrc.jsсо статусом200; - присутствует ли
data-esrc-get,data-esrc-post,data-esrc-putилиdata-esrc-delete; - нет ли одновременно нескольких конфликтующих method-атрибутов;
- есть ли у формы
button type="submit"; - нет ли ошибки JavaScript в Console.
Запрос есть, но блок пустой
Проверьте:
- корректен ли
data-esrc-target; - действительно ли endpoint возвращает HTML;
- не возвращает ли контроллер полный layout вместо fragment;
- не используется ли
data-esrc-swap="none"; - какой текст и статус видны в Network.
Сработала полная перезагрузка
Это обычно означает, что JavaScript не загрузился, элемент не был просканирован или ссылка не получила data-esrc-*. Это штатный fallback: после исправления загрузки runtime та же ссылка начнёт работать без перезагрузки.
Endpoint возвращает 419, 422 или 500
419: CSRF-токен отсутствует или устарел;422: сервер отклонил данные, верните понятный HTML с ошибками;500: смотрите логи приложения и сначала вызовите endpoint напрямую через Network/curl.
Для проверки endpoint отдельно:
curl -i -X POST https://example.test/tasks \
-H 'Accept: text/html' \
-H 'X-NQPHP-Request: true' \
--data 'title=Первая задача'
Краткая памятка
<!-- GET и обновление блока -->
<button data-esrc-get="/fragment" data-esrc-target="#result">Load</button>
<!-- POST-форма -->
<form data-esrc-post="/save" data-esrc-target="#result">...</form>
<!-- Удаление строки -->
<button data-esrc-delete="/items/1" data-esrc-target="closest .row" data-esrc-swap="outerHTML">
Delete
</button>
<!-- Навигация с URL без полной перезагрузки -->
<a href="/docs/next" data-esrc-get="/docs/next" data-esrc-target="article.doc" data-esrc-push-url="true">
Next
</a>
Связанные разделы: Маршрутизация, Контроллеры, Валидация, Безопасность, Vite.