Search by

besnovatyj / yii2-cms-jodit

besnovatyj

Редактор Jodit для Yii2 (собранный dist + виджет) со встроенной интеграцией файлового менеджера besnovatyj/filemanager-core.

Package info

github.com/besnovatyj/yii2-cms-jodit

Language:TypeScript

Type:yii2-extension

pkg:composer/besnovatyj/yii2-cms-jodit

Statistics

Installs: 14

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.3.1 2026-11-15 13:06 UTC

This package is auto-updated.

Last update: 2026-11-15 13:09:08 UTC


README

Редактор Jodit для Yii2: собранный dist + виджет со встроенной интеграцией файлового менеджера @besnovatyj/filemanager-core. Возможности — нативное редактирование HTML-исходника, очистка вставки из Word/сайтов и плагинная архитектура (MIT, TypeScript).

Состав пакета

assets/jodit-widget.ts          # entry: Jodit + CSS + регистрация кнопки ФМ, экспорт createEditor()
assets/plugins/fileManager.ts   # интеграция @besnovatyj/filemanager-core v1 (кнопка fileManager)
assets/plugins/explorer.ts      # интеграция @besnovatyj/filemanager-core2 — проводник (кнопка explorer, scope-токен)
assets/plugins/snippets.ts      # интеграция @besnovatyj/snippets-core (кнопка, вставка HTML сниппета)
assets/plugins/shortcodes.ts    # пикер шорткодов (кнопка, вставка примера; своё окно, без npm-ядра)
esbuild.js                      # сборка одной entry; jodit и ядро ФМ бандлятся внутрь
tsconfig.json                   # strict TS (только проверка типов; сборка — esbuild)
src/JoditWidget.php             # Yii2 InputWidget
src/JoditAsset.php              # AssetBundle (публикует dist/jodit-widget.js + .css)
dist/                           # jodit-widget.js + jodit-widget.css (коммитятся после сборки)
composer.json                   # besnovatyj/yii2-cms-jodit (yii2-extension)
package.json                    # @besnovatyj/yii2-cms-jodit-build (сборка)

Сборка (Node / Docker)

Node/npm доступны только в контейнере. Из корня пакета:

npm install        # подтянет jodit ^4 и ядра ФМ/сниппетов из npm
npm run build      # → dist/jodit-widget.js + dist/jodit-widget.css
npm run type-check # (опционально) строгая проверка типов через tsc --noEmit

dist/ коммитится в git — composer потребляет его без пересборки (как у остальных собранных пакетов CMS).

Оба ядра (@besnovatyj/filemanager-core, @besnovatyj/snippets-core) тянутся из npm registry по версии из package.json. Никаких локальных подмен и сборок из соседних каталогов сборка не делает: что в зависимостях — то и в бандле.

Использование

use Besnovatyj\Jodit\JoditWidget;

<?= $form->field($model, 'content')->widget(JoditWidget::class, [
    'height' => 500,
    'fmDefaultPath' => '/static',
    // 'enableFileManager' => false, // выключить кнопку файлового менеджера
    // 'config' => [ ... ],          // любые прочие переопределения опций Jodit
]) ?>

Тулбар

По умолчанию во всех размерах показывается полный набор кнопок Jodit (все группы) плюс кнопка fileManager. Настройка — через первоклассные свойства виджета:

<?= $form->field($model, 'content')->widget(JoditWidget::class, [
    // Свой основной тулбар (имена кнопок, сепараторы '|' '---' "\n" или группы
    // ['group' => 'font-style', 'buttons' => []]):
    'buttons' => ['bold', 'italic', '|', 'ul', 'ol', '|', 'link', 'image', 'fileManager', 'source'],

    // Адаптив: Jodit меняет набор по ширине. buttonsMD/SM/XS = null → наследуют $buttons
    // (полный набор на любой ширине). Задайте, если для узких мест нужен усечённый список:
    // 'buttonsMD' => [...], 'buttonsSM' => [...], 'buttonsXS' => ['bold', 'italic', 'dots'],
    // 'toolbarAdaptive' => false,           // отключить адаптив (всегда только $buttons)
    // 'sizeLG' => 900, 'sizeMD' => 700, 'sizeSM' => 400, // брейкпоинты (px)

    // Точечно убрать кнопки из полного набора, не переписывая список:
    'removeButtons' => ['ai-commands', 'ai-assistant'],
]) ?>

