|
|
|
@@ -1,209 +0,0 @@
|
|
|
|
|
# Implementation prompt — Templating module
|
|
|
|
|
|
|
|
|
|
> Hand this whole file to a Claude Sonnet model as its task. It is written to be
|
|
|
|
|
> self-contained but assumes the model can read the repository.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Mission
|
|
|
|
|
|
|
|
|
|
Implement the templating engine specified in `TEMPLATING.md` as a **new,
|
|
|
|
|
self-contained module** in this WordPress plugin (Reservair). Today the plugin
|
|
|
|
|
has two ad-hoc, regex-based templaters; your job is to replace them with one
|
|
|
|
|
properly-designed module and wire the existing call sites into it.
|
|
|
|
|
|
|
|
|
|
Build the smallest thing that satisfies the spec. `TEMPLATING.md` is explicit
|
|
|
|
|
that the language must stay simple ("Helm being the example of what not to do") —
|
|
|
|
|
do **not** add conditionals, loops, or expression evaluation. The only language
|
|
|
|
|
features are `{{ jsonpath }}` interpolation and custom elements.
|
|
|
|
|
|
|
|
|
|
## Read these first (in order)
|
|
|
|
|
|
|
|
|
|
1. `TEMPLATING.md` — the requirements you are implementing. Treat it as the spec.
|
|
|
|
|
2. `modules/Database/README.md` and `modules/Logger/README.md` — the **module
|
|
|
|
|
template** to imitate: a `modules/<Name>/` folder, namespace
|
|
|
|
|
`Reservair\<Name>`, a `README.md` with *Why / Usage / API reference* sections,
|
|
|
|
|
`Rsv`-prefixed classes, snake_case method names, a module-specific exception.
|
|
|
|
|
3. `modules/Database/Db.php` and `modules/Logger/Logger.php` — the coding style
|
|
|
|
|
to match (PHP 8.0 union types, typed properties, named args, `Logger` for
|
|
|
|
|
errors, a `\RuntimeException` subclass for failures).
|
|
|
|
|
4. The two things you are replacing:
|
|
|
|
|
- `includes/Services/Emails/RsvEmailTemplater.php` — `{{ word }}` → `$data[word]`.
|
|
|
|
|
- `includes/Services/Forms/RsvFormHtmlRenderer.php::draw_success_template()` —
|
|
|
|
|
swaps `{{ reservation_summary }}` for a client-filled placeholder.
|
|
|
|
|
5. `reservair.php::rsv_bootstrap()` — where runtime services and registries are
|
|
|
|
|
wired on `plugins_loaded`. New registration hooks fire from here.
|
|
|
|
|
6. `includes/Events/RsvEventDispatcher.php` — the `do_action`/`add_action` hook
|
|
|
|
|
convention used in this codebase.
|
|
|
|
|
|
|
|
|
|
## The module to create
|
|
|
|
|
|
|
|
|
|
- Path: `modules/Templating/`
|
|
|
|
|
- Namespace: `Reservair\Templating` (PSR-4 is already configured in
|
|
|
|
|
`composer.json`: `"Reservair\\": "modules/"` — no autoload changes needed).
|
|
|
|
|
- Must include `modules/Templating/README.md` following the Database/Logger
|
|
|
|
|
README shape.
|
|
|
|
|
|
|
|
|
|
## Architecture (a tiny compiler)
|
|
|
|
|
|
|
|
|
|
`TEMPLATING.md` describes a compiler with a swappable **frontend**. Honour that:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
source string ──[ frontend ]──▶ internal node tree ──[ renderer ]──▶ output string
|
|
|
|
|
RsvHtmlTemplateParser (frontend-agnostic)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- **Frontend** `RsvHtmlTemplateParser`: parses HTML into an internal node tree
|
|
|
|
|
(the "internal structure" from the spec). The renderer must depend only on the
|
|
|
|
|
node tree, never on HTML — so a future Markdown/other frontend can be dropped in
|
|
|
|
|
by producing the same tree. Define the parser behind a small interface (e.g.
|
|
|
|
|
`RsvTemplateParser` with `parse(string $source): RsvTemplateNode`) so the engine
|
|
|
|
|
takes a frontend by constructor injection and defaults to the HTML one.
|
|
|
|
|
- **Internal node tree**: a minimal set of node types is enough — e.g. a text
|
|
|
|
|
node, an interpolation node (holds a JSON Path), and a custom-element node
|
|
|
|
|
(holds tag name, attribute map, children). Keep it small and explicit.
|
|
|
|
|
- **Renderer/evaluator**: walks the tree with (a) the submitted-data symbol table
|
|
|
|
|
and (b) the custom-element registry, and concatenates strings.
|
|
|
|
|
|
|
|
|
|
You may use PHP's `DOMDocument` to do the actual HTML tokenizing inside the
|
|
|
|
|
frontend, but convert its output into your own node tree — do not leak DOM
|
|
|
|
|
objects into the renderer. Watch the usual `DOMDocument::loadHTML` pitfalls
|
|
|
|
|
(wrapping `<html>/<body>`, entity handling, UTF-8); strip the synthetic wrappers.
|
|
|
|
|
|
|
|
|
|
## Language semantics
|
|
|
|
|
|
|
|
|
|
### `{{ jsonpath }}` interpolation
|
|
|
|
|
- Resolves a JSON Path (RFC 9535) expression against the submitted data array and
|
|
|
|
|
substitutes the **atomic value** (string/number/bool) as text. Non-scalar
|
|
|
|
|
results (objects/arrays) resolve to empty string.
|
|
|
|
|
- Keep the resolver to the minimal subset the use cases need: child access by dot
|
|
|
|
|
and by bracket, and array index — e.g. `name`, `$.name`, `$.guest.email`,
|
|
|
|
|
`$.items[0]`. Do **not** implement wildcards, filters, slices, or recursion.
|
|
|
|
|
- **Use a simple token-walk implementation**, not a real JSON Path parser. Split
|
|
|
|
|
the path on `.`/`[`/`]` and walk the data array one key at a time:
|
|
|
|
|
```php
|
|
|
|
|
function resolve(string $path, array $data): mixed {
|
|
|
|
|
$tokens = preg_split('/[\.\[\]]+/', $path, -1, PREG_SPLIT_NO_EMPTY);
|
|
|
|
|
$current = $data;
|
|
|
|
|
foreach ($tokens as $token) {
|
|
|
|
|
if (!isset($current[$token])) return null;
|
|
|
|
|
$current = $current[$token];
|
|
|
|
|
}
|
|
|
|
|
return $current;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
This already handles bare keys, dotted access, and `[index]` in one pass. Make
|
|
|
|
|
two small additions so the `$`-rooted and quoted-bracket forms resolve: drop a
|
|
|
|
|
leading `$` token, and strip surrounding `'`/`"` from bracket keys (so
|
|
|
|
|
`$['guest']` works). A `null` return means "no such path" — render it as the
|
|
|
|
|
empty string.
|
|
|
|
|
- **Backward compatibility (required):** existing templates use a bare key,
|
|
|
|
|
`{{ reservation_summary }}` and email bodies like `{{ name }}`. A bare
|
|
|
|
|
identifier must resolve as a top-level key, identically to today.
|
|
|
|
|
- **Security:** the output target is HTML, so HTML-escape interpolated scalar
|
|
|
|
|
values by default (`esc_html`). This lets you delete the manual
|
|
|
|
|
`RsvEmailListener::escape_values()` pre-escaping once the engine owns escaping —
|
|
|
|
|
do that. Custom elements (below) are trusted and return their own markup.
|
|
|
|
|
|
|
|
|
|
### Custom elements
|
|
|
|
|
- A custom element is a registered handler keyed by tag name. The renderer, on
|
|
|
|
|
meeting `<some-element attr="x">…</some-element>`, builds a **symbol table** and
|
|
|
|
|
asks the handler to render a string.
|
|
|
|
|
- Per the spec: the symbol table contains the submitted-data symbols **plus** one
|
|
|
|
|
symbol per attribute (`<el attr="test">` adds `attr` => `"test"`). Decide and
|
|
|
|
|
document how children/inner content are exposed (a captured inner string is the
|
|
|
|
|
simplest; do the simplest thing that the reservation-summary case needs).
|
|
|
|
|
- Define a small interface, e.g.:
|
|
|
|
|
```php
|
|
|
|
|
interface RsvTemplateElement {
|
|
|
|
|
/** Render this element to a string given its symbol table. */
|
|
|
|
|
public function render(RsvTemplateSymbols $symbols): string;
|
|
|
|
|
/** Symbols/attributes this element understands — used by validation. */
|
|
|
|
|
public function symbols(): array;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
(Adjust names to fit, but keep "has a symbol table, outputs a string".)
|
|
|
|
|
|
|
|
|
|
### Registration hook
|
|
|
|
|
- The module fires `do_action('rsv-template-register-custom-elements', $registry)`
|
|
|
|
|
so the plugin and any extension can register elements in the handler. Register
|
|
|
|
|
the core element(s) the same way the plugin registers everything else (from a
|
|
|
|
|
callback wired in `rsv_bootstrap()`), not by hard-coding them inside the module.
|
|
|
|
|
|
|
|
|
|
### Validation
|
|
|
|
|
- Provide a `validate(string $source): array` (or a small result object) that
|
|
|
|
|
returns the problems in a template without rendering it: unknown/invalid JSON
|
|
|
|
|
Path symbols and unregistered custom elements. The spec calls this out as a
|
|
|
|
|
first-class capability ("The language can be easily validated for symbols
|
|
|
|
|
existence and validity").
|
|
|
|
|
|
|
|
|
|
## Public API (the facade)
|
|
|
|
|
|
|
|
|
|
Expose one obvious entry point — e.g. `RsvTemplateEngine` (or `RsvTemplate`):
|
|
|
|
|
|
|
|
|
|
```php
|
|
|
|
|
$engine = new RsvTemplateEngine(); // defaults to the HTML frontend + registry
|
|
|
|
|
$html = $engine->render($source, $data); // data = submitted values array
|
|
|
|
|
$errors = $engine->validate($source); // [] when valid
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Keep method names snake_case to match the other modules. Throw a module
|
|
|
|
|
exception (e.g. `RsvTemplateException extends \RuntimeException`) for malformed
|
|
|
|
|
templates, and log via `Reservair\Logger\Logger` where the existing modules do.
|
|
|
|
|
|
|
|
|
|
## Integration (wire the new module into the live call sites)
|
|
|
|
|
|
|
|
|
|
1. **Email bodies** — replace `RsvEmailTemplater` with the engine.
|
|
|
|
|
`RsvEmailListener` currently calls `(new RsvEmailTemplater())->render(...)` and
|
|
|
|
|
pre-escapes values; switch it to the engine and drop the manual escaping (the
|
|
|
|
|
engine escapes interpolations). Keep `RsvEmailTemplater` only if something else
|
|
|
|
|
needs it; otherwise remove it and update references.
|
|
|
|
|
2. **Form success message** — replace the regex in
|
|
|
|
|
`RsvFormHtmlRenderer::draw_success_template()` with the engine.
|
|
|
|
|
**Critical caveat:** `reservation_summary` in the success message is **not**
|
|
|
|
|
server data — it is the visitor's live selection, filled in the browser by
|
|
|
|
|
`assets/js/forms/RsvFormSender.js`, which looks for the
|
|
|
|
|
`<div class="rsv-success-summary">` placeholder. So model `reservation-summary`
|
|
|
|
|
as a registered custom element that, here, emits that exact placeholder div, so
|
|
|
|
|
the existing client JS keeps working unchanged. Do not try to compute the
|
|
|
|
|
summary server-side. The admin HTML is still sanitized with `wp_kses_post`
|
|
|
|
|
before/around templating, as today.
|
|
|
|
|
3. **Bootstrap** — in `rsv_bootstrap()`, after the form registry block, fire the
|
|
|
|
|
custom-element registration (or instantiate the engine's registry and register
|
|
|
|
|
core elements) consistent with how the form element registry is built there.
|
|
|
|
|
|
|
|
|
|
## Conventions & constraints (do not skip)
|
|
|
|
|
|
|
|
|
|
- **Match module style**, not `includes/` style: `Rsv` class prefix, snake_case
|
|
|
|
|
methods, typed properties, PHP 8.0 features. Files namespaced `Reservair\Templating`.
|
|
|
|
|
- **Doc comments state intent, not mechanics** — say *what/why*, never narrate the
|
|
|
|
|
loop. (This is a standing rule in this repo.)
|
|
|
|
|
- **No new Composer dependencies** unless genuinely unavoidable; the JSON Path
|
|
|
|
|
subset and HTML parsing are small enough to implement in-module. If you believe
|
|
|
|
|
a dependency is warranted, stop and justify it instead of adding it silently.
|
|
|
|
|
- **No database, no migrations** — this module is pure text transformation.
|
|
|
|
|
- **Security:** never emit unescaped submitted data; escape interpolations,
|
|
|
|
|
sanitize admin HTML with `wp_kses_post` at the boundary as today, and treat
|
|
|
|
|
custom-element output as trusted-by-registration.
|
|
|
|
|
- Ship `modules/Templating/README.md` (Why / Usage / API reference / Notes), and
|
|
|
|
|
delete or update `TEMPLATING.md`-superseded code so there is exactly one
|
|
|
|
|
templating path.
|
|
|
|
|
|
|
|
|
|
## Definition of done
|
|
|
|
|
|
|
|
|
|
- [ ] `modules/Templating/` exists with the engine, HTML frontend, node tree,
|
|
|
|
|
custom-element registry + interface, JSON Path resolver, validation, a
|
|
|
|
|
module exception, and `README.md`.
|
|
|
|
|
- [ ] `rsv-template-register-custom-elements` action is fired by the module and
|
|
|
|
|
consumed from `rsv_bootstrap()`; `reservation-summary` is registered there.
|
|
|
|
|
- [ ] Email bodies and form success messages render through the engine; existing
|
|
|
|
|
templates (`{{ name }}`, `{{ reservation_summary }}`) behave exactly as
|
|
|
|
|
before, including client-side summary fill.
|
|
|
|
|
- [ ] `RsvEmailTemplater` and the success-message regex are gone (or justified).
|
|
|
|
|
- [ ] `composer lint` (phpcs, phpstan, psalm — see `composer.json` scripts) passes
|
|
|
|
|
clean on the new and changed files.
|
|
|
|
|
- [ ] README includes at least one worked example for each use case (email,
|
|
|
|
|
success message) and a custom-element registration example.
|
|
|
|
|
|
|
|
|
|
If anything in `TEMPLATING.md` is ambiguous, prefer the **simpler** reading and
|
|
|
|
|
note the decision in the README rather than expanding the language.
|
Martin Slachta