Kindly EditDocumentationTry the editor

Custom elements

Declare a component's fields and repeated items so its card edits them in Simple and Developer mode, and fill items from posts.

Available from Kindly Edit 0.11.0.

A site's own components can say what their content is: which words, links, pictures, dates and choices an editor changes, and which parts repeat (slides, cards, people). Kindly Edit then shows those fields in the element's Content card, in Simple and Developer mode, so a client never has to find the right paragraph inside a slider or work out how to copy a slide. Repeated items can be added, copied, moved, removed and opened, and an item can fill itself in from a post, such as an event.

The page's HTML stays the only copy of the content. Every field reads and writes the element's own markup, found by a CSS selector. Nothing is rendered on the server, so:

  • click-to-edit on the page keeps working, and both ways of editing show the same words;
  • Undo, revisions, duplication, Save draft and Publish work exactly as for any other edit;
  • pages saved before the definition existed are edited the same way, with no migration.

Definitions are theme code, trusted like the theme's PHP, and are still validated. An invalid file is skipped whole and named in an admin notice to site managers ("Kindly Edit skipped the custom element in components/...: why"). It is never half applied.

Where a definition lives#

components/NN-slug.json in the theme, beside the component it describes:

components/11-featured-events.html   the component (header comment + one <section class="c-events">)
components/11-featured-events.json   its custom element definition
  • The definition's element is found by match. Leave match out and it defaults to . plus the first class of the paired HTML file's <section> (.c-events above). Its name defaults to the HTML header's Name.
  • A JSON file with no HTML beside it describes markup that is already on pages. It must then give match.
  • Child themes inherit the parent's definitions; a child file with the same name replaces the parent's.
  • Plugins can add or replace files with the cantata_edit_custom_element_files filter (basename => path) and change the normalized definitions with cantata_edit_custom_elements (slug => definition).

The slug is the file name without its number: 11-featured-events.json is featured-events.

A complete example#

A homepage "Featured events" slider, components/11-featured-events.json, whose slides are Kindly tabs and whose events are a meetings post type with date, end-date and location custom fields:

{
  "name": "Featured events",
  "items": {
    "label": "Slides",
    "add": "Add a slide",
    "tabs": true,
    "min": 1,
    "max": 8,
    "title": "tab",
    "fields": [
      { "key": "tab", "label": "Tab name", "selector": "@tab" },
      { "key": "label", "label": "Label", "selector": ".c-events-text > p:first-child:not(.c-events-when):not(.c-actions):not(.c-events-lead)" },
      { "key": "title", "label": "Title", "selector": ".c-events-title" },
      { "key": "when", "label": "Date and place", "selector": ".c-events-when" },
      { "key": "date", "label": "Date on the picture", "type": "date", "selector": ".c-events-date", "range": true, "parts": [
        { "selector": "span:first-child", "format": "M", "case": "upper" },
        { "selector": "strong", "format": "d" },
        { "selector": "span:last-child", "format": "Y" }
      ] },
      { "key": "button", "label": "Button", "selector": ".c-actions a" },
      { "key": "link", "label": "Button link", "type": "link", "selector": ".c-actions a" },
      { "key": "picture", "label": "Picture", "type": "image", "selector": ".c-events-media > img" }
    ],
    "source": {
      "label": "Event",
      "postType": "meetings",
      "sort": "meta:date",
      "upcoming": true,
      "fill": {
        "tab": "title",
        "title": "title",
        "when": "{meta:date..meta:end-date|F j, Y} - {meta:location}",
        "date": ["meta:date", "meta:end-date"],
        "link": "link"
      }
    }
  }
}

The definition#

Key Required Meaning
name no The card's heading and the toolbar button's name. Defaults to the component's Name.
match no A CSS selector for the element. Defaults to the paired component's section class.
fields one of these Fields of the element as a whole (a heading, a background choice).
items one of these Its repeated parts. See below.

Fields#

Each field is an object. At most 30 per list, with unique keys.

Key Meaning
key Lowercase letters, numbers and hyphens, starting with a letter.
label What the control is called. Defaults to the key.
type text (default), textarea, link, image, date, choice or toggle.
selector Where the field is, relative to the element (or to the item). Empty means the element or item itself. @tab means an item's tab name, for items in tabs.
simple false shows the field in Developer mode only. Fields show in both modes by default.
placeholder Hint text in an empty box.

