Xplain for Craft CMS

Usage

Where tips appear

  • Under each field in the entry form — with Craft's lightbulb, for admins and anyone with the permission.
  • In the field layout designer — the lightbulb indicator on each field, and the tip text in the field's settings slideout, where you can edit it.
  • Under the field's own settings (Settings → Fields → a field) — the full explanation: what it stores, every layout it is in, the Twig for each, the element query, the GraphQL selection and every tip.
  • Utilities → Xplain — every field in every layout, grouped by field, with the state of each tip and buttons to write, remove and export.

What a tip says

One paragraph:

  1. What the field stores — Dropdown — one of: light, dark, seasonal.
  2. The Twig that reads it in this layout — {{ entry.theme }}, or block.theme inside a Matrix entry type, category.theme on a category group, footer.theme on a global set.
  3. The most useful advice for that field — eager loading for relations, value-versus-label for options, is not null for numbers.

When a layout renames a field (a Craft 5 handle override), the tip leads with that, because it is the thing most likely to break a template:

This layout renames it: use teaser here, not the field's own summary.

Keeping tips current

With autoWrite on, saving a field, saving a layout, or deleting a field queues one job that rewrites every tip that changed. A tip can go stale without its own field changing — a Matrix field's tip lists its entry types' fields — so the job always checks everything.

Or by hand:

php craft xplain/tips            # a table of every placement and its state
php craft xplain/tips/write      # write missing and stale tips

Tip states

StateMeaning
Up to dateXplain wrote it and would write the same today.
Out of dateXplain wrote it, but the field or layout changed. The next write replaces it.
Not writtenNo tip yet.
Written by a personSomeone wrote or edited this tip. Xplain never touches it.
ExcludedThe field is in excludedFields.

Writing your own tip

Type it into the field layout designer as usual. The moment a tip's text differs from what Xplain wrote, it is yours. To hand a field back to Xplain, clear its tip and save the layout.

In CI

php craft project-config/apply
php craft xplain/tips/check

check exits 1 when any tip is missing or out of date — a schema change that went out without its notes.

The schema as Markdown

php craft xplain/explain/schema --output=docs/schema.md
php craft xplain/explain heroImage

or Download schema notes in the utility. One section per field: summary, facts, where it is used, a Twig block, advice, query and GraphQL.