Merkliste für MetaModels

Die Merkliste (Notelist) erweitert MetaModels um die Möglichkeit, in der FE-Ausgabe einzelne Datensätze (Items) einer Merkliste hinzuzufügen (add).

Einsatzmöglichkeiten für die Merkliste reichen von einer „normalen Merkliste“ über Vergleichslisten z.B. von Produkteigenschaften bis zu Warenkorbfunktionen.

Ist ein Datensatz in einer Merkliste gespeichert, kann der Datensatz natürlich auch aus der Merkliste wieder entfernt werden (remove).

Mit der Merkliste gibt es eine neue Filterregel, mit der eine MetaModels-Liste nach vorhandenen Merklist-Datensätzen gefiltert werden kann.

Für den Formulargenerator wurde ein neues Widget erstellt, mit dem die Datensätze der Merkliste aufgelistet und in der E-Mail mit übertragen werden - eine Versendung der E-Mail per Notification-Center ist auch möglich.

In jedem MetaModels können mehrere Merklisten angelegt werden. Damit ist es z.B. möglich, einen Datensatz bei zwei Merklisten einzutragen wie „Favoriten“ und „Bestellen“ oder man kann einen Datensatz von einer Merkliste wie „Vormerken“ zu einer weiteren Merkliste „Bestellen“ übertragen.

In der Konfiguration einer Merkliste kann ein Filter gesetzt werden, so dass nur noch bestimmte Datensätze in die Merkliste aufgenommen werden können - z.B. nur Mitarbeiter aus der Abteilung „Vertrieb“.

Die Merkliste arbeitet auch mit übersetzten MetaModels, so dass die Datensätze einer Merkliste auch beim Wechsel der Sprache erhalten bleiben.

Installation per Contao-Manager oder Composer

Voraussetzungen für die Installation:

Contao 5.3:

Bemerkung

Die Merkliste ist sofort einsatzbereit wird aber erst nach Erreichen der aktuellen Fundrasingsumme von 3.685€ frei geschaltet.
Für einen Zugang bitte eine E-Mail an info@e-spin.de

  • ^PHP 8.2

  • MetaModels 2.4

  • Notelist 2.4

  • optional Notification Center 2.3 oder NCPro

  • Zugang zum geschützten Repository - Daten nach Spende

Contao 4.13:

  • ^PHP 8.1

  • MetaModels 2.3

  • Notelist 2.3

  • optional Notification Center 1.7 oder 2.3

Merkliste anlegen

Nach der erfolgreichen Installation der Merkliste erscheint ein neues Icon in der Reihe der MetaModels-Icons, über welches man zum Anlegen und editieren der Merklisten gelangt.

img_notelist_icon

Legt man eine neue Merkliste an, so kann ein Name für die Merkliste vergeben werden. Als „Storage adapter“ stehen z.Z. die PHP-Session und die Contao-Session zur Verfügung. Bei der Contao-Session werden die Werte einer Merkliste bei eingeloggten Mitgliedern automatisch in den Sessionwerten der Datenbank gespeichert und stehen bei erneutem Login wieder zur Verfügung.

Über die Filterauswahl kann die Aufnahme auf Datensätze mit bestimmten Eigenschaften wie z.B. die „Abteilung“ oder Mitgliedergruppen eingeschränkt werden. Die Filterung auf Mitgliedergruppen ist z.B. über die Erweiterung „condition membergroup filter“ möglich.

img_nodelist_config

Über die Listenansicht erhält man Zugriff auf alle angelegten Merklisten.

img_notelist_overview

Merkliste in MetaModels-Liste aktivieren

Im CE MetaModels-Liste bzw. FE-Modul gibt es einen neuen Abschnitt „Notelist“, in dem eine oder mehrere der angelegten Merklisten aktiviert werden kann.

img_notelist_ce_mm-list

Die Reihenfolge der „Action-Ausgaben“ ist über die Sortierung der Merklisten per Drag&Drop veränderbar.

Wird für die Ausgabe das Standardtemplate verwendet müssen keine weiteren Änderungen vorgenommen werden und in der FE-Listenansicht sollten die Datensätze einen weiteren Link zum Hinzufügen zur Merkliste vorweisen.

