README

vendor-logo the-real-world.de

description

Replaces the plain text areas of the OXID admin (article and category long descriptions, CMS pages and every other field the core renders through its TextEditorHandler) with a WYSIWYG editor based on Summernote-Lite — the Bootstrap-free build of Summernote, so the admin needs no Bootstrap.

Toolbar: paragraph styles, bold/italic/underline/strikethrough, super-/subscript, lists, tables (incl. header rows), links, horizontal rule, video, special characters, HTML templates, full screen, code view.
File browser for the media folder out/media_rte/: upload, create folders, rename, delete, download, search, preview thumbnails. Opens from the editor, or standalone from the admin menu Service > Media (RTE) (clicking a file then copies its URL).
Portable media URLs: pictures and files are stored as {{ trwMediaPath('folder/picture.jpg') }} instead of a hard-coded URL, so content survives a change of domain or shop sub-directory.
Retina pictures: with "with retina" in the file browser, pictures wider than the midi size are inserted in midi size, with the original offered for high-density screens (srcset). The sizes are generated on request by trwdynimg (optional, see below).
Sanitizing: script tags are removed server-side when content is loaded into the editor, and DOMPurify cleans the content on save and in code view. Twig expressions in the content are kept intact.
CMS pages whose ident (OXLOADID) contains plain keep a plain text area (can be switched off).


Composer package	`therealworld/rte-module`
Module id	`trwrte`
Requires	OXID eShop CE `>=v7.4`, PHP `^8.3`, `ext-fileinfo`, `therealworld/tools-plugin` `>=v3.6.2`
Optional	`therealworld/dynimg-module` `>=v1.2.0`: file browser thumbnails and midi sizes for retina pictures

Installation

composer require therealworld/rte-module
vendor/bin/oe-console trw:module:setup trwrte

trw:module:setup (from therealworld/clirun-plugin) installs and activates the module; alternatively use oe:module:install and oe:module:activate trwrte. The module has no database migrations.

On activation the module

creates the media folder out/media_rte/ if missing (must be writable by the web server),
creates the relative symlink out/pictures/master/rte -> ../../media_rte, through which the trwdynimg endpoint finds the source pictures,
registers its picture sizes with trwdynimg (generated under out/pictures/generated/rte/, recursive folders, excluded from the watermark) — only if trwdynimg is installed. If you install it later, activate trwrte again (or run trw:module:refresh trwrte) so the sizes get registered.

Existing content with hard-coded media URLs

Content written before the trwMediaPath convention contains URLs like /out/media_rte/folder/picture.jpg. docs/migration-trwmediapath.sql is a prepared search and replace for oxcontents, oxartextends and oxcategories. It is not run automatically: back up the database, set the URL prefix actually stored, adapt the backreference syntax (MySQL 8 vs. MariaDB) and the language columns, then run it manually.

Configuration

Extensions > Modules > the-real-world - Rich Text Editor > Settings

Styles

Option	Default	Effect
Local frontend CSS files	`css/styles.min.css`	Theme stylesheets loaded into the editor, so content looks like in the shop. One per line, relative to the theme's resource folder.
External frontend CSS files	empty	Further stylesheets by absolute URL (e.g. web fonts). One per line.

Files and Filetypes

Option	Default	Effect
Allowed file extensions	`txt`, `gif`, `jpg`, `jpeg`, `png`, `webp`, `pdf`, `zip`, `doc`, `docx`, `odt`, `xls`, `xlsx`	Extensions accepted on upload and rename (case-insensitive). Files without an extension are refused.
Hidden file extensions	empty	Files with these extensions are not listed in the file browser
Allowed file types	MIME types matching the extensions above	MIME types accepted on upload. The type is detected on the server from the file content (`ext-fileinfo`), not taken from the browser.

An upload needs both an allowed extension and an allowed type. File and folder names are reduced to a-z, 0-9, _ and -; dots in the name become _, so x.php.png is stored as x_php.png. Paths that leave the media folder (../, ./) are refused for every action.

If you configured the allowed types yourself, check that every allowed extension has its detected type in the list — e.g. application/vnd.oasis.opendocument.text for odt (missing in older defaults); depending on the server's libmagic, docx/xlsx may be detected as application/zip.

Rights

Option	Default	Effect
File Upload allowed?	on	Upload in the file browser
Create Folder allowed?	on	Create folders
Deleting files and folders allowed?	on	Delete files and (empty or recursively deletable) folders

The rights are enforced on the server as well: a request for a switched-off action is answered with 403, not just hidden in the file browser.

CMS Pages

