Collections
A collection is a named, read-only view of one Dataverse table: which records are public, which columns show, and which controls visitors get. It renders as a card grid through [wbsdvc_collection] or the Dataverse Collection block, and as a detail page when a record is selected in the URL.
Collection fields
Everything on the Collections tab, in the order it appears. Logical names are lowercase; anything else is stripped.
| Field | Meaning |
|---|---|
| Key | Handle used in shortcodes and blocks. Required. |
| Table | Logical name, for example wbs_listing. Also the metadata source for labels and types. Required. |
| Entity set | Plural set name the Web API addresses, for example wbs_listings. Required. |
| Name column | Column shown as the card and detail title. Required. |
| Slug column | Column holding a URL-friendly slug for detail links. Empty means the record id is used. |
| Columns | Logical names to fetch and display as facts, one per line. Lookups are fetched through their _column_value property automatically. |
| Image URL column | A text column holding a public image URL. Superseded by the Image column below when both are set. |
| Status filter | OData expression ANDed into every read, for example statecode eq 0. Applies to the grid, direct links, media and update forms alike. |
| Order by | OData order, default createdon desc. The primary key is appended as a tiebreaker so pages never overlap. |
| Search columns | Text columns the search box matches, one per line. Empty hides the box. |
| Filter columns | Columns offered as dropdowns. Choice, status and yes/no columns list all their options; other columns list the values found on the current page. |
| Sort options | Choices offered to visitors as column asc or column desc, one per line. Empty keeps the fixed order. |
| Records per page | 1 to 100, default 12. A per_page or limit shortcode attribute takes precedence. |
| Cache lifetime | Seconds this collection's reads stay cached. Empty means the site default, 0 disables caching for this collection. |
| Image column | A Dataverse Image column. The picture is served through your site; see below. |
| File columns | File columns offered as downloads on the detail view, one per line. |
With the Pro add-on an Environment select appears as well. Developers can register collections in code with the wbs_dataverse_connect_collections filter; a collection saved on the tab with the same key overrides it.
Shortcode and block attributes
[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"]| Attribute | Effect |
|---|---|
| name | Collection key. Required. |
| per_page | Records per page, 1 to 100. limit is the older name and still wins when set. |
| columns | Grid columns, 1 to 4, default 3. |
| detail_page | Path of another page that renders the detail view. Empty means the current page serves both. |
| form | Key of a form attached under the detail view, related to the record. |
| search | 1 shows the search box (on the name column when none are configured), 0 hides it. |
| filters | 0 hides all filters; a comma list narrows them to those columns. Only columns the collection already exposes are honored. |
| sort | 0 hides the sort select; a list of column asc|desc narrows the choices to exposed columns. |
| slug (record only) | Slug or id of the record. Empty reads ?dvc= from the URL. |
The Dataverse Collection and Dataverse Record blocks carry the same attributes as sidebar controls. A shortcode cannot publish a column the admin did not whitelist: filter and sort names outside the collection's own columns are dropped silently.
Search, filters, sort and paging
Visitor state travels in four GET parameters: dvc_q (search term), dvc_f[column] (one per filter), dvc_sort and dvc_page. The toolbar is a plain GET form and the paging links are ordinary links, so everything works without JavaScript and every state has a shareable URL.
- Search builds
contains(column,'term')OR-joined over the search columns. Terms are cut at 100 characters and escaped for OData. - Filters are typed from the table metadata: whole numbers for choice, state, status and integer columns,
true/falsefor yes/no, GUIDs for lookups,ContainValuesfor multi-select choices, quoted strings otherwise. A value that does not fit the column is ignored. - Sort accepts only options listed in the configuration; anything else falls back to the fixed order.
- Paging follows the
@odata.nextLinkthe Web API returns, because Dataverse has no$skip. The page size travels asPrefer: odata.maxpagesize. Visited links are remembered per state so a later page resolves without walking from the start; one request follows at most 10 links, and page numbers stop at 1000. - Result count comes from
$count=true. Dataverse caps it at 5,000, shown as "5,000+ results".
Two limits to plan around:
- One collection per page. Two grids on one page share the same GET parameters and would both react to them.
- Filter options for non-choice columns come from the current page. A city that only occurs on page three is not offered until a visitor reaches page three. Use choice columns for anything you want filterable across the whole table.
Detail pages and slug URLs
Cards link to ?dvc=<slug> on the current page (or on detail_page). With a slug column set, the slug is matched first and a GUID still works as a fallback, so old id links survive the switch. Without a slug column the record id is used. The status filter applies to the lookup as well: an unpublished record is invisible even with a direct link.
The detail view shows the name, the image, the configured columns as a facts table, the downloads list and, when a form is attached, the form related to the record.
Caching
Reads are cached in transients for the site-wide TTL (Connection tab, default 300 seconds) or the collection's own lifetime. Only states drawn from a finite value space are cached: no search term, and filters only on yes/no, choice, state or status columns with a value from their metadata options. Everything else is read live, so a crawler cycling values cannot fill the database. Flush cache on the Connection tab invalidates every cached read at once, and saving a collection does the same. When Dataverse is unreachable the page shows a short notice instead of an error; administrators see the reason.
Templates and overrides
Output runs through PHP templates in the plugin's templates/ directory. Copy any of them to your-theme/wbs-connect-for-dataverse/ and edit the copy; the theme version wins and child themes work.
| Template | Renders |
|---|---|
| collection-list.php | The grid wrapper around the cards |
| collection-card.php | One card: image, title, facts |
| collection-toolbar.php | Search box, filter selects, sort select, Apply and Clear, result count |
| collection-pagination.php | Previous and Next links with the page number |
| record-detail.php | Title, image, facts table, downloads, attached form |
The variables each template receives are listed on the Hooks and templates page. Labels come from the table's display names; the wbs_dataverse_connect_field_label filter overrides them per column.
Image and file columns
Set an Image column and cards and detail pages show the picture; list File columns and the detail page offers them as downloads. Both are served through a public read-only REST route on your own site, so nothing on the page points at Dataverse or carries a token:
/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=thumbThe route only serves what a visitor could already see: the collection must exist, the record must pass the status filter and the column must be the image column or one of the file columns. Files up to 3.75 MB are cached for a day (5 MB of stored base64); bigger files are streamed uncached up to 32 MB. Images, PDFs, plain text, CSV and common audio and video types render inline; everything else is sent as a download. Browsers get a one-day Cache-Control and an ETag.