Changeset 3684724

Timestamp:

09/07/2026 11:19:00 AM (7 weeks ago)

Author:

ztwoods

Message:

Release 1.5.0

Location:

wbs-connect-for-dataverse/trunk

Files:

• assets/blocks-editor.css (added)
• assets/blocks.js (added)
• assets/wbs-connect-for-dataverse-forms.css (added)
• assets/wbs-connect-for-dataverse.css (modified) (1 diff)
• assets/wbs-connect-for-dataverse.js (modified) (3 diffs)
• blocks (added)
• blocks/collection (added)
• blocks/collection/block.json (added)
• blocks/form (added)
• blocks/form/block.json (added)
• blocks/record (added)
• blocks/record/block.json (added)
• includes/blocks.php (added)
• includes/bridge-wbs-forms.php (modified) (1 diff)
• includes/collections.php (modified) (13 diffs)
• includes/dataverse.php (modified) (7 diffs)
• includes/forms.php (modified) (5 diffs)
• includes/media.php (added)
• includes/metadata.php (added)
• includes/rest.php (modified) (6 diffs)
• includes/shortcodes.php (modified) (7 diffs)
• includes/webhooks.php (added)
• readme.txt (modified) (7 diffs)
• templates/collection-pagination.php (added)
• templates/collection-toolbar.php (added)
• templates/form.php (modified) (2 diffs)
• templates/record-detail.php (modified) (2 diffs)
• uninstall.php (modified) (1 diff)
• wbs-connect-for-dataverse.php (modified) (5 diffs)

wbs-connect-for-dataverse/trunk/assets/wbs-connect-for-dataverse.css