Важно про адаптив. При toolbarAdaptive = true свойство buttons работает только на ширине ≥ sizeLG; на более узких Jodit берёт buttonsMD/SM/XS. Виджет по умолчанию наследует их из buttons, поэтому кастомный список виден на всех ширинах — задавайте их отдельно только если осознанно хотите разные тулбары.

Или без модели:

<?= JoditWidget::widget([
    'name' => 'content',
    'value' => $html,
]) ?>

Виджет публикует ассеты, рендерит <textarea> и инициализирует Jodit ES-модулем через createEditor('#id', config). Jodit синхронизирует контент обратно в <textarea>, поэтому ActiveForm получает значение без дополнительного кода.

Файловый менеджер

Кнопка fileManager (при enableFileManager = true) открывает @besnovatyj/filemanager-core. Выбранные файлы вставляются в контент: картинки — как <img>, остальное — как ссылка. Конфиг коннектора/заголовков/пути задаёт PHP-виджет (getFmApiUrl(), getHeaders(), fmDefaultPath). Логика — в assets/plugins/fileManager.ts.

Проводник (файловый менеджер v2)

Кнопка explorer (при enableExplorer = true, по умолчанию включена) открывает проводник @besnovatyj/filemanager-core2 в режиме выбора с множественным выделением: изображения вставляются как <img>, остальные файлы — ссылкой с именем файла. Файлы без публичного URL (хранилище без отдачи наружу) пропускаются с предупреждением в консоли. Работает параллельно с v1-кнопкой fileManager под отдельной иконкой, пока v1 не выведен.

Свойства виджета: explorerStartPath (по умолчанию = fmDefaultPath), explorerConnector (по умолчанию /File/backend/api), explorerTheme (null — системная, 'light'/'dark'), explorerScoped (по умолчанию true: проводник заперт в explorerStartPath — виджет выпускает подписанный токен области, сервер отклоняет пути вне неё; false — свободная навигация). Логика — в assets/plugins/explorer.ts. Ядро подключено file:-зависимостью на packages/npm/filemanager-core2 — после публикации в npm заменить на версию.

Шорткоды

Кнопка shortcodes (при enableShortcodes = true) открывает список шорткодов с поиском и фильтром по типу; клик по строке вставляет пример вставки в позицию курсора — текстовым узлом, а не через insertHTML, чтобы редактор не интерпретировал разметку шорткода.

Список приходит из модуля besnovatyj/yii2-cms-shortcode (/Shortcode/backend/api/list, переопределяется свойством shortcodesUrl) и кэшируется на время жизни страницы. Composer-зависимость от модуля необязательна, но при включённой интеграции endpoint должен отвечать: иначе редактор показывает ошибку с повтором и блокирует редактирование и штатную отправку формы. Если интеграция не нужна, enableShortcodes = false отключает обработку и вырезает кнопку из всех тулбаров.

В отличие от файлового менеджера и сниппетов, отдельного npm-ядра здесь нет: данные плоские, UI — один список, поэтому пикер целиком лежит в assets/plugins/shortcodes.ts.

Очистка вставки

Работает штатный конвейер Jodit (cleanHTML + paste/paste-from-word):

  • из Word — диалог «с форматированием / очистить / только текст» (askBeforePasteFromWord);
  • с сайтов — по умолчанию allowedStyles: false, то есть чужие инлайновые стили режутся;
  • запрещены script,iframe,object,embed, снимаются on*-обработчики, обезвреживается javascript:.

Тонкая настройка — через config (ключи cleanHTML, allowTags/denyTags, defaultActionOnPaste*).

