Collections
Eine Collection ist eine benannte, schreibgeschützte Sicht auf eine Dataverse-Tabelle: welche Datensätze öffentlich sind, welche Spalten angezeigt werden und welche Bedienelemente Besucher erhalten. Sie wird über [wbsdvc_collection] oder den Block "Dataverse Collection" als Kartenraster gerendert, und als Detailseite, sobald in der URL ein Datensatz ausgewählt ist.
Felder einer Collection
Alle Felder des Tabs "Collections" in der Reihenfolge, in der sie dort erscheinen. Logische Namen sind kleingeschrieben; alles andere wird entfernt.
| Feld | Bedeutung |
|---|---|
| Key | Handle, das in Shortcodes und Blöcken verwendet wird. Pflichtfeld. |
| Table | Logischer Name, zum Beispiel wbs_listing. Zugleich die Metadatenquelle für Beschriftungen und Typen. Pflichtfeld. |
| Entity set | Pluralname des Entity Sets, den die Web API anspricht, zum Beispiel wbs_listings. Pflichtfeld. |
| Name column | Spalte, die als Titel der Karte und der Detailansicht angezeigt wird. Pflichtfeld. |
| Slug column | Spalte mit einem URL-tauglichen Slug für Detail-Links. Leer bedeutet, dass die Datensatz-ID verwendet wird. |
| Columns | Logische Namen der Spalten, die abgerufen und als Fakten angezeigt werden, eine pro Zeile. Lookups werden automatisch über ihre Eigenschaft _column_value abgerufen. |
| Image URL column | Eine Textspalte mit einer öffentlichen Bild-URL. Ist zusätzlich die "Image column" (siehe unten) gesetzt, hat diese Vorrang. |
| Status filter | OData-Ausdruck, der per AND an jeden Lesezugriff angehängt wird, zum Beispiel statecode eq 0. Gilt gleichermaßen für das Raster, direkte Links, Medien und Update-Formulare. |
| Order by | OData-Sortierung, Standard createdon desc. Der Primärschlüssel wird als zusätzliches Sortierkriterium angehängt, damit sich Seiten nie überschneiden. |
| Search columns | Textspalten, in denen das Suchfeld sucht, eine pro Zeile. Leer blendet das Suchfeld aus. |
| Filter columns | Spalten, die als Dropdowns angeboten werden. Auswahl-, Status- und Ja/Nein-Spalten listen alle ihre Optionen; andere Spalten listen die Werte, die auf der aktuellen Seite vorkommen. |
| Sort options | Auswahlmöglichkeiten für Besucher als column asc oder column desc, eine pro Zeile. Leer behält die feste Sortierung bei. |
| Records per page | 1 bis 100, Standard 12. Ein Shortcode-Attribut per_page oder limit hat Vorrang. |
| Cache lifetime | Sekunden, die Lesezugriffe dieser Collection im Cache bleiben. Leer bedeutet den Site-Standard, 0 deaktiviert das Caching für diese Collection. |
| Image column | Eine Dataverse-Image-Spalte. Das Bild wird über Ihre eigene Website ausgeliefert; siehe unten. |
| File columns | File-Spalten, die in der Detailansicht als Downloads angeboten werden, eine pro Zeile. |
Mit dem Pro-Add-on erscheint zusätzlich eine Auswahl "Environment". Entwickler können Collections per Code über den Filter wbs_dataverse_connect_collections registrieren; eine auf dem Tab gespeicherte Collection mit demselben Key überschreibt sie.
Shortcode- und Block-Attribute
[wbsdvc_collection name="listings" per_page="12" columns="3" detail_page="/listings" form="inquiry" search="1" filters="wbs_city,statecode" sort="wbs_price asc,createdon desc"]
[wbsdvc_record name="listings" slug="stadthaus-am-park" form="inquiry"]| Attribut | Wirkung |
|---|---|
| name | Key der Collection. Pflichtangabe. |
| per_page | Datensätze pro Seite, 1 bis 100. limit ist der ältere Name und hat weiterhin Vorrang, wenn er gesetzt ist. |
| columns | Rasterspalten, 1 bis 4, Standard 3. |
| detail_page | Pfad einer anderen Seite, die die Detailansicht rendert. Leer bedeutet, dass die aktuelle Seite beides übernimmt. |
| form | Key eines Formulars, das unter der Detailansicht eingebunden und mit dem Datensatz verknüpft wird. |
| search | 1 zeigt das Suchfeld (auf der Name column, wenn keine Suchspalten konfiguriert sind), 0 blendet es aus. |
| filters | 0 blendet alle Filter aus; eine kommagetrennte Liste beschränkt sie auf diese Spalten. Berücksichtigt werden nur Spalten, die die Collection bereits freigibt. |
| sort | 0 blendet die Sortierauswahl aus; eine Liste aus column asc|desc beschränkt die Auswahl auf freigegebene Spalten. |
| slug (nur Record) | Slug oder ID des Datensatzes. Leer liest ?dvc= aus der URL. |
Die Blöcke "Dataverse Collection" und "Dataverse Record" bieten dieselben Attribute als Einstellungen in der Seitenleiste. Ein Shortcode kann keine Spalte veröffentlichen, die der Administrator nicht freigegeben hat: Filter- und Sortiernamen außerhalb der eigenen Spalten der Collection werden stillschweigend verworfen.
Suche, Filter, Sortierung und Paging
Der Zustand des Besuchers wird in vier GET-Parametern übertragen: dvc_q (Suchbegriff), dvc_f[column] (einer pro Filter), dvc_sort und dvc_page. Die Toolbar ist ein einfaches GET-Formular und die Paging-Links sind gewöhnliche Links, daher funktioniert alles ohne JavaScript und jeder Zustand hat eine teilbare URL.
- Die Suche baut
contains(column,'term')auf, per OR über die Suchspalten verknüpft. Suchbegriffe werden nach 100 Zeichen abgeschnitten und für OData maskiert. - Filter werden anhand der Tabellenmetadaten typisiert: ganze Zahlen für Auswahl-, State-, Status- und Integer-Spalten,
true/falsefür Ja/Nein, GUIDs für Lookups,ContainValuesfür Mehrfachauswahlen, ansonsten Zeichenketten in Anführungszeichen. Ein Wert, der nicht zur Spalte passt, wird ignoriert. - Die Sortierung akzeptiert nur Optionen, die in der Konfiguration aufgeführt sind; alles andere fällt auf die feste Sortierung zurück.
- Das Paging folgt dem
@odata.nextLink, den die Web API zurückgibt, denn Dataverse kennt kein$skip. Die Seitengröße wird alsPrefer: odata.maxpagesizeübertragen. Besuchte Links werden je Zustand gemerkt, damit eine spätere Seite aufgelöst werden kann, ohne von vorn zu beginnen; eine Anfrage folgt höchstens 10 Links, und Seitenzahlen enden bei 1.000. - Die Trefferzahl stammt aus
$count=true. Dataverse begrenzt sie auf 5.000, angezeigt als "5,000+ results".
Zwei Grenzen, die Sie einplanen sollten:
- Eine Collection pro Seite. Zwei Raster auf einer Seite teilen sich dieselben GET-Parameter und würden beide darauf reagieren.
- Filteroptionen für Nicht-Auswahlspalten stammen von der aktuellen Seite. Eine Stadt, die nur auf Seite drei vorkommt, wird erst angeboten, wenn ein Besucher Seite drei erreicht. Verwenden Sie Auswahlspalten für alles, was über die gesamte Tabelle filterbar sein soll.
Detailseiten und Slug-URLs
Karten verlinken auf ?dvc=<slug> auf der aktuellen Seite (oder auf detail_page). Ist eine Slug-Spalte gesetzt, wird zuerst der Slug abgeglichen, und eine GUID funktioniert weiterhin als Fallback, sodass alte ID-Links die Umstellung überleben. Ohne Slug-Spalte wird die Datensatz-ID verwendet. Der Statusfilter gilt auch für diese Abfrage: Ein unveröffentlichter Datensatz bleibt selbst mit direktem Link unsichtbar.
Die Detailansicht zeigt den Namen, das Bild, die konfigurierten Spalten als Faktentabelle, die Downloadliste und, wenn ein Formular eingebunden ist, das mit dem Datensatz verknüpfte Formular.
Caching
Lesezugriffe werden in Transients zwischengespeichert, für die siteweite TTL (Tab "Connection", Standard 300 Sekunden) oder die eigene Lebensdauer der Collection. Nur Zustände aus einem endlichen Wertebereich werden gecacht: kein Suchbegriff, und Filter nur auf Ja/Nein-, Auswahl-, State- oder Status-Spalten mit einem Wert aus ihren Metadatenoptionen. Alles andere wird live gelesen, damit ein Crawler, der Werte durchprobiert, die Datenbank nicht füllen kann. Flush cache auf dem Tab "Connection" verwirft alle gecachten Lesezugriffe auf einmal; das Speichern einer Collection bewirkt dasselbe. Ist Dataverse nicht erreichbar, zeigt die Seite statt eines Fehlers einen kurzen Hinweis; Administratoren sehen den Grund.
Templates und Overrides
Die Ausgabe läuft über PHP-Templates im Verzeichnis templates/ des Plugins. Kopieren Sie ein beliebiges davon nach your-theme/wbs-connect-for-dataverse/ und bearbeiten Sie die Kopie; die Theme-Version hat Vorrang, und Child-Themes funktionieren.
| Template | Rendert |
|---|---|
| collection-list.php | Den Raster-Wrapper um die Karten |
| collection-card.php | Eine Karte: Bild, Titel, Fakten |
| collection-toolbar.php | Suchfeld, Filterauswahlen, Sortierauswahl, die Schaltflächen "Apply" und "Clear", Trefferzahl |
| collection-pagination.php | Die Links "Previous" und "Next" mit der Seitenzahl |
| record-detail.php | Titel, Bild, Faktentabelle, Downloads, eingebundenes Formular |
Die Variablen, die jedes Template erhält, sind auf der Seite Hooks und Templates aufgeführt. Beschriftungen stammen aus den Anzeigenamen der Tabelle; der Filter wbs_dataverse_connect_field_label überschreibt sie je Spalte.
Image- und File-Spalten
Setzen Sie eine Image column, und Karten wie Detailseiten zeigen das Bild; tragen Sie File columns ein, und die Detailseite bietet sie als Downloads an. Beides wird über eine öffentliche, schreibgeschützte REST-Route auf Ihrer eigenen Website ausgeliefert, sodass nichts auf der Seite auf Dataverse verweist oder ein Token enthält:
/wp-json/wbs-connect-for-dataverse/v1/media/<collection>/<record id>/<column>
/wp-json/wbs-connect-for-dataverse/v1/media/<collection>/<record id>/<column>?size=thumbDie Route liefert nur aus, was ein Besucher ohnehin sehen könnte: Die Collection muss existieren, der Datensatz muss den Statusfilter passieren, und die Spalte muss die Image column oder eine der File columns sein. Dateien bis 3,75 MB werden einen Tag lang gecacht (5 MB gespeichertes Base64); größere Dateien werden bis 32 MB ungecacht gestreamt. Bilder, PDFs, reiner Text, CSV und gängige Audio- und Videotypen werden inline dargestellt; alles andere wird als Download gesendet. Browser erhalten ein eintägiges Cache-Control und ein ETag.