Architecture

Package layers and extension points. Connector API: API. Save flows: Flows.

Components

Layer	Path	Role
Plugin	core/.../elements/plugins/mxeditorjs.plugin.php	MODX RTE hooks
Connector	assets/components/mxeditorjs/connector.php	Manager JSON API
Client	assets/components/mxeditorjs/js/mxeditorjs.js	Editor.js, MxEditorJsApp
PHP	core/components/mxeditorjs/src/	Renderer, Validator, Repository, MediaUploader, HtmlMigrator
Config	src/Config/EditorTools.php	Profiles and allowed tool list

No snippets or MODX processors in the package.

Two HTML builders

Path	When	Where
Client renderPreviewHtml()	Resource form save	mxeditorjs.ts
Server HtmlRenderer	content/save and content/migrate (not dry_run)	PHP

Duplicate logic for new blocks in both places. Otherwise manager preview and site HTML will diverge.

Database tables

Schema: core/components/mxeditorjs/model/schema/mxeditorjs.mysql.schema.xml

mxeditorjs_content

Field	Purpose
resource_id	UNIQUE, resource ID
content_json	Editor.js OutputData
content_version	Version counter
content_hash	SHA-256 of JSON
schema_version	Editor.js version from JSON
created_at, updated_at, created_by, updated_by	Audit

mxeditorjs_tv_content

Same fields + tmplvar_id, UNIQUE (resource_id, tmplvar_id).

HtmlRenderer

15 block types, including mxgallery. Alignment via tunes.alignmentTune.alignment for paragraph, header, list, quote.

Type	HTML
paragraph	<p>
header	<h1>–<h6>
list	<ul> / <ol>
checklist	<ul class="mxeditorjs-checklist">
image	<figure class="mxeditorjs-image"><img>
gallery	<figure class="mxeditorjs-gallery mxeditorjs-gallery--{fit|slider}">
mxgallery	mxGallery block (HTML depends on the mxGallery snippet)
attaches	<p><a download>
embed	<div class="mxeditorjs-embed"><iframe>
delimiter	<hr>
quote	<blockquote> + <cite>
code	<pre><code>
raw	raw HTML
table	<table>
warning	<div class="mxeditorjs-warning">

Extension:

$renderer->registerBlockRenderer('myBlock', function (array $data, array $block): string {
    return '<div>...</div>';
});

EditorTools

Class MxEditorJs\Config\EditorTools:

• DEFAULT_AVAILABLE: CSV of all block tools
• PACKAGE_PROFILES: reference default, minimal, blog, full
• resolve(): final list with the allowed-tool list and upgrade merge
• migrateProfiles() / migrateAvailableTools(): add gallery and mxgallery on upgrade
• parseList(): parse a CSV tool list

Priority: enabled_tools → profiles[profile].tools ∩ available_tools (+ upgrade merge) → available_tools.

ContentValidator

Allowed types: paragraph, header, list, checklist, quote, table, code, raw, embed, image, gallery, mxgallery, attaches, delimiter, warning.

Client (TypeScript)

Sources: assets/components/mxeditorjs/js/src/.

Module	Purpose
mxeditorjs.ts	MxEditorJsApp, RTE hooks, syncToTextarea, renderPreviewHtml
tools/ImageTool.ts	Image + Media Browser
tools/GalleryTool.ts	Gallery on @kiberpro/editorjs-gallery
tools/MxGalleryTool.ts	mxGallery block (ids / collection)
tools/AttachesTool.ts	Attaches + patch-package
tools/LinkAutocomplete.ts	MODX resource search
tools/MediaBrowser.ts	Shared browser for Image/Gallery
tools/ParagraphTool.ts, HeaderTool.ts, ChecklistTool.ts	Wrappers with validate

Block tools (profile): paragraph, header, list, checklist, quote, table, code, raw, embed, image, gallery, mxgallery, attaches, delimiter, warning.

Always on: inline marker, inlineCode, underline, linkAutocomplete. Tunes: alignmentTune. Plugin: editorjs-undo.

Embed

@editorjs/embed has no toolbox button: Paste API only. buildTools() defines services, including RuTube (embedUrl for rutube.ru/video/...). Add a service in mxeditorjs.ts, not via system settings.

RTE integration

• MODx.loadRTE / unloadRTE: main content and TVs
• MutationObserver: textarea.modx-richtext (except #ta)
• Toolbar: Source (Ctrl+U), Fullscreen (F11)
• Version in URL: ?v={filemtime} on CSS/JS

Client build

npm install    # postinstall → patch-package (@editorjs/attaches)
npm run build  # IIFE → assets/.../js/mxeditorjs.js
npm run dev    # watch + sourcemap

Entry: assets/.../src/mxeditorjs.ts. Target ES2020, format IIFE, global MxEditorJs.

Patch patches/@editorjs+attaches+1.3.2.patch replaces appendCallback with rendered. Otherwise the Attaches file dialog will not open.

Adding a new block tool

1. npm install @editorjs/new-tool
2. Import and register in buildTools() (mxeditorjs.ts)
3. Add type to ContentValidator::ALLOWED_BLOCK_TYPES
4. Render in HtmlRenderer and renderPreviewHtml()
5. Add ID to mxeditorjs.available_tools and profiles
6. npm run build, sync to installed MODX

Transport and upgrade

php _build/build.php
# → core/packages/mxeditorjs-*.transport.zip

On upgrade, transport settings are not overwritten (settings => false). Resolvers add gallery and mxgallery to available_tools and the default / full / blog profiles.

Resolver resolver_06_metrics.php sends anonymous install stats to https://metrics.modx.pro/.

Site styles

gallery-front.css loads only in the manager. Add CSS on the site yourself. See Integration.

Requirements

	Version
MODX	3.0.3+
PHP	8.2+
Node.js	18+ (client build only)