Skip to content

Add dynamic {aql:} placeholder tokens for query values - #180

Open
ryanwelcher wants to merge 17 commits into
trunkfrom
feature/dynamic-placeholders
Open

ryanwelcher wants to merge 17 commits into
trunkfrom
feature/dynamic-placeholders

Conversation

@ryanwelcher

@ryanwelcher ryanwelcher commented Sep 8, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds dynamic placeholder tokens of the form {aql:name} that can be used in any query value, most usefully as a meta query value. Tokens are resolved centrally on the raw block query params before any trait or the aql_query_vars filter runs, so every control (built in or third party) supports them without per-control code.

  • Placeholder_Resolver (includes/Placeholder_Resolver.php). A pure class that reads only the context array passed to it, never global WP state, so it is fully unit-testable. Tokens that resolve to nothing are left in the value verbatim. A logged-out {aql:user_id} therefore compares against a literal string that matches no real meta value, so the clause matches nothing rather than widening to match everything.
  • Resolved in all three query paths. Frontend inherited queries, frontend non-inherited queries via query_loop_block_query_vars, and editor previews via rest_{post_type}_query. The editor sends the edited post ID with preview requests (aql_preview_post_id) via an apiFetch middleware so post-relative tokens resolve correctly in the block editor.
  • Built-in placeholders. Current post, parent, author, logged-in user, current term on archives, and a family of date and time tokens (current_date, current_date_compact for ACF Ymd dates, current_datetime, current_time, current_timestamp, zero-padded date parts, and date_minus_* / date_plus_* offsets). All use the site timezone.
  • Two extension filters. aql_resolve_placeholder resolves a custom token at query time and aql_placeholder_list lists it in the editor picker.
  • Editor picker. The Meta Value field becomes a single-value token field that lists placeholders on focus with label and description. PlaceholderTextControl is exported on window.aql so custom SlotFill controls can reuse it.
  • Docs. New "Dynamic placeholders" section in extending-aql.md covering the token table, recipes (upcoming ACF events, running events, relationship fields), custom registration, and a caching note. Readme entries added.

Testing

  • npm run test:unit on this branch: 205 tests, 340 assertions, all passing. tests/unit/Placeholder_Resolver_Tests.php covers every built-in token, unresolved-token passthrough, nested arrays, and the filter hooks.
  • New Playwright spec tests/e2e/tests/dynamic-placeholders.spec.ts covers the picker in the Meta Value field. Not run in this session (needs a wp-env instance).

Related

#179 (meta query modal) is stacked on this branch and should merge after it.

@ryanwelcher
ryanwelcher added this pull request to stack #183 September 10, 2026 15:18
@ryanwelcher ryanwelcher added this to the 5.1 milestone Sep 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant