Bildergalerie
- Paul Maul
- Dirk Münker
- Sebastian Schulz
Konfiguration
Bereich | Beschreibung |
|---|---|
Konfigurations-Schlüssel | Eine Zeichenkette, die über die HTTP-Parameter an den Server übertragen wird, damit die entsprechende Galerie genutzt werden kann. |
Zeige Dateien die keine Bilder sind | Dateien die keine Bilder sind, werden bei einer aktivierter Checkbox auch eingeblendet. |
Primärer Ordner | Ein wählbarer Ordner. |
Sekundärer Ordner | Ein Ordner, der in der Gallerie zusätzlich zur Auswahl steht. |
Manuelle Ordner-Angabe | Eine Pfadangabe zu einem Ordner. Hier können Wildcards benutzt werden. |
Zeige meine Dateien | Ist diese Checkbox aktiviert, ist es dem Nutzer möglich, auf die Dateien zuzugreifen, die von Ihnen bzw. vom aktuell angemeldeten Benutzer hochgeladenen Dateien wurden. Diese Dateien müssen nicht unbedingt im Hauptpfad liegen, um dort angezeigt zu werden. Meine DateienBeachten Sie, dass mit "Meine Dateien" immer die Dateien gemeint sind, die unter dem aktuell angemeldeten Benutzer-Konto hochgeladen wurden. |
Zeige Dateien aus dem primären Ordner | Bei aktiver Checkbox wird der Hauptpfad in der mam/gallery Oberfläche sichtbar als "Ordner" angezeigt. Sie können dann Dateien vom Hauptpfad auswählen. Der Hauptpfad ist dieser, welchen Sie oben definiert haben. |
Zeige Dateien aus dem sekundären Ordner | Bei aktiver Checkbox wird zusätzlich zu dem primären Ordner auch der sekundäre Ordner angezeigt. |
Anzahl Datensätze pro Seite | Mit dieser Option können Sie x Datensätze (Dateien) pro Seite anzeigen lassen. Ist die Anzahl pro Seite niedriger als Dateien insgesamt angezeigt werden können, wird eine Seitenauswahl angezeigt, mit der Sie auf einzelne Seiten springen können. |
Weitere Dateien | Über dieses Auswahlfeld wird festgelegt, wie die Optionen für "weitere Dateien" dargestellt werden.
Standardmäßig wird die Pagination dargestellt, sofern keine Option gewählt wurde. |
Zeige Dateien aus Kategorien | Ist die Checkbox aktiv, ist der Abruf der Kategorien in der Galerie möglich. |
Um die Konfiguration der Galerie zu erweitern, sollten weitere Entitäten erstellt werden, die einen Fremdschlüsselbezug zu einem Galeriedatensatzes besitzen. Die Konfigurationsoberfläche kann über das OnPopulateForm-Event von ComponentForm erweitert werden.
Verwendung
Die Galerie kann über den entsprechenden Button eines Datei-Feldes geöffnet werden. Die Galerie wird dabei in einem Modal platziert.
Die Galerie ist standardmäßig aus folgenden Elementen aufgebaut.
Nr. | Bereich | Beschreibung |
|---|---|---|
1 & 2 | Marginalie - Toolbar & Baum | Die Organisationseinheiten einer Galerie können über entsprechende Ui-Elemente in der Toolbar, oder im rekursiven Baum dargestellt werden. Je nach Kontext, sollte der Programmierer eine passende Darstellung wählen. |
3 | Blätterfunktion | Wenn sich viele Dateien im Hauptpfad befinden, bzw. mehr Dateien wie in der Konfiguration "Anzahl Datensätze pro Seite" angegeben, können Sie hier auf verschiedene Seiten springen. Falls es nur eine Seite gibt, wird die Seitenauswahl nicht angezeigt. Es ist möglich die Blätterfunktion durch einen "Mehr"-Button zu ersetzen, der weitere Kacheln nachlädt, sofern weitere Elemente vorhanden sind. |
4 | Dateisuche | Mit dieser Option können Sie nach Dateien suchen indem Sie den Namen eingeben, oder Buchstaben und Zahlen, welche der Dateinamen enthält. Das suchen nach Dateiendungen (z.B. ".jpg", ".png", ...) ist ebenfalls möglich. Danach einen Klick auf die Enter-Taste um die Suche zu starten. Die Dateien werden Ihnen rechts im großen Feld angezeigt. |
5 | Sortierung | Hier kann die Sortierung gewählt werden. Es werden alle Spalten aufgelistet, die als Sortierspalten gekennzeichnet sind und keine Systemspalten sind. |
6 | Sichtbare Werte | Hier können die Werte gewählt werden, die in den Kacheln sichtbar sein sollen. Die Einstellung wird im WebStorage persistiert. Die Sortierung ist in der Parameterliste bei Anfragen an die Galerie vorhanden und muss von den Listenern/Subscribern, welche die Dateien aus der Datenbank beschaffen, entsprechend verarbeitet werden. |
7 | Datei-Kachel | Die Kachel besteht aus mehreren Unterelementen.
|
Aktionen
Im Kopfbereich der Galerie lassen sich unter Umständen Buttons finden, über die bestimmte Aktionen ausgeführt werden können.
Upload: Wurde der Upload in der Konfiguration der Galerie aktiviert, so können Dateien in dieser Organisationseinheit hochgeladen werden. Derzeit ist diese Funktion nur für "Favorisierte Dateien" und "Meine Dateien" verfügbar.
Aufbau der Galerie
Die Galerie besitzt grundlegend zwei Einsteigspunkte:
Ui/Modal/Engine::galleryHaupteinstiegspunkt. Diese Methode liefert die Galerie als Ganzes aus.
UI/Modal/Engine::pwa/gallery/files/wrapperDiese Methode ist für den Hauptbereich zuständig. Wird ein Element einer Organisationseinheit gewählt, wird der Hauptinhalt entsprechend aktualisiert.
gallery
Den Haupteinstiegspunkt bildet gallery. Wird diese Methode aufgerufen, wird der Rahmen für die Galerie platziert. Die Marginalie bzw. der Hauptbereich werden nachgeladen.
Marginalie
Die Marginalie wird über die Methode Ui\Modal\Manager::buildMargin erstellt. In der Marginalie befinden sich Elemente, die der Navigation dienen. Diese Elemente geben an, was im Hauptbereich dargestellt wird.
Im Kopfbereich der Marginalie befindet sich eine Toolbar, in der Buttons platziert werden können. Diese Buttons werden üblicherweise genutzt um die Navigation zu Dateien zu ermöglichen, die keine dahinterliegende Struktur besitzen (z.B. willkürliche Session Dateien).
Im Körper der Marginalie hingegen werden strukturierte Organisationseinheiten dargestellt, welche wiederum Dateien enthalten. Ein Beispiel für solche Organisationseinheiten sind Ordner, die weitere Unterordner besitzen und explizit über die Konfiguration der Galerie freigegeben wurden.
Hauptbereich
Der Hauptbereich wird über den Aufruf Ui\Modal\Engine::pwaGalleryContent geladen. Während sich die Marginalie mit der Frage beschäftigt, was dargestellt wird, beschäftigt sich der Hauptbereich hingegen damit, wie die vorab "gewählten" Inhalte dargestellt werden. Der Hauptbereich wird wiederum in zwei Bereiche untergliedert; eine Kopfzeile, in der Steuerelemente angezeigt werden und ein Hauptbereich in dem hauptsächlich die Dateikarten angezeigt werden.
Im Kopfbereich dieser Ansicht werden Elemente platziert, mit denen man die Filterung und Ansichtseinstellungen für die Dateikacheln beeinflussen kann. In diesem Bereich finden sich gängige Funktionen wie z.B. eine Suche oder Sortierungsmöglichkeiten wieder. Die Steuerungsparameter wie z.B. der Suchbegriff des Suchfeldes können über eigene JavaScript-Dateien an das JavaScript galleryRequest übermittelt werden. Wurden die gewünschten Parameter übermittelt, lässt sich eine neue Anfrage für Dateien auslösen. Somit gibt es nur eine zentrale Stelle, welche die Anfragen für die Galerie ausführt. Die in galleryRequest platzierten Elemente sind somit möglichst unabhängig voneinander.
Im Hauptbereich werden die auf Basis der im Kopfbereich bereitgestellten Steuerungsparameter gesammelten Dateien in Form von Karten dargestellt. Dieser Aufruf bezieht die geforderten Dateien anhand der Steuerungs- und Filterparameter aus Marginalie und Request, aus der Datenbank und mappt diese zu den Kachel-Objekten aus dem Styleguide.
Events
PHP
Die Galerie löst Events aus, um die Manipulation der Galerie möglich zu machen. Diese Events verfügen über ein Kontext-Objekt, welches alle nötigen Daten beinhaltet.
Folgende Events werden ausgelöst, um die Inhalte der Galerie zu füllen. Es existieren weitere Events, um die Galerie präziser zu manipulieren.
Event | Beschreibung |
|---|---|
OnPopulateMargin | Ein Event, um den FrameworkContainer der Marginalie zu füllen. GalleryCore löst in Reaktion auf dieses Event diese weiteren Events aus:
|
OnPopulateGalleryContent | Ein Even, um den FrameworkContainer des Hauptbereiches zu füllen. GalleryCore löst in Reaktion auf dieses Event diese weiteren Events aus:
|
Ui/Modal implementiert zahlreiche Listener, um die Basisfunktionalität der Galerie bereitzustellen.
Übersicht aller Events
JavaScript
Sämtliche detail-Objekte der Events einer Galerie sollten den String "galleryIdentifier" enthalten, da es möglich ist, dass mehrere Galerien aktiv sind. Dieser Identifier wird zur Unterscheidung benötigt.
Event | event.detail | Beschreibung |
|---|---|---|
onTriggerUpdateGalleryRequestParams | Dieses Event kann von Elementen im Request-Bereich der Galerie getriggert werden, um der Galerie zu signalisieren, dass die Parameterliste aktualisiert werden soll. Dieses Event löst wiederum "onCollectGalleryRequestParams" aus. | |
onCollectGalleryRequestParams | Dieses Event wird vom Request-Bereich selbst getriggert, sobald die Parameterliste aktualisiert werden soll. Die Elemente im Request-Bereich können auf das Event reagieren und die Parameterliste befüllen. Um die Parameter an die Galerie zurückzugeben ist das Event "onUpdateGalleryRequestParams" vom Listener auszulösen. onCollectGalleryRequestParams: function (event) {
if (event.detail.galleryIdentifier === this.galleryIdentifier) {
var eventOptions = {
detail: {
params:
{
query: this.element.value
},
galleryIdentifier: this.galleryIdentifier
},
bubbles: true
}
var customEvent = new CustomEvent('onUpdateGalleryRequestParams', eventOptions);
this.element.dispatchEvent(customEvent)
}
} | |
onUpdateGalleryRequestParams |
| Dieses Event aktualisiert die Parameterliste des Request-Objekts mit den im event definierten Parametern des detail-Objekts. |
onGalleryRequestReload |
| Wird dieses Event ausgelöst, werden neue Inhalte für die Galerie angefragt. Die Parameterliste des Request-Objekts wird für diese Anfrage genutzt. Über die Parameter "target" und "replaceTarget" kann man bestimmen, welche HTML-Inhalte teilweise oder vollständig ersetzt werden. |
onUpdateWebStorage |
| Dieses Event löst eine Aktualisierung des WebStorage in brandbox aus. Es sollte beachtet werden, dass die WebStorage Einträge der Galerie über einen Scope (Kontext) verfügen sollen. Beispielsweise sollte die Einstellung der sichtbaren Kachelwerte unabhängig von der Sortierung gespeichert werden. |
GalleryFileClicked |
| Dieses Event wird i.d.R. ausgelöst, wenn eine Dateikachel angeklickt wird. Auf das Event kann reagiert werden, wenn bei dem Klick auf eine Datei ein spezielles Verhalten erwartet wird. Normalerweise wird das Input-Feld mit den Daten des detail-Objekts befüllt, sodass die Vorschau generiert werden kann (siehe Base/Widget/js/gallery::UIGallery.onFileClick). |
GalleryRemoveFile |
| Über die Angabe einer contentID lässt sich die entsprechende Kachel aus der Galerie entfernen (nur UI!). Dieses Event wird bspw. beim Löschen oder beim Entfavorisieren in der "Favorisierte Dateien"-Ansicht ausgelöst. |
Einbindung in der Dateiauswahl
Die Galerie kann im Feld vom Typ "Dateiauswahl" hinzugefügt werden. Um das zu ermöglichen, muss die Konfiguration des Feldes angepasst werden.
In der Konfiguration muss ein neues Objekt "gallery" angelegt werden. Dieses Objekt besitzt zwei Eigenschaften:
isEnabled
Boolescher Wert. Dieser Wert entscheidet, ob der Button für die Galerie dargestellt werden soll.
configKey
Zeichenkette. Der Identifikator des gewünschten Galerie-Datensatzes.
InputFile.gallery
"identifier": "identifierInputFile1",
"labels": {
"de": "Dateifeld mit Galerie",
"en": "File field with gallery"
},
"formType": "file",
"configuration": {
"gallery": {
"isEnabled": true,
"configKey": "base-shopArticle"
}
}
Bildauswahl als Eingabefeld
Es ist möglich eine Sammlung von Bildern als Eingabefeld zu nutzen. Somit erfolgt die Bildauswahl nicht über das Modal der Galerie, sondern durch einen Klick auf ein Bild, welches direkt beim Feld dargestellt wird. Der Bilderpool wird durch den Primärordner einer Galerie festgelegt. Diese Galerie muss in der Konfiguration festgelegt werden. Der Typ für das Feld ist ImageSelect.
{
"identifier": "imageSelection",
"labels": {
"de": "Bildauswahl",
"en": "ImageSelection"
},
"formType": "ImageSelect",
"configuration": {
"galleryId": 95
}
}