@@ -84 +84 @@
 .dvc-form__status--error { color: #a02222; }
 
+.dvc-collection { margin: 1rem 0; }
+
+.dvc-toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-end;
+    gap: 0.75rem 1rem;
+    margin: 0 0 1.25rem;
+    padding: 0.9rem 1rem;
+    background: #f6f6f6;
+    border: 1px solid #e0e0e0;
+    border-radius: 8px;
+}
+.dvc-toolbar__field { display: flex; flex-direction: column; gap: 0.3rem; min-width: 10rem; flex: 1 1 10rem; }
+.dvc-toolbar__field--search { flex: 2 1 14rem; }
+.dvc-toolbar__label { font-size: 0.85rem; font-weight: 500; color: #555; }
+.dvc-toolbar__input,
+.dvc-toolbar__select {
+    width: 100%;
+    padding: 0.5rem 0.65rem;
+    border: 1px solid #ccc;
+    border-radius: 6px;
+    font: inherit;
+    background: #fff;
+    box-sizing: border-box;
+}
+.dvc-toolbar__input:focus,
+.dvc-toolbar__select:focus { outline: 2px solid #333; outline-offset: 1px; }
+.dvc-toolbar__actions { display: flex; align-items: center; gap: 0.75rem; flex: 0 0 auto; }
+.dvc-toolbar__submit {
+    background: #141414;
+    color: #fff;
+    border: 0;
+    border-radius: 6px;
+    padding: 0.55rem 1.2rem;
+    font: inherit;
+    font-weight: 600;
+    cursor: pointer;
+}
+.dvc-toolbar__submit:hover { background: #333; }
+.dvc-toolbar__reset { font-size: 0.9rem; color: #555; }
+.dvc-toolbar__count { flex: 1 0 100%; margin: 0; font-size: 0.85rem; color: #666; }
+@media (max-width: 560px) {
+    .dvc-toolbar__field,
+    .dvc-toolbar__field--search { flex-basis: 100%; }
+    .dvc-toolbar__actions { width: 100%; }
+}
+
+.dvc-pagination {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 1.25rem;
+    margin: 1.5rem 0 1rem;
+    font-size: 0.95rem;
+}
+.dvc-pagination__link {
+    padding: 0.45rem 1rem;
+    border: 1px solid #ccc;
+    border-radius: 6px;
+    color: inherit;
+    text-decoration: none;
+    background: #fff;
+}
+.dvc-pagination__link:hover { border-color: #333; }
+.dvc-pagination__link--disabled { opacity: 0.45; }
+.dvc-pagination__page { color: #666; }
+
+.dvc-files { list-style: none; margin: 0; padding: 0; }
+.dvc-files__item { padding: 0.45rem 0; border-bottom: 1px solid #ececec; }
+.dvc-files__item:last-child { border-bottom: 0; }
+.dvc-files__link { font-weight: 500; }
+.dvc-files__label { margin-left: 0.6rem; color: #666; font-size: 0.9em; }
+
 .dvc-notice {
     padding: 0.9rem 1.1rem;

wbs-connect-for-dataverse/trunk/assets/wbs-connect-for-dataverse.js

@@ -2 +2 @@
 (function () {
     'use strict';
+
+    /**
+     * Serialize the form. Names ending in [] become arrays (multi-select
+     * choices); the empty sentinel of an untouched group is dropped. A
+     * checkbox preceded by a hidden "0" input sends "1" or "0", never nothing.
+     */
+    function collect(form) {
+        var data = {};
+        new FormData(form).forEach(function (v, k) {
+            if (k.slice(-2) === '[]') {
+                var key = k.slice(0, -2);
+                if (!data[key]) {
+                    data[key] = [];
+                }
+                if (v !== '') {
+                    data[key].push(v);
+                }
+                return;
+            }
+            data[k] = v;
+        });
+        var consent = form.querySelector('input[name="consent"]');
+        if (consent) {
+            data.consent = consent.checked ? 1 : 0;
+        }
+        return data;
+    }
+
+    function resetTurnstile(form) {
+        var widget = form.querySelector('.cf-turnstile');
+        if (widget && window.turnstile && typeof window.turnstile.reset === 'function') {
+            try {
+                window.turnstile.reset(widget);
+            } catch (e) {
+                // The widget is optional; a failed reset only means a fresh page load is needed.
+            }
+        }
+    }
 
     function init(form) {
@@ -10 +48 @@
         }
         var submitLabel = button.textContent;
+        var updateMode = form.getAttribute('data-dvc-mode') === 'update';
+
+        function fail(message) {
+            button.disabled = false;
+            button.textContent = submitLabel;
+            status.textContent = message || form.getAttribute('data-dvc-error');
+            status.className = 'dvc-form__status dvc-form__status--error';
+            resetTurnstile(form);
+        }
 
         form.addEventListener('submit', function (e) {
             e.preventDefault();
-            var data = {};
-            new FormData(form).forEach(function (v, k) { data[k] = v; });
-            var consent = form.querySelector('input[name="consent"]');
-            if (consent) {
-                data.consent = consent.checked ? 1 : 0;
-            }
             button.disabled = true;
             button.textContent = form.getAttribute('data-dvc-sending') || submitLabel;
+            status.textContent = '';
+            status.className = 'dvc-form__status';
             fetch(form.getAttribute('data-dvc-rest') || form.action, {
                 method: 'POST',
@@ -27 +70 @@
                     'X-WP-Nonce': form.getAttribute('data-dvc-nonce') || ''
                 },
-                body: JSON.stringify(data)
+                body: JSON.stringify(collect(form))
             }).then(function (r) {
                 return r.json().then(function (j) { return { ok: r.ok, body: j }; });
             }).then(function (res) {
                 if (res.ok && res.body && res.body.ok) {
-                    form.querySelectorAll('input, textarea, button').forEach(function (el) { el.disabled = true; });
+                    if (res.body.redirect) {
+                        window.location.assign(res.body.redirect);
+                        return;
+                    }
+                    if (updateMode) {
+                        button.disabled = false;
+                        button.textContent = submitLabel;
+                        resetTurnstile(form);
+                    } else {
+                        form.querySelectorAll('input, textarea, select, button').forEach(function (el) { el.disabled = true; });
+                    }
                     status.textContent = res.body.message || '';
                     status.className = 'dvc-form__status dvc-form__status--ok';
                 } else {
-                    button.disabled = false;
-                    button.textContent = submitLabel;
-                    status.textContent = (res.body && res.body.message) ? res.body.message : form.getAttribute('data-dvc-error');
-                    status.className = 'dvc-form__status dvc-form__status--error';
+                    fail(res.body && res.body.message ? res.body.message : '');
                 }
             }).catch(function () {
-                button.disabled = false;
-                button.textContent = submitLabel;
-                status.textContent = form.getAttribute('data-dvc-error');
-                status.className = 'dvc-form__status dvc-form__status--error';
+                fail('');
             });
         });

wbs-connect-for-dataverse/trunk/includes/bridge-wbs-forms.php

@@ -150 +150 @@
     wbs_dataverse_connect_review_note_success();
 
+    /**
+     * Fires after a record was created from a form submission.
+     *
+     * @param string $key        Form or bridge map key.
+     * @param string $entity_set Entity set the record was created in.
+     * @param string $id         GUID of the new record, '' when unknown.
+     * @param array  $record     The payload that was posted.
+     */
+    do_action('wbs_dataverse_connect_record_created', 'bridge:' . $slug, $entity_set, is_array($result) ? (string) ($result['id'] ?? '') : '', $record);
+
     // Mark this form's submission as captured for wbs_forms_submission_handled.
     $GLOBALS['wbs_dataverse_connect_bridge_handled'][(int) $form_id] = true;

wbs-connect-for-dataverse/trunk/includes/collections.php

@@ -15 +15 @@
  *   status_filter    optional OData filter, e.g. statecode eq 0
  *   order_by         optional OData orderby, default createdon desc
+ *   search_columns   columns the visitor search box matches; empty hides it
+ *   filter_columns   columns offered as filter selects
+ *   sort_options     "column asc|desc" choices offered to visitors; empty
+ *                    keeps the fixed order_by
+ *   per_page         records per page, 1-100, default 12
+ *   cache_ttl        seconds this collection's reads stay cached, '' for
+ *                    the site default, 0 for no caching
+ *
+ * Visitor state (search term, filters, sort, page) travels in the GET vars
+ * dvc_q, dvc_f[<column>], dvc_sort and dvc_page. Only columns and sort
+ * options whitelisted in the config are honored; anything else is
+ * ignored silently. Paging follows @odata.nextLink because Dataverse has
+ * no $skip: the links of visited pages are cached per state so a later
+ * page resolves without re-walking from the start. One request follows
+ * at most WBS_DATAVERSE_CONNECT_PAGE_HOPS links, and only states drawn
+ * from a finite value space (no search term, filters on choice, status
+ * and yes/no columns only) are cached at all; everything else is read
+ * live so visitors cannot grow the transient table without bound.
  *
  * Collections registered in code via the wbs_dataverse_connect_collections
@@ -20 +38 @@
  * merged over them, so the admin can override a code-registered key.
  */
+
+const WBS_DATAVERSE_CONNECT_PER_PAGE_DEFAULT = 12;
+const WBS_DATAVERSE_CONNECT_PER_PAGE_MAX     = 100;
+const WBS_DATAVERSE_CONNECT_SEARCH_MAXLEN    = 100;
+const WBS_DATAVERSE_CONNECT_PAGE_MAX         = 1000;
+const WBS_DATAVERSE_CONNECT_PAGE_HOPS        = 10;
+const WBS_DATAVERSE_CONNECT_METADATA_RETRY   = 300;
 
 /** All collections, keyed by collection key. */
@@ -61 +86 @@
 
 /**
+ * A list of logical names from an array or a comma / newline separated
+ * string. Empty entries and duplicates are dropped, order is kept.
+ */
+function wbs_dataverse_connect_logical_list($value) {
+    if (is_string($value)) {
+        $value = preg_split('/[\r\n,]+/', $value);
+    }
+    if (!is_array($value)) {
+        return [];
+    }
+    $out = [];
+    foreach ($value as $item) {
+        if (!is_scalar($item)) {
+            continue;
+        }
+        $name = wbs_dataverse_connect_logical_name(trim((string) $item));
+        if ($name !== '' && !in_array($name, $out, true)) {
+            $out[] = $name;
+        }
+    }
+    return $out;
+}
+
+/**
+ * The first $length characters of a string, cut on character boundaries
+ * so a multibyte character is never split into invalid UTF-8.
+ */
+function wbs_dataverse_connect_truncate($value, $length) {
+    $value = (string) $value;
+    if (function_exists('mb_substr')) {
+        return mb_substr($value, 0, (int) $length, 'UTF-8');
+    }
+    $cut = preg_replace('/^(.{0,' . (int) $length . '}).*$/su', '$1', $value);
+    return $cut === null ? substr($value, 0, (int) $length) : $cut;
+}
+
+/**
+ * One sort option, "column asc" or "column desc", from loose input such
+ * as "Createdon DESC". Missing direction means ascending; '' when the
+ * column is missing.
+ */
+function wbs_dataverse_connect_sort_option($value) {
+    $parts  = preg_split('/\s+/', strtolower(trim((string) $value)));
+    $column = wbs_dataverse_connect_logical_name($parts[0] ?? '');
+    if ($column === '') {
+        return '';
+    }
+    $direction = (($parts[1] ?? 'asc') === 'desc') ? 'desc' : 'asc';
+    return $column . ' ' . $direction;
+}
+
+/** Sort options list from an array or a comma / newline separated string. */
+function wbs_dataverse_connect_sort_list($value) {
+    if (is_string($value)) {
+        $value = preg_split('/[\r\n,]+/', $value);
+    }
+    if (!is_array($value)) {
+        return [];
+    }
+    $out = [];
+    foreach ($value as $item) {
+        if (!is_scalar($item)) {
+            continue;
+        }
+        $option = wbs_dataverse_connect_sort_option($item);
+        if ($option !== '' && !in_array($option, $out, true)) {
+            $out[] = $option;
+        }
+    }
+    return $out;
+}
+
+/** Records per page clamped to 1-100; anything below 1 means $default. */
+function wbs_dataverse_connect_per_page($value, $default = WBS_DATAVERSE_CONNECT_PER_PAGE_DEFAULT) {
+    $value = (int) $value;
+    if ($value < 1) {
+        $value = (int) $default;
+    }
+    return max(1, min(WBS_DATAVERSE_CONNECT_PER_PAGE_MAX, $value));
+}
+
+/** Cache lifetime setting: '' keeps the site default, otherwise seconds >= 0. */
+function wbs_dataverse_connect_normalize_cache_ttl($value) {
+    if ($value === '' || $value === null || $value === false) {
+        return '';
+    }
+    if (is_string($value) && trim($value) === '') {
+        return '';
+    }
+    return max(0, (int) $value);
+}
+
+/**
  * Validate and normalize one collection config. Returns the clean config
  * array or null when a required field is missing.
@@ -67 +185 @@
     if (!is_array($config)) {
         return null;
-    }
-
-    $columns = [];
-    if (isset($config['columns']) && is_array($config['columns'])) {
-        foreach ($config['columns'] as $column) {
-            $column = wbs_dataverse_connect_logical_name($column);
-            if ($column !== '') {
-                $columns[] = $column;
-            }
-        }
     }
 
@@ -85 +193 @@
         'name_column'      => wbs_dataverse_connect_logical_name($config['name_column'] ?? ''),
         'slug_column'      => wbs_dataverse_connect_logical_name($config['slug_column'] ?? ''),
-        'columns'          => array_values(array_unique($columns)),
+        'columns'          => wbs_dataverse_connect_logical_list($config['columns'] ?? []),
         'image_url_column' => wbs_dataverse_connect_logical_name($config['image_url_column'] ?? ''),
         'status_filter'    => sanitize_text_field($config['status_filter'] ?? ''),
         'order_by'         => sanitize_text_field($config['order_by'] ?? ''),
+        'search_columns'   => wbs_dataverse_connect_logical_list($config['search_columns'] ?? []),
+        'filter_columns'   => wbs_dataverse_connect_logical_list($config['filter_columns'] ?? []),
+        'sort_options'     => wbs_dataverse_connect_sort_list($config['sort_options'] ?? []),
+        'per_page'         => wbs_dataverse_connect_per_page($config['per_page'] ?? 0),
+        'cache_ttl'        => wbs_dataverse_connect_normalize_cache_ttl($config['cache_ttl'] ?? ''),
     ];
 
@@ -111 +224 @@
 }
 
-/** $select list for a collection: id, name, slug, image and the configured columns. */
+/**
+ * Name of a column in $select and in the rows Dataverse returns: lookup,
+ * customer and owner columns are exposed as _<column>_value (the bare
+ * logical name is a navigation property $select refuses); every other
+ * column keeps its name. Without metadata the name is kept as is.
+ */
+function wbs_dataverse_connect_value_column($config, $column) {
+    $type = wbs_dataverse_connect_column_type($config, $column);
+    if (in_array($type, ['Lookup', 'Customer', 'Owner'], true)) {
+        return '_' . $column . '_value';
+    }
+    return $column;
+}
+
+/**
+ * Key under which a row carries a column: the name itself when present,
+ * otherwise the _<column>_value form lookups arrive in.
+ */
+function wbs_dataverse_connect_record_key($record, $column) {
+    $record = (array) $record;
+    if (!array_key_exists($column, $record) && array_key_exists('_' . $column . '_value', $record)) {
+        return '_' . $column . '_value';
+    }
+    return $column;
+}
+
+/**
+ * $select list for a collection: id, name, slug, image, the configured
+ * columns and the filter columns (their page values feed the filter
+ * selects of columns without metadata options). Lookups are selected
+ * through their _value property.
+ */
 function wbs_dataverse_connect_collection_select($config) {
     $columns = array_merge(
         [wbs_dataverse_connect_id_column($config), $config['name_column']],
-        $config['columns']
+        $config['columns'],
+        (array) ($config['filter_columns'] ?? [])
     );
     if ($config['slug_column'] !== '') {
@@ -123 +268 @@
         $columns[] = $config['image_url_column'];
     }
-    return implode(',', array_unique($columns));
+    $out = [];
+    foreach (array_unique($columns) as $column) {
+        $out[] = wbs_dataverse_connect_value_column($config, $column);
+    }
+    return implode(',', array_unique($out));
+}
+
+/** Client context of a collection read. */
+function wbs_dataverse_connect_collection_context($config) {
+    return ['type' => 'collection', 'config' => $config];
+}
+
+/** Cache lifetime of a collection's reads: null for the site default. */
+function wbs_dataverse_connect_collection_ttl($config) {
+    $ttl = $config['cache_ttl'] ?? '';
+    return ($ttl === '' || $ttl === null) ? null : max(0, (int) $ttl);
+}
+
+/**
+ * Attribute metadata of a collection's table, memoized per request so a
+ * grid of many cards asks the metadata module once. A failed fetch is
+ * remembered per connection and table for WBS_DATAVERSE_CONNECT_METADATA_RETRY
+ * seconds so an unavailable EntityDefinitions endpoint costs one failed
+ * request per window, not one per page view. [] when metadata is
+ * unavailable; the callers fall back to their heuristics.
+ */
+function wbs_dataverse_connect_collection_attributes($config) {
+    static $memo = [];
+
+    $table = (string) ($config['table'] ?? '');
+    if ($table === '') {
+        return [];
+    }
+    $key = $table . '|' . (string) ($config['key'] ?? '');
+    if (!array_key_exists($key, $memo)) {
+        $context = ['type' => 'metadata', 'config' => $config];
+        $conn    = wbs_dataverse_connect_active_connection($context);
+        $failed  = 'wbsdvc_metaerr' . wbs_dataverse_connect_cache_ver() . '_' . md5((string) ($conn['env_url'] ?? '') . '|' . $table);
+        if (get_transient($failed) !== false) {
+            $memo[$key] = [];
+            return $memo[$key];
+        }
+        $attrs = wbs_dataverse_connect_metadata_attributes($table, $context);
+        if (is_array($attrs) && !is_wp_error($attrs)) {
+            $memo[$key] = $attrs;
+        } else {
+            $memo[$key] = [];
+            set_transient($failed, 1, WBS_DATAVERSE_CONNECT_METADATA_RETRY);
+        }
+    }
+    return $memo[$key];
+}
+
+/** AttributeType of one column, '' when metadata is unavailable. */
+function wbs_dataverse_connect_column_type($config, $column) {
+    $attrs = wbs_dataverse_connect_collection_attributes($config);
+    return isset($attrs[$column]['type']) ? (string) $attrs[$column]['type'] : '';
+}
+
+/**
+ * Columns a collection already exposes through its config: the name
+ * column, the displayed columns, the filter columns and the column of
+ * the admin's order_by. Shortcode attributes may narrow the controls to
+ * these but never reach beyond them, so an author placing a shortcode
+ * cannot publish a column the admin did not whitelist.
+ */
+function wbs_dataverse_connect_exposed_columns($config) {
+    $columns = array_merge(
+        [$config['name_column']],
+        (array) ($config['columns'] ?? []),
+        (array) ($config['filter_columns'] ?? [])
+    );
+    $order = wbs_dataverse_connect_sort_option($config['order_by'] ?? '');
+    if ($order !== '') {
+        $columns[] = explode(' ', $order)[0];
+    }
+    return array_values(array_unique(array_filter($columns, 'strlen')));
+}
+
+/**
+ * Apply the [wbsdvc_collection] attributes that reshape the config:
+ * search ("1"/"0"), filters ("0" or a column list), sort ("0" or a list
+ * of "column asc|desc"), per_page. Filter and sort columns named by the
+ * shortcode are honored only when the config already exposes them (see
+ * wbs_dataverse_connect_exposed_columns; sort also accepts the columns
+ * of the configured sort options); the rest is dropped silently.
+ * Returns the adjusted config; the stored one is untouched.
+ */
+function wbs_dataverse_connect_collection_overrides($config, $args) {
+    $exposed = wbs_dataverse_connect_exposed_columns($config);
+
+    $search = trim((string) ($args['search'] ?? ''));
+    if ($search === '0') {
+        $config['search_columns'] = [];
+    } elseif ($search === '1' && empty($config['search_columns'])) {
+        $config['search_columns'] = [$config['name_column']];
+    }
+
+    $filters = trim((string) ($args['filters'] ?? ''));
+    if ($filters === '0') {
+        $config['filter_columns'] = [];
+    } elseif ($filters !== '' && $filters !== '1') {
+        $config['filter_columns'] = array_values(array_intersect(wbs_dataverse_connect_logical_list($filters), $exposed));
+    }
+
+    $sort = trim((string) ($args['sort'] ?? ''));
+    if ($sort === '0') {
+        $config['sort_options'] = [];
+    } elseif ($sort !== '' && $sort !== '1') {
+        $sortable = $exposed;
+        foreach ((array) ($config['sort_options'] ?? []) as $option) {
+            $sortable[] = explode(' ', $option)[0];
+        }
+        $options = [];
+        foreach (wbs_dataverse_connect_sort_list($sort) as $option) {
+            if (in_array(explode(' ', $option)[0], $sortable, true)) {
+                $options[] = $option;
+            }
+        }
+        $config['sort_options'] = $options;
+    }
+
+    if ((int) ($args['per_page'] ?? 0) > 0) {
+        $config['per_page'] = wbs_dataverse_connect_per_page($args['per_page']);
+    }
+    return $config;
+}
+
+/**
+ * Visitor state of a collection view: q (search term), filters
+ * (column => value, whitelisted columns only), sort (a configured sort
+ * option or ''), page and per_page. $source defaults to the registered
+ * query vars; tests pass an array shaped like $_GET.
+ */
+function wbs_dataverse_connect_collection_state($config, $args = [], $source = null) {
+    if ($source === null) {
+        $source = [
+            'dvc_q'    => get_query_var('dvc_q', ''),
+            'dvc_f'    => get_query_var('dvc_f', []),
+            'dvc_sort' => get_query_var('dvc_sort', ''),
+            'dvc_page' => get_query_var('dvc_page', ''),
+        ];
+    }
+
+    $q = '';
+    if (!empty($config['search_columns']) && isset($source['dvc_q']) && is_scalar($source['dvc_q'])) {
+        $q = trim(wbs_dataverse_connect_truncate(sanitize_text_field((string) $source['dvc_q']), WBS_DATAVERSE_CONNECT_SEARCH_MAXLEN));
+    }
+
+    $filters = [];
+    $raw = isset($source['dvc_f']) && is_array($source['dvc_f']) ? $source['dvc_f'] : [];
+    foreach ((array) ($config['filter_columns'] ?? []) as $column) {
+        if (!isset($raw[$column]) || !is_scalar($raw[$column])) {
+            continue;
+        }
+        $value = trim(sanitize_text_field((string) $raw[$column]));
+        if ($value !== '') {
+            $filters[$column] = wbs_dataverse_connect_truncate($value, 200);
+        }
+    }
+
+    $sort = '';
+    if (isset($source['dvc_sort']) && is_scalar($source['dvc_sort'])) {
+        $candidate = wbs_dataverse_connect_sort_option($source['dvc_sort']);
+        if ($candidate !== '' && in_array($candidate, (array) ($config['sort_options'] ?? []), true)) {
+            $sort = $candidate;
+        }
+    }
+
+    $page = isset($source['dvc_page']) && is_scalar($source['dvc_page']) ? (int) $source['dvc_page'] : 1;
+
+    return [
+        'q'        => $q,
+        'filters'  => $filters,
+        'sort'     => $sort,
+        'page'     => max(1, min(WBS_DATAVERSE_CONNECT_PAGE_MAX, $page)),
+        'per_page' => wbs_dataverse_connect_per_page($args['per_page'] ?? 0, $config['per_page'] ?? WBS_DATAVERSE_CONNECT_PER_PAGE_DEFAULT),
+    ];
+}
+
+/** Whether the visitor narrowed or re-sorted the view. */
+function wbs_dataverse_connect_state_active($state) {
+    return ($state['q'] ?? '') !== '' || !empty($state['filters']) || ($state['sort'] ?? '') !== '';
+}
+
+/**
+ * The GET args that reproduce a state (page excluded), ready for
+ * add_query_arg. Empty parts are left out so URLs stay short.
+ */
+function wbs_dataverse_connect_state_args($state) {
+    $args = [];
+    if (($state['q'] ?? '') !== '') {
+        $args['dvc_q'] = $state['q'];
+    }
+    if (!empty($state['filters'])) {
+        $args['dvc_f'] = $state['filters'];
+    }
+    if (($state['sort'] ?? '') !== '') {
+        $args['dvc_sort'] = $state['sort'];
+    }
+    return $args;
+}
+
+/** Lowercase GUID from loose input, '' when it is not one. */
+function wbs_dataverse_connect_guid($value) {
+    $guid = strtolower(preg_replace('/[^0-9a-fA-F\-]/', '', (string) $value));
+    return strlen($guid) === 36 ? $guid : '';
+}
+
+/**
+ * OData comparison for one filter value, typed by the column metadata:
+ * whole numbers for Picklist, State, Status and integers, plain numbers
+ * for Decimal, Double and Money, true/false for Boolean, GUIDs for lookups
+ * and identifiers, ContainValues for multi-select choices, a quoted
+ * string otherwise. Without metadata statecode and statuscode are treated
+ * as numbers and the literals true/false as booleans. '' means the value
+ * does not fit the column and the filter is skipped.
+ */
+function wbs_dataverse_connect_filter_expression($config, $column, $value) {
+    $value = trim((string) $value);
+    if ($value === '') {
+        return '';
+    }
+    $type = wbs_dataverse_connect_column_type($config, $column);
+    if ($type === '') {
+        if (in_array($column, ['statecode', 'statuscode'], true)) {
+            $type = 'State';
+        } elseif ($value === 'true' || $value === 'false') {
+            $type = 'Boolean';
+        }
+    }
+
+    switch ($type) {
+        case 'Picklist':
+        case 'State':
+        case 'Status':
+        case 'Integer':
+        case 'BigInt':
+            return preg_match('/^-?\d+$/', $value) ? $column . ' eq ' . $value : '';
+        case 'Decimal':
+        case 'Double':
+        case 'Money':
+            return preg_match('/^-?\d+(\.\d+)?$/', $value) ? $column . ' eq ' . $value : '';
+        case 'Boolean':
+            if ($value === '1' || $value === 'true') {
+                return $column . ' eq true';
+            }
+            if ($value === '0' || $value === 'false') {
+                return $column . ' eq false';
+            }
+            return '';
+        case 'Lookup':
+        case 'Customer':
+        case 'Owner':
+            $guid = wbs_dataverse_connect_guid($value);
+            return $guid !== '' ? '_' . $column . '_value eq ' . $guid : '';
+        case 'Uniqueidentifier':
+            $guid = wbs_dataverse_connect_guid($value);
+            return $guid !== '' ? $column . ' eq ' . $guid : '';
+        case 'MultiSelectPicklist':
+            return preg_match('/^-?\d+$/', $value)
+                ? "Microsoft.Dynamics.CRM.ContainValues(PropertyName='" . $column . "',PropertyValues=['" . $value . "'])"
+                : '';
+    }
+    return $column . " eq '" . wbs_dataverse_connect_odata_str($value) . "'";
+}
+
+/**
+ * Combined $filter of a state: the status filter first, then the search
+ * (contains() OR-joined over the search columns), then one comparison per
+ * filter value, all ANDed. '' when nothing applies.
+ */
+function wbs_dataverse_connect_collection_filter($config, $state) {
+    $parts = [];
+    if ($config['status_filter'] !== '') {
+        $parts[] = '(' . $config['status_filter'] . ')';
+    }
+
+    $q = (string) ($state['q'] ?? '');
+    if ($q !== '' && !empty($config['search_columns'])) {
+        $term = wbs_dataverse_connect_odata_str($q);
+        $contains = [];
+        foreach ($config['search_columns'] as $column) {
+            $contains[] = 'contains(' . $column . ",'" . $term . "')";
+        }
+        $parts[] = '(' . implode(' or ', $contains) . ')';
+    }
+
+    foreach ((array) ($state['filters'] ?? []) as $column => $value) {
+        if (!in_array($column, (array) ($config['filter_columns'] ?? []), true)) {
+            continue;
+        }
+        $expression = wbs_dataverse_connect_filter_expression($config, $column, $value);
+        if ($expression !== '') {
+            $parts[] = $expression;
+        }
+    }
+    $access = wbs_dataverse_connect_access_filter($config, 'list');
+    if ($access !== '') {
+        $parts[] = '(' . $access . ')';
+    }
+    return implode(' and ', $parts);
+}
+
+/**
+ * $orderby of a state: the chosen sort option, else order_by, else
+ * createdon desc. The primary key is appended as a tiebreaker unless the
+ * order already names it, so pages never overlap on equal values.
+ */
+function wbs_dataverse_connect_collection_order($config, $state) {
+    $order = (string) ($state['sort'] ?? '');
+    if ($order === '') {
+        $order = $config['order_by'] !== '' ? $config['order_by'] : 'createdon desc';
+    }
+    $id = wbs_dataverse_connect_id_column($config);
+    if (!preg_match('/(^|,)\s*' . preg_quote($id, '/') . '(\s|,|$)/', $order)) {
+        $order .= ',' . $id . ' asc';
+    }
+    return $order;
+}
+
+/**
+ * OData path of the first page of a state: entity set, $select, $filter,
+ * $orderby, $top and $count. Later pages follow the nextLink Dataverse
+ * returns, so this is only ever built for page one.
+ */
+function wbs_dataverse_connect_collection_query($config, $state) {
+    $state = array_merge(['q' => '', 'filters' => [], 'sort' => '', 'page' => 1, 'per_page' => $config['per_page'] ?? WBS_DATAVERSE_CONNECT_PER_PAGE_DEFAULT], (array) $state);
+
+    $path = $config['entity_set'] . '?$select=' . wbs_dataverse_connect_collection_select($config);
+    $filter = wbs_dataverse_connect_collection_filter($config, $state);
+    if ($filter !== '') {
+        $path .= '&$filter=' . rawurlencode($filter);
+    }
+    // No $top: Dataverse omits the nextLink once $top is satisfied, so a
+    // $top equal to the page size would make page two unreachable. The page
+    // size travels as Prefer: odata.maxpagesize (see _collection_page).
+    $path .= '&$orderby=' . rawurlencode(wbs_dataverse_connect_collection_order($config, $state))
+        . '&$count=true';
+    return $path;
+}
+
+/**
+ * Whether a state may be persisted (response cache and page links).
+ * Only states drawn from a finite value space are: no search term, and
+ * every filter either a yes/no column or a choice, state, status or
+ * multi-select column whose value is one of its metadata options. A
+ * search term or a filter on any other column (free text, numbers,
+ * lookups) is read live, so a crawler cycling values cannot fill the
+ * transient table.
+ */
+function wbs_dataverse_connect_state_cacheable($config, $state) {
+    if (($state['q'] ?? '') !== '') {
+        return false;
+    }
+    $attrs = wbs_dataverse_connect_collection_attributes($config);
+    foreach ((array) ($state['filters'] ?? []) as $column => $value) {
+        $type = isset($attrs[$column]['type']) ? (string) $attrs[$column]['type'] : '';
+        if ($type === 'Boolean') {
+            continue;
+        }
+        if (in_array($type, ['Picklist', 'State', 'Status', 'MultiSelectPicklist'], true)
+            && !empty($attrs[$column]['options'])
+            && isset($attrs[$column]['options'][(string) $value])) {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+
+/** Transient key holding the page links and count of one state. */
+function wbs_dataverse_connect_state_key($config, $state) {
+    $conn = wbs_dataverse_connect_active_connection(wbs_dataverse_connect_collection_context($config));
+    return 'wbsdvc_p' . wbs_dataverse_connect_cache_ver() . '_' . md5(
+        (string) ($conn['env_url'] ?? '') . '|' . $config['key'] . '|' . wbs_dataverse_connect_collection_query($config, $state)
+    );
+}
+
+/**
+ * Path relative to the api base from an absolute @odata.nextLink, ''
+ * when the link does not point at the Web API.
+ */
+function wbs_dataverse_connect_link_path($link) {
+    if (preg_match('#/api/data/v[0-9.]+/(.+)$#i', (string) $link, $m)) {
+        return $m[1];
+    }
+    return '';
+}
+
+/** Pages a result set spans by its count, or $fallback when the count is unknown or capped. */
+function wbs_dataverse_connect_page_limit($count, $per_page, $fallback) {
+    if ($count === null || (int) $count >= 5000) {
+        return $fallback;
+    }
+    return max(1, (int) ceil((int) $count / max(1, (int) $per_page)));
+}
+
+/**
+ * One page of a collection for a state. Page one is the query itself;
+ * page N follows the nextLinks, starting from the nearest link cached for
+ * this state. When fewer pages exist the last reachable page is returned
+ * (its 'page' tells which): the wanted page is clamped to the pages the
+ * count allows as soon as it is known, and one request follows at most
+ * WBS_DATAVERSE_CONNECT_PAGE_HOPS links, so a far page on an uncached
+ * state costs a bounded number of round trips. Returns
+ * ['records', 'page', 'per_page', 'has_prev', 'has_next', 'count'] or
+ * WP_Error; count is null until Dataverse reports it (it caps at 5000).
+ */
+function wbs_dataverse_connect_collection_page($config, $state) {
+    $per_page = wbs_dataverse_connect_per_page($state['per_page'] ?? 0, $config['per_page'] ?? WBS_DATAVERSE_CONNECT_PER_PAGE_DEFAULT);
+    $want     = max(1, (int) ($state['page'] ?? 1));
+
+    $context = wbs_dataverse_connect_collection_context($config);
+    $context['headers'] = [
+        'Prefer' => 'odata.include-annotations="OData.Community.Display.V1.FormattedValue",odata.maxpagesize=' . $per_page,
+    ];
+    $ttl       = wbs_dataverse_connect_collection_ttl($config);
+    $store_ttl = ($ttl === null) ? wbs_dataverse_connect_cache_ttl() : $ttl;
+    if (!wbs_dataverse_connect_state_cacheable($config, $state)) {
+        $ttl       = 0;
+        $store_ttl = 0;
+    }
+
+    $links = [];
+    $count = null;
+    $key   = wbs_dataverse_connect_state_key($config, $state);
+    if ($store_ttl > 0) {
+        $stored = get_transient($key);
+        if (is_array($stored)) {
+            $links = is_array($stored['links'] ?? null) ? $stored['links'] : [];
+            $count = isset($stored['count']) ? (int) $stored['count'] : null;
+            $want  = min($want, wbs_dataverse_connect_page_limit($count, $per_page, $want));
+        }
+    }
+
+    $page = 1;
+    $path = wbs_dataverse_connect_collection_query($config, $state);
+    for ($p = $want; $p >= 2; $p--) {
+        if (!empty($links[$p])) {
+            $page = $p;
+            $path = (string) $links[$p];
+            break;
+        }
+    }
+
+    $records = [];
+    $next    = '';
+    $dirty   = false;
+    $hops    = 0;
+    while (true) {
+        $body = wbs_dataverse_connect_get($path, $ttl, $context);
+        if (is_wp_error($body)) {
+            return $body;
+        }
+        $hops++;
+        $records = (isset($body['value']) && is_array($body['value'])) ? $body['value'] : [];
+        if (isset($body['@odata.count']) && (int) $body['@odata.count'] !== $count) {
+            $count = (int) $body['@odata.count'];
+            $dirty = true;
+        }
+        $want = min($want, wbs_dataverse_connect_page_limit($count, $per_page, $want));
+        $next = wbs_dataverse_connect_link_path($body['@odata.nextLink'] ?? '');
+        if ($next !== '' && (($links[$page + 1] ?? '') !== $next)) {
+            $links[$page + 1] = $next;
+            $dirty = true;
+        }
+        if ($page >= $want || $next === '' || $hops >= WBS_DATAVERSE_CONNECT_PAGE_HOPS) {
+            break;
+        }
+        $page++;
+        $path = $next;
+    }
+
+    if ($dirty && $store_ttl > 0) {
+        set_transient($key, ['links' => $links, 'count' => $count], $store_ttl);
+    }
+
+    return [
+        'records'  => $records,
+        'page'     => $page,
+        'per_page' => $per_page,
+        'has_prev' => $page > 1,
+        'has_next' => $next !== '',
+        'count'    => $count,
+    ];
 }
 
 /**
  * Records of a collection, newest first unless order_by says otherwise.
- * Returns an array of rows or WP_Error.
- */
-function wbs_dataverse_connect_get_records($config, $limit = 12) {
-    $order_by = $config['order_by'] !== '' ? $config['order_by'] : 'createdon desc';
-
-    $path = $config['entity_set']
-        . '?$select=' . wbs_dataverse_connect_collection_select($config);
-    if ($config['status_filter'] !== '') {
-        $path .= '&$filter=' . rawurlencode($config['status_filter']);
-    }
-    $path .= '&$orderby=' . rawurlencode($order_by)
-        . '&$top=' . (int) $limit;
-
-    $result = wbs_dataverse_connect_get($path, null, ['type' => 'collection', 'config' => $config]);
-    if (is_wp_error($result)) {
-        return $result;
-    }
-    return isset($result['value']) && is_array($result['value']) ? $result['value'] : [];
+ * The first page of the default state, kept for callers of earlier
+ * versions. Returns an array of rows or WP_Error.
+ */
+function wbs_dataverse_connect_get_records($config, $limit = WBS_DATAVERSE_CONNECT_PER_PAGE_DEFAULT) {
+    $result = wbs_dataverse_connect_collection_page($config, ['per_page' => $limit]);
+    return is_wp_error($result) ? $result : $result['records'];
 }
 
@@ -161 +779 @@
     }
 
-    $guid = strtolower(preg_replace('/[^0-9a-fA-F\-]/', '', $slug));
-    if (strlen($guid) !== 36) {
-        $guid = '';
-    }
+    $guid = wbs_dataverse_connect_guid($slug);
 
     if ($config['slug_column'] !== '') {
@@ -190 +805 @@
         $filter = '(' . $config['status_filter'] . ') and ' . $filter;
     }
+    $access = wbs_dataverse_connect_access_filter($config, 'single');
+    if ($access !== '') {
+        $filter = '(' . $access . ') and ' . $filter;
+    }
 
     $path = $config['entity_set']
@@ -196 +815 @@
         . '&$top=1';
 
-    $result = wbs_dataverse_connect_get($path, null, ['type' => 'collection', 'config' => $config]);
+    $result = wbs_dataverse_connect_get($path, wbs_dataverse_connect_collection_ttl($config), wbs_dataverse_connect_collection_context($config));
     if (is_wp_error($result)) {
         return $result;
@@ -212 +831 @@
  */
 function wbs_dataverse_connect_display_value($record, $column) {
-    $formatted = $record[$column . '@OData.Community.Display.V1.FormattedValue'] ?? null;
+    $key       = wbs_dataverse_connect_record_key($record, $column);
+    $formatted = $record[$key . '@OData.Community.Display.V1.FormattedValue'] ?? null;
     if (is_string($formatted) && $formatted !== '') {
         return $formatted;
     }
-    $value = $record[$column] ?? '';
+    $value = $record[$key] ?? '';
     if (is_bool($value)) {
         return $value ? __('Yes', 'wbs-connect-for-dataverse') : __('No', 'wbs-connect-for-dataverse');
@@ -224 +844 @@
 
 /**
- * Human label for a column: the table's publisher prefix is stripped,
- * underscores become spaces, words are capitalized. wbs_locationtext on
- * wbs_listing becomes "Locationtext". Override per column with the
- * wbs_dataverse_connect_field_label filter.
+ * Human label for a column: the display name from the table metadata
+ * when available, otherwise a guess from the logical name (the table's
+ * publisher prefix is stripped, underscores become spaces, words are
+ * capitalized: wbs_locationtext on wbs_listing becomes "Locationtext").
+ * Override per column with the wbs_dataverse_connect_field_label filter.
  */
 function wbs_dataverse_connect_field_label($config, $column) {
-    $label = $column;
-    $pos = strpos($config['table'], '_');
-    if ($pos !== false) {
-        $prefix = substr($config['table'], 0, $pos + 1);
-        if (strpos($label, $prefix) === 0) {
-            $label = substr($label, strlen($prefix));
-        }
-    }
-    $label = ucwords(str_replace('_', ' ', $label));
+    $attrs = wbs_dataverse_connect_collection_attributes($config);
+    $label = isset($attrs[$column]['label']) ? trim((string) $attrs[$column]['label']) : '';
+
+    if ($label === '') {
+        $label = $column;
+        $pos = strpos((string) ($config['table'] ?? ''), '_');
+        if ($pos !== false) {
+            $prefix = substr($config['table'], 0, $pos + 1);
+            if (strpos($label, $prefix) === 0) {
+                $label = substr($label, strlen($prefix));
+            }
+        }
+        $label = ucwords(str_replace('_', ' ', $label));
+    }
+
+    /**
+     * The label shown for a column in cards, detail tables and the toolbar.
+     *
+     * @param string $label  Metadata display name or the heuristic label.
+     * @param string $column Column logical name.
+     * @param array  $config The collection config.
+     */
     return apply_filters('wbs_dataverse_connect_field_label', $label, $column, $config);
+}
+
+/**
+ * Options of one filter select as value => label. Choice, state, status,
+ * yes/no and multi-select columns list every option from the metadata.
+ * Other columns list the distinct values found in $records, which is the
+ * current page only: a value that occurs on a later page is not offered
+ * until the visitor reaches it. Labels are the formatted display values;
+ * lookups are offered by id with the referenced record's name as label.
+ */
+function wbs_dataverse_connect_filter_options($config, $column, $records) {
+    $attrs = wbs_dataverse_connect_collection_attributes($config);
+    $type  = isset($attrs[$column]['type']) ? (string) $attrs[$column]['type'] : '';
+    if (in_array($type, ['Picklist', 'State', 'Status', 'Boolean', 'MultiSelectPicklist'], true) && !empty($attrs[$column]['options'])) {
+        $out = [];
+        foreach ((array) $attrs[$column]['options'] as $value => $label) {
+            $label = (string) $label;
+            $out[(string) $value] = $label !== '' ? $label : (string) $value;
+        }
+        return $out;
+    }
+
+    $out = [];
+    foreach ((array) $records as $record) {
+        if (!is_array($record)) {
+            continue;
+        }
+        $key = wbs_dataverse_connect_record_key($record, $column);
+        if (!isset($record[$key]) || !is_scalar($record[$key])) {
+            continue;
+        }
+        $raw = $record[$key];
+        if (is_bool($raw)) {
+            $value = $raw ? 'true' : 'false';
+        } else {
+            $value = trim((string) $raw);
+        }
+        if ($value === '' || isset($out[$value])) {
+            continue;
+        }
+        $label = wbs_dataverse_connect_display_value($record, $column);
+        $out[$value] = $label !== '' ? $label : $value;
+    }
+    natcasesort($out);
+    return $out;
+}
+
+/** Sort choices of a collection as option value => visitor label. */
+function wbs_dataverse_connect_sort_choices($config) {
+    $out = [];
+    foreach ((array) ($config['sort_options'] ?? []) as $option) {
+        $parts = explode(' ', $option);
+        $label = wbs_dataverse_connect_field_label($config, $parts[0]);
+        $out[$option] = (($parts[1] ?? 'asc') === 'desc')
+            /* translators: %s: column label. */
+            ? sprintf(__('%s (descending)', 'wbs-connect-for-dataverse'), $label)
+            /* translators: %s: column label. */
+            : sprintf(__('%s (ascending)', 'wbs-connect-for-dataverse'), $label);
+    }
+    return $out;
 }
 
@@ -293 +987 @@
     return apply_filters('wbs_dataverse_connect_record_vm', $vm, $config, $record);
 }
+
+/** The visitor-state query vars WordPress should recognize. */
+function wbs_dataverse_connect_reading_query_vars($vars) {
+    foreach (['dvc_q', 'dvc_f', 'dvc_sort', 'dvc_page'] as $var) {
+        if (!in_array($var, $vars, true)) {
+            $vars[] = $var;
+        }
+    }
+    return $vars;
+}
+add_filter('query_vars', 'wbs_dataverse_connect_reading_query_vars');
+
+/** Extra rows of the collection edit form: search, filters, sort, paging, cache. */
+function wbs_dataverse_connect_collection_reading_fields($editing) {
+    $search   = $editing !== null ? implode("\n", (array) ($editing['search_columns'] ?? [])) : '';
+    $filters  = $editing !== null ? implode("\n", (array) ($editing['filter_columns'] ?? [])) : '';
+    $sorts    = $editing !== null ? implode("\n", (array) ($editing['sort_options'] ?? [])) : '';
+    $per_page = $editing !== null ? (int) ($editing['per_page'] ?? WBS_DATAVERSE_CONNECT_PER_PAGE_DEFAULT) : WBS_DATAVERSE_CONNECT_PER_PAGE_DEFAULT;
+    $ttl      = $editing !== null ? ($editing['cache_ttl'] ?? '') : '';
+    ?>
+    <tr>
+        <th scope="row"><label for="dvc_search_columns"><?php esc_html_e('Search columns', 'wbs-connect-for-dataverse'); ?></label></th>
+        <td><textarea id="dvc_search_columns" name="dvc_search_columns" class="regular-text" rows="3"><?php echo esc_textarea($search); ?></textarea>
+            <p class="description"><?php esc_html_e('Text columns the visitor search box matches, one per line. Leave empty to hide the search box.', 'wbs-connect-for-dataverse'); ?></p></td>
+    </tr>
+    <tr>
+        <th scope="row"><label for="dvc_filter_columns"><?php esc_html_e('Filter columns', 'wbs-connect-for-dataverse'); ?></label></th>
+        <td><textarea id="dvc_filter_columns" name="dvc_filter_columns" class="regular-text" rows="3"><?php echo esc_textarea($filters); ?></textarea>
+            <p class="description"><?php esc_html_e('Columns offered as filter dropdowns, one per line. Choice, status and yes/no columns list all their options; other columns list the values found on the current page only.', 'wbs-connect-for-dataverse'); ?></p></td>
+    </tr>
+    <tr>
+        <th scope="row"><label for="dvc_sort_options"><?php esc_html_e('Sort options', 'wbs-connect-for-dataverse'); ?></label></th>
+        <td><textarea id="dvc_sort_options" name="dvc_sort_options" class="regular-text" rows="3" placeholder="createdon desc"><?php echo esc_textarea($sorts); ?></textarea>
+            <p class="description"><?php esc_html_e('Sort choices offered to visitors, one per line as column and direction, for example createdon desc. Leave empty to keep the fixed order.', 'wbs-connect-for-dataverse'); ?></p></td>
+    </tr>
+    <tr>
+        <th scope="row"><label for="dvc_per_page"><?php esc_html_e('Records per page', 'wbs-connect-for-dataverse'); ?></label></th>
+        <td><input type="number" id="dvc_per_page" name="dvc_per_page" class="small-text" min="1" max="<?php echo (int) WBS_DATAVERSE_CONNECT_PER_PAGE_MAX; ?>"
+                   value="<?php echo (int) $per_page; ?>">
+            <p class="description"><?php esc_html_e('1 to 100, default 12. A limit or per_page attribute on the shortcode takes precedence.', 'wbs-connect-for-dataverse'); ?></p></td>
+    </tr>
+    <tr>
+        <th scope="row"><label for="dvc_cache_ttl"><?php esc_html_e('Cache lifetime (seconds)', 'wbs-connect-for-dataverse'); ?></label></th>
+        <td><input type="number" id="dvc_cache_ttl" name="dvc_cache_ttl" class="small-text" min="0"
+                   value="<?php echo esc_attr((string) $ttl); ?>">
+            <p class="description"><?php esc_html_e('How long this collection stays cached. Leave empty for the site default, 0 to disable caching for this collection.', 'wbs-connect-for-dataverse'); ?></p></td>
+    </tr>
+    <?php
+}
+add_action('wbs_dataverse_connect_collection_fields', 'wbs_dataverse_connect_collection_reading_fields');
+
+/** Attach the posted reading rows to the collection config being saved. */
+function wbs_dataverse_connect_save_collection_reading($config, $post) {
+    $config['search_columns'] = wbs_dataverse_connect_logical_list($post['dvc_search_columns'] ?? '');
+    $config['filter_columns'] = wbs_dataverse_connect_logical_list($post['dvc_filter_columns'] ?? '');
+    $config['sort_options']   = wbs_dataverse_connect_sort_list($post['dvc_sort_options'] ?? '');
+    $config['per_page']       = wbs_dataverse_connect_per_page($post['dvc_per_page'] ?? 0);
+    $config['cache_ttl']      = wbs_dataverse_connect_normalize_cache_ttl(is_scalar($post['dvc_cache_ttl'] ?? '') ? $post['dvc_cache_ttl'] : '');
+    return $config;
+}
+add_filter('wbs_dataverse_connect_save_collection', 'wbs_dataverse_connect_save_collection_reading', 10, 2);
+
+/**
+ * Extra OData restriction applied to every read of a collection, for
+ * example "only records owned by the signed-in visitor". Empty by default;
+ * add-ons return an expression that is ANDed with the status filter for
+ * both the grid ($scope 'list') and single-record lookups ($scope 'single'),
+ * so a direct link, a media request or a form bound to a hidden record all
+ * see the same restriction.
+ */
+function wbs_dataverse_connect_access_filter($config, $scope) {
+    /**
+     * Restrict which records of a collection are readable at all.
+     *
+     * @param string $expression OData filter expression, '' for none.
+     * @param array  $config     The collection config.
+     * @param string $scope      'list' or 'single'.
+     */
+    $expression = apply_filters('wbs_dataverse_connect_access_filter', '', $config, $scope);
+    return is_string($expression) ? trim($expression) : '';
+}
+
+/**
+ * Whether the current visitor may see a collection, a record, a form or a
+ * media file at all. True unless an add-on says otherwise (for example a
+ * collection that requires sign-in). $config is the collection or form
+ * config, $scope one of 'collection', 'record', 'form', 'media'.
+ */
+function wbs_dataverse_connect_can_view($config, $scope) {
+    /**
+     * Gate a collection, record, form or media file for the current visitor.
+     *
+     * @param bool   $allowed True to render, false to refuse.
+     * @param array  $config  Collection or form config.
+     * @param string $scope   'collection', 'record', 'form' or 'media'.
+     */
+    return (bool) apply_filters('wbs_dataverse_connect_can_view', true, $config, $scope);
+}
+
+/** Notice shown in place of gated content. Add-ons replace it with a sign-in prompt. */
+function wbs_dataverse_connect_denied_notice($config, $scope) {
+    $html = '<div class="dvc-notice dvc-notice--denied">'
+        . esc_html__('Please sign in to view this content.', 'wbs-connect-for-dataverse')
+        . '</div>';
+    /**
+     * Markup rendered when wbs_dataverse_connect_can_view refused.
+     *
+     * @param string $html   Default notice.
+     * @param array  $config Collection or form config.
+     * @param string $scope  'collection', 'record' or 'form'.
+     */
+    return apply_filters('wbs_dataverse_connect_denied_notice', $html, $config, $scope);
+}

wbs-connect-for-dataverse/trunk/includes/dataverse.php

@@ -48 +48 @@
  * wbs_dataverse_connect_active_connection). Sets Prefer so responses
  * carry formatted-value annotations (choices, money, dates, lookups)
- * alongside the raw values. Returns the decoded array or WP_Error.
+ * alongside the raw values; $context['headers'] (name => value) is merged
+ * over the request headers, which is how paging passes its Prefer.
+ * Metadata reads ($context['type'] 'metadata') do not touch the health
+ * state: they are optional and fall back to heuristics, so a failing
+ * EntityDefinitions endpoint next to working data reads must not raise
+ * and clear alerts in turn. Returns the decoded array or WP_Error.
  */
 function wbs_dataverse_connect_get($path, $ttl = null, $context = []) {
-    $conn = wbs_dataverse_connect_active_connection($context);
+    $conn  = wbs_dataverse_connect_active_connection($context);
+    $track = (($context['type'] ?? '') !== 'metadata');
     $ttl = ($ttl === null) ? wbs_dataverse_connect_cache_ttl() : (int) $ttl;
-    $key = 'wbsdvc_c' . wbs_dataverse_connect_cache_ver() . '_' . md5($conn['env_url'] . '|' . $path);
+    $key = 'wbsdvc_c' . wbs_dataverse_connect_cache_ver() . '_' . md5($conn['env_url'] . '|' . $path . '|' . wp_json_encode($context['headers'] ?? []));
 
     if ($ttl > 0) {
@@ -69 +75 @@
     $headers = wbs_dataverse_connect_default_headers($token);
     $headers['Prefer'] = 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"';
+    $headers = array_merge($headers, (array) ($context['headers'] ?? []));
 
     $resp = wp_remote_get(wbs_dataverse_connect_api_base($conn) . $path, [
@@ -84 +91 @@
             )
         );
-        wbs_dataverse_connect_health_failure('network', $error->get_error_message());
+        if ($track) {
+            wbs_dataverse_connect_health_failure('network', $error->get_error_message());
+        }
         return $error;
     }
@@ -97 +106 @@
     if ($code >= 400 || !is_array($body)) {
         $detail = wbs_dataverse_connect_error_detail($body, $code);
-        if (wbs_dataverse_connect_health_relevant_status($code)) {
+        if ($track && wbs_dataverse_connect_health_relevant_status($code)) {
             wbs_dataverse_connect_health_failure('api', $detail);
         }
@@ -103 +112 @@
     }
 
-    wbs_dataverse_connect_health_success();
+    if ($track) {
+        wbs_dataverse_connect_health_success();
+    }
     if ($ttl > 0) {
         set_transient($key, $body, $ttl);
@@ -118 +129 @@
  */
 function wbs_dataverse_connect_post($path, $body, $context = []) {
+    return wbs_dataverse_connect_write('POST', $path, $body, $context);
+}
+
+/**
+ * Uncached PATCH (update) of one record, $path being the addressed
+ * record such as "contacts(guid)". Same contract as
+ * wbs_dataverse_connect_post: ['id' => guid] on success, WP_Error
+ * otherwise. Callers that must never create through an upsert pass
+ * ['headers' => ['If-Match' => '*']] in $context.
+ */
+function wbs_dataverse_connect_patch($path, $body, $context = []) {
+    return wbs_dataverse_connect_write('PATCH', $path, $body, $context);
+}
+
+/** Shared body of the two write methods. Never cached. */
+function wbs_dataverse_connect_write($method, $path, $body, $context = []) {
     $conn = wbs_dataverse_connect_active_connection($context);
     $where = (($context['type'] ?? '') === 'form' && isset($context['config']['key']))
@@ -130 +157 @@
     $headers = wbs_dataverse_connect_default_headers($token);
     $headers['Content-Type'] = 'application/json; charset=utf-8';
-
-    $resp = wp_remote_post(wbs_dataverse_connect_api_base($conn) . $path, [
+    $headers = array_merge($headers, (array) ($context['headers'] ?? []));
+
+    $resp = wp_remote_request(wbs_dataverse_connect_api_base($conn) . $path, [
+        'method'  => $method,
         'timeout' => 15,
         'headers' => $headers,

wbs-connect-for-dataverse/trunk/includes/forms.php

@@ -3 +3 @@
 
 /**
- * Forms: the generalized write path. A form is a named mapping from
- * submitted fields to columns of one Dataverse table:
+ * Forms: the generalized write path. A form is a named, typed mapping
+ * from submitted fields to columns of one Dataverse table:
  *
  *   key             unique handle used in [wbsdvc_form name="..."]
- *   table           logical name of the target table
- *   entity_set      plural entity set name the create is POSTed to
- *   field_map       submitted field name => column logical name
- *   required        submitted field names that must be filled in
+ *   table           logical name of the target table (metadata source)
+ *   entity_set      plural entity set name the write goes to
+ *   fields          ordered list of typed fields, each
+ *                     name         submitted field name
+ *                     column       column logical name
+ *                     type         text|email|phone|textarea|number|money|date|
+ *                                  datetime|choice|multichoice|boolean|lookup|hidden
+ *                     label        '' means metadata label, then a prettified name
+ *                     required     bool; metadata can add to it, never remove
+ *                     options      value => label for choice/multichoice when
+ *                                  metadata is unavailable or should be narrowed
+ *                     lookup_table, lookup_entity_set, lookup_name_column,
+ *                     lookup_nav   for lookup fields (resolve-by-name and bind)
+ *                     default      value of a hidden field, initial value otherwise
+ *   field_map       derived view: submitted field name => column logical name
+ *   required        derived view: submitted field names that must be filled in
  *   require_consent whether the consent checkbox is shown and enforced
  *   relate_to       optional ['nav' => lookup navigation property (schema
  *                   name casing), 'collection' => collection key] binding a
- *                   submission to the record it came from
+ *                   created record to the record the form was shown on
+ *   mode            create (POST a new record) or update (PATCH the record
+ *                   the page is bound to via ?dvc=<slug> or the shortcode)
+ *   bind_to         collection key the update mode resolves and checks the
+ *                   record through; falls back to relate_to's collection
+ *   success_message message shown after a successful write, '' = default
+ *   redirect_url    same-host URL the visitor is sent to after success
+ *   turnstile       whether Cloudflare Turnstile is required on this form
  *
- * v1 maps submitted values to text columns; the relate_to lookup bind is
- * the one exception. Choices, booleans and other typed columns are left
- * to the wbs_dataverse_connect_form_record filter.
+ * Configs saved before 1.5 only carry field_map and required; they are
+ * upgraded on normalization (every entry becomes a text field, email,
+ * phone and message keep their special types), so nothing changes for
+ * existing sites.
  *
  * Same merge order as collections: the wbs_dataverse_connect_forms filter
  * first, the settings page over it.
- */
+ *
+ * Turnstile keys are site-wide options (wbs_dataverse_connect_turnstile_site_key
+ * and _secret_key). The plugin's own settings screen is not editable from
+ * this module, so the keys are entered inside the form editor rows and
+ * stored as options from the save hook; every form shares them.
+ */
+
+const WBS_DATAVERSE_CONNECT_LOOKUP_CAP = 200;
 
 /** All forms, keyed by form key. */
@@ -63 +90 @@
 }
 
+/** Field types a form can render and type, type => label. */
+function wbs_dataverse_connect_field_types() {
+    return [
+        'text'        => __('Text', 'wbs-connect-for-dataverse'),
+        'email'       => __('Email', 'wbs-connect-for-dataverse'),
+        'phone'       => __('Phone', 'wbs-connect-for-dataverse'),
+        'textarea'    => __('Multi-line text', 'wbs-connect-for-dataverse'),
+        'number'      => __('Number', 'wbs-connect-for-dataverse'),
+        'money'       => __('Money', 'wbs-connect-for-dataverse'),
+        'date'        => __('Date', 'wbs-connect-for-dataverse'),
+        'datetime'    => __('Date and time', 'wbs-connect-for-dataverse'),
+        'choice'      => __('Choice', 'wbs-connect-for-dataverse'),
+        'multichoice' => __('Multi-select choice', 'wbs-connect-for-dataverse'),
+        'boolean'     => __('Yes/no', 'wbs-connect-for-dataverse'),
+        'lookup'      => __('Lookup', 'wbs-connect-for-dataverse'),
+        'hidden'      => __('Hidden (fixed value)', 'wbs-connect-for-dataverse'),
+    ];
+}
+
+/**
+ * Parse "key = value" lines into an assoc array. A line without "=" is
+ * kept with an empty value so a bare option value still counts.
+ */
+function wbs_dataverse_connect_parse_pairs($text) {
+    $out = [];
+    foreach (preg_split('/[\r\n]+/', (string) $text) as $line) {
+        $line = trim($line);
+        if ($line === '') {
+            continue;
+        }
+        if (strpos($line, '=') === false) {
+            $out[$line] = '';
+            continue;
+        }
+        list($k, $v) = array_map('trim', explode('=', $line, 2));
+        if ($k !== '') {
+            $out[$k] = $v;
+        }
+    }
+    return $out;
+}
+
+/**
+ * Validate and normalize one field spec. Returns the clean field or null
+ * when name or column is missing. The field name defaults to the column.
+ */
+function wbs_dataverse_connect_normalize_field($raw) {
+    if (!is_array($raw)) {
+        return null;
+    }
+    $column = wbs_dataverse_connect_logical_name($raw['column'] ?? '');
+    $name   = sanitize_key($raw['name'] ?? '');
+    if ($name === '') {
+        $name = sanitize_key($column);
+    }
+    if ($name === '' || $column === '') {
+        return null;
+    }
+
+    $type = sanitize_key($raw['type'] ?? 'text');
+    if (!isset(wbs_dataverse_connect_field_types()[$type])) {
+        $type = 'text';
+    }
+
+    $options = [];
+    if ($type === 'choice' || $type === 'multichoice') {
+        $source = $raw['options'] ?? [];
+        if (is_string($source)) {
+            $source = wbs_dataverse_connect_parse_pairs($source);
+        }
+        foreach ((array) $source as $value => $label) {
+            if (!is_scalar($value) || !is_numeric((string) $value)) {
+                continue;
+            }
+            $label = is_scalar($label) ? sanitize_text_field((string) $label) : '';
+            $options[(int) $value] = $label !== '' ? $label : (string) (int) $value;
+        }
+    }
+
+    $lookup = ['lookup_table' => '', 'lookup_entity_set' => '', 'lookup_name_column' => '', 'lookup_nav' => ''];
+    if ($type === 'lookup') {
+        $source = $raw;
+        // The admin editor carries the lookup facts in the options textarea.
+        if (isset($raw['options']) && is_string($raw['options'])) {
+            $pairs  = wbs_dataverse_connect_parse_pairs($raw['options']);
+            $source = array_merge($raw, [
+                'lookup_table'       => $pairs['table'] ?? ($raw['lookup_table'] ?? ''),
+                'lookup_entity_set'  => $pairs['entity_set'] ?? ($raw['lookup_entity_set'] ?? ''),
+                'lookup_name_column' => $pairs['name_column'] ?? ($raw['lookup_name_column'] ?? ''),
+                'lookup_nav'         => $pairs['nav'] ?? ($raw['lookup_nav'] ?? ''),
+            ]);
+        }
+        $lookup = [
+            'lookup_table'       => wbs_dataverse_connect_logical_name($source['lookup_table'] ?? ''),
+            'lookup_entity_set'  => wbs_dataverse_connect_logical_name($source['lookup_entity_set'] ?? ''),
+            'lookup_name_column' => wbs_dataverse_connect_logical_name($source['lookup_name_column'] ?? ''),
+            'lookup_nav'         => wbs_dataverse_connect_nav_name($source['lookup_nav'] ?? ''),
+        ];
+        if ($lookup['lookup_nav'] === '') {
+            $lookup['lookup_nav'] = $column;
+        }
+    }
+
+    return array_merge([
+        'name'     => $name,
+        'column'   => $column,
+        'type'     => $type,
+        'label'    => sanitize_text_field((string) ($raw['label'] ?? '')),
+        'required' => !empty($raw['required']),
+        'options'  => $options,
+        'default'  => sanitize_text_field((string) ($raw['default'] ?? '')),
+    ], $lookup);
+}
+
+/** Type of a legacy field-map entry, from its conventional name. */
+function wbs_dataverse_connect_legacy_field_type($field) {
+    switch ($field) {
+        case 'email':
+            return 'email';
+        case 'phone':
+            return 'phone';
+        case 'message':
+            return 'textarea';
+    }
+    return 'text';
+}
+
+/**
+ * A same-host redirect target. Accepts an absolute URL on the site's own
+ * host or a path starting with "/". Returns the absolute URL or ''.
+ */
+function wbs_dataverse_connect_form_redirect_url($raw) {
+    $raw = trim((string) $raw);
+    if ($raw === '') {
+        return '';
+    }
+    if ($raw[0] === '/' && (strlen($raw) === 1 || $raw[1] !== '/')) {
+        $raw = home_url($raw);
+    }
+    $url  = esc_url_raw($raw, ['http', 'https']);
+    $host = wp_parse_url($url, PHP_URL_HOST);
+    $home = wp_parse_url(home_url('/'), PHP_URL_HOST);
+    if ($url === '' || !is_string($host) || strcasecmp($host, (string) $home) !== 0) {
+        return '';
+    }
+    return $url;
+}
+
 /**
  * Validate and normalize one form config. Returns the clean config array
@@ -72 +247 @@
     }
 
-    $field_map = [];
-    if (isset($config['field_map']) && is_array($config['field_map'])) {
-        foreach ($config['field_map'] as $field => $column) {
-            $field  = sanitize_key($field);
-            $column = wbs_dataverse_connect_logical_name($column);
-            if ($field !== '' && $column !== '') {
-                $field_map[$field] = $column;
-            }
-        }
-    }
-
-    $required = [];
+    $legacy_required = [];
     if (isset($config['required']) && is_array($config['required'])) {
         foreach ($config['required'] as $field) {
-            $field = sanitize_key($field);
-            if ($field !== '' && isset($field_map[$field])) {
-                $required[] = $field;
-            }
+            $legacy_required[] = sanitize_key($field);
+        }
+    }
+
+    $fields = [];
+    if (isset($config['fields']) && is_array($config['fields'])) {
+        foreach ($config['fields'] as $name => $raw) {
+            if (is_array($raw) && !isset($raw['name']) && is_string($name)) {
+                $raw['name'] = $name;
+            }
+            $field = wbs_dataverse_connect_normalize_field($raw);
+            if ($field !== null && !isset($fields[$field['name']])) {
+                $fields[$field['name']] = $field;
+            }
+        }
+    }
+    // Pre-1.5 configs (and the legacy field map textarea) become typed fields.
+    if (isset($config['field_map']) && is_array($config['field_map'])) {
+        foreach ($config['field_map'] as $name => $column) {
+            $field = wbs_dataverse_connect_normalize_field([
+                'name'     => $name,
+                'column'   => $column,
+                'type'     => wbs_dataverse_connect_legacy_field_type(sanitize_key($name)),
+                'required' => in_array(sanitize_key($name), $legacy_required, true),
+            ]);
+            if ($field !== null && !isset($fields[$field['name']])) {
+                $fields[$field['name']] = $field;
+            }
+        }
+    }
+
+    $field_map = [];
+    $required  = [];
+    foreach ($fields as $name => $field) {
+        $field_map[$name] = $field['column'];
+        if ($field['required']) {
+            $required[] = $name;
         }
     }
@@ -102 +299 @@
     }
 
+    $bind_to = sanitize_key($config['bind_to'] ?? '');
+    if ($bind_to === '' && $relate_to !== null) {
+        $bind_to = $relate_to['collection'];
+    }
+    $mode = (($config['mode'] ?? 'create') === 'update' && $bind_to !== '') ? 'update' : 'create';
+
     $clean = [
         'key'             => sanitize_key(isset($config['key']) ? $config['key'] : $key),
         'table'           => wbs_dataverse_connect_logical_name($config['table'] ?? ''),
         'entity_set'      => wbs_dataverse_connect_logical_name($config['entity_set'] ?? ''),
+        'fields'          => array_values($fields),
         'field_map'       => $field_map,
-        'required'        => array_values(array_unique($required)),
+        'required'        => $required,
         'require_consent' => !empty($config['require_consent']),
         'relate_to'       => $relate_to,
+        'mode'            => $mode,
+        'bind_to'         => $bind_to,
+        'success_message' => sanitize_text_field((string) ($config['success_message'] ?? '')),
+        'redirect_url'    => wbs_dataverse_connect_form_redirect_url($config['redirect_url'] ?? ''),
+        'turnstile'       => !empty($config['turnstile']),
     ];
 
-    if ($clean['key'] === '' || $clean['entity_set'] === '' || empty($clean['field_map'])) {
+    if ($clean['key'] === '' || $clean['entity_set'] === '' || empty($clean['fields'])) {
         return null;
     }
@@ -144 +353 @@
     return ucwords(str_replace(['_', '-'], ' ', $field));
 }
+
+/** Client context of a form's reads and writes. */
+function wbs_dataverse_connect_form_context($config) {
+    return ['type' => 'form', 'config' => $config];
+}
+
+/**
+ * Metadata facts of a field's column, or null when unavailable. The
+ * table's attribute map is fetched once per request and form: the client
+ * caches successful reads but not failures, and every field asks for its
+ * label, required level and options in turn, so without this memo an
+ * unreachable environment would cost several timeouts per field.
+ */
+function wbs_dataverse_connect_form_field_meta($config, $field) {
+    static $maps = [];
+    if (empty($config['table']) || !function_exists('wbs_dataverse_connect_metadata_attributes')) {
+        return null;
+    }
+    $key = $config['table'] . '|' . md5(serialize($config));
+    if (!array_key_exists($key, $maps)) {
+        $attrs = wbs_dataverse_connect_metadata_attributes($config['table'], wbs_dataverse_connect_form_context($config));
+        $maps[$key] = is_array($attrs) ? $attrs : [];
+    }
+    $column = wbs_dataverse_connect_logical_name($field['column']);
+    return isset($maps[$key][$column]) ? $maps[$key][$column] : null;
+}
+
+/** Display label of a field: admin label, metadata label, then the name heuristic. */
+function wbs_dataverse_connect_form_field_display_label($config, $field) {
+    if (($field['label'] ?? '') !== '') {
+        return $field['label'];
+    }
+    $meta = wbs_dataverse_connect_form_field_meta($config, $field);
+    if ($meta && $meta['label'] !== '') {
+        return $meta['label'];
+    }
+    return wbs_dataverse_connect_form_field_label($field['name']);
+}
+
+/** Whether a field must be filled: the admin flag, or the column's required level. */
+function wbs_dataverse_connect_form_field_required($config, $field) {
+    if ($field['required']) {
+        return true;
+    }
+    if ($field['type'] === 'hidden' || $field['type'] === 'boolean') {
+        return false;
+    }
+    $meta = wbs_dataverse_connect_form_field_meta($config, $field);
+    return $meta ? !empty($meta['required']) : false;
+}
+
+/** value => label options of a choice field: the admin's, else metadata's. */
+function wbs_dataverse_connect_form_field_options($config, $field) {
+    if (!empty($field['options'])) {
+        return $field['options'];
+    }
+    $meta = wbs_dataverse_connect_form_field_meta($config, $field);
+    return $meta && is_array($meta['options']) ? $meta['options'] : [];
+}
+
+/** The collection an update-mode form resolves its record through, or null. */
+function wbs_dataverse_connect_form_bind_collection($config) {
+    if (empty($config['bind_to'])) {
+        return null;
+    }
+    $collection = wbs_dataverse_connect_collection($config['bind_to']);
+    if ($collection === null || $collection['entity_set'] !== $config['entity_set']) {
+        return null;
+    }
+    return $collection;
+}
+
+/** A lowercased 36-char GUID, or '' when the input is not one. */
+function wbs_dataverse_connect_form_guid($raw) {
+    $guid = strtolower(preg_replace('/[^0-9a-fA-F\-]/', '', (string) $raw));
+    return strlen($guid) === 36 ? $guid : '';
+}
+
+/** Primary key column of a lookup field's target table, '' when unknown. */
+function wbs_dataverse_connect_form_lookup_id_column($field) {
+    $table = (string) ($field['lookup_table'] ?? '');
+    return $table !== '' ? $table . 'id' : '';
+}
+
+/**
+ * id => name rows of a lookup target for the select, capped at
+ * WBS_DATAVERSE_CONNECT_LOOKUP_CAP and cached like any read. Empty when
+ * the field lacks the lookup facts or the read fails.
+ */
+function wbs_dataverse_connect_form_lookup_options($field, $context = []) {
+    $set  = (string) ($field['lookup_entity_set'] ?? '');
+    $name = (string) ($field['lookup_name_column'] ?? '');
+    $id   = wbs_dataverse_connect_form_lookup_id_column($field);
+    if ($set === '' || $name === '' || $id === '') {
+        return [];
+    }
+    $path = $set
+        . '?$select=' . rawurlencode($id . ',' . $name)
+        . '&$orderby=' . rawurlencode($name . ' asc')
+        . '&$top=' . WBS_DATAVERSE_CONNECT_LOOKUP_CAP;
+    $body = wbs_dataverse_connect_get($path, null, $context);
+    if (is_wp_error($body) || empty($body['value']) || !is_array($body['value'])) {
+        return [];
+    }
+    $out = [];
+    foreach ($body['value'] as $row) {
+        $guid = wbs_dataverse_connect_form_guid($row[$id] ?? '');
+        if ($guid === '') {
+            continue;
+        }
+        $label = isset($row[$name]) && is_scalar($row[$name]) ? (string) $row[$name] : '';
+        $out[$guid] = $label !== '' ? $label : $guid;
+        if (count($out) >= WBS_DATAVERSE_CONNECT_LOOKUP_CAP) {
+            break;
+        }
+    }
+    return $out;
+}
+
+/**
+ * Resolve a lookup target's GUID by matching its name column, so a form
+ * can offer labels instead of ids. Cached read; '' when nothing matches.
+ */
+function wbs_dataverse_connect_form_resolve_lookup($field, $value, $context = []) {
+    $set  = (string) ($field['lookup_entity_set'] ?? '');
+    $name = (string) ($field['lookup_name_column'] ?? '');
+    $id   = wbs_dataverse_connect_form_lookup_id_column($field);
+    $value = trim((string) $value);
+    if ($set === '' || $name === '' || $id === '' || $value === '') {
+        return '';
+    }
+    $path = $set
+        . '?$select=' . rawurlencode($id)
+        . '&$filter=' . rawurlencode($name . " eq '" . wbs_dataverse_connect_odata_str($value) . "'")
+        . '&$top=1';
+    $body = wbs_dataverse_connect_get($path, null, $context);
+    if (is_wp_error($body) || empty($body['value'][0][$id])) {
+        return '';
+    }
+    return wbs_dataverse_connect_form_guid($body['value'][0][$id]);
+}
+
+/** Interpret a checkbox or yes/no submission as a two-option value. */
+function wbs_dataverse_connect_form_truthy($raw) {
+    if (is_bool($raw)) {
+        return $raw;
+    }
+    if (is_array($raw)) {
+        return !empty($raw);
+    }
+    return in_array(strtolower(trim((string) $raw)), ['1', 'true', 'on', 'yes', 'ja', 'y'], true);
+}
+
+/** A submitted date as Y-m-d, '' when it does not parse. */
+function wbs_dataverse_connect_form_date($raw) {
+    $raw = trim((string) $raw);
+    if ($raw === '') {
+        return '';
+    }
+    if (preg_match('/^(\d{4})-(\d{2})-(\d{2})(T.*)?$/', $raw, $m)) {
+        return checkdate((int) $m[2], (int) $m[3], (int) $m[1]) ? $m[1] . '-' . $m[2] . '-' . $m[3] : '';
+    }
+    $ts = strtotime($raw);
+    return $ts ? gmdate('Y-m-d', $ts) : '';
+}
+
+/**
+ * A submitted date and time as ISO 8601 UTC. Values without an offset
+ * (the datetime-local input) are read in the site's timezone.
+ */
+function wbs_dataverse_connect_form_datetime($raw) {
+    $raw = trim((string) $raw);
+    if ($raw === '') {
+        return '';
+    }
+    try {
+        $dt = new DateTime($raw, wp_timezone());
+    } catch (Exception $e) {
+        return '';
+    }
+    $dt->setTimezone(new DateTimeZone('UTC'));
+    return $dt->format('Y-m-d\TH:i:s\Z');
+}
+
+/**
+ * Resolve a choice submission to its option value: an exact value in
+ * $options, a numeric passthrough (when options are unknown), then a
+ * case-insensitive label match. null when nothing resolves.
+ */
+function wbs_dataverse_connect_form_option($raw, $options) {
+    $raw = is_scalar($raw) ? trim((string) $raw) : '';
+    if ($raw === '') {
+        return null;
+    }
+    $numeric = ctype_digit(ltrim($raw, '-'));
+    if ($numeric && (empty($options) || isset($options[(int) $raw]))) {
+        return (int) $raw;
+    }
+    foreach ($options as $value => $label) {
+        if (strcasecmp((string) $label, $raw) === 0) {
+            return (int) $value;
+        }
+    }
+    return null;
+}
+
+/** Validation error for a field, phrased for the visitor. */
+function wbs_dataverse_connect_form_field_error($code, $label) {
+    switch ($code) {
+        case 'required':
+            /* translators: %s: field label. */
+            $message = sprintf(__('Please fill in "%s".', 'wbs-connect-for-dataverse'), $label);
+            break;
+        case 'email':
+            /* translators: %s: field label. */
+            $message = sprintf(__('Please enter a valid email address for "%s".', 'wbs-connect-for-dataverse'), $label);
+            break;
+        case 'option':
+            /* translators: %s: field label. */
+            $message = sprintf(__('Please choose one of the offered values for "%s".', 'wbs-connect-for-dataverse'), $label);
+            break;
+        default:
+            /* translators: %s: field label. */
+            $message = sprintf(__('Please enter a valid value for "%s".', 'wbs-connect-for-dataverse'), $label);
+    }
+    return new WP_Error('wbs_dataverse_connect_validation', $message, ['field' => $code]);
+}
+
+/**
+ * Type one submitted value for the Web API. $field is a normalized field
+ * spec (see wbs_dataverse_connect_normalize_field), $raw the submitted
+ * value (scalar or array), $context the client context whose 'config'
+ * supplies the table for metadata. Returns:
+ *
+ *   null      nothing to write (empty submission)
+ *   WP_Error  the value is invalid; the message is visitor-facing
+ *   mixed     the typed value: string, int, float, bool, CSV of ints for
+ *             multichoice, or the target GUID for a lookup (the caller
+ *             builds the @odata.bind from lookup_entity_set and lookup_nav)
+ *
+ * Required-ness is not judged here; callers decide whether null is a
+ * problem. The WBS Forms bridge does its own typing today and could adopt
+ * this helper later.
+ */
+function wbs_dataverse_connect_typed_value($field, $raw, $context = []) {
+    $type   = (string) ($field['type'] ?? 'text');
+    $config = isset($context['config']) && is_array($context['config']) ? $context['config'] : null;
+    $label  = $config ? wbs_dataverse_connect_form_field_display_label($config, $field) : wbs_dataverse_connect_form_field_label($field['name']);
+
+    if ($type !== 'multichoice' && is_array($raw)) {
+        $raw = reset($raw);
+    }
+    if ($type !== 'multichoice' && $type !== 'boolean') {
+        $raw = is_scalar($raw) ? trim((string) $raw) : '';
+        if ($raw === '') {
+            return null;
+        }
+    }
+
+    switch ($type) {
+        case 'email':
+            $email = sanitize_email($raw);
+            if ($email === '' || !is_email($email)) {
+                return wbs_dataverse_connect_form_field_error('email', $label);
+            }
+            return $email;
+
+        case 'textarea':
+            return sanitize_textarea_field($raw);
+
+        case 'number':
+        case 'money':
+            $number = str_replace(' ', '', $raw);
+            if (strpos($number, '.') === false) {
+                $number = str_replace(',', '.', $number);
+            }
+            if (!is_numeric($number)) {
+                return wbs_dataverse_connect_form_field_error('invalid', $label);
+            }
+            if ($type === 'money') {
+                return (float) $number;
+            }
+            $meta = $config ? wbs_dataverse_connect_form_field_meta($config, $field) : null;
+            $integer = $meta ? in_array($meta['type'], ['Integer', 'BigInt'], true) : (preg_match('/^-?\d+$/', $number) === 1);
+            return $integer ? (int) round((float) $number) : (float) $number;
+
+        case 'date':
+            $date = wbs_dataverse_connect_form_date($raw);
+            return $date !== '' ? $date : wbs_dataverse_connect_form_field_error('invalid', $label);
+
+        case 'datetime':
+            $dt = wbs_dataverse_connect_form_datetime($raw);
+            return $dt !== '' ? $dt : wbs_dataverse_connect_form_field_error('invalid', $label);
+
+        case 'choice':
+            $options = $config ? wbs_dataverse_connect_form_field_options($config, $field) : (array) ($field['options'] ?? []);
+            $value = wbs_dataverse_connect_form_option($raw, $options);
+            return $value === null ? wbs_dataverse_connect_form_field_error('option', $label) : $value;
+
+        case 'multichoice':
+            $options = $config ? wbs_dataverse_connect_form_field_options($config, $field) : (array) ($field['options'] ?? []);
+            $items = is_array($raw) ? $raw : preg_split('/\s*,\s*/', (string) $raw);
+            $values = [];
+            foreach ((array) $items as $item) {
+                $item = is_scalar($item) ? trim((string) $item) : '';
+                if ($item === '') {
+                    continue;
+                }
+                $value = wbs_dataverse_connect_form_option($item, $options);
+                if ($value === null) {
+                    return wbs_dataverse_connect_form_field_error('option', $label);
+                }
+                $values[] = $value;
+            }
+            if (empty($values)) {
+                return null;
+            }
+            return implode(',', array_values(array_unique($values)));
+
+        case 'boolean':
+            if (is_array($raw)) {
+                $raw = end($raw);
+            }
+            if (!is_bool($raw) && (!is_scalar($raw) || trim((string) $raw) === '')) {
+                return null;
+            }
+            return wbs_dataverse_connect_form_truthy($raw);
+
+        case 'lookup':
+            $guid = wbs_dataverse_connect_form_guid($raw);
+            if ($guid === '' && !empty($field['lookup_entity_set'])) {
+                $guid = wbs_dataverse_connect_form_resolve_lookup($field, $raw, $context);
+            }
+            return $guid !== '' ? $guid : wbs_dataverse_connect_form_field_error('option', $label);
+
+        case 'hidden':
+            // A fixed value still has to match the column's type when metadata knows it.
+            $meta  = $config ? wbs_dataverse_connect_form_field_meta($config, $field) : null;
+            $mtype = $meta ? (string) $meta['type'] : '';
+            if ($mtype === 'Boolean') {
+                return wbs_dataverse_connect_form_truthy($raw);
+            }
+            if (is_numeric($raw) && in_array($mtype, ['Picklist', 'State', 'Status', 'Integer', 'BigInt'], true)) {
+                return (int) $raw;
+            }
+            if (is_numeric($raw) && in_array($mtype, ['Decimal', 'Double', 'Money'], true)) {
+                return (float) $raw;
+            }
+            return sanitize_text_field($raw);
+
+        case 'text':
+        case 'phone':
+        default:
+            return sanitize_text_field($raw);
+    }
+}
+
+/**
+ * Fresh read of the record an update form edits, limited to the form's
+ * columns. Returns the row, null when it does not exist, or WP_Error.
+ */
+function wbs_dataverse_connect_form_load_record($config, $record_id) {
+    $guid = wbs_dataverse_connect_form_guid($record_id);
+    if ($guid === '') {
+        return null;
+    }
+    $select = [];
+    foreach ($config['fields'] as $field) {
+        $select[] = $field['type'] === 'lookup' ? '_' . $field['column'] . '_value' : $field['column'];
+    }
+    $path = $config['entity_set'] . '(' . $guid . ')?$select=' . rawurlencode(implode(',', array_unique($select)));
+    $row  = wbs_dataverse_connect_get($path, 0, wbs_dataverse_connect_form_context($config));
+    if (is_wp_error($row)) {
+        $status = (int) ($row->get_error_data()['status'] ?? 0);
+        return $status === 404 ? null : $row;
+    }
+    return $row;
+}
+
+/**
+ * The record an update form is bound to, checked through the bind
+ * collection so a hidden record cannot be edited by guessing its id.
+ * $record_id is a GUID or ''. Returns the GUID or '' when not visible.
+ */
+function wbs_dataverse_connect_form_bound_record($config, $record_id = '') {
+    $collection = wbs_dataverse_connect_form_bind_collection($config);
+    if ($collection === null) {
+        return '';
+    }
+    $guid = wbs_dataverse_connect_form_guid($record_id);
+    if ($guid !== '') {
+        $row = wbs_dataverse_connect_query_single($collection, wbs_dataverse_connect_id_column($collection) . ' eq ' . $guid);
+    } else {
+        $slug = function_exists('get_query_var') ? (string) get_query_var('dvc', '') : '';
+        $row  = $slug !== '' ? wbs_dataverse_connect_get_record($collection, $slug) : null;
+    }
+    if (!is_array($row) || is_wp_error($row)) {
+        return '';
+    }
+    return wbs_dataverse_connect_form_guid($row[wbs_dataverse_connect_id_column($collection)] ?? '');
+}
+
+/** Initial input value of a field from an existing record, by type. */
+function wbs_dataverse_connect_form_prefill($field, $record) {
+    if ($field['type'] === 'hidden' || !is_array($record)) {
+        return $field['default'];
+    }
+    $column = $field['type'] === 'lookup' ? '_' . $field['column'] . '_value' : $field['column'];
+    if (!array_key_exists($column, $record) || $record[$column] === null) {
+        return '';
+    }
+    $value = $record[$column];
+    switch ($field['type']) {
+        case 'boolean':
+            return wbs_dataverse_connect_form_truthy($value) ? '1' : '0';
+        case 'multichoice':
+            return array_map('intval', array_filter(explode(',', (string) $value), 'strlen'));
+        case 'choice':
+            return (string) (int) $value;
+        case 'date':
+            return substr((string) $value, 0, 10);
+        case 'datetime':
+            try {
+                $dt = new DateTime((string) $value, new DateTimeZone('UTC'));
+            } catch (Exception $e) {
+                return '';
+            }
+            $dt->setTimezone(wp_timezone());
+            return $dt->format('Y-m-d\TH:i');
+        case 'lookup':
+            return wbs_dataverse_connect_form_guid($value);
+    }
+    return is_scalar($value) ? (string) $value : '';
+}
+
+/** Turnstile site and secret key. */
+function wbs_dataverse_connect_turnstile_keys() {
+    return [
+        'site_key'   => trim((string) get_option('wbs_dataverse_connect_turnstile_site_key', '')),
+        'secret_key' => trim((string) get_option('wbs_dataverse_connect_turnstile_secret_key', '')),
+    ];
+}
+
+/** Whether a form's Turnstile switch can take effect (both keys present). */
+function wbs_dataverse_connect_turnstile_active($config) {
+    if (empty($config['turnstile'])) {
+        return false;
+    }
+    $keys = wbs_dataverse_connect_turnstile_keys();
+    return $keys['site_key'] !== '' && $keys['secret_key'] !== '';
+}
+
+/**
+ * Verify a Turnstile token with Cloudflare's siteverify endpoint. True on
+ * success; false on a failed challenge or an unreachable endpoint.
+ */
+function wbs_dataverse_connect_turnstile_verify($token, $ip = '') {
+    $token = trim((string) $token);
+    $keys  = wbs_dataverse_connect_turnstile_keys();
+    if ($token === '' || $keys['secret_key'] === '') {
+        return false;
+    }
+    $body = ['secret' => $keys['secret_key'], 'response' => $token];
+    if ($ip !== '') {
+        $body['remoteip'] = $ip;
+    }
+    // phpcs:ignore PluginCheck.CodeAnalysis.Offloading.OffloadedContent -- Cloudflare Turnstile verification, only when a form has the challenge switched on; documented under External services.
+    $resp = wp_remote_post('https://challenges.cloudflare.com/turnstile/v0/siteverify', [
+        'timeout' => 10,
+        'body'    => $body,
+    ]);
+    if (is_wp_error($resp)) {
+        return false;
+    }
+    $decoded = json_decode((string) wp_remote_retrieve_body($resp), true);
+    return is_array($decoded) && !empty($decoded['success']);
+}
+
+/**
+ * Everything templates/form.php prints, pre-resolved: fields with labels,
+ * options and initial values, the bound record in update mode, the
+ * Turnstile site key. Enqueues the form stylesheet and, when active, the
+ * Turnstile script. $record_id is the GUID the shortcode resolved, or ''.
+ * Returns ['error' => WP_Error] when the bound record cannot be read and
+ * ['config_error' => string] when the form is set up wrong.
+ */
+function wbs_dataverse_connect_form_view($config, $record_id = '') {
+    wp_enqueue_style('wbs-connect-for-dataverse-forms');
+
+    $context = wbs_dataverse_connect_form_context($config);
+    $record  = null;
+    $missing = false;
+
+    if ($config['mode'] === 'update') {
+        if (wbs_dataverse_connect_form_bind_collection($config) === null) {
+            return ['config_error' => sprintf(
+                /* translators: %s: form key. */
+                __('Dataverse Connect: form "%s" is in update mode but its bind collection is missing or targets another table.', 'wbs-connect-for-dataverse'),
+                $config['key']
+            )];
+        }
+        $record_id = wbs_dataverse_connect_form_bound_record($config, $record_id);
+        $record    = $record_id !== '' ? wbs_dataverse_connect_form_load_record($config, $record_id) : null;
+        if (is_wp_error($record)) {
+            return ['error' => $record];
+        }
+        $missing = ($record === null);
+    }
+
+    $fields = [];
+    foreach ($config['fields'] as $field) {
+        $options = [];
+        if ($field['type'] === 'choice' || $field['type'] === 'multichoice') {
+            $options = wbs_dataverse_connect_form_field_options($config, $field);
+        } elseif ($field['type'] === 'lookup') {
+            $options = wbs_dataverse_connect_form_lookup_options($field, $context);
+        }
+        $fields[] = [
+            'name'     => $field['name'],
+            'type'     => $field['type'],
+            'label'    => wbs_dataverse_connect_form_field_display_label($config, $field),
+            'required' => wbs_dataverse_connect_form_field_required($config, $field),
+            'options'  => $options,
+            'value'    => wbs_dataverse_connect_form_prefill($field, $record),
+        ];
+    }
+
+    $turnstile = wbs_dataverse_connect_turnstile_active($config);
+    if ($turnstile) {
+        wp_enqueue_script('wbs-connect-for-dataverse-turnstile');
+    }
+
+    $view = [
+        'uid'          => 'dvc-form-' . substr(md5($config['key'] . $record_id . wp_rand()), 0, 8),
+        'mode'         => $config['mode'],
+        'record_id'    => $record_id,
+        'missing'      => $missing,
+        'fields'       => $fields,
+        'turnstile'    => $turnstile ? wbs_dataverse_connect_turnstile_keys()['site_key'] : '',
+        'submit_label' => $config['mode'] === 'update'
+            ? __('Save changes', 'wbs-connect-for-dataverse')
+            : __('Send', 'wbs-connect-for-dataverse'),
+    ];
+
+    /**
+     * The view model of a rendered form.
+     *
+     * @param array  $view      Fields, mode, record id, Turnstile site key.
+     * @param array  $config    The normalized form config.
+     * @param array|null $record The bound record in update mode.
+     */
+    return apply_filters('wbs_dataverse_connect_form_view', $view, $config, $record);
+}
+
+/** Front-end assets of the typed forms; the base handles are registered in shortcodes.php. */
+function wbs_dataverse_connect_forms_register_assets() {
+    wp_register_style('wbs-connect-for-dataverse-forms', WBS_DATAVERSE_CONNECT_URL . 'assets/wbs-connect-for-dataverse-forms.css', ['wbs-connect-for-dataverse'], WBS_DATAVERSE_CONNECT_VERSION);
+    wp_register_script('wbs-connect-for-dataverse-turnstile', 'https://challenges.cloudflare.com/turnstile/v0/api.js', [], null, true); // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion,PluginCheck.CodeAnalysis.EnqueuedResourceOffloading.OffloadedContent -- Cloudflare Turnstile widget, loaded only on pages whose form has the challenge switched on; documented under External services.
+}
+add_action('wp_enqueue_scripts', 'wbs_dataverse_connect_forms_register_assets');
+
+/** Turnstile key options; sanitized on every write path. */
+function wbs_dataverse_connect_forms_admin_init() {
+    register_setting('wbs_dataverse_connect_forms', 'wbs_dataverse_connect_turnstile_site_key', [
+        'type'              => 'string',
+        'sanitize_callback' => 'sanitize_text_field',
+        'default'           => '',
+    ]);
+    register_setting('wbs_dataverse_connect_forms', 'wbs_dataverse_connect_turnstile_secret_key', [
+        'type'              => 'string',
+        'sanitize_callback' => 'wbs_dataverse_connect_sanitize_turnstile_secret',
+        'default'           => '',
+    ]);
+}
+add_action('admin_init', 'wbs_dataverse_connect_forms_admin_init');
+
+/** The secret is never pre-filled; an empty submit keeps the stored one. */
+function wbs_dataverse_connect_sanitize_turnstile_secret($value) {
+    if (!is_string($value) || trim($value) === '') {
+        return (string) get_option('wbs_dataverse_connect_turnstile_secret_key', '');
+    }
+    return trim($value);
+}
+
+/** Number of rows the field table shows: the existing fields plus room to grow. */
+function wbs_dataverse_connect_forms_row_count($editing) {
+    $count = ($editing !== null && !empty($editing['fields'])) ? count($editing['fields']) : 0;
+    return max(12, $count + 3);
+}
+
+/** The options textarea text of one field, mirroring how it is parsed. */
+function wbs_dataverse_connect_forms_options_text($field) {
+    $lines = [];
+    if ($field['type'] === 'lookup') {
+        $lines[] = 'table = ' . $field['lookup_table'];
+        $lines[] = 'entity_set = ' . $field['lookup_entity_set'];
+        $lines[] = 'name_column = ' . $field['lookup_name_column'];
+        $lines[] = 'nav = ' . $field['lookup_nav'];
+    } else {
+        foreach ((array) $field['options'] as $value => $label) {
+            $lines[] = $value . ' = ' . $label;
+        }
+    }
+    return implode("\n", $lines);
+}
+
+/**
+ * The 1.5 rows of the form editor: the typed field table, mode and bind
+ * collection, success message, redirect URL, Turnstile. Plain HTML, no
+ * script; more rows appear after saving.
+ */
+function wbs_dataverse_connect_forms_admin_rows($editing) {
+    $types  = wbs_dataverse_connect_field_types();
+    $rows   = wbs_dataverse_connect_forms_row_count($editing);
+    $fields = ($editing !== null && !empty($editing['fields'])) ? $editing['fields'] : [];
+    $keys   = wbs_dataverse_connect_turnstile_keys();
+    $collections = wbs_dataverse_connect_collections();
+    ?>
+    <tr>
+        <th scope="row"><?php esc_html_e('Fields', 'wbs-connect-for-dataverse'); ?></th>
+        <td>
+            <p class="description" style="margin-bottom:8px;">
+                <?php esc_html_e('One row per input, in display order. Name is the submitted field name (defaults to the column), Column the logical name. Options: for choices one "value = label" per line (empty means the column\'s own choices); for lookups the lines "table = ...", "entity_set = ...", "name_column = ..." and "nav = <navigation property>". Default is the fixed value of a hidden field. Rows filled here take precedence over the field map above; the map still works for plain text forms.', 'wbs-connect-for-dataverse'); ?>
+            </p>
+            <table class="widefat striped dvc-admin-fields" style="max-width:1100px;">
+                <thead>
+                    <tr>
+                        <th style="width:2em;">#</th>
+                        <th><?php esc_html_e('Name', 'wbs-connect-for-dataverse'); ?></th>
+                        <th><?php esc_html_e('Column', 'wbs-connect-for-dataverse'); ?></th>
+                        <th><?php esc_html_e('Type', 'wbs-connect-for-dataverse'); ?></th>
+                        <th><?php esc_html_e('Label', 'wbs-connect-for-dataverse'); ?></th>
+                        <th><?php esc_html_e('Required', 'wbs-connect-for-dataverse'); ?></th>
+                        <th><?php esc_html_e('Options', 'wbs-connect-for-dataverse'); ?></th>
+                        <th><?php esc_html_e('Default', 'wbs-connect-for-dataverse'); ?></th>
+                    </tr>
+                </thead>
+                <tbody>
+                <?php for ($i = 0; $i < $rows; $i++) :
+                    $field = isset($fields[$i]) ? $fields[$i] : null;
+                    $base  = 'dvc_fields[' . $i . ']';
+                ?>
+                    <tr>
+                        <td><?php echo (int) ($i + 1); ?></td>
+                        <td><input type="text" name="<?php echo esc_attr($base . '[name]'); ?>" value="<?php echo esc_attr($field ? $field['name'] : ''); ?>" style="width:100%;"></td>
+                        <td><input type="text" name="<?php echo esc_attr($base . '[column]'); ?>" value="<?php echo esc_attr($field ? $field['column'] : ''); ?>" style="width:100%;"></td>
+                        <td>
+                            <select name="<?php echo esc_attr($base . '[type]'); ?>">
+                                <?php foreach ($types as $type => $label) : ?>
+                                    <option value="<?php echo esc_attr($type); ?>" <?php selected($field ? $field['type'] : 'text', $type); ?>><?php echo esc_html($label); ?></option>
+                                <?php endforeach; ?>
+                            </select>
+                        </td>
+                        <td><input type="text" name="<?php echo esc_attr($base . '[label]'); ?>" value="<?php echo esc_attr($field ? $field['label'] : ''); ?>" style="width:100%;"></td>
+                        <td style="text-align:center;"><input type="checkbox" name="<?php echo esc_attr($base . '[required]'); ?>" value="1" <?php checked($field && $field['required']); ?>></td>
+                        <td><textarea name="<?php echo esc_attr($base . '[options]'); ?>" rows="2" style="width:100%;"><?php echo esc_textarea($field ? wbs_dataverse_connect_forms_options_text($field) : ''); ?></textarea></td>
+                        <td><input type="text" name="<?php echo esc_attr($base . '[default]'); ?>" value="<?php echo esc_attr($field ? $field['default'] : ''); ?>" style="width:100%;"></td>
+                    </tr>
+                <?php endfor; ?>
+                </tbody>
+            </table>
+        </td>
+    </tr>
+    <tr>
+        <th scope="row"><label for="dvc_mode"><?php esc_html_e('Mode', 'wbs-connect-for-dataverse'); ?></label></th>
+        <td>
+            <select id="dvc_mode" name="dvc_mode">
+                <option value="create" <?php selected($editing ? $editing['mode'] : 'create', 'create'); ?>><?php esc_html_e('Create a new record per submission', 'wbs-connect-for-dataverse'); ?></option>
+                <option value="update" <?php selected($editing ? $editing['mode'] : 'create', 'update'); ?>><?php esc_html_e('Update the record the page is bound to', 'wbs-connect-for-dataverse'); ?></option>
+            </select>
+            <p class="description"><?php esc_html_e('Update mode prefills the inputs from the record selected by ?dvc=<slug> (or the record the form is attached to) and saves changes back with a PATCH. The application user needs Write on the table, and every visitor who can see the record can edit the mapped columns.', 'wbs-connect-for-dataverse'); ?></p>
+        </td>
+    </tr>
+    <tr>
+        <th scope="row"><label for="dvc_bind_to"><?php esc_html_e('Bind to collection', 'wbs-connect-for-dataverse'); ?></label></th>
+        <td>
+            <select id="dvc_bind_to" name="dvc_bind_to">
+                <option value=""><?php esc_html_e('(the "Relate to" collection)', 'wbs-connect-for-dataverse'); ?></option>
+                <?php foreach ($collections as $key => $collection) : ?>
+                    <option value="<?php echo esc_attr($key); ?>" <?php selected($editing ? $editing['bind_to'] : '', $key); ?>><?php echo esc_html($key . ' (' . $collection['entity_set'] . ')'); ?></option>
+                <?php endforeach; ?>
+            </select>
+            <p class="description"><?php esc_html_e('Collection of the same table whose status filter decides which records may be edited in update mode.', 'wbs-connect-for-dataverse'); ?></p>
+        </td>
+    </tr>
+    <tr>
+        <th scope="row"><label for="dvc_success_message"><?php esc_html_e('Success message', 'wbs-connect-for-dataverse'); ?></label></th>
+        <td><input type="text" id="dvc_success_message" name="dvc_success_message" class="large-text"
+                   value="<?php echo esc_attr($editing ? $editing['success_message'] : ''); ?>">
+            <p class="description"><?php esc_html_e('Shown after a successful submission. Empty means the default thank-you text.', 'wbs-connect-for-dataverse'); ?></p></td>
+    </tr>
+    <tr>
+        <th scope="row"><label for="dvc_redirect_url"><?php esc_html_e('Redirect after success', 'wbs-connect-for-dataverse'); ?></label></th>
+        <td><input type="text" id="dvc_redirect_url" name="dvc_redirect_url" class="regular-text"
+                   value="<?php echo esc_attr($editing ? $editing['redirect_url'] : ''); ?>" placeholder="/thank-you">
+            <p class="description"><?php esc_html_e('Optional page on this site the visitor is sent to instead of the message. Other hosts are ignored.', 'wbs-connect-for-dataverse'); ?></p></td>
+    </tr>
+    <tr>
+        <th scope="row"><?php esc_html_e('Cloudflare Turnstile', 'wbs-connect-for-dataverse'); ?></th>
+        <td>
+            <label>
+                <input type="checkbox" name="dvc_turnstile" value="1" <?php checked($editing && $editing['turnstile']); ?>>
+                <?php esc_html_e('Require a Turnstile challenge on this form.', 'wbs-connect-for-dataverse'); ?>
+            </label>
+            <p class="description"><?php esc_html_e('The keys below are shared by all forms on this site and are saved together with this form. Without both keys the challenge is skipped.', 'wbs-connect-for-dataverse'); ?></p>
+            <p>
+                <label for="dvc_turnstile_site_key"><?php esc_html_e('Site key', 'wbs-connect-for-dataverse'); ?></label><br>
+                <input type="text" id="dvc_turnstile_site_key" name="dvc_turnstile_site_key" class="regular-text" autocomplete="off"
+                       value="<?php echo esc_attr($keys['site_key']); ?>">
+            </p>
+            <p>
+                <label for="dvc_turnstile_secret_key"><?php esc_html_e('Secret key', 'wbs-connect-for-dataverse'); ?></label><br>
+                <input type="password" id="dvc_turnstile_secret_key" name="dvc_turnstile_secret_key" class="regular-text" autocomplete="off" value=""
+                       <?php if ($keys['secret_key'] !== '') : ?>placeholder="<?php esc_attr_e('Saved. Leave blank to keep the current secret.', 'wbs-connect-for-dataverse'); ?>"<?php endif; ?>>
+            </p>
+        </td>
+    </tr>
+    <?php
+}
+add_action('wbs_dataverse_connect_form_fields', 'wbs_dataverse_connect_forms_admin_rows');
+
+/** The posted field table rows, normalized, in order. */
+function wbs_dataverse_connect_forms_posted_fields($post) {
+    $fields = [];
+    if (!isset($post['dvc_fields']) || !is_array($post['dvc_fields'])) {
+        return $fields;
+    }
+    ksort($post['dvc_fields'], SORT_NUMERIC);
+    foreach ($post['dvc_fields'] as $row) {
+        $field = wbs_dataverse_connect_normalize_field($row);
+        if ($field !== null && !isset($fields[$field['name']])) {
+            $fields[$field['name']] = $field;
+        }
+    }
+    return $fields;
+}
+
+/**
+ * Runs just before the plugin's own save handler. That handler builds the
+ * config from the legacy field map textarea and rejects an empty map, so
+ * the rows of the field table are folded into the map here; a form set up
+ * entirely through the table then saves without touching the textarea.
+ */
+function wbs_dataverse_connect_forms_fold_fields() {
+    if (!current_user_can('manage_options') || !isset($_POST['dvc_fields']) || !is_array($_POST['dvc_fields'])) {
+        return;
+    }
+    if (!isset($_POST['_wpnonce']) || !wp_verify_nonce(sanitize_text_field(wp_unslash($_POST['_wpnonce'])), 'wbs_dataverse_connect_save_form')) {
+        return;
+    }
+    $post   = wp_unslash($_POST);
+    $fields = wbs_dataverse_connect_forms_posted_fields($post);
+    if (empty($fields)) {
+        return;
+    }
+    $lines = [];
+    foreach (preg_split('/[\r\n]+/', (string) ($post['dvc_field_map'] ?? '')) as $line) {
+        $line = trim($line);
+        if ($line !== '') {
+            $lines[] = $line;
+        }
+    }
+    foreach ($fields as $name => $field) {
+        $lines[] = $name . ' = ' . $field['column'];
+    }
+    $_POST['dvc_field_map'] = wp_slash(implode("\n", array_unique($lines)));
+}
+add_action('admin_post_wbs_dataverse_connect_save_form', 'wbs_dataverse_connect_forms_fold_fields', 5);
+
+/**
+ * Attach the typed fields and the 1.5 options to the config being stored,
+ * and store the site-wide Turnstile keys.
+ */
+function wbs_dataverse_connect_forms_save($config, $post) {
+    $fields = wbs_dataverse_connect_forms_posted_fields($post);
+    // Legacy map entries without a row keep working as upgraded text fields.
+    foreach ($config['fields'] as $field) {
+        if (!isset($fields[$field['name']])) {
+            $fields[$field['name']] = $field;
+        }
+    }
+
+    $config['fields']          = array_values($fields);
+    $config['mode']            = sanitize_key($post['dvc_mode'] ?? 'create');
+    $config['bind_to']         = sanitize_key($post['dvc_bind_to'] ?? '');
+    $config['success_message'] = sanitize_text_field((string) ($post['dvc_success_message'] ?? ''));
+    $config['redirect_url']    = (string) ($post['dvc_redirect_url'] ?? '');
+    $config['turnstile']       = !empty($post['dvc_turnstile']);
+
+    $redirect = wbs_dataverse_connect_form_redirect_url($config['redirect_url']);
+    $config['redirect_url'] = ($redirect !== '' && wp_http_validate_url($redirect)) ? $redirect : '';
+
+    if (array_key_exists('dvc_turnstile_site_key', $post)) {
+        update_option('wbs_dataverse_connect_turnstile_site_key', sanitize_text_field((string) $post['dvc_turnstile_site_key']), false);
+    }
+    if (array_key_exists('dvc_turnstile_secret_key', $post) && trim((string) $post['dvc_turnstile_secret_key']) !== '') {
+        update_option('wbs_dataverse_connect_turnstile_secret_key', trim((string) $post['dvc_turnstile_secret_key']), false);
+    }
+
+    // Re-run normalization so the stored config is exactly what runtime sees.
+    $clean = wbs_dataverse_connect_normalize_form($config['key'], $config);
+    return $clean !== null ? $clean : $config;
+}
+add_filter('wbs_dataverse_connect_save_form', 'wbs_dataverse_connect_forms_save', 10, 2);

wbs-connect-for-dataverse/trunk/includes/rest.php

@@ -3 +3 @@
 
 /**
- * Submission endpoint: POST wbs-connect-for-dataverse/v1/submit creates a record
- * in the Dataverse table mapped by the named form. Nonce-verified,
- * honeypot-protected and rate limited per IP.
+ * Submission endpoint: POST wbs-connect-for-dataverse/v1/submit writes a
+ * record in the Dataverse table mapped by the named form: a create for
+ * forms in create mode, a PATCH of the bound record in update mode.
+ * Nonce-verified, honeypot-protected, rate limited per IP and, when the
+ * form asks for it, checked with Cloudflare Turnstile. Every value is
+ * typed and validated per field before it reaches the Web API.
  */
 
@@ -21 +24 @@
 }
 
+/** A validation failure as the visitor sees it. */
+function wbs_dataverse_connect_rest_invalid($message) {
+    return new WP_REST_Response(['error' => 'validation_error', 'message' => $message], 400);
+}
+
 function wbs_dataverse_connect_handle_submit(WP_REST_Request $req) {
     $nonce = $req->get_header('x_wp_nonce');
@@ -48 +56 @@
         return new WP_REST_Response(['error' => 'unknown_form'], 400);
     }
-
-    // Only mapped fields are read from the payload, everything else is ignored.
-    $values = [];
-    foreach ($config['field_map'] as $field => $column) {
-        $raw = $payload[$field] ?? '';
-        if (!is_scalar($raw)) {
-            $raw = '';
-        }
-        $values[$field] = ($field === 'email')
-            ? sanitize_email((string) $raw)
-            : sanitize_textarea_field((string) $raw);
-    }
-
-    foreach ($config['required'] as $field) {
-        if (!isset($values[$field]) || $values[$field] === '') {
+    if (!wbs_dataverse_connect_can_view($config, 'form')) {
+        return new WP_REST_Response(['error' => 'forbidden', 'message' => __('Please sign in to use this form.', 'wbs-connect-for-dataverse')], 403);
+    }
+
+    if (wbs_dataverse_connect_turnstile_active($config)
+        && !wbs_dataverse_connect_turnstile_verify((string) ($payload['cf-turnstile-response'] ?? ''), wbs_dataverse_connect_client_ip())) {
+        return new WP_REST_Response([
+            'error'   => 'turnstile_failed',
+            'message' => __('Please complete the security check and try again.', 'wbs-connect-for-dataverse'),
+        ], 400);
+    }
+
+    $values = wbs_dataverse_connect_collect_values($config, $payload);
+
+    if ($config['require_consent'] && empty($payload['consent'])) {
+        return wbs_dataverse_connect_rest_invalid(__('Please confirm your consent.', 'wbs-connect-for-dataverse'));
+    }
+
+    $update    = ($config['mode'] === 'update');
+    $record_id = wbs_dataverse_connect_form_guid((string) ($payload['record'] ?? ''));
+    if ($update) {
+        // The bound record must be visible through the bind collection;
+        // a guessed id of a hidden record is refused.
+        $record_id = wbs_dataverse_connect_form_bound_record($config, $record_id);
+        if ($record_id === '') {
             return new WP_REST_Response([
-                'error'   => 'validation_error',
-                'message' => __('Please fill in all required fields.', 'wbs-connect-for-dataverse'),
+                'error'   => 'unknown_record',
+                'message' => __('This record is no longer available.', 'wbs-connect-for-dataverse'),
             ], 400);
         }
     }
-    if (isset($values['email']) && $values['email'] !== '' && !is_email($values['email'])) {
-        return new WP_REST_Response([
-            'error'   => 'validation_error',
-            'message' => __('Please enter a valid email address.', 'wbs-connect-for-dataverse'),
-        ], 400);
-    }
-    if ($config['require_consent'] && empty($payload['consent'])) {
-        return new WP_REST_Response([
-            'error'   => 'validation_error',
-            'message' => __('Please confirm your consent.', 'wbs-connect-for-dataverse'),
-        ], 400);
-    }
-
-    $record = wbs_dataverse_connect_build_submission($config, $values, (string) ($payload['record'] ?? ''));
-    if (empty($record)) {
-        return new WP_REST_Response([
-            'error'   => 'validation_error',
-            'message' => __('Please fill in all required fields.', 'wbs-connect-for-dataverse'),
-        ], 400);
+
+    $record = wbs_dataverse_connect_build_submission($config, $values, $record_id);
+    if (is_wp_error($record)) {
+        return wbs_dataverse_connect_rest_invalid($record->get_error_message());
+    }
+    if (empty($record) && !$update) {
+        return wbs_dataverse_connect_rest_invalid(__('Please fill in all required fields.', 'wbs-connect-for-dataverse'));
     }
 
     /**
-     * Last stop before the create. Use this to map values onto typed
-     * columns (choices, booleans, dates) or to add fixed values.
+     * Last stop before the write. Use this to add fixed values or to
+     * adjust typed values; $config['mode'] tells a create from an update.
      *
-     * @param array $record  Column => value payload for the Web API create.
+     * @param array $record  Column => value payload for the Web API write.
      * @param array $config  The normalized form config.
      * @param array $values  The sanitized submitted values by field name.
@@ -100 +106 @@
     $record = apply_filters('wbs_dataverse_connect_form_record', $record, $config, $values);
 
-    $result = wbs_dataverse_connect_post($config['entity_set'], $record, ['type' => 'form', 'config' => $config]);
+    $context = wbs_dataverse_connect_form_context($config);
+    if ($update) {
+        if (empty($record)) {
+            return wbs_dataverse_connect_rest_success($config, $record_id);
+        }
+        $context['headers'] = ['If-Match' => '*'];
+        $result = wbs_dataverse_connect_patch($config['entity_set'] . '(' . $record_id . ')', $record, $context);
+    } else {
+        $result = wbs_dataverse_connect_post($config['entity_set'], $record, $context);
+    }
+
     if (is_wp_error($result)) {
         // Log the Dataverse detail for the admin, keep the visitor message generic.
-        error_log('[wbs-connect-for-dataverse] form "' . $config['key'] . '" create failed: ' . $result->get_error_message()); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
+        error_log('[wbs-connect-for-dataverse] form "' . $config['key'] . '" ' . ($update ? 'update' : 'create') . ' failed: ' . $result->get_error_message()); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
         return new WP_REST_Response([
             'error'   => 'send_error',
@@ -111 +127 @@
 
     wbs_dataverse_connect_review_note_success();
-    return new WP_REST_Response(['ok' => true, 'message' => wbs_dataverse_connect_form_success_message()], 200);
-}
-
-function wbs_dataverse_connect_form_success_message() {
+
+    $id = $update ? $record_id : (is_array($result) ? (string) ($result['id'] ?? '') : '');
+    if ($update) {
+        /**
+         * Fires after a record was updated from a form submission.
+         *
+         * @param string $key        Form key.
+         * @param string $entity_set Entity set of the record.
+         * @param string $id         GUID of the updated record.
+         * @param array  $record     The payload that was patched.
+         */
+        do_action('wbs_dataverse_connect_record_updated', $config['key'], $config['entity_set'], $id, $record);
+    } else {
+        /**
+         * Fires after a record was created from a form submission.
+         *
+         * @param string $key        Form or bridge map key.
+         * @param string $entity_set Entity set the record was created in.
+         * @param string $id         GUID of the new record, '' when unknown.
+         * @param array  $record     The payload that was posted.
+         */
+        do_action('wbs_dataverse_connect_record_created', $config['key'], $config['entity_set'], $id, $record);
+    }
+
+    return wbs_dataverse_connect_rest_success($config, $id);
+}
+
+/** The success response: message, record id and the optional redirect. */
+function wbs_dataverse_connect_rest_success($config, $id) {
+    $body = [
+        'ok'      => true,
+        'message' => wbs_dataverse_connect_form_success_message($config),
+        'id'      => $id,
+    ];
+    if ($config['redirect_url'] !== '') {
+        $body['redirect'] = $config['redirect_url'];
+    }
+    return new WP_REST_Response($body, 200);
+}
+
+/** The form's own success message, or the default one. */
+function wbs_dataverse_connect_form_success_message($config = null) {
+    if (is_array($config) && !empty($config['success_message'])) {
+        return $config['success_message'];
+    }
+    if (is_array($config) && ($config['mode'] ?? 'create') === 'update') {
+        return __('Thank you. Your changes have been saved.', 'wbs-connect-for-dataverse');
+    }
     return __('Thank you. Your message has been sent, we will get back to you shortly.', 'wbs-connect-for-dataverse');
 }
 
 /**
- * Assemble the create payload: mapped non-empty values, plus the lookup
- * bind when the form relates submissions to a collection record. Lookup
- * binds use the schema-name casing of the navigation property.
+ * Read the configured fields from the payload, sanitized but untyped.
+ * Only fields the form knows are read; hidden fields carry their fixed
+ * value whatever was posted; keys absent from the payload stay absent so
+ * an update never blanks a column the form did not send.
+ */
+function wbs_dataverse_connect_collect_values($config, $payload) {
+    $values = [];
+    foreach ($config['fields'] as $field) {
+        $name = $field['name'];
+        if ($field['type'] === 'hidden') {
+            $values[$name] = $field['default'];
+            continue;
+        }
+        if (!is_array($payload) || !array_key_exists($name, $payload)) {
+            continue;
+        }
+        $raw = $payload[$name];
+        if (is_array($raw)) {
+            $items = [];
+            foreach ($raw as $item) {
+                $item = is_scalar($item) ? sanitize_text_field((string) $item) : '';
+                if ($item !== '') {
+                    $items[] = $item;
+                }
+            }
+            $values[$name] = $items;
+            continue;
+        }
+        if (!is_scalar($raw)) {
+            $raw = '';
+        }
+        switch ($field['type']) {
+            case 'email':
+                $values[$name] = sanitize_email((string) $raw);
+                break;
+            case 'textarea':
+                $values[$name] = sanitize_textarea_field((string) $raw);
+                break;
+            default:
+                $values[$name] = sanitize_text_field((string) $raw);
+        }
+    }
+    return $values;
+}
+
+/**
+ * Assemble the write payload: every field typed through
+ * wbs_dataverse_connect_typed_value, lookups as @odata.bind, plus the
+ * relate_to bind on creates. In update mode an emptied field clears its
+ * column (null); lookups and yes/no columns are left alone. Returns the
+ * column => value array or WP_Error with a visitor-facing message when a
+ * required field is empty or a value is invalid.
  */
 function wbs_dataverse_connect_build_submission($config, $values, $record_id) {
-    $record = [];
-    foreach ($config['field_map'] as $field => $column) {
-        if (isset($values[$field]) && $values[$field] !== '') {
-            $record[$column] = $values[$field];
-        }
-    }
-
-    if (is_array($config['relate_to'])) {
-        $guid = strtolower(preg_replace('/[^0-9a-fA-F\-]/', '', $record_id));
-        if (strlen($guid) === 36) {
+    $context = wbs_dataverse_connect_form_context($config);
+    $update  = (($config['mode'] ?? 'create') === 'update');
+    $record  = [];
+
+    foreach ($config['fields'] as $field) {
+        $name    = $field['name'];
+        $present = array_key_exists($name, $values);
+        $typed   = $present ? wbs_dataverse_connect_typed_value($field, $values[$name], $context) : null;
+        if (is_wp_error($typed)) {
+            return $typed;
+        }
+
+        $required = wbs_dataverse_connect_form_field_required($config, $field);
+        if ($typed === null) {
+            if ($required) {
+                return wbs_dataverse_connect_form_field_error('required', wbs_dataverse_connect_form_field_display_label($config, $field));
+            }
+            if ($update && $present && !in_array($field['type'], ['lookup', 'hidden', 'boolean'], true)) {
+                $record[$field['column']] = null;
+            }
+            continue;
+        }
+        if ($field['type'] === 'boolean' && $field['required'] && $typed === false) {
+            return wbs_dataverse_connect_form_field_error('required', wbs_dataverse_connect_form_field_display_label($config, $field));
+        }
+
+        if ($field['type'] === 'lookup') {
+            if ($field['lookup_entity_set'] === '') {
+                continue; // Nothing to bind against; the admin left the lookup facts out.
+            }
+            $record[$field['lookup_nav'] . '@odata.bind'] = '/' . $field['lookup_entity_set'] . '(' . $typed . ')';
+            continue;
+        }
+        $record[$field['column']] = $typed;
+    }
+
+    if (!$update && is_array($config['relate_to'])) {
+        $guid = wbs_dataverse_connect_form_guid($record_id);
+        if ($guid !== '') {
             $collection = wbs_dataverse_connect_collection($config['relate_to']['collection']);
             if ($collection !== null) {
@@ -144 +282 @@
 }
 
+/** The visitor's address as seen by PHP, '' when unknown. */
+function wbs_dataverse_connect_client_ip() {
+    return isset($_SERVER['REMOTE_ADDR']) ? sanitize_text_field(wp_unslash($_SERVER['REMOTE_ADDR'])) : '';
+}
+
 /** Sliding per-IP counter in a transient. */
 function wbs_dataverse_connect_rate_limit_ok() {
-    $ip = isset($_SERVER['REMOTE_ADDR']) ? sanitize_text_field(wp_unslash($_SERVER['REMOTE_ADDR'])) : '';
+    $ip = wbs_dataverse_connect_client_ip();
     if ($ip === '') {
         return true;

wbs-connect-for-dataverse/trunk/includes/shortcodes.php

@@ -4 +4 @@
 /**
  * Shortcodes:
- *   [wbsdvc_collection name="<key>" limit="12" columns="3" detail_page="/path" form="<form key>"]
+ *   [wbsdvc_collection name="<key>" per_page="12" columns="3" detail_page="/path" form="<form key>"
+ *                      search="1|0" filters="col1,col2|0" sort="col asc,col2 desc|0"]
+ *     (limit is the older name of per_page and still wins when set)
  *   [wbsdvc_record name="<key>" slug="..." form="<form key>"]   (or the page reads ?dvc=<slug-or-id>)
  *   [wbsdvc_form name="<form key>" record="<slug-or-id>"]
+ *
+ * The collection view reads its visitor state from the GET vars dvc_q,
+ * dvc_f[<column>], dvc_sort and dvc_page; the toolbar and pagination
+ * templates write them. One collection per page keeps that state
+ * unambiguous: two grids on one page share the same vars.
  */
 
@@ -18 +25 @@
 }
 
-/** Normalize and clamp the [wbsdvc_collection] attributes. */
+/**
+ * Normalize and clamp the [wbsdvc_collection] attributes. per_page is 0
+ * when neither limit nor per_page was given, which lets the collection
+ * config decide; search, filters and sort are passed on as typed.
+ */
 function wbs_dataverse_connect_parse_collection_atts($atts) {
     $atts = shortcode_atts([
         'name'        => '',
-        'limit'       => 12,
+        'limit'       => '',
+        'per_page'    => '',
         'columns'     => 3,
         'detail_page' => '',
         'form'        => '',
+        'search'      => '',
+        'filters'     => '',
+        'sort'        => '',
     ], $atts, 'wbsdvc_collection');
 
-    $limit = (int) $atts['limit'];
-    $limit = max(1, min(50, $limit ?: 12));
+    $per_page = (int) $atts['limit'];
+    if ($per_page < 1) {
+        $per_page = (int) $atts['per_page'];
+    }
+    $per_page = $per_page < 1 ? 0 : wbs_dataverse_connect_per_page($per_page);
 
     $columns = (int) $atts['columns'];
@@ -36 +54 @@
     return [
         'name'        => sanitize_key($atts['name']),
-        'limit'       => $limit,
+        'limit'       => $per_page,
+        'per_page'    => $per_page,
         'columns'     => $columns,
         'detail_page' => trim((string) $atts['detail_page']),
         'form'        => sanitize_key($atts['form']),
+        'search'      => trim((string) $atts['search']),
+        'filters'     => trim((string) $atts['filters']),
+        'sort'        => trim((string) $atts['sort']),
     ];
 }
@@ -97 +119 @@
     }
     return '<div class="dvc-notice dvc-notice--error">' . esc_html($message) . '</div>';
+}
+
+/**
+ * Toolbar view model and markup: search box, one select per filter
+ * column, sort select, Apply button. The form GETs to the current page
+ * without its query string; the address's own args (page_id on plain
+ * permalinks) travel as hidden inputs, the dvc vars never do. '' when
+ * the collection offers no controls and no count.
+ */
+function wbs_dataverse_connect_collection_toolbar($config, $state, $records, $result, $base) {
+    static $instance = 0;
+    $instance++;
+    $prefix = 'dvc-' . $config['key'] . '-' . $instance;
+
+    $search = null;
+    if (!empty($config['search_columns'])) {
+        $search = [
+            'name'  => 'dvc_q',
+            'id'    => $prefix . '-q',
+            'value' => $state['q'],
+            'label' => __('Search', 'wbs-connect-for-dataverse'),
+        ];
+    }
+
+    $filters = [];
+    foreach ((array) $config['filter_columns'] as $column) {
+        $options = wbs_dataverse_connect_filter_options($config, $column, $records);
+        $current = (string) ($state['filters'][$column] ?? '');
+        if ($current !== '' && !isset($options[$current])) {
+            $options[$current] = $current;
+        }
+        $filters[] = [
+            'column'  => $column,
+            'name'    => 'dvc_f[' . $column . ']',
+            'id'      => $prefix . '-f-' . $column,
+            'label'   => wbs_dataverse_connect_field_label($config, $column),
+            'options' => $options,
+            'value'   => $current,
+        ];
+    }
+
+    $sort = null;
+    $choices = wbs_dataverse_connect_sort_choices($config);
+    if (!empty($choices)) {
+        $sort = [
+            'name'    => 'dvc_sort',
+            'id'      => $prefix . '-sort',
+            'options' => $choices,
+            'value'   => $state['sort'],
+            'label'   => __('Sort by', 'wbs-connect-for-dataverse'),
+        ];
+    }
+
+    $count = isset($result['count']) ? (int) $result['count'] : null;
+    if ($search === null && empty($filters) && $sort === null && $count === null) {
+        return '';
+    }
+
+    $action = $base;
+    $hidden = [];
+    $query  = (string) wp_parse_url($base, PHP_URL_QUERY);
+    if ($query !== '') {
+        $action = substr($base, 0, strpos($base, '?'));
+        parse_str($query, $pairs);
+        foreach ((array) $pairs as $name => $value) {
+            $name = (string) $name;
+            if (!is_scalar($value) || $name === 'dvc' || strpos($name, 'dvc_') === 0) {
+                continue;
+            }
+            $hidden[$name] = (string) $value;
+        }
+    }
+
+    return wbs_dataverse_connect_template('collection-toolbar.php', [
+        'toolbar' => [
+            'action'    => $action,
+            'hidden'    => $hidden,
+            'search'    => $search,
+            'filters'   => $filters,
+            'sort'      => $sort,
+            'count'     => $count,
+            'active'    => wbs_dataverse_connect_state_active($state),
+            'reset_url' => $base,
+        ],
+    ]);
+}
+
+/**
+ * Pagination view model and markup: previous and next links that keep
+ * the search, filter and sort state. '' on a single page.
+ */
+function wbs_dataverse_connect_collection_pagination($config, $state, $result, $base) {
+    if (empty($result['has_prev']) && empty($result['has_next'])) {
+        return '';
+    }
+    $page    = max(1, (int) $result['page']);
+    $current = add_query_arg(wbs_dataverse_connect_state_args($state), $base);
+
+    return wbs_dataverse_connect_template('collection-pagination.php', [
+        'pagination' => [
+            'page'     => $page,
+            'has_prev' => !empty($result['has_prev']),
+            'has_next' => !empty($result['has_next']),
+            'prev_url' => !empty($result['has_prev']) ? add_query_arg('dvc_page', $page - 1 > 1 ? $page - 1 : false, $current) : '',
+            'next_url' => !empty($result['has_next']) ? add_query_arg('dvc_page', $page + 1, $current) : '',
+            'count'    => isset($result['count']) ? (int) $result['count'] : null,
+        ],
+    ]);
 }
 
@@ -122 +252 @@
         );
     }
-
-    $records = wbs_dataverse_connect_get_records($config, $args['limit']);
-    if (is_wp_error($records)) {
-        return wbs_dataverse_connect_outage_notice($records);
-    }
+    if (!wbs_dataverse_connect_can_view($config, 'collection')) {
+        return wbs_dataverse_connect_denied_notice($config, 'collection');
+    }
+    $config = wbs_dataverse_connect_collection_overrides($config, $args);
+    $state  = wbs_dataverse_connect_collection_state($config, $args);
+
+    $result = wbs_dataverse_connect_collection_page($config, $state);
+    if (is_wp_error($result)) {
+        return wbs_dataverse_connect_outage_notice($result);
+    }
+    $records = $result['records'];
+
+    wbs_dataverse_connect_enqueue_style();
+
+    $base       = wbs_dataverse_connect_detail_base('');
+    $toolbar    = wbs_dataverse_connect_collection_toolbar($config, $state, $records, $result, $base);
+    $pagination = wbs_dataverse_connect_collection_pagination($config, $state, $result, $base);
+
     if (empty($records)) {
-        return '<div class="dvc-notice">' . esc_html__('There is nothing to show at the moment.', 'wbs-connect-for-dataverse') . '</div>';
-    }
-    wbs_dataverse_connect_review_note_success();
-
-    wbs_dataverse_connect_enqueue_style();
-
-    $detail_base = wbs_dataverse_connect_detail_base($args['detail_page']);
-    $cards = '';
-    foreach ($records as $record) {
-        $vm = wbs_dataverse_connect_record_vm($config, $record, $detail_base);
-        $cards .= wbs_dataverse_connect_template('collection-card.php', ['vm' => $vm]);
-    }
-
-    return wbs_dataverse_connect_template('collection-list.php', [
-        'cards'   => $cards,
-        'columns' => $args['columns'],
-    ]);
+        $empty = wbs_dataverse_connect_state_active($state)
+            ? __('Nothing matches your search. Try different terms or clear the filters.', 'wbs-connect-for-dataverse')
+            : __('There is nothing to show at the moment.', 'wbs-connect-for-dataverse');
+        $body = '<div class="dvc-notice">' . esc_html($empty) . '</div>';
+    } else {
+        wbs_dataverse_connect_review_note_success();
+
+        $detail_base = wbs_dataverse_connect_detail_base($args['detail_page']);
+        $cards = '';
+        foreach ($records as $record) {
+            $vm = wbs_dataverse_connect_record_vm($config, $record, $detail_base);
+            $cards .= wbs_dataverse_connect_template('collection-card.php', ['vm' => $vm]);
+        }
+        $body = wbs_dataverse_connect_template('collection-list.php', [
+            'cards'   => $cards,
+            'columns' => $args['columns'],
+        ]);
+    }
+
+    return '<div class="dvc-collection">' . $toolbar . $body . $pagination . '</div>';
 }
 
@@ -165 +311 @@
     }
 
+    if (!wbs_dataverse_connect_can_view($config, 'record')) {
+        return wbs_dataverse_connect_denied_notice($config, 'record');
+    }
     $slug = trim((string) $atts['slug']);
     if ($slug === '') {
@@ -217 +366 @@
     }
 
+    if (!wbs_dataverse_connect_can_view($config, 'form')) {
+        return wbs_dataverse_connect_denied_notice($config, 'form');
+    }
+
     // Resolve a slug to the record id so the submission can be bound to it.
     $record_id = '';
     $slug = trim((string) $atts['record']);
-    if ($slug !== '' && is_array($config['relate_to'])) {
-        $collection = wbs_dataverse_connect_collection($config['relate_to']['collection']);
+    if ($slug !== '') {
+        // relate_to names the collection for create forms; update forms may bind through bind_to alone.
+        $collection = is_array($config['relate_to'])
+            ? wbs_dataverse_connect_collection($config['relate_to']['collection'])
+            : wbs_dataverse_connect_form_bind_collection($config);
         if ($collection !== null) {
             $record = wbs_dataverse_connect_get_record($collection, $slug);

wbs-connect-for-dataverse/trunk/readme.txt

@@ -3 +3 @@
 Tags: dataverse, dynamics-365, microsoft, crm, integration
 Requires at least: 6.0
-Tested up to: 7.0
+Tested up to: 7.1
 Requires PHP: 8.0
-Stable tag: 1.4.0
+Stable tag: 1.5.0
 License: GPLv2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
@@ -19 +19 @@
 * **Collections.** Publish any Dataverse table by naming the table, the columns and an optional status filter. No code required; developers can also register collections via a filter.
 * **Grid and detail on one page.** `[wbsdvc_collection]` renders the card grid, and the same page renders the detail view when a record is selected, so links stay short.
+* **Search, filters, sort and paging.** Offer visitors a search box, filter dropdowns and sort choices per collection, and page through long tables with Previous and Next links that keep the current state. Column labels come from the table's display names in Dataverse.
+* **Block editor.** Dataverse Collection, Dataverse Record and Dataverse Form blocks wrap the shortcodes with a dropdown of your configured collections and forms and a live preview.
+* **Images and files.** Show a Dataverse Image column on cards and detail pages and offer File columns as downloads, served through your own site so nothing points at Dataverse directly.
 * **Clean detail URLs.** Point a collection at a slug column and detail links use readable slugs (`?dvc=my-record`) instead of raw record ids. Id links keep working as a fallback.
-* **Write-back forms.** Map form fields to columns of any table; submissions create records in Dataverse, optionally related to the record the form was shown on. Every submission is nonce-verified, honeypot-checked and rate limited.
+* **Write-back forms.** Build a form as a list of typed fields (text, email, phone, multi-line, number, money, date, date and time, choice, multi-select choice, yes/no, lookup, hidden). Values are validated and converted on the server, table metadata fills in labels, options and required levels, and submissions create records in Dataverse, optionally related to the record the form was shown on. Every submission is nonce-verified, honeypot-checked and rate limited; Cloudflare Turnstile can be switched on per form.
+* **Edit mode.** An update-mode form prefills from the record the page shows and saves changes back to it, limited to records visible through the bound collection.
+* **Webhooks.** Post a signed JSON message to URLs of your choice when a form creates a record and when the Dataverse connection fails or recovers, for Power Automate flows or Teams alerts.
 * **Server-side authentication.** The plugin signs in with an Entra ID app registration (client-credentials flow) and a Dataverse application user with a least-privilege role. Credentials never reach the browser; `wp-config.php` constants are the recommended home for them.
 * **Caching and fail-open.** Reads are cached with a configurable TTL. When Dataverse is unreachable, pages show a friendly notice instead of failing; the site never goes blank.
@@ -33 +38 @@
 **External services**
 
-This plugin connects to two external services, both operated by Microsoft and both belonging to you, the site owner. Data flows only between your WordPress host and your own Microsoft tenant's endpoints; nothing is sent to WOODS Business Solutions or any other third party, and the plugin contains no telemetry.
+This plugin connects to two external services, both operated by Microsoft and both belonging to you, the site owner, plus one optional third-party service you switch on per form. Data flows only between your WordPress host and your own Microsoft tenant's endpoints; nothing is sent to WOODS Business Solutions or any other third party, and the plugin contains no telemetry.
 
 1. **Microsoft Entra ID token endpoint** (`login.microsoftonline.com`). The plugin requests OAuth2 access tokens here using the tenant id, client id and client secret you configure. This happens whenever a cached token has expired.
 2. **Your Microsoft Dataverse environment** (the `*.dynamics.com` URL you configure, for example `https://yourorg.crm4.dynamics.com`). The plugin reads the records you chose to publish and creates the records your visitors submit through configured forms (typically a name, email address, phone number and message). This happens on page views of pages using the shortcodes (subject to caching) and on form submissions.
 
-These services are governed by Microsoft's terms and privacy statement:
+3. **Cloudflare Turnstile** (optional). When you switch on the Turnstile toggle for a form and enter a site key and secret key, that form loads the Turnstile widget script from `challenges.cloudflare.com` in the visitor's browser and, on submit, your site sends the challenge token together with the visitor's IP address to Cloudflare's siteverify endpoint to confirm the challenge passed. Forms without the toggle never contact Cloudflare. Terms: [https://www.cloudflare.com/website-terms/](https://www.cloudflare.com/website-terms/), privacy: [https://www.cloudflare.com/privacypolicy/](https://www.cloudflare.com/privacypolicy/)
+
+Webhooks you configure yourself post to the URLs you enter and nowhere else.
+
+The Microsoft services are governed by Microsoft's terms and privacy statement:
 
 * Terms: [https://www.microsoft.com/licensing/terms](https://www.microsoft.com/licensing/terms)
@@ -49 +58 @@
 1. Install and activate the plugin.
 2. In the Entra admin center, create an app registration (no redirect URI needed) and a client secret.
-3. In the Power Platform admin center, create an application user for that app registration in your environment and assign it a least-privilege security role: Read on the tables you publish, Create on the tables your forms write to. Do not use System Administrator.
+3. In the Power Platform admin center, create an application user for that app registration in your environment and assign it a least-privilege security role: Read on the tables you publish, Create on the tables your forms write to, Write on tables used by update-mode forms. Do not use System Administrator.
 4. Enter tenant id, client id, client secret and environment URL under Settings, Dataverse Connect, or define them as `WBS_DATAVERSE_CONNECT_TENANT_ID`, `WBS_DATAVERSE_CONNECT_CLIENT_ID`, `WBS_DATAVERSE_CONNECT_CLIENT_SECRET` and `WBS_DATAVERSE_CONNECT_ENV_URL` in `wp-config.php` (recommended).
 5. Run "Test connection" on the settings page.
-6. Add a collection on the Collections tab and put `[wbsdvc_collection name="<key>"]` on a page.
+6. Add a collection on the Collections tab and put `[wbsdvc_collection name="<key>"]` on a page, or insert the Dataverse Collection block. Optional shortcode attributes: `per_page`, `columns`, `detail_page`, `form`, `search`, `filters`, `sort`.
 
 == Frequently Asked Questions ==
@@ -80 +89 @@
 Any table the application user can read, standard or custom. A collection needs the table's logical name, its entity set name, a name column and the columns to display. Writes work against any table the application user may create records in, with values mapped to text columns; typed columns can be handled via a developer filter.
 
+= Can visitors edit records? =
+
+Only through an update-mode form, and only records that are visible through the collection the form is bound to. The application user needs Write on that table. Records that fail the collection's status filter cannot be opened or changed.
+
 = Are the templates customizable? =
 
@@ -93 +106 @@
 
 == Changelog ==
+
+= 1.5.0 =
+* Search, filters and sort on collections: pick the columns on the Collections tab and visitors get a search box, filter dropdowns and sort choices that work without JavaScript. The [wbsdvc_collection] shortcode accepts per_page, search, filters and sort.
+* Paging: set the records per page on the collection or in the shortcode; Previous and Next links keep the current search, filters and sort, and a result count is shown when Dataverse reports one. Each collection can also have its own cache lifetime.
+* Column labels in cards, detail tables and the toolbar come from the table's display names in Dataverse instead of being guessed from logical names.
+* Typed form fields: a form is now an ordered list of fields with a type, label, required flag, options and default each. Choices, dates, numbers, money, yes/no and lookups are validated and converted on the server. Forms saved with earlier versions keep working unchanged.
+* Update mode for forms: prefill from the record the page shows and save changes back to it. Only records visible through the bound collection can be edited.
+* Cloudflare Turnstile per form, plus a custom success message and an optional redirect after a successful submission.
+* Block editor: Dataverse Collection, Dataverse Record and Dataverse Form blocks with a dropdown of configured collections and forms and a live preview.
+* Image and File columns: pictures on cards and detail pages and file downloads, served through your own site. Only published records are served; files up to 5 MB are cached for a day.
+* Webhooks tab: post a JSON message, optionally signed with a shared secret, when a form creates a record and when the connection fails or recovers. Every webhook has a Test link.
+* Developers: wbs_dataverse_connect_patch() and wbs_dataverse_connect_get_raw() in the client, a wbs_dataverse_connect_typed_value() helper, the actions wbs_dataverse_connect_record_created, wbs_dataverse_connect_record_updated and wbs_dataverse_connect_webhook_dispatched, and filters for the toolbar, the block dropdowns, webhook payloads and media handling. Two new templates, collection-toolbar.php and collection-pagination.php, can be overridden from the theme.
 
 = 1.4.0 =
@@ -116 +141 @@
 == Upgrade Notice ==
 
+= 1.5.0 =
+Search, filters, sort and paging on collections, typed form fields with an edit mode, block editor support, image and file columns, and webhooks. Existing collections and forms keep working unchanged; the application user needs Write on a table only if you switch a form to update mode.
+
 = 1.4.0 =
 Adds a one-time, snoozable request to rate the plugin plus permanent Rate and Support links. No functional changes to collections, forms or the connection.

wbs-connect-for-dataverse/trunk/templates/form.php

@@ -3 +3 @@
  * Write-back form. Override by copying to <theme>/wbs-connect-for-dataverse/.
  * Available: $config (normalized form config), $record_id (GUID of the
- * related record or ''), $rest_url, $nonce.
+ * related or bound record, or ''), $rest_url, $nonce.
  *
- * The submit handler lives in assets/wbs-connect-for-dataverse.js and reads the
- * data-dvc-* attributes; no inline script is printed.
+ * The view model comes from wbs_dataverse_connect_form_view(): every field
+ * carries its type, label, required flag, options and initial value, so
+ * this file only decides on markup. The submit handler lives in
+ * assets/wbs-connect-for-dataverse.js and reads the data-dvc-* attributes;
+ * no inline script is printed.
  */
 if (!defined('ABSPATH')) { exit; }
 
-$wbs_dataverse_connect_form_uid = 'dvc-form-' . substr(md5($config['key'] . $record_id . wp_rand()), 0, 8);
+$wbs_dataverse_connect_view = wbs_dataverse_connect_form_view($config, $record_id);
+
+if (isset($wbs_dataverse_connect_view['error'])) {
+    echo wbs_dataverse_connect_outage_notice($wbs_dataverse_connect_view['error']); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- escaped by the notice builder
+    return;
+}
+if (isset($wbs_dataverse_connect_view['config_error'])) {
+    echo wbs_dataverse_connect_config_notice($wbs_dataverse_connect_view['config_error']); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- escaped by the notice builder
+    return;
+}
+if (!empty($wbs_dataverse_connect_view['missing'])) {
+    echo '<div class="dvc-notice">' . esc_html__('This record is no longer available.', 'wbs-connect-for-dataverse') . '</div>';
+    return;
+}
+
+$wbs_dataverse_connect_form_uid = $wbs_dataverse_connect_view['uid'];
 ?>
-<form class="dvc-form" id="<?php echo esc_attr($wbs_dataverse_connect_form_uid); ?>" method="post"
+<form class="dvc-form dvc-form--<?php echo esc_attr($wbs_dataverse_connect_view['mode']); ?>" id="<?php echo esc_attr($wbs_dataverse_connect_form_uid); ?>" method="post"
       action="<?php echo esc_url($rest_url); ?>"
       data-dvc-rest="<?php echo esc_url($rest_url); ?>"
       data-dvc-nonce="<?php echo esc_attr($nonce); ?>"
+      data-dvc-mode="<?php echo esc_attr($wbs_dataverse_connect_view['mode']); ?>"
       data-dvc-sending="<?php echo esc_attr__('Sending...', 'wbs-connect-for-dataverse'); ?>"
       data-dvc-error="<?php echo esc_attr__('Your message could not be sent. Please try again later.', 'wbs-connect-for-dataverse'); ?>">
     <input type="hidden" name="form" value="<?php echo esc_attr($config['key']); ?>">
-    <input type="hidden" name="record" value="<?php echo esc_attr($record_id); ?>">
+    <input type="hidden" name="record" value="<?php echo esc_attr($wbs_dataverse_connect_view['record_id']); ?>">
     <p class="dvc-form__hp" aria-hidden="true">
         <label><?php echo esc_html__('Website', 'wbs-connect-for-dataverse'); ?><input type="text" name="_dvc_website" tabindex="-1" autocomplete="off"></label>
     </p>
 
-    <?php foreach (array_keys($config['field_map']) as $wbs_dataverse_connect_field) :
-        $wbs_dataverse_connect_required = in_array($wbs_dataverse_connect_field, $config['required'], true);
-        $wbs_dataverse_connect_field_id = $wbs_dataverse_connect_form_uid . '-' . $wbs_dataverse_connect_field;
-        $wbs_dataverse_connect_label    = wbs_dataverse_connect_form_field_label($wbs_dataverse_connect_field);
+    <?php foreach ($wbs_dataverse_connect_view['fields'] as $wbs_dataverse_connect_field) :
+        $wbs_dataverse_connect_name     = $wbs_dataverse_connect_field['name'];
+        $wbs_dataverse_connect_type     = $wbs_dataverse_connect_field['type'];
+        $wbs_dataverse_connect_value    = $wbs_dataverse_connect_field['value'];
+        $wbs_dataverse_connect_required = !empty($wbs_dataverse_connect_field['required']);
+        $wbs_dataverse_connect_field_id = $wbs_dataverse_connect_form_uid . '-' . $wbs_dataverse_connect_name;
+        $wbs_dataverse_connect_marker   = $wbs_dataverse_connect_required ? ' <span class="dvc-form__required" aria-hidden="true">*</span>' : '';
+
+        if ($wbs_dataverse_connect_type === 'hidden') : ?>
+            <input type="hidden" name="<?php echo esc_attr($wbs_dataverse_connect_name); ?>" value="<?php echo esc_attr((string) $wbs_dataverse_connect_value); ?>">
+            <?php continue;
+        endif;
     ?>
+        <?php if ($wbs_dataverse_connect_type === 'boolean') : ?>
+            <p class="dvc-form__row dvc-form__row--check">
+                <input type="hidden" name="<?php echo esc_attr($wbs_dataverse_connect_name); ?>" value="0">
+                <label class="dvc-form__check" for="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>">
+                    <input type="checkbox" id="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>" name="<?php echo esc_attr($wbs_dataverse_connect_name); ?>" value="1"
+                           <?php checked((string) $wbs_dataverse_connect_value, '1'); ?><?php echo $wbs_dataverse_connect_required ? ' required' : ''; ?>>
+                    <span><?php echo esc_html($wbs_dataverse_connect_field['label']); ?><?php echo $wbs_dataverse_connect_marker; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static markup ?></span>
+                </label>
+            </p>
+            <?php continue; ?>
+        <?php endif; ?>
+
+        <?php if ($wbs_dataverse_connect_type === 'multichoice') : ?>
+            <fieldset class="dvc-form__row dvc-form__fieldset">
+                <legend class="dvc-form__label"><?php echo esc_html($wbs_dataverse_connect_field['label']); ?><?php echo $wbs_dataverse_connect_marker; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static markup ?></legend>
+                <input type="hidden" name="<?php echo esc_attr($wbs_dataverse_connect_name); ?>[]" value="">
+                <?php foreach ($wbs_dataverse_connect_field['options'] as $wbs_dataverse_connect_option => $wbs_dataverse_connect_option_label) : ?>
+                    <label class="dvc-form__choice">
+                        <input type="checkbox" name="<?php echo esc_attr($wbs_dataverse_connect_name); ?>[]" value="<?php echo esc_attr((string) $wbs_dataverse_connect_option); ?>"
+                               <?php checked(is_array($wbs_dataverse_connect_value) && in_array((int) $wbs_dataverse_connect_option, $wbs_dataverse_connect_value, true)); ?>>
+                        <span><?php echo esc_html($wbs_dataverse_connect_option_label); ?></span>
+                    </label>
+                <?php endforeach; ?>
+            </fieldset>
+            <?php continue; ?>
+        <?php endif; ?>
+
         <p class="dvc-form__row">
-            <label class="dvc-form__label" for="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>"><?php echo esc_html($wbs_dataverse_connect_label); ?><?php echo $wbs_dataverse_connect_required ? ' *' : ''; ?></label>
-            <?php if ($wbs_dataverse_connect_field === 'message') : ?>
+            <label class="dvc-form__label" for="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>"><?php echo esc_html($wbs_dataverse_connect_field['label']); ?><?php echo $wbs_dataverse_connect_marker; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static markup ?></label>
+            <?php if ($wbs_dataverse_connect_type === 'textarea') : ?>
                 <textarea class="dvc-form__input dvc-form__textarea" id="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>"
-                          name="<?php echo esc_attr($wbs_dataverse_connect_field); ?>" rows="5" <?php echo $wbs_dataverse_connect_required ? 'required' : ''; ?>></textarea>
-            <?php elseif ($wbs_dataverse_connect_field === 'email') : ?>
-                <input class="dvc-form__input" id="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>" type="email"
-                       name="<?php echo esc_attr($wbs_dataverse_connect_field); ?>" <?php echo $wbs_dataverse_connect_required ? 'required' : ''; ?>>
-            <?php elseif ($wbs_dataverse_connect_field === 'phone') : ?>
-                <input class="dvc-form__input" id="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>" type="tel"
-                       name="<?php echo esc_attr($wbs_dataverse_connect_field); ?>" <?php echo $wbs_dataverse_connect_required ? 'required' : ''; ?>>
-            <?php else : ?>
-                <input class="dvc-form__input" id="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>" type="text"
-                       name="<?php echo esc_attr($wbs_dataverse_connect_field); ?>" <?php echo $wbs_dataverse_connect_required ? 'required' : ''; ?>>
+                          name="<?php echo esc_attr($wbs_dataverse_connect_name); ?>" rows="5"<?php echo $wbs_dataverse_connect_required ? ' required' : ''; ?>><?php echo esc_textarea((string) $wbs_dataverse_connect_value); ?></textarea>
+            <?php elseif ($wbs_dataverse_connect_type === 'choice' || ($wbs_dataverse_connect_type === 'lookup' && !empty($wbs_dataverse_connect_field['options']))) : ?>
+                <select class="dvc-form__input dvc-form__select" id="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>"
+                        name="<?php echo esc_attr($wbs_dataverse_connect_name); ?>"<?php echo $wbs_dataverse_connect_required ? ' required' : ''; ?>>
+                    <option value=""><?php echo esc_html__('Please choose', 'wbs-connect-for-dataverse'); ?></option>
+                    <?php foreach ($wbs_dataverse_connect_field['options'] as $wbs_dataverse_connect_option => $wbs_dataverse_connect_option_label) : ?>
+                        <option value="<?php echo esc_attr((string) $wbs_dataverse_connect_option); ?>" <?php selected((string) $wbs_dataverse_connect_option, (string) $wbs_dataverse_connect_value); ?>><?php echo esc_html($wbs_dataverse_connect_option_label); ?></option>
+                    <?php endforeach; ?>
+                </select>
+            <?php else :
+                $wbs_dataverse_connect_input = ['type' => 'text', 'extra' => ''];
+                switch ($wbs_dataverse_connect_type) {
+                    case 'email':
+                        $wbs_dataverse_connect_input = ['type' => 'email', 'extra' => ''];
+                        break;
+                    case 'phone':
+                        $wbs_dataverse_connect_input = ['type' => 'tel', 'extra' => ''];
+                        break;
+                    case 'number':
+                        $wbs_dataverse_connect_input = ['type' => 'number', 'extra' => ' step="any"'];
+                        break;
+                    case 'money':
+                        $wbs_dataverse_connect_input = ['type' => 'number', 'extra' => ' step="0.01"'];
+                        break;
+                    case 'date':
+                        $wbs_dataverse_connect_input = ['type' => 'date', 'extra' => ''];
+                        break;
+                    case 'datetime':
+                        $wbs_dataverse_connect_input = ['type' => 'datetime-local', 'extra' => ''];
+                        break;
+                }
+            ?>
+                <input class="dvc-form__input" id="<?php echo esc_attr($wbs_dataverse_connect_field_id); ?>" type="<?php echo esc_attr($wbs_dataverse_connect_input['type']); ?>"
+                       name="<?php echo esc_attr($wbs_dataverse_connect_name); ?>" value="<?php echo esc_attr((string) $wbs_dataverse_connect_value); ?>"<?php echo $wbs_dataverse_connect_input['extra']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static attribute ?><?php echo $wbs_dataverse_connect_required ? ' required' : ''; ?>>
             <?php endif; ?>
         </p>
@@ -56 +134 @@
     <?php endif; ?>
 
+    <?php if ($wbs_dataverse_connect_view['turnstile'] !== '') : ?>
+        <div class="dvc-form__row dvc-form__turnstile cf-turnstile" data-sitekey="<?php echo esc_attr($wbs_dataverse_connect_view['turnstile']); ?>"></div>
+    <?php endif; ?>
+
     <p class="dvc-form__row">
-        <button class="dvc-form__submit" type="submit"><?php echo esc_html__('Send', 'wbs-connect-for-dataverse'); ?></button>
+        <button class="dvc-form__submit" type="submit"><?php echo esc_html($wbs_dataverse_connect_view['submit_label']); ?></button>
     </p>
     <p class="dvc-form__status" role="status" aria-live="polite"></p>

wbs-connect-for-dataverse/trunk/templates/record-detail.php

@@ -2 +2 @@
 /**
  * Record detail view. Override by copying to <theme>/wbs-connect-for-dataverse/.
- * Available: $vm (view model array, see wbs_dataverse_connect_record_vm()),
- * $form (pre-rendered form HTML, empty when no form is attached).
+ * Available: $vm (view model array, see wbs_dataverse_connect_record_vm();
+ * $vm['files'] lists downloadable file columns as ['column', 'label',
+ * 'url', 'name'] when the collection has any), $form (pre-rendered form
+ * HTML, empty when no form is attached).
  */
 if (!defined('ABSPATH')) { exit; }
@@ -33 +35 @@
     <?php endif; ?>
 
+    <?php if (!empty($vm['files']) && is_array($vm['files'])) : ?>
+        <section class="dvc-detail__files">
+            <h2 class="dvc-detail__heading"><?php echo esc_html__('Downloads', 'wbs-connect-for-dataverse'); ?></h2>
+            <ul class="dvc-files">
+                <?php foreach ($vm['files'] as $wbs_dataverse_connect_file) :
+                    if (!is_array($wbs_dataverse_connect_file) || empty($wbs_dataverse_connect_file['url'])) {
+                        continue;
+                    }
+                    $wbs_dataverse_connect_file_name = (string) ($wbs_dataverse_connect_file['name'] ?? '');
+                    if ($wbs_dataverse_connect_file_name === '') {
+                        $wbs_dataverse_connect_file_name = (string) ($wbs_dataverse_connect_file['label'] ?? $wbs_dataverse_connect_file['column'] ?? '');
+                    }
+                ?>
+                    <li class="dvc-files__item">
+                        <a class="dvc-files__link" href="<?php echo esc_url($wbs_dataverse_connect_file['url']); ?>"><?php echo esc_html($wbs_dataverse_connect_file_name); ?></a>
+                        <?php if (!empty($wbs_dataverse_connect_file['label']) && $wbs_dataverse_connect_file['label'] !== $wbs_dataverse_connect_file_name) : ?>
+                            <span class="dvc-files__label"><?php echo esc_html($wbs_dataverse_connect_file['label']); ?></span>
+                        <?php endif; ?>
+                    </li>
+                <?php endforeach; ?>
+            </ul>
+        </section>
+    <?php endif; ?>
+
     <?php if (!empty($form)) : ?>
         <section class="dvc-detail__form">

wbs-connect-for-dataverse/trunk/uninstall.php

@@ -23 +23 @@
     'wbsdvc_health',
     'wbsdvc_review',
+    'wbsdvc_webhooks',
+    'wbs_dataverse_connect_turnstile_site_key',
+    'wbs_dataverse_connect_turnstile_secret_key',
 ];
 foreach ($wbs_dataverse_connect_options as $wbs_dataverse_connect_option) {

wbs-connect-for-dataverse/trunk/wbs-connect-for-dataverse.php

@@ -4 +4 @@
  * Plugin URI: https://woods.consulting/wbs-dataverse-connect-for-wordpress/
  * Description: Publish Microsoft Dataverse records as lists and detail views on your WordPress site, and write form submissions straight back into Dataverse tables.
- * Version: 1.4.0
+ * Version: 1.5.0
  * Author: WOODS Business Solutions
  * Author URI: https://woods.consulting
@@ -16 +16 @@
 if (!defined('ABSPATH')) { exit; }
 
-define('WBS_DATAVERSE_CONNECT_VERSION', '1.4.0');
+define('WBS_DATAVERSE_CONNECT_VERSION', '1.5.0');
 define('WBS_DATAVERSE_CONNECT_PATH', plugin_dir_path(__FILE__));
 define('WBS_DATAVERSE_CONNECT_URL',  plugin_dir_url(__FILE__));
@@ -23 +23 @@
 require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/health.php';
 require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/dataverse.php';
+require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/metadata.php';
 require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/collections.php';
 require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/forms.php';
@@ -28 +29 @@
 require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/shortcodes.php';
 require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/rest.php';
+require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/media.php';
+require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/webhooks.php';
+require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/blocks.php';
 require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/admin.php';
 require_once WBS_DATAVERSE_CONNECT_PATH . 'includes/review.php';
@@ -50 +54 @@
 add_action('admin_init', 'wbs_dataverse_connect_admin_init');
 wbs_dataverse_connect_review_boot();
+wbs_dataverse_connect_blocks_boot();
 add_action('admin_post_wbs_dataverse_connect_flush', 'wbs_dataverse_connect_handle_flush');
 add_action('admin_post_wbs_dataverse_connect_test', 'wbs_dataverse_connect_handle_test');