Конвертер BBCode в HTML

Описание

BBCode — текстовая разметка с тегами в квадратных скобках. Конвертер преобразует её в HTML для отображения в браузере. Например, [b]Важно[/b] превращается в <b>Важно</b>.

В ERP преобразование применяется там, где экран вызывает конвертер: например, при выводе описания обычного процесса, некоторых параметров и подсказок. Наличие BBCode в сохранённом тексте само по себе не гарантирует форматирование во всех редакторах и интерфейсах.

Реализация

Используется библиотека org.kefirsf:kefirbb:1.5. Состав поддерживаемых тегов определяется конфигурацией ERP, а не полным набором возможностей библиотеки.

Точка входа — метод ru.bgcrm.servlet.jsp.JSPFunction.bbEncode(String). Он передаёт строку процессору, созданному из ресурса bb.properties.xml.

В JSP функция зарегистрирована в библиотеке тегов http://bgrcrm.ru/jsp/taglib/util под именем bbEncode. При подключённом префиксе u вызов выглядит так:

${u:bbEncode(process.description)}

Из Java или Kotlin можно вызвать тот же метод:

String html = JSPFunction.bbEncode(sourceText);

bbEncode и htmlEncode имеют разное назначение. htmlEncode экранирует угловые скобки и обрабатывает переносы строк, но не преобразует BBCode. Не экранируйте готовый результат bbEncode повторно, если требуется отобразить форматирование: иначе браузер покажет HTML как текст.

Конфигурация

Актуальный файл находится в core/src/main/resources/bb.properties.xml. Это ресурс приложения в classpath; прежний путь src/resources/bb.properties.xml больше не соответствует структуре проекта.

Конфигурация содержит:

области обработки scope — наборы правил и их наследование;
правила code — входные pattern и выходной template;
ссылки coderef — подключение именованного правила к области;
переменные var — содержимое или атрибуты, обрабатываемые в заданной области.

Основная область — ROOT. Для содержимого кода, ссылок, таблиц и списков используются свои области, поэтому вложенные теги могут обрабатываться по-разному.

Процессор создаётся в статическом поле JSPFunction. Чтобы применить изменение XML, включите ресурс в сборку приложения и перезапустите ERP. Редактирование файла без перезагрузки приложения не является командой перечитать правила.

Поддерживаемая разметка

Большинство тегов распознаётся без учёта регистра, например [B]Текст[/B]. Используйте закрывающие теги и правильную вложенность: [b][i]Текст[/i][/b].

Выравнивание текста

BBCode Результат

BBCode	Результат
`[left]Текст[/left]`	Абзац с выравниванием слева.
`[center]Текст[/center]`	Абзац по центру.
`[right]Текст[/right]`	Абзац справа.
`[justify]Текст[/justify]`	Абзац с выравниванием по ширине.

[left]Текст[/left]

Абзац с выравниванием слева.

[center]Текст[/center]

Абзац по центру.

[right]Текст[/right]

Абзац справа.

[justify]Текст[/justify]

Абзац с выравниванием по ширине.

Эти правила создают HTML-элемент p с атрибутом align. Фактическое отображение зависит и от стилей экрана.

Оформление текста

BBCode Результат

BBCode	Результат
`[b]Текст[/b]`	Жирный текст (`b`).
`[i]Текст[/i]`	Курсив (`i`).
`[u]Текст[/u]`	Подчёркивание (`u`).
`[s]Текст[/s]`	Зачёркивание (`s`).
`[color=#336699]Текст[/color]`	Цвет через `span` и CSS-свойство `color`.
`[bg=green]Текст[/bg]`	Фон через CSS-свойство `background-color`.
`[size=14pt]Текст[/size]`	Размер через CSS-свойство `font-size`.
`[h1]Заголовок[/h1]` … `[h6]Заголовок[/h6]`	HTML-заголовки соответствующего уровня.

[b]Текст[/b]

Жирный текст (b).

[i]Текст[/i]

Курсив (i).

[u]Текст[/u]

Подчёркивание (u).

[s]Текст[/s]

Зачёркивание (s).