Option	Default	Effect
dont use RTE-Editor for Plain-Content	on	CMS pages whose ident (`OXLOADID`) contains `plain` (e.g. the texts of the plain-text mails) get a simple text area instead of the editor. Switched off, they get the editor as well.
Server-side sanitizing (remove script tags)	on	Removes `<script>` tags from stored content when it is loaded into the editor
Editor sanitizing with DOMPurify	on	Cleans the content with DOMPurify on save and in code view
Store emojis as HTML entities	on	Converts characters from U+10000 upwards (emojis) into numeric entities on save. Needed as long as the columns are `utf8mb3`, where a 4-byte character truncates the text. Switch off only after converting to `utf8mb4`.

Images

Option	Default	Effect
Format of the file browser preview image	`80*60`	Thumbnail size (width*height) in the file browser
Size of the midi pictures	`900*2700`	Size (width*height) of the pictures inserted "with retina"; the width is what counts. Quality and WebP come from the shop settings. After a change run `trw:dynimg:prune` and `trw:dynimg:warmup`.
Only use the attributes of the image link	on	Image dialog shows only the link attributes, not those of the image itself
Only use the standard options for images	on	Image dialog offers only link target, title and alt text, not styles, classes, roles, rel

HTML templates

The editor's template button inserts predefined HTML snippets, optionally after a small form whose input replaces placeholders. Any module can contribute templates via assets/summernote_templates/templates.json; the module ships a hello-world example that is only shown as long as no other module has registered templates. The full description (file format, field types, registration) is in assets/summernote_templates/README.md.

Logging

Failed file browser actions are logged to log/trwrte/<date>.log.

Limits and caveats

Stored content contains {{ trwMediaPath(...) }} expressions. They resolve only where the shop renders the field through the template engine.
Without trwdynimg no thumbnails or midi sizes are generated; the file browser and pages then get the original picture.
New CMS pages get the editor; the plain text area appears once the page is saved with plain in its ident.
The media folder is delivered by the web server as it is. As defence in depth, make sure the server does not execute scripts in out/media_rte/.
The editor and file browser bundle (assets/src/) is prebuilt; rebuilding is only needed when changing the sources in resources/ (see resources/README.md).

For developers

Chain extensions

TextEditorHandler (core): renderRichTextEditor() delegates to the EditorRendererInterface service.
ContentMain (admin) + model Content: plain text area for plain CMS pages (isPlainContent(), depends on boolTRWRTENotForPlainContent).

Services

Service id	Purpose
`TheRealWorld\RteModule\Service\EditorRendererInterface`	Renders one editor instance; `render(..., $sProfile)` with `EditorConfigBuilder::PROFILE_FULL` or `PROFILE_MINIMAL` (text with links only, no images, drag & drop off) — usable from own admin forms
`TheRealWorld\RteModule\Service\EditorConfigBuilder`	Builds toolbar, style tags, template list, DOMPurify config as arrays; extend for own style tags (`getStyleTags()`)
`TheRealWorld\RteModule\HtmlFilter\HtmlFilterInterface`	Server-side script-tag filter

Twig functions

Function	Result
`trwMediaPath('folder/file.jpg')`	URL of a media file, host-relative incl. shop sub-directory; without argument the prefix
`trwMediaMidiPath('folder/file.jpg')`	URL of the midi size (the original if there is none)
`trwMediaRetinaSrcset('folder/file.jpg')`	`srcset` with midi and original (empty if there is no midi)

Editor template and JS

views/twig/admin/trwrte_editor.html.twig renders a <textarea data-trwrte> plus a JSON config block; the ES module bundle initialises all such text areas automatically.
Blocks for other modules: trwrte_styles, trwrte_summernote_options, trwrte_dompurify_config, trwrte_plugins.
JS overrides, shallow-merged per editor: window.trwrteOptionOverrides / window.trwrteDompurifyOverrides = { '*': {...}, 'editor_<field>': {...} }.
Admin headitem.html.twig (block admin_headitem_js) wraps the core's copyLongDesc(): on save it masks Twig, runs DOMPurify, converts media URLs to trwMediaPath(...) and unmasks Twig again.
TextEditorHandler::addLocale($lang, $locale) adds editor locales (de-DE, en-GB are built in).

File browser

Admin controller TextEditorFileBrowser (cl=texteditorfilebrowser, key lowercase like in menu.xml), protected by an XSRF cookie: write actions need the cookie and the same token in the request, a missing cookie is a failure. Besides the editor and standalone mode it has a picker mode (&sel=<field>&picker=1) for other admin forms that need to choose a single picture.

Assets

Sources in resources/ (Vite, SCSS, ES modules, jQuery bundled and exposed as window.jQuery), output in assets/src/.

therealworld / rte-module

Package info

Security

Statistics