Verwendet man ein eigenes Template, so ist für die neuen Links eine entsprechend Anpassung notwendig. Die Links sind im Knoten action enthalten und können z.B. mit dem folgenden Code ausgegeben werden (Ziffer entspricht der ID der Merkliste):

1<a href="<?= $arrItem['actions']['notelist_1']['href'] ?>" class="<?= $arrItem['actions']['notelist_1']['class'] ?>"><?= $arrItem['actions']['notelist_1']['label'] ?></a>

img_notelist_fe_list

Ausgabe der Merkliste per Filter

Die Ausgabe der Merkliste im FE erfolgt über eine normale MetaModels-Liste, die auf die Elemente der Merkliste gefiltert wird.

Für die Filterung muss ein Filter mit der neuen Filterregel „Notelist“ angelegt werden. In der Filterregel ist lediglich die Merkliste auszuwählen, dessen Elemente ausgegeben werden sollen.

img_notelist_filterrule

In der FE-Ausgabe der gefilterten Liste, sieht man nur noch die Mitarbeiter der Merkliste.

img_notelist_filtered_list

In der Listenausgabe wäre es z.B. möglich, eine weitere Merkliste zu aktivieren, um die Elemente von einer merkliste zu einer weiteren zu übernehmen - z.B. von „Vormerken“ zu „Bestellen“.

In den Einstellungen der Merkliste kann optional ein Filter für die Aufnahme zu einer Merkliste gesetzt werden. Sind z.B. nur Mitarbeiter erlaubt, die zum Vertrieb gehören, sieht die Liste wie folgt aus:

img_notelist_fe_list_with_filter

Datenanzeige und Übernahme im Formular

Im Formulargenerator steht ein neues Widget „MetaModels Merkliste“ zur Verfügung. Mit diesem Widget wird sowohl die Anzeige der Datensätze einer Merkliste im Formular als auch in der E-Mail gesteuert. Wurden für ein MetaModel mehrere Merklisten angelegt, so können auch mehrere ausgegeben werden.

Die Konfigurationsmöglichkeiten mussten in die möglichen Schnittstellen eines Contao-Widgets eingeschleust werden, so dass an mehreren Stellen Auswahlen getroffen werden müssen.

In dem Bereich „Template-Einstellungen“ gibt es jeweils für die Ausgabe im Formular (Formularfeld-Template) als auch in der E-Mail (E-Mail-Template) ein Template, welches als „Wrapper“ die Ausgabeliste umschließt. In den Templates werden in einer Schleife alle Merklisten mit Ausgabe des Namens und darin alle Datensätze ausgegeben (siehe Bereich „Feldkonfiguration“). Zu beachten ist, dass das Template für das Formular form_metamodels_notelist.html5 noch ein „altes“ Template ist - hingegen für die E-Mail schon ein Twig-Template email_metamodels_notelist.text.html.twig.

Im Bereich „Feldkonfiguration“ kann ausgewählt werden, welche Merkliste bzw. Merklisten ausgegeben werden sollen. Für die Listenausgabe im Formular als auch in der E-Mail müssen entsprechende Rendereinstellungen angelegt sein, welche die gewünschten Attribute ausgeben. Zusätzlich kann für jede Merkliste über die Checkbox „Liste leeren“ bestimmt werden, ob nach der Formularverarbeitung die Liste geleert werden soll.

img_nodelist_form_widget

Bei den Rendereinstellungen ist zu beachten, dass für die Ausgabe in einer Standard-E-Mail des Contao-Formulars nur das Textformat unterstützt wird - für Ausgaben als HTML-E-Mail sollte die Erweiterung Notification-Center eingesetzt werden. Als Vorlage für die Rendereinstellungen stehen mit der Erweiterung die Dateien metamodel_prerendered_notelists_form.html5 und metamodel_prerendered_notelists_form.text zur Verfügung.

Mit denTemplates werden auch automatisch die Daten mit ausgegeben, die zusätzlichen jedem Datensatz der Merkliste mitgegeben werden können (Payload). Das ist über ein „Mini“-Formular oder Event-Listener möglich.

