Editor iWE3 (Tiptap)

Überblick¶

Der Imperia Web Editor 3 (IWE3) ist der Rich-Text-Editor in imperia CMS. Er basiert auf Tiptap, einer modernen Open-Source-Bibliothek für Textbearbeitung, und löst den bisherigen iWE2 (CKEditor-basiert) ab.

Was bedeutet das für Admins?

IWE3 ist schlanker und modular aufgebaut: Funktionen sind in sogenannten Bundles zusammengefasst.
Wählen Sie einfach ein Bundle (minimal, fallback, full) oder definieren Ihr eigenes.
Der Editor arbeitet immer eingebettet im Editmode. Inhalte werden als HTML im angegebenen Metafeld gespeichert und im Template per  ausgegeben.

Schnellstart¶

Eine minimale Editor-Instanz wird im Template mit einer Processing Instruction (PI) eingefügt:

<?imperia iwe3
    id: body
?>

id bestimmt das Metafeld, in das der Editor schreibt.
Ausgabe im Template:

<!--XX-body-->

Dynamische IDs¶

In flexiblen Modulen oder mehrsprachigen Templates muss die ID eindeutig sein. Kombinieren Sie dazu die Flex- oder Sprachvariablen:

<?imperia iwe3
    id: text_<!--XX-FLEX_INDEX-->_<!--XX-FLEX_ID-->
?>

Konfiguration & Bundles¶

Konfigurationshierarchie¶

Die Einstellungen des Editors ergeben sich aus einer festen Reihenfolge:

Default-Konfiguration (TIPTAP_CONFIG) Breite = 100 %, Höhe = 600 px, Rechtschreibprüfung = aus, Bundle = full.
CustomConfig (optional) Eine eigene JS-Datei unter htdocs/..., die ein CUSTOM_CONFIG Objekt exportiert.
PI-Parameter config.* Werte, die direkt in der Processing Instruction gesetzt werden, überschreiben alles andere.

Parameter-Referenz¶

Parameter	Typ / Werte	Default	Beispiel	Wirkung
`id` (Pflicht)	String	–	`body`, `text_de_01`	Name des Metafelds, Teil der DOM-ID
`content`	String/HTML (eine Zeile)	–	`<p>Hallo</p>`	Initialinhalt, wenn Metafeld leer
`customConfig`	Pfad (JS-Datei)	–	`/custom/iwe3_config.js`	Lädt `CUSTOM_CONFIG` aus eigener Datei
`config.width`	CSS-Länge	`100%`	`800px`, `80vw`	Breite des Editors
`config.height`	CSS-Länge	`600px`	`400px`, `70vh`	Höhe des Editors
`config.resizable`	Boolean (`true/false`)	`true`	`false`	Ob Editorgröße per Drag geändert werden kann
`config.spellcheck`	Boolean	`false`	`true`	Aktiviert native Rechtschreibprüfung
`config.sourceModeType`	String (enum)	`html`	`html`	Art der Quellansicht
`config.canInspect`	Boolean	`true`	`false`	Steuert, ob Inspektionshilfen sichtbar sind
`config.bundle`	String	`full`	`minimal`, `fallback`	Wählt Funktionspaket (Bundle)
`config.class`	String (CSS-Klassen)	–	`editor-teaser`	Zusätzliche Klassen am Editor-Wrapper
`config.bubbleMenu`	Boolean	`true`	`false`	Blendet kontextabhängige Mini-Toolbar ein
`config.placeholder`	String	-	`Beginnen Sie hier zu tippen...`	Legt den Platzhaltertext fest, der angezeigt wird, solange der Editor leer ist

Bundles¶

IWE3 liefert drei Bundles mit, die unterschiedliche Funktionsumfänge bereitstellen:

Bundle	Enthaltene Funktionen (Auswahl)
minimal	Bold, Italic, Listen, Links, Format (Absätze & Überschriften), Styles, Undo/Redo, Plain-Paste
fallback	Bold, Italic, Unterstreichen, Durchstreichen, Sub-/Superscript, Listen, Indent, Blockquote, Textausrichtung, Links, Bilder, Tabellen, Quellcode, Undo/Redo
full	Alles aus `fallback` plus Schriftarten, Schriftgrößen, Suchen/Ersetzen, ClearAll, Spellcheck, Druckfunktion, erweiterte Tabellenfunktionen

Eigene Konfigurationen¶

Admins können eigene Bundles definieren, indem sie eine customConfig.js anlegen. Die Datei muss ein CUSTOM_CONFIG Objekt exportieren.

Beispiel (Minimal-Bundle mit Bold & Italic):

import { FEATURE_BUNDLES, MENUBAR_DEFINITIONS } from '/imperia/js/i-tiptap/config.js';

FEATURE_BUNDLES.ImperiaMinimal = {
  menubar: [MENUBAR_DEFINITIONS.Bold, MENUBAR_DEFINITIONS.Italic],
  extensions: { StarterKit: {} },
};

export const CUSTOM_CONFIG = {
  width: '100%',
  height: '400px',
  resizable: false,
  bundle: 'ImperiaMinimal',
  bundles: FEATURE_BUNDLES,
};

