Martin Slachta
@@ -0,0 +1,181 @@
|
||||
# Implementation Brief: Live form preview in the form editor
|
||||
|
||||
## Goal
|
||||
Add a real-time form preview pane beside the elements editor on the form **edit** page. Reuse the existing PHP renderer (`RsvFormHtmlRenderer`) via a new admin REST endpoint — do **not** build a JS renderer.
|
||||
|
||||
## Context you need (don't re-derive)
|
||||
- **Editor**: `includes/Views/RsvFormsPage.php`. `show_edit()` renders the edit page; `elements_table_script()` emits the inline `<script>` that drives the elements table. Elements live in an in-memory JS object `rsv_elements_source`; `rsv_elements_source.get_all()` returns the elements array (without internal `id`). Nothing is persisted until the form is saved (PUT).
|
||||
- **Renderer**: `includes/Services/Forms/RsvFormHtmlRenderer.php`. `draw(RsvFormDefinition $form): bool` **echoes** the real `<form>` HTML; returns `false` and echoes nothing when the form has no elements. This is the same renderer the frontend uses (`src/render.php`).
|
||||
- **Definition object**: `new RsvFormDefinition(string $id, array $definition)` where `$definition` has keys `elements` (array), `email_key`, `success_message`.
|
||||
- **Assets**: admin already enqueues the `rsv-client` bundle (`rsv_enqueue_admin_assets` in `includes/RsvAssetsDefinition.php`). It defines the custom elements (`<rsv-reservation-selector>`, `<rsv-reservation-summary>`) and bundles the form CSS (`RsvFormStyles.css` -> confirmed in `build/client.css`). **So form HTML injected via `innerHTML` into the admin page is styled and auto-upgrades its custom elements — no extra assets needed.**
|
||||
- `ReservairServiceAPI.nonce` and `ReservairServiceAPI.restUrl` are available globally in admin (localized onto `rsv-client`).
|
||||
- The registries `$rsv_form_registry` / `$rsv_template_registry` are populated on `plugins_loaded` (`rsv_bootstrap`), which runs for REST requests too.
|
||||
- REST errors are handled globally by the `rest_dispatch_request` filter in `includes/RsvRestApiDefinition.php` (any `Throwable` -> 500 JSON `{error}`), so the endpoint needs no try/catch.
|
||||
- `RsvColumnLayout::split('3:2')->column(fn)->column(fn)->output()` (`modules/Layout/RsvColumnLayout.php`) renders side-by-side columns; each callable just echoes. CSS for `.rsv-cols`/`.rsv-col` already exists (used on the list page).
|
||||
|
||||
## The plan is JS-inline only — no webpack rebuild
|
||||
All new editor JS goes inside the existing inline `<script>` in `elements_table_script()`. Do **not** add CSS to `assets/css/*` (that would require a webpack rebuild); use inline `style=""`/a `<style>` block in the PHP if you want the sticky preview.
|
||||
|
||||
---
|
||||
|
||||
## Task 1 — Preview endpoint
|
||||
**File:** `includes/Controllers/RsvFormDefinitionController.php`
|
||||
|
||||
In `register_routes()`, add a standalone route (the `\d+` id route won't match the non-numeric `preview`, so order is safe):
|
||||
|
||||
```php
|
||||
register_rest_route($this->namespace, '/' . $this->resource_name . '/preview', [
|
||||
'methods' => 'POST',
|
||||
'callback' => [$this, 'preview'],
|
||||
'permission_callback' => [RsvRestPolicy::class, 'admin'],
|
||||
]);
|
||||
```
|
||||
|
||||
Add the method:
|
||||
|
||||
```php
|
||||
/** Renders an unsaved definition to HTML for the editor's live preview. */
|
||||
function preview(WP_REST_Request $request): WP_REST_Response {
|
||||
$definition = $request->get_json_params()['definition'] ?? [];
|
||||
if (!is_array($definition)) {
|
||||
$definition = [];
|
||||
}
|
||||
|
||||
ob_start();
|
||||
(new RsvFormHtmlRenderer())->draw(new RsvFormDefinition('preview', $definition));
|
||||
$html = ob_get_clean();
|
||||
|
||||
return new WP_REST_Response(['html' => $html], 200);
|
||||
}
|
||||
```
|
||||
|
||||
Notes: no-elements case -> `$html` is `''` (handled client-side). A malformed element payload would throw, but the global filter turns it into a 500 the client catch handles gracefully.
|
||||
|
||||
---
|
||||
|
||||
## Task 2 — Editor layout (two columns + preview pane)
|
||||
**File:** `includes/Views/RsvFormsPage.php`, `show_edit()`.
|
||||
|
||||
Replace the current Form Elements block (the `<h2>Form Elements</h2>` heading, `#form_elements_table`, the add button, and the submit button — currently around lines 133–142) with a split layout. **Keep the existing IDs `form_elements_table` and `rsv_add_element_btn`.** `RsvColumnLayout` is already imported at the top of the file.
|
||||
|
||||
```php
|
||||
<hr>
|
||||
<h2>Form Elements</h2>
|
||||
<p>Define the fields that will appear in this form.</p>
|
||||
<?php
|
||||
RsvColumnLayout::split('3:2')
|
||||
->column(function (): void { ?>
|
||||
<div id="form_elements_table"></div>
|
||||
<p>
|
||||
<button type="button" class="button" id="rsv_add_element_btn">+ Add Element</button>
|
||||
</p>
|
||||
<p class="submit">
|
||||
<button type="submit" form="edit_form_definition" class="button button-primary">Update Form Definition</button>
|
||||
</p>
|
||||
<?php })
|
||||
->column(function (): void { ?>
|
||||
<h3>Live preview</h3>
|
||||
<div id="rsv_form_preview" class="rsv-form-preview" style="position: sticky; top: 40px;"></div>
|
||||
<?php })
|
||||
->output();
|
||||
?>
|
||||
```
|
||||
|
||||
The container is `rsv-form-preview` (a plain wrapper) — **not** `reservair-form`; the injected HTML brings its own `<form class="reservair-form ...">`.
|
||||
|
||||
---
|
||||
|
||||
## Task 3 — Editor wiring (inline JS in `elements_table_script()`)
|
||||
|
||||
### 3a. Shared definition collector + preview functions
|
||||
Add at the top level of the script (right after the `rsv_elements_source` IIFE). `<?= $form_id ?>` is the meta form's id (`edit_form_definition` on the edit page):
|
||||
|
||||
```js
|
||||
function rsv_collect_definition() {
|
||||
const form = document.getElementById('<?= $form_id ?>');
|
||||
const get = (n) => form?.querySelector(`[name="${n}"]`)?.value ?? '';
|
||||
return {
|
||||
name: get('name'),
|
||||
definition: {
|
||||
email_key: get('definition.email_key'),
|
||||
success_message: get('definition.success_message'),
|
||||
elements: rsv_elements_source.get_all(),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
const rsv_preview_el = document.getElementById('rsv_form_preview');
|
||||
let rsv_preview_timer = null;
|
||||
|
||||
function rsv_schedule_preview() {
|
||||
if (!rsv_preview_el) return;
|
||||
clearTimeout(rsv_preview_timer);
|
||||
rsv_preview_timer = setTimeout(rsv_render_preview, 300);
|
||||
}
|
||||
|
||||
function rsv_render_preview() {
|
||||
if (!rsv_preview_el) return;
|
||||
fetch('<?= get_rest_url(null, 'reservations/v1/form-definition/preview') ?>', {
|
||||
method: 'POST',
|
||||
credentials: 'same-origin',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Accept': 'application/json',
|
||||
'X-WP-Nonce': ReservairServiceAPI.nonce,
|
||||
},
|
||||
body: JSON.stringify(rsv_collect_definition()),
|
||||
})
|
||||
.then(r => r.ok ? r.json() : r.json().then(e => { throw new Error(e.error || 'Preview failed'); }))
|
||||
.then(data => {
|
||||
rsv_preview_el.innerHTML = data.html || '<p class="rsv-preview-empty">No fields to preview yet.</p>';
|
||||
})
|
||||
.catch(() => { rsv_preview_el.innerHTML = '<p class="rsv-preview-empty">Preview unavailable.</p>'; });
|
||||
}
|
||||
|
||||
// The preview form is inert: block submission (capture so it works after re-render).
|
||||
rsv_preview_el?.addEventListener('submit', (e) => e.preventDefault(), true);
|
||||
```
|
||||
|
||||
### 3b. Trigger preview on every mutation
|
||||
- **Inline edit** (`rsv_render_element_inline_form`, the `builder.build({...})` options): change the two callbacks to also schedule a preview:
|
||||
```js
|
||||
on_success: () => { elements_dt.refresh(); rsv_schedule_preview(); },
|
||||
on_cancel: () => { elements_dt.refresh(); rsv_schedule_preview(); },
|
||||
```
|
||||
- **Move Up / Move Down / Remove** `func_action`s and the **`rsv_add_element_btn` onclick**: add `rsv_schedule_preview();` right after each `dt.refresh()` / `elements_dt.refresh()`.
|
||||
- **Meta fields**: after the existing `rsv_email_key_select` block, add:
|
||||
```js
|
||||
const rsv_meta_form = document.getElementById('<?= $form_id ?>');
|
||||
['name', 'definition.email_key', 'definition.success_message'].forEach((n) => {
|
||||
const el = rsv_meta_form?.querySelector(`[name="${n}"]`);
|
||||
el?.addEventListener('input', rsv_schedule_preview);
|
||||
el?.addEventListener('change', rsv_schedule_preview);
|
||||
});
|
||||
```
|
||||
|
||||
### 3c. Reuse the collector for saving
|
||||
Simplify the existing `RsvAdminForm.bind(...)` `transform` to reuse the collector (keeps preview == saved shape):
|
||||
```js
|
||||
transform: () => rsv_collect_definition(),
|
||||
```
|
||||
|
||||
### 3d. Initial render
|
||||
At the end of the script add:
|
||||
```js
|
||||
rsv_render_preview();
|
||||
```
|
||||
(`rsv_render_preview` no-ops when `#rsv_form_preview` is absent, e.g. the create page, so the shared script stays safe there.)
|
||||
|
||||
---
|
||||
|
||||
## Edge cases / constraints
|
||||
- A freshly-added element defaults to `type: 'text'`, which has no registered handler -> silently skipped in the preview until a real type is chosen. Expected.
|
||||
- The `<rsv-reservation-selector>` in the preview will fetch availability read-only by `timetable-id` — fine, makes the preview realistic.
|
||||
- Use form id `'preview'` (already in the endpoint) so it never collides with a real numeric form id.
|
||||
- Don't touch `RsvFormHtmlRenderer` — submission is neutralized client-side.
|
||||
|
||||
## Verification
|
||||
- `php -l includes/Controllers/RsvFormDefinitionController.php includes/Views/RsvFormsPage.php`
|
||||
- `composer lint` (runs phpcs, phpstan, psalm) — must pass.
|
||||
- No JS build needed (all editor JS is inline).
|
||||
- Manual: open a form's edit page -> edit/add/reorder elements and change the meta fields -> preview updates within ~300 ms and matches the frontend form.
|
||||
Reference in New Issue
Block a user