In den Listentemplates ist neben den üblichen Knoten raw text auch notelists_names als Liste der Merklisten-Namen vorhanden.

Der Payload wird über die Knoten notelists_payload_values notelists_payload_labels übermittelt.

Folgend nochmal die Hierarchie der Templates:

Formularausgabe auf Webseite:

  • form_metamodels_notelist.html5 - Wrapper aus Formularwidget mit Ausgabe aller Merklisten inkl. Name

    • metamodel_prerendered.html5 - Listentemplate aus dem ausgewählten Rendersettings; alternativ das Template metamodel_prerendered_notelists_form.html5 auswählen für Ausgabe des Payloads

Ausgabe in der E-Mail:

  • email_metamodels_notelist.text.html.twig - Wrapper für E-Mail mit Ausgabe aller Merklisten inkl. Name

    • metamodel_prerendered.html5 - Listentemplate aus dem ausgewählten Rendersettings; alternativ das Template metamodel_prerendered_notelists_form.html5 auswählen für Ausgabe des Payloads

Bemerkung

Diese Option steht ab MM 2.4 mit Contao 5.3 zur Verfügung

Für die Ausgabe als HTML-E-Mail sollte die Erweiterung Notification-Center eingesetzt werden. Hier stehen eigene Simple-Tokens zur Verfügung, die mit „##mm::“ starten - es gibt

  • ##mm::notelist_name::<id-notelist>## - Ausgabe des NL-Titels für ID als Text

  • ##mm::notelist::<id-notelist>::<id-rendersetting>## - Ausgabe der NL-Items für ID mit Rendersetting-ID als Text

  • ##mm::notelist::<id-notelist>::<id-rendersetting>::html## - Ausgabe der NL-Items für ID mit Rendersetting-ID als HTML

Bei der Eingabe von „##mm“ werden die möglichen Tokens angezeigt.

Mit den Werten ist eine individuelle Gestaltung der Ausgabe im Formular-Widget als auch in der E-Mail möglich. Die vorhandenen Templates können wie üblich mit eigenen Varianten überschrieben werden.

Bemerkung

Eine Bearbeitung z. B. Löschen der Elemente der Merkliste ist im Formular nicht möglich, da bei einem Reload der Seite die schon im Formular eingegebene Daten verloren gehen würden.

Man kann vor der Ausgabe des Formulars eine Liste mit allen Elementen der Merkliste ausgeben und dort diese einzeln bearbeiten oder die gesamte Liste löschen - siehe Link.

1<p><a href="de/metamodels/note-list-contact-form.html?notelist_2_action=clear">Clear List 2</a></p>

img_nodelist_form_fe_list_edit_items

Die Daten werden per E-Mail übertragen und können über das E-Mail-Template in der Ausgabe angepasst werden. Für die Versendung stehen die Contao-Formularoption oder auch das „Notification Center (NC)“ zur Verfügung.

img_notelist_email_list

Bei Verwendung des NC kann auch die Textausgabe des E-Mail-Renderings in HTML über ein eigenes Simple-Token konvertiert werden z. B. die Zeilenumbrüche in <br>-Tags. Im NCpro ist es sehr einfach im Backend eigene Token zu definieren - die Twig-Filter nl2br und raw helfen bei der Ausgabe.

Übermittlung zusätzlicher Daten für jedes Item

Als Option können für jedes Item zusätzliche Daten an die Merkliste wie z.B. eine Anzahl, Freitext o.ä. übermittelt werden. Dafür erstellt man über den Formulargenerator ein Formular, welches die anzuzeigenden Felder beinhaltet z.B. Auswahlfeld für eine Anzahl und Textfeld für eine kurze Info - ein Absendefeld ist nicht notwendig und wird automatisch generiert.

Dieses angelegte Formular steht nun in den Einstellungen der Merkliste zur Verfügung - Formulare, die schon ein Merkliste-Formularelement beinhalten, werden nicht angezeigt (Rekursion!).

