Hooks and templates
Last updated: September 2026, plugin 1.5.2
Every filter and action the free plugin exposes, with its signature and purpose, followed by the templates a theme can override and the variables each receives. Generated from the docblocks in includes/; the prefix is wbs_dataverse_connect_ throughout.
Filters
Collections and reading
| Filter | Arguments | Purpose |
|---|
| wbs_dataverse_connect_collections | $collections | Register collections in code (key => config); settings-page collections with the same key override them. |
|---|
| wbs_dataverse_connect_normalize_collection | $clean, $key, $config | Last stop of collection normalization; add-ons carry extra config keys through here. |
|---|
| wbs_dataverse_connect_field_label | $label, $column, $config | The label of a column in cards, detail tables and the toolbar, after metadata and the heuristic. |
|---|
| wbs_dataverse_connect_record_vm | $vm, $config, $record | The view model of one record before the templates print it (id, name, slug, url, image, fields, files, record). |
|---|
| wbs_dataverse_connect_access_filter | $expression, $config, $scope | OData expression ANDed into every read of a collection; $scope is list or single. Empty by default. |
|---|
| wbs_dataverse_connect_can_view | $allowed, $config, $scope | Gate a collection, record, form or media file for the current visitor; $scope is collection, record, form or media. |
|---|
| wbs_dataverse_connect_denied_notice | $html, $config, $scope | Markup shown when can_view refused; add-ons replace it with a sign-in prompt. |
|---|
| wbs_dataverse_connect_metadata_ttl | $seconds | How long table metadata stays cached. Default one day. |
|---|
| wbs_dataverse_connect_metadata_attributes | $attrs, $table, $context | The attribute map of a table after fetching (label, type, required, format, maxlength, options, targets). |
|---|
Forms and writing
| Filter | Arguments | Purpose |
|---|
| wbs_dataverse_connect_forms | $forms | Register forms in code (key => config); settings-page forms override them. |
|---|
| wbs_dataverse_connect_normalize_form | $clean, $key, $config | Last stop of form normalization; add-ons carry extra config keys through here. |
|---|
| wbs_dataverse_connect_form_view | $view, $config, $record | The view model of a rendered form: fields with labels, options and values, mode, record id, Turnstile site key. |
|---|
| wbs_dataverse_connect_form_record | $record, $config, $values | Last stop before the write: the column => value payload; $config['mode'] tells a create from an update. |
|---|
| wbs_dataverse_connect_bridge_maps | $maps | WBS Forms bridge maps keyed by form slug. |
|---|
| wbs_dataverse_connect_bridge_record | $record, $map, $submission, $form_id | Last stop before a bridged create. |
|---|
Connection, admin and settings
| Filter | Arguments | Purpose |
|---|
| wbs_dataverse_connect_connection | $conn, $context | The connection (tenant_id, client_id, client_secret, env_url, auth) used for the request described by $context (type collection, form, admin or metadata, plus config). |
|---|
| wbs_dataverse_connect_token_args | $args, $conn | The wp_remote_post args of the token request; swap the client secret for a certificate assertion here. |
|---|
| wbs_dataverse_connect_admin_tabs | $tabs | Settings page tabs (slug => label); render an added tab with the render_tab_{slug} action. |
|---|
| wbs_dataverse_connect_save_collection | $config, $post | The collection config about to be stored, with the unslashed POST data for extra rows. |
|---|
| wbs_dataverse_connect_save_form | $config, $post | Same for forms. |
|---|
| wbs_dataverse_connect_blocks_data | $data | Data handed to the block editor: collections and forms as value/label pairs, settings URLs. |
|---|
| wbs_dataverse_connect_review_due | $due | Return false to keep the one-time review request off a site. |
|---|
Health, media and webhooks
| Filter | Arguments | Purpose |
|---|
| wbs_dataverse_connect_alert_recipients | $to | Email addresses failure and recovery alerts go to. |
|---|
| wbs_dataverse_connect_alert_cooldown | $seconds | Wait before re-alerting about the same failure episode. Default six hours. |
|---|
| wbs_dataverse_connect_media_ttl | $seconds | How long proxied images and files are cached, in the transient and via Cache-Control. Default one day. |
|---|
| wbs_dataverse_connect_media_max_bytes | $bytes | Upper bound of one proxied file. Default 32 MB. |
|---|
| wbs_dataverse_connect_media_inline_types | $inline | MIME types served inline; everything else is downloaded as an attachment. |
|---|
| wbs_dataverse_connect_webhook_payload | $payload, $event, $hook | The message about to be posted ({event, site, time, data}); $hook is the receiving webhook, null for a preview. |
|---|
| wbs_dataverse_connect_webhook_args | $args, $hook, $event | The wp_remote_post args of a delivery, before the body is signed. |
|---|
Actions
| Action | Arguments | Fires |
|---|
| wbs_dataverse_connect_record_created | $key, $entity_set, $id, $record | After a form or the bridge created a record; $key is the form key or bridge:<slug>. |
|---|
| wbs_dataverse_connect_record_updated | $key, $entity_set, $id, $record | After an update-mode form patched a record. |
|---|
| wbs_dataverse_connect_bridge_created | $id, $form_id, $record | After the WBS Forms bridge wrote a submission (older companion of record_created). |
|---|
| wbs_dataverse_connect_health_event | $kind, $state | On every recorded failure and every recovery; $kind is failure or recovery. |
|---|
| wbs_dataverse_connect_webhook_dispatched | $event, $data, $sent | After an event was handed to its webhooks, with the number of deliveries. |
|---|
| wbs_dataverse_connect_collection_fields | $editing | Inside the collection editor's table, before the submit button; $editing is the config or null when adding. |
|---|
| wbs_dataverse_connect_form_fields | $editing | Same for the form editor. |
|---|
| wbs_dataverse_connect_render_tab_{slug} | none | Renders the content of a tab added through admin_tabs. |
|---|
The bridge consumes wbs_forms_after_submit($form_id, $fields, $meta) from WBS Forms and answers the wbs_forms_submission_handled filter with true after a successful create.
Client functions
Add-ons and theme code use the same client the plugin uses. Every read goes through the cache and the health monitor; writes are never cached. The request functions return the decoded array or a WP_Error; the helpers below return what their row says.
| Function | Purpose |
|---|
wbs_dataverse_connect_get($path, $ttl = null, $context = []) | Cached GET relative to the API base; $ttl null is the site default, 0 skips the cache; $context['headers'] merges extra request headers. |
|---|
wbs_dataverse_connect_post($path, $body, $context = []) | Create. Returns ['id' => guid]. |
|---|
wbs_dataverse_connect_patch($path, $body, $context = []) | Update of one addressed record such as contacts(guid); pass ['headers' => ['If-Match' => '*']] to forbid upserts. |
|---|
wbs_dataverse_connect_get_raw($path, $context = []) | Raw bytes of a $value request, for media; returns body, type, name and status. |
|---|
wbs_dataverse_connect_typed_value($field, $raw, $context = []) | Type one submitted value for the Web API by a normalized field spec; null for empty, WP_Error for invalid. |
|---|
wbs_dataverse_connect_render_form($config, $record_id = '') | Render a form bound to a record. |
|---|
wbs_dataverse_connect_template($name, $vars = []) | Load a template with theme override. |
|---|
Templates
Templates live in wbs-connect-for-dataverse/templates/. Copy a file to your-theme/wbs-connect-for-dataverse/ (child themes work) and edit the copy. Variables are extracted into the template scope; everything in a view model is pre-formatted, the template only escapes and prints.
| Template | Variables |
|---|
| collection-list.php | $cards (pre-rendered card HTML), $columns (1 to 4) |
|---|
| collection-card.php | $vm: id, name, slug, url (detail link or empty), image, fields (list of column, label, value), files, record (the raw row) |
|---|
| collection-toolbar.php | $toolbar: action, hidden (name => value inputs), search (null or name, id, value, label), filters (list of column, name, id, label, options, value), sort (null or name, id, options, value, label), count (int or null), active, reset_url |
|---|
| collection-pagination.php | $pagination: page, has_prev, has_next, prev_url, next_url, count |
|---|
| record-detail.php | $vm as above, with files as a list of column, label, url, name; $form (pre-rendered form HTML or empty) |
|---|
| form.php | $config (normalized form config), $record_id (GUID or empty), $rest_url, $nonce; the template calls wbs_dataverse_connect_form_view() for the typed fields |
|---|
Front-end classes are prefixed dvc-. The form's submit handler in assets/wbs-connect-for-dataverse.js reads the data-dvc-* attributes of the form element, so a custom form.php keeps working as long as it keeps them.