[color=#336699]Текст[/color]

Цвет через span и CSS-свойство color.

[bg=green]Текст[/bg]

Фон через CSS-свойство background-color.

[size=14pt]Текст[/size]

Размер через CSS-свойство font-size.

[h1]Заголовок[/h1] … [h6]Заголовок[/h6]

HTML-заголовки соответствующего уровня.

В color, bg и size передаётся значение CSS. Для размера указывайте единицу, например 14pt или 16px. В этих правилах нет отдельного списка разрешённых цветов или размеров.

Ссылки и изображения

[url=https://example.org/help]Открыть справку[/url]
[url]https://example.org/help[/url]
[url=/user/search]Поиск в ERP[/url]
[url=mailto:help@example.org]Написать письмо[/url]
[img]https://example.org/image.png[/img]

Для ссылок предусмотрены HTTP, HTTPS, mailto и локальные адреса. Адрес без схемы, например [url]example.org[/url], преобразуется в ссылку с http://.

Тег img создаёт изображение по указанному адресу. Он не загружает файл в ERP и не создаёт вложение. Адрес должен быть доступен браузеру пользователя; после переноса текста на другой сайт локальный адрес может указывать уже на другой ресурс.

Цитаты и блоки кода

[quote]Текст цитаты[/quote]
[code][b]Этот BBCode показан как текст[/b][/code]

quote создаёт blockquote и допускает вложенное оформление. code создаёт pre; обычные оформляющие BBCode-теги внутри него остаются текстом.

При этом область code использует базовые правила: перенос строки превращается в <br/>, экранирование и некоторые правила HTML продолжают работать. Поэтому code не следует считать режимом полного буквального сохранения любых HTML-тегов.

Списки

[list][*]Первый пункт[*][b]Второй пункт[/b][/list]

Результат — маркированный список ul с элементами li. Начало пункта обозначается []; закрывающий [/li] не требуется. Настроенное правило также распознаёт одиночную как начало пункта, поэтому внутри списка используйте её с учётом этого поведения.

Нумерованный вариант [list=1] в текущей конфигурации не задан.

Таблицы

[table][tr][th]Поле[/th][th]Значение[/th][/tr][tr][td]Статус[/td][td][b]Готово[/b][/td][/tr][/table]

Используйте table, строки tr, заголовочные ячейки th и обычные ячейки td. Текст вне строк таблицы и вне ячеек строки игнорируется соответствующими областями обработки. Внутри ячеек допускается BBCode.

Параметры ширины, рамок и объединения ячеек этими правилами не предусмотрены. Оформление полученного HTML задают стили страницы.

Спойлер

[details][summary]Подробности[/summary]Дополнительный текст[/details]

Конвертер создаёт HTML-элементы details и summary: заголовок раскрывает и сворачивает содержимое.

Само правило не проверяет readOnly и может преобразовывать текст любого поля, переданного в bbEncode. Однако поведение в интерфейсе зависит от контейнера. Например, в редактируемой таблице значение может быть обёрнуто в ссылку открытия редактора; нажатие тогда может открыть редактирование вместо ожидаемой работы спойлера. Проверьте результат именно на целевом экране. Для самостоятельного интерактивного блока предпочтителен вывод без оборачивающего обработчика редактирования.

Символы, кавычки и комментарии

BBCode Результат

BBCode	Результат
`[symbol=copy/]`	HTML-сущность `©` — знак авторского права.
`[symbol=nbsp/]`	HTML-сущность ` ` — неразрывный пробел.
`[aquote]Текст[/aquote]`	Кавычки-ёлочки через `«` и `»`.
`[* служебный комментарий *]`	Комментарий удаляется из результата.

[symbol=copy/]

[symbol=nbsp/]

HTML-сущность   — неразрывный пробел.

[aquote]Текст[/aquote]

Кавычки-ёлочки через « и ».

[* служебный комментарий *]

Комментарий удаляется из результата.

Комментарий — это часть исходного текста, а не скрытое хранилище: его не следует использовать для данных, которые нельзя показывать читателю исходного значения.

Экранирование

Перед квадратной скобкой поставьте обратную косую черту, чтобы показать её буквально:

\[b\]Текст\[/b\]

Результат — [b]Текст[/b] без жирного оформления. Две обратные косые черты превращаются в одну. При записи строки в Java, JSON или другой формат учитывайте также экранирование самого этого формата.

Обычные переносы строк преобразуются в <br/>. Неизвестные или незакрытые BBCode-теги могут остаться в тексте; конвертер не гарантирует исправление некорректной разметки.

HTML и ограничения преобразования

Базовые правила экранируют символы &, <, >, одинарные и двойные кавычки. Исключения предусмотрены для некоторых распознанных конструкций:

<b>Текст</b> сохраняется как жирный текст; посторонние атрибуты этого тега отбрасываются;
<br> и <br/> сохраняются как переносы;
неизвестный HTML, например <script>…</script>, выводится как экранированный текст.

Это набор правил форматирования, а не универсальный HTML-редактор или средство проверки произвольного HTML и CSS. Используйте документированные теги; для нестандартных конструкций проверьте фактический результат.

Изменение правил и проверка

При добавлении нового именованного code подключите его через coderef к нужной области, например ROOT. Одного определения правила вне области недостаточно для его применения к обычному тексту.

Проверьте не только простой пример, но и вложенные теги, переносы строк, атрибуты, неизвестную и незакрытую разметку. HTML-шаблоны в XML должны использовать XML-экранирование, например <b>.

Проверки существующего поведения находятся в core/src/test/java/ru/bgcrm/util/BBCodeXSSTest.java. Они проверяют жирный текст, переносы, экранирование и удаление атрибутов. После изменения правил выполните эти проверки и проверьте отображение на экранах, которые вызывают bbEncode.