In der Listendarstellung wird bei jedem Item nun das Formular inkl. einem „Add/Edit-Button“ angezeigt. Die Daten werden vom Formular auch mit verarbeitet und z.B. per E-Mail mitgesendet (s. o.).

img_notelist_fe_list_with_form

InsertTags

Für die Ausgabe der Anzahl der Items in den Merklisten sind verschiedene InsertTags implementiert. Diese geben die Anzahl wie folgt aus (‚mm_mitarbeiterliste‘ ist das entsprechende MetaModels):

  • Anzahl aller Items: {{metamodels_notelist::sum::mm_mitarbeiterliste}}

  • Anzahl aller Items der Merkliste ID 1: {{metamodels_notelist::sum::mm_mitarbeiterliste::1}}

  • Anzahl aller Items der Merkliste ID 1 und 2: {{metamodels_notelist::sum::mm_mitarbeiterliste::1,2}}

Ist kein Item in der Merkliste, wird 0 (Null) ausgegeben.

Events

Soll die Manipulation einer Notelist (add, remove, clear) überwacht werden, steht dafür ein Eventlistener zur Verfügung.

Mit dem Eventlistener kann z.B. ein Rückmeldung an die Webseite erfolgen oder ein Logging/Tracking der Aktionen.

Als Beispiel für eine Rückmeldung kann ein Listener wie folgt erstellt werden (siehe auch Registrierung von Services):

 1<?php
 2// src/EventListener/ManipulateNoteListListener.php
 3namespace App\EventListener;
 4
 5use Contao\Message;
 6use MetaModels\NoteListBundle\Event\ManipulateNoteListEvent;
 7use Terminal42\ServiceAnnotationBundle\Annotation\ServiceTag;
 8
 9/**
10 * @ServiceTag("kernel.event_listener", event="metamodels.note-list.manipulate")
11 */
12class ManipulateNoteListListener
13{
14    public function __invoke(ManipulateNoteListEvent $event)
15    {
16        // Only handle note list "1".
17        if ('1' !== ($listId = $event->getNoteList()->getStorageKey())) {
18            return;
19        }
20
21        switch ($event->getOperation()) {
22            case ManipulateNoteListEvent::OPERATION_ADD:
23                Message::addConfirmation('Added ' . $event->getItem()->get('id') . ' to ' . $listId);
24                // Add your own notes in metaData.
25                $metaData = $event->getNoteList()->getMetaDataFor($event->getItem());
26                $metaData['tstamp'] = time();
27                $event->getNoteList()->updateMetaDataFor($event->getItem(), $metaData);
28                break;
29            case ManipulateNoteListEvent::OPERATION_REMOVE:
30                Message::addConfirmation('Removed ' . $event->getItem()->get('id') . ' to ' . $listId);
31                break;
32            case ManipulateNoteListEvent::OPERATION_CLEAR:
33                Message::addConfirmation('Cleared ' . $listId);
34                break;
35            default:
36                throw new \RuntimeException('Unknown note list operation: ' . $event->getOperation());
37        }
38    }
39}

Auf der Webseite kann in einem Template die Rückmeldung über die Ausgabe der Contao-Message erfolgen - z. B. mit folgenden Code in einem eigenen Template als ce_html_message.html5

1<?php
2$message = \Contao\Message::generateUnwrapped(null, true);
3?>
4<?php if ($message): ?>
5<div class="alert alert-primary" role="alert">
6    <p class="mb-0"><?= $message?></p>
7</div>
8<?php endif; ?>

Zudem können über diesen Event auch zusätzliche Informationen abgespeichert werden - siehe bei OPERATION_ADD.

Known Issues and Next Features

  • Seite(n) mit Merkliste/Notelist dürfen nicht gecached werden

  • in Contao ab 4.9 können die Templates mit den Extensions .text und .twig nicht mehr im Bereich Templates erzeugt werden, da Contao das nicht mehr unterstützt - die Dateien per SSH/SFTP oder Lokal anlegen

Spenden

Ein Dank für die Spenden* für die Erweiterung an:

Version 2.4:

Version 2.0 bis 2.3:

(*Spenden in Netto)