{"result":{"depiction_url":null,"edges":{"subject":{"objects":[{"created":"2026-10-13T15:23:53Z","object_id":{"id":2555,"is_a":["categorization","keyword","keyword_information_type"],"name":"zotonic_topic_reference","title":"Reference","uri":"https:\/\/zotonic.com\/id\/2555"},"seq":1},{"created":"2026-10-13T15:23:53Z","object_id":{"id":2561,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_content_editor","title":"Content editor","uri":"https:\/\/zotonic.com\/id\/2561"},"seq":2},{"created":"2026-10-13T15:23:53Z","object_id":{"id":2563,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_frontend_developer","title":"Frontend developer","uri":"https:\/\/zotonic.com\/id\/2563"},"seq":3},{"created":"2026-10-13T15:23:53Z","object_id":{"id":2570,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_content_authoring","title":"Content authoring","uri":"https:\/\/zotonic.com\/id\/2570"},"seq":4},{"created":"2026-10-13T15:23:53Z","object_id":{"id":2576,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_media_management","title":"Media management","uri":"https:\/\/zotonic.com\/id\/2576"},"seq":5},{"created":"2026-10-13T15:23:53Z","object_id":{"id":2635,"is_a":["categorization","keyword","keyword_architecture"],"name":"zotonic_topic_module","title":"Module","uri":"https:\/\/zotonic.com\/id\/2635"},"seq":6},{"created":"2026-10-13T15:23:53Z","object_id":{"id":2638,"is_a":["categorization","keyword","keyword_task"],"name":"zotonic_topic_edit","title":"Edit","uri":"https:\/\/zotonic.com\/id\/2638"},"seq":7},{"created":"2026-10-13T15:23:53Z","object_id":{"id":2672,"is_a":["categorization","keyword","keyword_technology"],"name":"zotonic_topic_html","title":"HTML","uri":"https:\/\/zotonic.com\/id\/2672"},"seq":8},{"created":"2026-10-13T15:23:53Z","object_id":{"id":2673,"is_a":["categorization","keyword","keyword_technology"],"name":"zotonic_topic_javascript","title":"JavaScript","uri":"https:\/\/zotonic.com\/id\/2673"},"seq":9}],"predicate":{"id":308,"is_a":["meta","predicate"],"name":"subject","title":{"_type":"trans","tr":{"en":"Keyword"}},"uri":"http:\/\/purl.org\/dc\/elements\/1.1\/subject"}}},"id":3088,"is_a":["text","documentation","reference","module"],"links":[{"rel":"self","target":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/3088"},{"rel":"hub","target":"https:\/\/zotonic.com\/.zotonic\/websub"}],"medium":null,"medium_url":null,"name":"doc_module_mod_editor_tiptap","page_url":{"en":"https:\/\/zotonic.com\/docs\/3088\/mod_editor_tiptap","x-default":"https:\/\/zotonic.com\/docs\/3088\/mod_editor_tiptap"},"preview_url":null,"resource":{"version":21,"pivot_location_lat":null,"title":"mod_editor_tiptap","is_authoritative":true,"body":"

Adds a rich-text editor based on Tiptap and ProseMirror to Zotonic forms.\nIt provides headings, emphasis, lists, links, Zotonic media, tables, undo\/redo,\nand full-window editing through a plain JavaScript interface.<\/p>\n

Setup<\/h2>\n

Enable mod_editor_tiptap<\/code> instead of mod_editor_tinymce<\/code> on the site's Modules\npage. It depends on mod_base<\/code> and mod_admin<\/code>, but does not require TinyMCE to be\nenabled or load any TinyMCE templates or JavaScript. Existing _editor.tpl<\/code>\nincludes select this editor when the module is enabled.<\/p>\n

{% include "_editor.tpl" id=id %}\n<textarea id="body" name="body" class="z_editor-init">{{ id.body|escape }}<\/textarea>\n<\/code><\/pre>\n
The page must include Zotonic's normal JavaScript and {% script %}<\/code> support.\nTextareas marked do_zeditor<\/code> can use the existing widget initialization instead.\nThe original textarea remains the form field; the editor synchronizes its value\nbefore a wired or native form submission.<\/p>\n
Editor lifecycle<\/h2>\n
Editors initialize near the viewport. Call z_editor.init()<\/code> after showing a\nlanguage tab or otherwise revealing fields; the standard admin already does so.\nVisited editors stay alive when tabs are hidden, preserving their undo history.\nNew textareas in AJAX fragments are discovered automatically, and editors whose\nelements are removed are destroyed.<\/p>\n
JavaScript API<\/th>Behavior<\/th><\/tr><\/thead>
z_editor.init()<\/code><\/td>Discover editor textareas throughout the document.<\/td><\/tr>
z_editor.add(root)<\/code><\/td>Discover editor textareas in the supplied element or container.<\/td><\/tr>
z_editor.save(root)<\/code><\/td>Write changed editor content to textareas in that scope.<\/td><\/tr>
z_editor.remove(root)<\/code><\/td>Save and destroy editors in that scope and cancel pending initialization.<\/td><\/tr>
z_editor_tiptap.get(textareaId)<\/code><\/td>Return the mounted Tiptap editor, or undefined<\/code> before initialization or after removal.<\/td><\/tr><\/tbody><\/table>\n
The root argument accepts a DOM element, selector, or jQuery collection. Omitting\nit selects the document. Before directly serializing a form, call\nz_editor.save(form)<\/code>. Explicit removal followed by addition starts a new undo\nhistory. Content edits emit the existing z:editorChange<\/code> form notification.\nFull-window editing preserves the instance; Escape returns to the normal view.<\/p>\n
Profiles and extensions<\/h2>\n
The three built-in profiles are simple<\/code> (basic text and links), normal<\/code>\n(formatting, lists, media and full-window editing), and advanced<\/code> (all controls,\nincluding tables, alignment and text direction). Admin pages select advanced<\/code>\non the body element.<\/p>\n
Select a profile with data-editor-profile<\/code> on the textarea or any ancestor.\nThe nearest attribute wins; missing, empty or unknown names use normal<\/code>.\nField names and the old data-zeditor.config<\/code> no longer select profiles.<\/p>\n
<section data-editor-profile="normal">\n    <textarea name="body$en" class="z_editor-init"><\/textarea>\n    <textarea name="summary$en" class="z_editor-init" data-editor-profile="simple"><\/textarea>\n<\/section>\n<\/code><\/pre>\n
Profiles are defined in _editor_tiptap_profiles.tpl<\/code>, loaded before the editor\nbundle. Override that template in your site using its simple<\/code>, normal<\/code>, and\nadvanced<\/code> blocks. Each block contains JavaScript object properties:<\/p>\n
{% overrules %}\n{% block simple %}\ntoolbar: ['bold', 'italic', 'link', 'unlink']\n{% endblock %}\n<\/code><\/pre>\n
A profile can also define extensions, paste handlers and custom buttons in the\nsame block. The optional window.z_editor_tiptap_config.default<\/code> supplies shared\noptions; the selected profile is shallow-merged over it. Arrays are replaced,\nnot concatenated. Profiles are read at editor creation; changing attributes or\ndefinitions does not rebuild mounted editors. There are no m.config<\/code> settings.\nThe admin editor_profile<\/code> template block can override the body-level default.<\/p>\n
Profile option<\/th>Purpose<\/th><\/tr><\/thead>
toolbar<\/code><\/td>Ordered array of control names; `<\/td><\/tr>
extensions<\/code><\/td>Additional Tiptap extensions, or a function receiving { Editor, Extension, Node, Mark }<\/code> and returning an array.<\/td><\/tr>
buttons<\/code><\/td>Custom controls keyed by toolbar name, each with label<\/code>, optional Lucide icon<\/code> data, and run(editor)<\/code>.<\/td><\/tr>
transformPastedHTML(html)<\/code><\/td>Replace the default paste normalizer.<\/td><\/tr>
onCreate(editor, textarea)<\/code><\/td>Run additional integration after mounting.<\/td><\/tr><\/tbody><\/table>\n
Toolbar controls include undo<\/code>, redo<\/code>, format<\/code>, bold<\/code>, italic<\/code>, underline<\/code>,\nstrike<\/code>, subscript<\/code>, superscript<\/code>, bulletList<\/code>, orderedList<\/code>, indent<\/code>,\noutdent<\/code>, blockquote<\/code>, codeBlock<\/code>, alignLeft<\/code>, alignCenter<\/code>, alignRight<\/code>,\nltr<\/code>, rtl<\/code>, horizontalRule<\/code>, hardBreak<\/code>, link<\/code>, unlink<\/code>, zlink<\/code>, zmedia<\/code>,\ntable<\/code>, removeFormat<\/code>, and fullscreen<\/code>.<\/p>\n
A smaller toolbar does not remove content types from the document schema, so\nreduced frontend forms can preserve content created in the full admin editor.\nThe extension constructors are also exposed on z_editor_tiptap<\/code>. Build custom\nextensions against the bundled Tiptap\/ProseMirror versions.<\/p>\n
Asides and Markdown admonitions are supported in every profile. Add aside<\/code> and\nnote<\/code> to a profile's toolbar to expose the wrap\/unwrap controls. Notes are emitted\nas <div class="admonition note" role="note"><\/code> with an editable, translated title\nparagraph (first admonition-title<\/code>). Existing aside-based admonitions retain their\ntag and classes. Both containers support regular block content, including media,\nlists and code. Their generic body styling can be overridden by site CSS.<\/p>\n
Template options<\/h2>\n
_editor.tpl<\/code> accepts these integration options:<\/p>\n
Option<\/th>Purpose<\/th><\/tr><\/thead>
id<\/code><\/td>Resource used as the subject of link\/media selection dialogs.<\/td><\/tr>
tiptap_overrides_tpl<\/code><\/td>JavaScript configuration include; defaults to _editor_tiptap_overrides_js.tpl<\/code>.<\/td><\/tr>
is_editor_include<\/code><\/td>Load assets and configure the editor without calling z_editor_init()<\/code> in this include.<\/td><\/tr>
zmedia_tabs_enabled<\/code>, zmedia_tabs_disabled<\/code><\/td>Media chooser tab lists; the disabled list defaults to ["new"]<\/code>.<\/td><\/tr>
zlink_tabs_enabled<\/code>, zlink_tabs_disabled<\/code><\/td>Internal-link chooser tab lists.<\/td><\/tr><\/tbody><\/table>\n
The compatibility templates _admin_tinymce.tpl<\/code> and\n_admin_frontend_tinymce_init.tpl<\/code> integrate older callers and frontend admin\nwithout loading TinyMCE. TinyMCE's tinyInit<\/code>, overrides_tpl<\/code>, and plugin settings\nare not interpreted; migrate them to Tiptap profiles and extensions.<\/p>\n
Styles and media<\/h2>\n
Generic document typography is defined in priv\/lib\/css\/editor-tiptap-body.css<\/code>.\nOverride that asset in the site, or add styles through _editor_tiptap_head.tpl<\/code>,\nwhich loads after the defaults. Scope content styles under .z-tiptap-body<\/code>.\nEditor controls and structural styles are in css\/editor-tiptap.css<\/code>. The content\nis ordinary page DOM, not an iframe, so site CSS can also affect it.<\/p>\n
The link\/media selection dialogs come from mod_admin<\/code>; their callbacks are\nz_editor_tiptap.linkDone<\/code> and z_editor_tiptap.mediaDone<\/code>. Select a media item and\nuse the media button, or double-click it, to open its properties. The module owns\n_editor_tiptap_media_props.tpl<\/code> and _editor_tiptap_media_preview.tpl<\/code>; the latter\nuses the shared admin_media_preview<\/code> dispatch. The properties template exposes\nblocks for caption help, alignment, size, crop, class, link, and the edit button.\nName a site-specific class control class<\/code>.<\/p>\n
Media nodes serialize back to Zotonic z-media<\/code> HTML comments, including their\nsite-specific options. Render saved bodies through the existing show_media<\/code>\nfilter. Dialog selections are mapped through intervening editor transactions;\ncallbacks for removed editors are ignored.<\/p>\n
Permissions and events<\/h2>\n
The media_props<\/code> postback_notify<\/code>, delegated to mod_editor_tiptap<\/code>, accepts\nid<\/code>, JSON-encoded options<\/code>, and request_id<\/code> for the originating dialog.\nIt requires an authenticated user and a visible resource. Invalid or inaccessible\nresources produce an error notification. Malformed option JSON becomes an empty\noptions map; only the known string\/boolean properties are passed to the template.\nThe handler opens a dialog and does not update a resource.<\/p>\n
The editor does not grant permission to save content. Resource updates must use\nthe normal ACL-checked and HTML-sanitizing Zotonic save paths. Browser-side URL\nchecks and read-only controls are not server-side authorization.<\/p>\n
Content compatibility<\/h2>\n
Untouched textareas are not rewritten. After editing, content is serialized using\nthe supported schema. Standard text formatting, images, links, lists, and tables\nare supported; arbitrary HTML, scripts\/iframes, and every TinyMCE style or element\nare not. Test representative existing bodies before migrating a site.<\/p>\n
Paste cleanup removes Office typography and reconstructs basic mso-list<\/code>\nparagraphs. It is not the commercial Tiptap Office paste handler: complex list\nnumbering, embedded images, footnotes, and exact Word layout are not guaranteed.\nCooperative editing with Yjs\/Cotonic is not included.<\/p>\n
Building<\/h2>\n
Browser assets and third-party license notices ship in priv\/lib<\/code>. No runtime\nCDN or Node.js service is required. SCSS sources live in priv\/lib-src\/scss\/<\/code>;\nthe JavaScript package and tests live in priv\/lib-src\/tiptap\/<\/code>.<\/p>\n
The default build (or make css<\/code>) compiles only CSS using Dart Sass (sass<\/code> on\nPATH, overridable with SASS<\/code>). It never runs the JavaScript Makefile or npm.\nUse the explicit js<\/code> target to rebuild the browser bundle:<\/p>\n
make -C apps\/zotonic_mod_editor_tiptap\nmake -C apps\/zotonic_mod_editor_tiptap js\nmake -C apps\/zotonic_mod_editor_tiptap test\n.\/rebar3 compile\n<\/code><\/pre>\n
Node.js\/npm are development dependencies. Package versions are pinned in\npriv\/lib-src\/tiptap\/package-lock.json<\/code>; the JS build emits the JavaScript bundle and its\nthird-party license notices. Zotonic integration code is Apache-2.0 licensed.<\/p>","slug":"mod_editor_tiptap","doc_module_config":[],"is_protected":false,"visible_for":0,"tz":"UTC","language":["en"],"doc_source_hash":"f4d0001f3a89996c11c413825d760dd8664127975696e7eb2cd845fd67dcebb8","is_featured":false,"content_group_id":{"id":2551,"is_a":["meta","content_group"],"name":"content_group_imported_docs","title":"Imported documentation","uri":"https:\/\/zotonic.com\/id\/content_group_imported_docs"},"category_id":{"id":320,"is_a":["meta","category"],"name":"module","title":"Modules","uri":"https:\/\/test.zotonic.com\/id\/320"},"doc_source_path":"apps\/zotonic_mod_editor_tiptap\/src\/mod_editor_tiptap.erl","publication_start":"2026-10-13T15:23:53Z","github_url":"https:\/\/github.com\/zotonic\/zotonic\/blob\/master\/apps\/zotonic_mod_editor_tiptap\/src\/mod_editor_tiptap.erl","pivot_location_lng":null,"doc_source_kind":"module","name":"doc_module_mod_editor_tiptap","is_unfindable":false,"is_published":true,"pivot_geocode":null,"created":"2026-10-13T15:23:53Z","uri":null,"doc_status":"current","is_dependent":false,"erlang_app":"zotonic_mod_editor_tiptap","publication_end":"9999-06-01T00:00:00Z","modifier_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"privacy":0,"doc_source_commit":"92d27433689eef55504265c6dd5486c65dd73483\n","creator_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"modified":"2026-10-13T15:40:14Z","title_slug":"mod_editor_tiptap"},"uri":"https:\/\/zotonic.com\/id\/3088","uri_template":"https:\/\/zotonic.com\/id\/:id","websub":{"hub":"https:\/\/zotonic.com\/.zotonic\/websub","topic":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/3088"}},"status":"ok"}