# Intro
Das Plugin vereinfacht das Erstellen von individuellen CMS Elemente für die Shopware 6 Erlebniswelten. Das Plugin ist in erste Linie an Integratoren, Agenturen und Kunden mit HTML Kenntnissen gerichtet.
Ein CMS Element besteht immer aus zwei Dateien:
- Template Datei - für die Ausgabe im Frontend
- Konfigurationsdatei - zur Konfiguration der Felder des Elements
und werden in Plugin(s) im Verzeichnis
custom/plugins/**PLUGINNAME**/src/Resources/neti_cms_elements/**ELEMENTNAME**/
gespeichert und ausgelesen.
In Version 4.3.0 können optional Vorschaudateien für eine verbesserte Vorschau des Elements in der Administration hinzugefügt werden.
Achtung
Die Dateien für ein CMS Element sollten immer in einem eigenen Plugin oder in dem eigenen Custom Theme gespeichert werden. Damit wird vermieden, dass das CMS Element (bzw. deren Dateien) bei einem Plugin-Update verloren gehen.
Demoplugin
Hier (opens new window) findest du ein Demo Plugin mit verschiedenen vorgefertigten Inhaltselementen. Kann auch als Boilerplate für eigene Inhaltselemente verwendet werden.
# Element erstellen
Es gibt mehrere Wege ein neues CMS Element zu erstellen.
Tipp
Elemente, die über die Administration oder über die Konsole angelegt werden, haben zur demonstrationszwecken standardmäßig alle verfügbaren Konfigurationsmöglichkeiten und Felder definiert, welche im zugehörigen Template strukturiert ausgegeben werden. Nach dem Erstellen kann die Konfiguration und das Template angepasst werden.
# Administration
Die einfachste Methode ein Element zu erstellen ist über die Administration.
- Klicke dazu im Bereich "Inhalte > CMS Elemente". Hier findest du auch alle bereits erstellten Inhaltselemente.
- Klicke nun auf den Button "Hinzufügen". Es öffnet sich ein Modal.
- Vergib für dein Element einen aussagekräftigen Namen (kann später geändert werden) und das Plugin, in dem das Element abgelegt werden soll.
Achtung
Es werden aus Sicherheitsgründen nur Plugins angezeigt, die ein Requirement auf das CmsElementBuilder Plugin haben. Passe dazu in deinem Plugin oder Theme die Datei composer.json an und ergänze diese um:
"require": {
"netinventors/next-cms-element-builder": ">=4"
},
2
3
und
"extra": {
"netinventors": {
"NetiNextCmsElementBuilder": {
"config": {
"writeAccess": true
}
}
}
}
2
3
4
5
6
7
8
9
Fehlt die Konfiguration "writeAccess": true oder ist "false" können aus dem Plugin nur Elemente gelesen aber keine geschrieben werden.
Plugin erstellen
Falls du noch kein Plugin erstellt hast, gib in der Konsole:
bin/console plugin:create
ein und folge den Anweisungen. Passe danach die composer.json wie oben beschrieben an. Verwende Alternativ unser Boilerplate Plugin (opens new window)
Nach dem "Speichern", erscheint folgende Meldung mit dem Pfad in dem das neue CMS Element gespeichert wurde.
Klicke nun auf "Schließen", es wird die Administration neu geladen damit das neu erstellte CMS Element direkt verfügbar ist und in den Erlebniswelten genutzt werden kann. Öffne oder erstelle nun eine Erlebniswelt. In der Blockkategorie "CMS Element Builder" findest du das neue Element. Füge es ein und klicke auf das Zahnradsymbol um es zu öffnen. Hier siehst du nun alle Felder, die ein Inhaltselement beinhalten kann.
Um das Element deinen Bedürfnissen anzupassen, klicke hier.
# Konsole
Alternativ lässt sich ein CMS Element auch über die Konsole anlegen, wie folgt. Das Element wird nur dann registriert, wenn das ausgewählte Plugin installiert und aktiviert wurde.
# Element anlegen
bin/console neti:ceb:create <pluginName> <elementName>
# Anschließend muss das Element registriert werden
bin/console neti:ceb:sync:elements
2
3
4
5
Das neue Element ist nun in der Administration verfügbar und kann in einer beliebigen Erlebniswelt genutzt werden.
Um das Element deinen Bedürfnissen anzupassen, klicke hier.
# Plugin
Lade hier (opens new window) unser Demo Plugin herunter und passe es deinen Wünschen nach an. Hier kannst du ebenfalls eigene Elemente erstellen.
# Element bearbeiten
Die durch die Administration oder per Console erstellten Elemente enthalten standardmäßig alle verfügbaren Felder, wie Text, Textarea, etc. um dein Element deinen Bedürfnissen anzupassen, lade das Element aus dem Plugin.
Beispiel:
Hast du ein Element mit dem Namen "hallowelt" im Plugin "NetiNextCmsElementBuilderDemo" erstellt, findest du es im Verzeichnis: "custom/plugins/NetiNextCmsElementBuilderDemo/src/Resources/neti_cms_elements/hallowelt"
# config.json anpassen
In der Config passt du die Felder an, die in deinem neuen Element verwenden sollen. Hier findest du eine Übersicht der konfigurierbaren Felder. Lösche nicht benötigte Felder. Selbstverständlich kannst du mehrere Felder vom selben Typ (z.B. "text") verwenden.
Tipp:
Der Elementschlüssel, z.B. "dummyText" kann frei benannt werden. Der Elementschlüssel darf innerhalb der Datei nicht doppelt vorkommen. Der Elementschlüssel wird im Template verwendet.
# Beispiel falsch:
"config": {
"dummyText": {
"type": "text",
"label": {
"de-DE": "Text 1",
"en-GB": "Text 1"
},
"value": "Textfeld 1",
"helpText": {
"de-DE": "Hilfetext",
"en-GB": "Helptext"
}
},
"dummyText": {
"type": "text",
"label": {
"de-DE": "Text 2",
"en-GB": "Text 2"
},
"value": "Ich bin ein Textfeld",
"helpText": {
"de-DE": "Hilfetext",
"en-GB": "Helptext"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
(Der Elementschlüssel "dummyText" wurde zwei mal verwendet.)
# Beispiel richtig:
"config": {
"myTextField1": {
"type": "text",
"label": {
"de-DE": "Text 1",
"en-GB": "Text 1"
},
"value": "Textfeld 1",
"helpText": {
"de-DE": "Hilfetext",
"en-GB": "Helptext"
}
},
"myTextField2": {
"type": "text",
"label": {
"de-DE": "Text 2",
"en-GB": "Text 2 "
},
"value": "Ich bin ein Textfeld",
"helpText": {
"de-DE": "Hilfetext",
"en-GB": "Helptext"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# Template anpassen
Tipp
Hast du ein Element mit dem Namen z.B. "hallowelt" im Plugin "NetiNextCmsElementBuilderDemo" erstellt, findest du es im Verzeichnis: "custom/plugins/NetiNextCmsElementBuilderDemo/src/Resources/neti_cms_elements/hallowelt"
Öffne die Datei "template.html.twig" und passe diese deinen Wünschen entsprechen an. Hier findest du auch Beispiele, wie die Felder im Template ausgegeben werden können.
Styling
Das CSS Styling der Elemente kannst du in deinem Theme durchführen oder ebenfalls in deinem Plugin, was die Inhaltselemente enthält. In unserem Demoplugin findest du die Styles unter:
custom/plugins/NetiNextCmsElementBuilderDemo/src/Resources/app/storefront/src/scss/base.scss
# Anpassungen einspielen
Wurden alle Anpassungen durchgeführt lade die Dateien auf deinen Webserver.
Synchronisieren
Damit alle Änderungen sichtbar werden, ist es erforderlich, dass du im Modul "Inhalte > CMS Elemente" den Button "Synchronisieren" ausführst und ggf. den Cache löschst.
# Element Vorschau
In der Version 4.3.0 ist es nun möglich, Dateien in einer verbesserten Elementvorschau in der Administration zu platzieren.
Verbesserte Vorschau des Dummy-Elements
Wie im der folgenden Datei-Struktur zu erkennen, gibt es 3 neue Dateien.
Die Datei admin_preview.html wird für eine statische Vorschau verwendet, wenn das Element im "Element wechseln"-Modal ausgewählt wird
oder bei der Auswahl eines Blocks in der Blockkategorie "CMS Element Builder".
Die Datei admin_component.html wird für eine Vorschau verwendet, welche dynamische Inhalte enthalten kann.
Dynamische Werte können mit einem Platzhalter wie %dummyLink.target% eingefügt werden, wenn der
Konfigurationsschlüssel des Elements beispielsweise dummyLink genannt wurde.
Bei genauerer Betrachtung des Inhalts der Datei admin_preview.html ist zu sehen, dass die Bild-URL relativ zum
Speicherort der Datei angegeben wurde. Diese Referenz wird später automatisch aufgelöst und durch eine Base64-URL
ersetzt. Dies funktioniert natürlich nur, wenn das referenzierte Bild tatsächlich existiert.
<img src="img/preview.png" />
# Element löschen
Achtung
Elemente können nur auf Dateiebene gelöscht werden. Dies ist ein Sicherheitsfeature um zu verhindern, dass Elemente versehentlich aus der Liste gelöscht werden können.
Um ein Element zu löschen, sind folgende Schritte notwendig:
- Lösche den Ordner des Elements mit dem Template und der Konfigurationsdatei. Beispiel:
custom/plugins/DEINPLUGIN/src/Resources/neti_cms_elements/DEINELEMENT - Anschließend synchronisiere die Elemente im Modul
- In der Spalte aktiv sollte nun ein X stehen - das zeigt an, dass das Element nun gelöscht werden kann.
- Klicke auf die Optionen und wähle hier löschen. Das Element wird nun vollständig entfernt
Soft delete
Der Datenbankeintrag des Elements bleibt nach dem Löschen zur Sicherheit bestehen und wird aber als gelöscht markiert. Die Datenbanktabelle lautet: neti_ceb_element - im Notfall kann somit ein Element und dessen Konfiguration wieder hergestellt werden.
← Installation Felder →