Скрипты админки и сайта

Как подключать и вызывать общие скрипты DevCraft: ядро админки, фильтр, перевод, Composer и публичный клиент

Для кого: разработчик модуля. Здесь — что делает каждый общий скрипт, в каком порядке его подключать и какие функции вызывать из своего кода.

Скрипты лежат в devcraft/src/templates/core/assets/js/. Админка подключает их из layout.twig. Публичный клиент сайта идёт через публичные ресурсы оболочки, не через этот шаблон.

Порядок в админке

Снизу страницы, после Metro:

файл словаря языка (translation.{локаль}.js) — кладёт словарь в DevCraftI18n.dictionary;
translator.js — функции __ и DevCraftTranslate;
devcraft.js — запросы, окна, уведомления;
filter.js — полоса фильтра, если она есть на странице;
скрипты модуля из описания (assets.js).

composer.js подключается только на экранах Composer, после devcraft.js.

dc_public.js на страницах сайта, не в админке.

filter.js и composer.js ждут уже загруженный devcraft.js. Если ядра нет, в консоли будет ошибка и скрипт остановится.

Перевод (`translator.js`)

Файл читает словарь window.DevCraftI18n.dictionary. Ключ словаря — фраза на русском. Если перевода нет, на экран уходит сама фраза.

Подстановки в тексте: :имя:, {имя} или %имя%.

__('Сообщение отправлено');
DevCraftTranslate('Пакет :name: установлен', { name: 'twig/twig' });

__ и DevCraftTranslate делают одно и то же. В админке вызывайте __: его уже используют devcraft.js и filter.js.

Ядро (`devcraft.js`)

После загрузки доступен объект DevCraft. Метод DevCraft.boot() сам вешает сохранение настроек, верхнюю панель и фильтр. Повторно вызывать его из модуля не нужно.

DevCraft.Ajax.post(method, data) шлёт POST на devcraft/ajax.php. В адресе: controller=admin, method — имя из описания модуля, mod — из body[data-mod]. В теле: user_hash и JSON в поле data.

Поле __loaderText в data на сервер не уходит: это только подпись заставки на время запроса.

DevCraft.Ajax.post('settings', { theme: 'dark' }).then(function (payload) {
    if (payload.success) {
        window.location.reload();
    }
});

DevCraft.Ajax.postMultipart(url, formData) — отправка файла. Адрес собирайте через DevCraft.Ajax.url(base, params). Хеш сессии добавится сам, если его ещё нет в FormData.

Ответ с полем notice показывает DevCraft.Ajax.handleNotice(payload).

Окна и текст

Вызов	Что делает
`DevCraft.notify(title, message, type)`	уведомление Metro. `type`: `success`, `warning`, `error`, `info`
`DevCraft.notifyError(title, message, details)`	ошибка, подробности можно развернуть
`DevCraft.toast(message)`	короткая всплывающая строка
`DevCraft.metroDialogCreate(options)`	окно Metro. Кнопки из `actions` приводятся к кнопкам Metro 5
`DevCraft.copyText(text)`	копирует строку. На обычном HTTP — запасной способ без защищённого контекста
`DevCraft.Settings.save(form)`	сохраняет форму настроек с классом `js-settings-form`

Заставка на весь экран: DevCraft.showLoader(text) и DevCraft.hideLoader(). Ajax.post включает и выключает её сам.

Отладка в консоли (DevCraft.Debug.log) пишет строки только если у body стоит data-debug="1" (режим отладки или ?dc_debug=1).

Фильтр (`filter.js`)

Скрипт оживляет полосу из шаблона core/includes/form/filter_bar.twig. На корне полосы два атрибута:

data-filter-catalog — JSON каталога полей;
data-filter-rules — JSON уже выбранных правил.

DevCraft.boot() вызывает DevCraft.Filter.boot(): рисует полосу, таблицу с источником фильтра и читает правила из адреса страницы.

Своими руками обычно достаточно разметки. Если нужно из кода:

Вызов	Что делает
`DevCraft.Filter.boot()`	первый запуск полосы и таблицы
`DevCraft.Filter.openRuleDialog()`	окно нового правила
`DevCraft.Filter.applyRules()`	записать правила из окна и обновить список
`DevCraft.Filter.submitForm()`	отправить форму фильтра
`DevCraft.Filter.clearRules()`	убрать все правила

Остальные поля DevCraft.Filter.* обслуживают полосу, чипы и таблицу. Менять их из модуля стоит только если вы правите сам фильтр.

Пакеты (`composer.js`)

Подключается на экране пакетов после ядра. Сам слушает щелчки.

Кнопка действия:

<button type="button"
        class="js-composer-action"
        data-action-type="install"
        data-package="vendor/name"
        data-version="^1.0">
    Установить
</button>

data-action-type: install, update, remove, install_all.

Кнопка dump-autoload: класс js-dump-autoload.

Из кода:

DevCraft.Composer.runAction('update', 'twig/twig', '^3.14', button);
DevCraft.Composer.runDumpAutoload(button);

Пока команда идёт, повторный вызов игнорируется. Успех обновляет таблицу #dc-composer-table. Текст ошибки Composer открывается в окне.

Сайт (`dc_public.js`)

Это не админка. Файл ставится в оболочку сайта через публичные скрипты. После загрузки есть DevCraftPublic и событие dc:public:ready.

Адрес запросов: body[data-dc-ajax-base], иначе мета dc-ajax-base, иначе dle_root + devcraft/ajax.php, иначе /devcraft/ajax.php.

DevCraftPublic.Ajax.post('notifications', 'mark_read', { id: 15 });

Запрос идёт с controller=public. Хеш берётся из dle_login_hash или из поля user_hash.

postMultipart(mod, method, formData) — то же для файла.

Уведомление: если на странице есть DLEPush, текст уходит туда. Иначе — короткое Metro-уведомление или строка в консоли.

Скрипты админки и сайта v200.4.2