Im Template wird diese Config so eingebunden:

<?imperia iwe3
    id: teaser
    customConfig: /custom/iwe3_config.js
?>

Styling & Darstellung¶

DOM-Struktur im Editmode¶

IWE3 rendert im Editmode einen umschließenden Wrapper mit eindeutiger ID und CSS-Klassen. Das Grundgerüst sieht so aus:

<div id="iwe3_<PI.id>" class="imperiaTipTap" data-source="<PI.id>">
  <div class="i-tiptap-wrapper <config.class>" 
       style="width:<config.width>; height:<config.height>;">
    <div class="i-tiptap-header"></div>
    <div class="i-tiptap-content"></div>
    <div class="i-tiptap-footer"></div>
  </div>
</div>

Wichtige Elemente¶

#iwe3_<id> → eindeutige Container-ID (abhängig von PI-Parameter id)
.imperiaTipTap → Standardklasse für alle Instanzen
.i-tiptap-wrapper → umschließender Block, bekommt Breite/Höhe aus Config
<config.class> → zusätzliche Admin-definierte Klasse (z. B. editor-teaser)
.i-tiptap-header / -content / -footer → Unterbereiche für Toolbar, Editierfeld, Footer

Größe des Editors¶

Breite wird über config.width gesteuert (z. B. 800px, 100%, 70vw).
Höhe wird über config.height gesetzt (z. B. 400px, 600px).
Resizable (true/false): erlaubt es Redakteuren, die Editorgröße per Drag zu ändern.

Wenn keine Werte angegeben sind, gilt: 100 % Breite, 600 px Höhe, resizable = true.

Eigene Klassen verwenden¶

Über den Parameter config.class können Admins zusätzliche CSS-Klassen an den Wrapper hängen, um unterschiedliche Editoren konsistent zu stylen.

Beispiel:

<?imperia iwe3
    id: teaser
    config.width: 100%
    config.height: 300px
    config.class: teaser-editor
?>

/* styles.css */
.teaser-editor .i-tiptap-content {
  background: #f8f8f8;
  font-size: 14px;
}

So können Teaser-Editoren abweichend vom Standardlayout gestaltet werden.

Responsive Verhalten¶

Standardmäßig passt sich der Editor horizontal an (Breite = 100 %).
Mit config.width auf relative Werte (vw, %) können Admins das Verhalten explizit steuern.
config.height kann ebenfalls prozentual gesetzt werden (70vh), um sich an die Viewport-Höhe anzupassen.

Migration von IWE2¶

IWE3 ist der Nachfolger des CKEditor-basierten iWE2. Viele frühere Konfigurationsoptionen wurden vereinfacht oder durch Bundles ersetzt. Diese Tabelle hilft beim Umstieg von alten Templates auf IWE3.

Vergleichstabelle¶

IWE2	IWE3	Ersatz / Hinweis
`width`, `height`	weiterhin vorhanden	als `config.width`, `config.height` (mit CSS-Einheiten wie `px`, `%`, `vh/vw`)
`external`, `externalStyle`, `windowWidth`, `windowHeight`	entfällt	IWE3 ist immer eingebettet; Größe & Style über `config.width/height` und `config.class`
`id`	weiterhin vorhanden	unverändert, muss eindeutig sein
`content`	weiterhin vorhanden	Initialinhalt (eine Zeile)
`customConfig`	weiterhin vorhanden	verweist jetzt auf ein JS-Modul mit `CUSTOM_CONFIG` statt auf CKEditor-config.js
`externalURI`	entfällt
`bodyId`, `bodyClass`	entfällt	ersetzt durch `config.class` und DOM-Struktur
`docType`, `baseHref`	entfällt	keine Editor-interne Steuerung mehr, im HTML-Output des Projekts definieren
`MAMAdditionalParams`, `MAMAdditionalLinkParams`, `MAMCaption`	entfällt	Bild- und Link-Handling über `MAMImage` / `MAMLink`
Quellcode-Ansicht (`Source`)	weiterhin vorhanden	als Toolbar-Icon im Bundle

Sicherheit¶

IWE3 speichert Inhalte als HTML im angegebenen Metafeld. Admins können durch die Wahl von Bundles und Konfigurationen beeinflussen, welche Funktionen Redakteur\:innen nutzen dürfen und welche Risiken vermieden werden sollten.

Link-Protokolle¶

Die in IWE3 enthaltenen Links erlaubt standardmäßig nur bestimmte, sichere Protokolle:

http
https
mailto

Damit wird verhindert, dass unsichere oder exotische Protokolle (z. B. javascript:) eingefügt werden.

HTML-Inhalte¶

Welche HTML-Elemente verfügbar sind, hängt direkt von den aktiven Extensions und Bundles ab (z. B. Tabellen nur im full-Bundle).

Bilder und Medien¶

Bilder werden über die MAMImage-Extension eingefügt.
Assets stammen aus dem Media Asset Management (MAM) und sind dadurch konsistent verwaltet.