Spintax

常見問題集

How do I create a template?

Go to Spintax > Add New in the WordPress admin. Enter a title and your spintax markup in the editor.

What syntax does the plugin use?

• {a|b|c} — randomly picks one option
• [a|b|c] — permutation: picks N elements, shuffles, joins with space
• [<minsize=2;maxsize=3;sep=", ";lastsep=" and "> a|b|c|d] — configured permutation
• %variable% — variable reference
• #set %var% = value — local variable definition
• {?VAR?then|else} — conditional: render a branch by truthiness of %VAR% (also {?!VAR?then} inverted)
• {plural %Count%: form1|form2|form3} — plural agreement: picks the correct grammatical form by count (RU 3-form, EN 2-form)
• /#comment#/ — block comment (stripped from output)
• #include "slug" — embed another template

Full syntax reference with examples and a live playground: https://spintax.net/docs/syntax

Where can I learn more?

• Documentation hub: https://spintax.net/docs/ — guides, reference, recipes
• Compact syntax reference: https://spintax.net/docs/syntax — all primitives in one page (13 languages)
• Plural agreement guide: https://spintax.net/docs/plural-spintax/ — {plural N: form1|form2|form3} in depth (EN/RU)
• Conditional spintax guide: https://spintax.net/docs/conditional-spintax/ — {?VAR?then|else} value-driven branching (EN/RU)
• Authoring mindset: https://spintax.net/docs/authoring-mindset/ — write the final text first, add markup last (EN/RU)
• Live playground: https://spintax.net/play/ — write a template, set variables, render N variants in your browser (EN/RU)

Does caching require Redis or Memcached?

The plugin uses the WordPress Object Cache API. With a persistent backend (Redis, Memcached), cached output persists across requests. Without one, templates are re-rendered on each page load.

Can I pass variables through shortcodes?

Yes: [spintax slug="greeting" name="Alice" city="Moscow"] makes %name% and %city% available inside the template.

What are ACF / post-meta bindings?

A binding pairs a Spintax template (or a per-post inline source) with one target field on one post type — for example “Posts → ACF: hero_subtitle”. Configure it once under Spintax → Bindings and the plugin populates the field on every matching post on save, on a cron schedule, or on demand via Bulk Apply. Manual edits are preserved by default (hash-tracked); flags control whether the binding auto-seeds empty fields, regenerates on every save, or clears the field when the template renders to empty.

Can I bind to ACF fields?

Yes. Bindings support both ACF (text / textarea / wysiwyg, top-level fields) and plain post-meta keys. ACF Free and Pro are both supported; nested fields (repeater / flexible_content rows) are not supported in 2.0 — that lands in a later release. The form-side field picker auto-fills the stable ACF field key so writes work on the first save without ACF’s reference-meta handshake.

Do I need Action Scheduler?

It’s a recommended optional dependency for binding-heavy sites. The plugin works without it, but two features degrade:

• The admin Bulk Apply button uses Action Scheduler to dispatch chunked async jobs. Without AS, the button returns an error pointing at the WP-CLI fallback (wp spintax bindings apply --binding=<id> --all).
• Per-binding cron schedules still fire, but the cron callback runs the walk synchronously instead of enqueueing an async job. On large catalogues that risks PHP-FPM timeouts on the cron worker.

Many WP shops already ship Action Scheduler bundled with WooCommerce or other plugins — check Plugins → Installed Plugins for “Action Scheduler” before installing it separately. If the Bindings admin page shows an “Action Scheduler is not installed” notice at the top, you don’t have it loaded yet; install Action Scheduler to make one-click admin Bulk Apply and async cron walks available.

What WP-CLI commands does the plugin add?

Five subcommands under wp spintax bindings:

• wp spintax bindings list [--format=table|json|csv] — list all bindings on the site.
• wp spintax bindings apply --binding=<id> [--all|--post=<id>] [--dry-run] — run a binding against all matching posts (or a single post), with optional dry-run. This is the no-Action-Scheduler fallback path for Bulk Apply.
• wp spintax bindings test --binding=<id> --post=<id> — dry-run a binding against one post and report what BindingApplier::plan() would do (would_write, current value, rendered preview, skip reason). Same logic as the admin Test panel.
• wp spintax bindings export [--format=json] [> bindings.json] — emit the full bindings store as JSON, deduped by (post_type, target.key).
• wp spintax bindings import --file=bindings.json [--overwrite] [--dry-run] — import bindings from JSON. --overwrite updates matches on the same target triple; without it, duplicates are skipped. Use --dry-run to preview the plan without writing.

The export/import pair is the recommended staging→production sync path; bindings are not exposed over REST in 2.0.

What variables can I use inside a bound template?

A binding template renders with four layered variable sources (later layers override earlier ones — see spec §4.3):

