Um Dateien in Brandbox hochzuladen, ohne den hochladenden Nutzern einen Zugang zu brandbox zu gestatten, ist es möglich Uploadformulare zu generieren, welche sich dynamisch erweitern lassen.
Erstellt man beispielsweise ein Uploadformular für Kategorien, so kann man über einen Link mit Verifizierungstoken auf dieses Formular zugreifen. Der Uploadprozess besteht aus drei Schritten:
- Upload der Dateien
- Befüllen der Felder pro Datei (sofern vorhanden) bzw. Hinzufügen oder Entfernen von Dateien
- Abschluss des Uploadvorgangs
Im Fall der Kategorie gibt es keine zusätzlichen Felder im zweiten Schritt. Das Verknüpfen der hochgeladenen Dateien zur vorausgewählten Kategorie findet im dritten Schritt codeseitig statt.
Um das Formular optisch und inhaltlich zu verändern werden Events angeboten. Auch die Verarbeitung der hochgeladenen Dateien ist über Events manipulierbar.
Es sollte eine öffentliche Rolle vorhanden sein, die es ermöglicht Dateien und Ordner anzulegen. Ist das nicht der Fall, wird der Uploadvorgang fehlschlagen.
Aufbau des Plugins
Die dynamischen Uploadformulare basieren auf der Entität dynamicUpload. Diese Entität enthält sowohl Informationen, die für den Upload zwingend benötigt werden, als auch Informationen, die die Basisfunktionalität ergänzen.
Benötigte Parameter sind:
- Name
- IDs der Verifizierungstoken
Optionale Parameter sind:
- Ablaufdatum des Formulars
- ID des Dateinamenformats
- ID der temporären Rolle
Integrationsspezifische Informationen sind in eigenen Entitäten zu speichern (siehe dynamicUploadCategory in "dam/category").
Die Events verfügen über Referenzen zur jeweiligen dynamicUpload-Entiät und zum entsprechenden verificationToken. Diese Werte werden in einem Kontext-Objekt gespeichert, das in jedem DynamicUpload-Event zur Verfügung steht, da diese Events von OnPopulateDynamicUploadAbstract ableiten.
Über diese Werte kann eine Integrationsstelle die jeweilige Entität finden (z.B. dynamicUploadCategory anhand von dynamicUploadID).
Konfiguration
Die Uploadformulare besitzen eine Konfigurationstabelle (landingPage). Das ist derzeit eine Panel-Tabelle. Das bedeutet, dass die Einstellungen für alle dynamischen Uploadformulare gelten.
| Property | Bezeichnung | Beschreibung |
|---|---|---|
| backgroundImage | Hintergrundbild | Zeichenkette. Enthält den relativen Pfad zum gewünschten Hintergrundbild. |
| logo | Logo | Zeichenkette. Enthält den relativen Pfad zum gewünschten Logo. |
Verwendung
Allgemeines
Alle Events im mehrstufigen Uploadprozess leiten von der Klasse Base\Upload\lib\event\OnPopulateDynamicUploadAbstract ab um stets einen geeigneten Kontext bereitzustellen.
Uploadprozess
Um ein dynamisches Uploadformular zu erstellen ist zunächst lediglich eine existierende dynamicUpload-Entität mit einem dazugehörigen Verifizierungstoken notwendig. Mit dem URL-Token des Verifizierungstoken muss nun die URL "yourhost.com/public?request=dam/upload.formUpload&vToken=urlToken" aufgerufen werden. Um sich dich Entitäten erzeugen zu lassen kann die öffentliche Methode dam\upload\engine::createDynamicUpload genutzt werden. Die benötigten Entitäten kann der Integrator auch selbst erzeugen (siehe dam/ui).
Der Upload Prozess besteht aus drei Schritten. Einstiegspunkte für diese Schritte sind öffentliche Methoden. Alle Schritte/öffentlichen Methoden erwarten die URL-Repräsentation eines Verifizierungstoken. Ist dieser nicht vorhanden, fehlerhaft oder abgelaufen, so wird eine generische Fehlermeldung ausgegeben.
Schritt 1 (Base/Upload.formUpload):
Einstiegspunkt für den Uploadprozess ist Base/Upload.formUpload. Hier wird das Formular initial platziert. In diesem Schritt lässt sich der Container über das Event OnPopulateEntrypoint erweitern. In diesem Event werden wiederum weitere Events ausgelöst:
- OnPopulateEntrypointHeadline
- OnPopulateEntrypointForm
- OnPopulateEntrypointButtons
Standardmäßig wird im Formular das Upload-Feld platziert. Das Upload-Feld lädt Dateien sequentiell hoch und fügt diese einem DynamicUploadProcess-Datensatz hinzu.
Schritt 2 (Base/Upload.dynamicUploadEditSelection):
Wurden die Dateien hochgeladen, wird Base/Upload.formUploadEdit aufgerufen. Hier wird das Event OnPopulateEdit aufgerufen, welches intern wiederum folgende Events auslöst, um die Inhalte für den Container zu erhalten:
- OnPopulateFileEntry
- OnPopulateButtons
Jede hochgeladene Datei ist eine Reihe im Formular. Einer Reihe können über das Event OnPopulateFileEntry weitere Felder hinzugefügt werden. Die hinzugefügten Felder folgen keinem Schema. Die Formulardaten werden an den nächsten Request weitergegeben und können dort von weiteren Listenern verarbeitet werden.
Im Container wird außerdem ein Button platziert, welcher den Upload von weiteren Dateien erlaubt.
Schritt 3 (Base/Upload.formDynamicUploadSubmit):
Einen Abschluss findet der Vorgang im Schritt Base/Upload.formUploadSubmit. Hier wird das Event OnPopulateResult ausgelöst. Standardmäßig werden die Dateien in einen Systemordner verschoben. Sollte der Pfad der Dateien geändert werden, ist auf die Prioritäten zu achten.