By type:

  • text, textarea: the words of the first match. A node that also holds an icon (an <svg>) keeps it; only its own words change. A node with formatted words or a picture inside is left to on-page editing, so the card shows no box for it. attr edits an attribute instead: aria-label, title, alt or a data- attribute.
  • link: the href of the match (or the first link inside it). Accepts /page, #part, ?query, https://, http://, mailto: and tel:.
  • image: the <img> of the match: replace it from the Media Library and say what it shows (its alt text).
  • date: a date, or a start and end date with "range": true. It is stored on the match as data-ke-date="2027-04-27/2027-04-28" and written as words with PHP date format (default F j, Y). Give parts instead when a date is split over several nodes (a badge): each part has a selector inside the match, a format and optionally "case": "upper" or "lower". Ranges in one month are written once with the days as a range ("April 27–28, 2027", "27–28"); others say both dates. A date written before the element was declared is read from its words ("Feb" "04" "2027"); placeholder words read as no date.
  • choice: one class from options, a list of [ "class", "Label" ] pairs (at least two). "" is "none".
  • toggle: a checkbox that adds or removes class.

Items#

Key Meaning
selector The repeated parts, inside the element. Items of a nested element of the same kind are not counted.
tabs true instead of selector: the items are the panels of the element's Kindly tabs (.cb-tabs), each with its tab. Adding, copying, moving and removing keep each tab and panel together and show the one changed.
label The list's heading ("Slides").
add The add button's words ("Add a slide"). A new item copies the last one with plain words for a name and is called "New slide".
min, max How few and how many (defaults 1 and 50).
title The key of the field shown on each row of the list. Defaults to the first field.
fields The item's fields, as above.
source Lets an item fill itself in from a post.

Each row in the list has its name, a button to open the item's own fields, Copy and Remove; rows are dragged or moved with the keyboard. Opening an item shows it on the page.

Filling an item from a post#

Key Meaning
postType One post type, or a list of up to five.
label What one is called ("Event"). The button says "Fill from event".
fill Which item fields take what from the post: { "field key": expression }.
sort date (newest first, the default), title, or meta:KEY (soonest first, by the date in that field).
upcoming With a meta:KEY sort, leaves out posts whose date has passed.

Expressions:

Expression Value
title, excerpt, link The post's title, excerpt, and its address relative to the site.
date Its publish date.
meta:KEY A custom field. Protected keys (starting with _) are refused here and in sort.
term:TAXONOMY Its first term in that taxonomy.
image, image:KEY Its featured image, or the attachment whose ID is in meta KEY (for an image field).
"{meta:date..meta:end-date|F j, Y} - {meta:location}" A template: words with {expression}, {expression|format} for a date, or {start..end|format} for a date range. Separators left dangling by an empty value are trimmed.
["meta:date", "meta:end-date"] For a date field: its start and end.

Dates in meta may be Unix timestamps (stored as UTC midnight, as JetEngine and ACF date pickers do), Ymd, or text WordPress can read. They are read as the calendar date they are, in any time zone.

Filling copies the post's values into the item once, in one Undo step, and remembers the post on the item (data-ke-from="ID"). The opened item then names the post, with Fill in again (to pick up a changed date) and Change. Empty values leave a field as it is. Nothing updates by itself: the page always shows what was published.

The list and the values come from GET /wp-json/cantata-edit/v1/element-source?element=SLUG[&search=WORDS|&id=ID]. It needs edit_posts, reads only the declared post types, and only posts the person may read. See element-source REST endpoint.

In the editor#

  • Simple mode: clicking anything inside a custom element shows a toolbar button with its name ("Featured events"). It opens the element's card with its fields and items. Built-in containers and layouts around it are not offered in Simple mode.
  • Developer mode: selecting the element shows the same card in its Content tab. Selecting something inside it offers a button to that card before the nearer built-in element's settings. The built-in elements it is made of (its tabs, for example) keep their own settings when you select them.
  • Phones use the same card in the bottom sheet.

Checking a definition#

  1. Open a page with the element as a site manager. An invalid file shows a notice in the WordPress dashboard.
  2. Click the element's words and press its toolbar button in Simple mode. Every field you declared should show, filled with what the page says.
  3. Change each field and watch the page change. Add, copy, move and remove an item, Undo, Save draft, reload, Publish.
  4. With a source, fill an item from a post and check every filled field, then Fill in again.

The plugin's own tests: wp eval-file tests/custom-elements-test.php (validation, dates, the REST route and its permissions, against the active theme's definitions) and tests/custom-elements-native-browser.mjs (the card in both modes on a scratch site; set KINDLY_WP, KINDLY_URL, and FIXTURE_HTML to test a saved page's markup).

About this page

Documents Kindly Edit 0.9.16. Source: docs/CUSTOM-ELEMENTS.md, includes/custom-elements.php, assets/custom-elements.js. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.