• Global variables — the #set block in Settings → Spintax → Global Variables. Site-wide.
• Per-binding overrides — a #set block in the binding’s Variables → “Per-binding #set overrides” textarea. Applies to that binding only.
• Post context (opt-in via the binding’s “Expose post context as %vars%” checkbox) — %post_id%, %post_title%, %post_url%, %post_slug%, %post_date%, %post_modified%, %author_id%, %author_name%.
• ACF sibling fields (opt-in via “Expose ACF sibling fields as %acf_%”) — every top-level ACF text/textarea/wysiwyg field in the binding’s post type group, available as %acf_<field_name>%. Reads happen after ACF persists its values (save_post priority 20 hook), so siblings are always fresh on save_post triggers. Only meaningful for ACF-target bindings.

A binding’s source can also use the rest of the Spintax syntax ({a|b|c}, [a|b], {?VAR?then|else}, {plural %N%: ...}, #include "slug", /#comment#/).

How do I schedule bindings to run automatically?

Two trigger paths, both configurable per binding under “Triggers”:

• Fire on post save (checkbox, default on) — hooks save_post priority 20. Runs after ACF persists its own field values, so sibling reads see fresh data. Skipped during autosave / bulk-edit / REST batch imports / revisions / trash flips.
• Cron schedule (dropdown: disabled / hourly / twicedaily / daily) — each binding gets its own WP-Cron hook spintax_binding_cron_<binding_id>. On the scheduled tick, the callback enqueues an Action Scheduler walk (or runs synchronously if AS isn’t installed — see the Action Scheduler FAQ above). Independent of save_post; use this to refresh content periodically without an editor touch.

For one-off “apply now” operations, click Bulk Apply on the binding card. The button needs Action Scheduler; without it, the admin notice points at the WP-CLI fallback.

How does the plugin handle manual edits to bound fields?

Each binding tracks a SHA-1 signature of its last-rendered value in post-meta _spintax_last_render_sig_<binding_id>. On every subsequent run with Preserve manual edits enabled (default), it compares the current target value’s hash to the stored signature:

• If the hashes match, the value hasn’t been touched outside the binding — safe to regenerate.
• If they differ, treat it as a manual edit; skip with SKIP_MANUAL_EDIT_DETECTED and log the skip.

Combined with Regenerate on every save, this gives a “refresh on save unless edited” workflow. With Auto-seed empty fields instead, the binding only writes when the target is empty — manual edits are preserved by definition because they’re never overwritten.

There is a “cold-start” exception: when a binding first sees a post with non-empty target content and no signature yet, it treats the existing value as an unwritten manual baseline and skips (SKIP_COLD_START_MANUAL) until the editor clicks the binding’s “Initialize from current value” path (a later UI addition) or accepts the regeneration by clearing the field first.

I edited a template. Why aren’t the changes showing up on the front end?

Bindings are a pre-generation system, not a render-on-read layer. The rendered string is stored in the target field; consumers (themes, blocks, REST readers) get that stored value directly. Editing the source template doesn’t propagate to existing posts until a trigger writes a fresh value to each one.

When you edit a template that has bindings pointing at it, the plugin:

1. Bumps an internal render-cache version on each affected binding.
2. Surfaces an admin notice on the template-edit screen (“N bindings depend on this template”).
3. Shows a “Stale: source template edited” badge on each affected binding’s card.

To push the new content to existing posts, click Bulk Apply on each affected binding (or run wp spintax bindings apply --binding=<id> --all from the CLI). The Stale badge only clears when the entire walk completes with zero failures — partial-failure walks keep the badge so you notice the divergence and retry.

Is there a hard cap on bindings?

200 bindings per site. The store is a single autoloaded option (~500 bytes per binding), and the cap keeps autoload memory bounded. If you genuinely need more, please open an issue with your use case.

Which fields can’t I bind to?

The form rejects five tiers of reserved keys at save time:

• WordPress-internal meta — keys starting with _wp_, _edit_, _oembed_, plus _pingme, _encloseme, _thumbnail_id.
• Plugin-internal meta — _spintax_* prefixes (source, signature, cache-version slots used by other bindings).
• wp_posts columns — post_title, post_content, post_excerpt, post_name, post_status, post_date, post_modified, post_parent, post_author, post_type, post_password, etc. These aren’t post-meta and writing to them via update_post_meta() silently creates shadow rows.
• Cross-binding uniqueness — only one binding per (post type, target key), regardless of whether the kind is ACF or post_meta (they share the same database row).
• ACF field key validity — when binding to an ACF field, the stable field key (e.g. field_5f8a1234abcd) is required, and verified against acf_get_field() when ACF is loaded.

On multisite, are bindings shared across the network?

No — bindings are per-site. Each subsite manages its own. Use wp --url=site2 spintax bindings import --file=site1-bindings.json to copy bindings between subsites via the WP-CLI export/import round-trip.

Can I manage bindings via REST?

Not in 2.0; bindings are admin-only. The wp spintax bindings WP-CLI surface covers staging→production sync scenarios. REST API exposure is tracked for a later release.

I’m coming from `nested-spintax-for-acf`. Is there a migration path?

Yes. After activating Spintax 2.0, a dismissible admin banner points to Tools → Spintax Migration. The wizard scans for predecessor data, shows a per-row preview, and creates bindings deduped by (post type, target field). Per-post sources and variables are copied non-destructively — the old plugin’s data stays in place until you delete it.