Что осталось проверить/доработать (осознанно вынесено)

  1. Полный набор плагинов подключается явно: import 'jodit/esm/plugins/all.js' + jodit/es2021/jodit.fat.min.css. Главный вход jodit регистрирует лишь урезанный core (без source/resizer/fullsize/align/paste-from-word) — их кнопки рендерятся, но молча не работают. Чтобы уменьшить бандл, all.js можно заменить на курированный список нужных import 'jodit/esm/plugins/<name>/<name>.js'.
  2. API Jodit (Jodit.make, editor.selection.insertImage/insertHTML, форма контрола кнопки, имена встроенных иконок) выверен по докам; перед боевым использованием — один smoke-тест: собрать, открыть форму, проверить тулбар, вставку из ФМ и сохранение.
  3. Uploader (drag&drop / вставка картинок) — по умолчанию выключен (uploadUrl = ''), вставка идёт через файловый менеджер. Для прямой загрузки нужен коннектор, отвечающий в формате Jodit ({ success, data: { baseurl, files, ... } }) — отдельная серверная ручка, обязанная пройти UploadPolicy файлового модуля.
  4. CodeMirror как sourceEditor — Jodit поддерживает замену встроенного редактора исходника через sourceEditor; порт твоего CodeMirror-плагина — отдельная задача (точка расширения готова: передать реализацию в config).

Автоматические текстовые шорткоды

Плагин получает определения через API модуля шорткодов. Конкретные имена и разрешение обратной замены задаются серверным модулем; файловый менеджер продолжает передавать обычные публичные URL.

Для определения с reverse.mode = "url-prefix" реальные адреса в src, href, poster, srcset преобразуются в токен при получении HTML для исходника и textarea. WYSIWYG использует реальные адреса. Поддерживается список кандидатов srcset, включая неизменяемые data: URL. Путь, URL-кодирование, query и fragment не пересобираются. Выбирается наиболее длинный подходящий префикс с проверкой домена и границ пути.

Существующие токены сохраняются, в том числе при выключенном reverse: выключение запрещает создание нового токена, а не прямое превью уже введённого. Изменённая через диалог картинка не восстанавливается из устаревшей метки. Текст статьи, CSS и текстовые виджетные шорткоды автоматически не преобразуются. Прямая подстановка выполняется одним проходом.

Загрузка обязательна при включённой интеграции. До готовности редактор заблокирован; при ошибке показана панель с причиной и кнопкой повторной загрузки. Пока один из редакторов формы не готов, штатный submit отменяется. После восстановления пользователь отправляет форму повторно. Исходная textarea не отключается, первоначальный readonly сохраняется. Намеренный обход через form.submit() или произвольный AJAX не является защищаемым сценарием.

Одновременные запросы редакторов и пикера с одинаковыми URL и заголовками объединяются. Успешный ответ кэшируется до перезагрузки страницы; после изменения определений в админке обновите страницу редактора. Ошибочный запрос можно повторить. Старый ответ без reverse означает none; неизвестный режим или некорректная структура нового ответа вызывает явную ошибку.

При enableShortcodes = false механизм не включается. Автоматическое определение установки модуля пока не добавлено: включённая интеграция с недоступным API покажет ошибку. На сервере контент перед сохранением не меняется. Вывод шорткодов на frontend остаётся ответственностью темы.

Проверки

npm run type-check
npm run build
node tests/shortcodes.mjs

Браузерная проверка требует Playwright с установленным Chromium (playwright install chromium) и системными библиотеками. Playwright можно предоставить отдельной установкой через PLAYWRIGHT_MODULE=/absolute/path/to/playwright/index.mjs; зависимости production-бандла не меняются. Скрипт сам собирает тестовый бандл во временную папку и запускает локальный HTTP-сервер. Проверки используют настоящий Jodit, включая source/textarea, превью, undo/redo, ошибки API, повтор, несколько редакторов и блокировку формы. Данные рабочего приложения не используются.

Порядок поставки: новая миграция и серверная поддержка API, затем обновлённый dist. Сборка выполняется штатным ESBuild; коммиты, теги, push и применение миграции к рабочей БД выполняются отдельно.