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. Leavematchout and it defaults to.plus the first class of the paired HTML file's<section>(.c-eventsabove). Its name defaults to the HTML header'sName. - 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_filesfilter (basename => path) and change the normalized definitions withcantata_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.attredits an attribute instead:aria-label,title,altor adata-attribute. - link: the
hrefof the match (or the first link inside it). Accepts/page,#part,?query,https://,http://,mailto:andtel:. - 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 asdata-ke-date="2027-04-27/2027-04-28"and written as words with PHP dateformat(defaultF j, Y). Givepartsinstead when a date is split over several nodes (a badge): each part has aselectorinside the match, aformatand 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#
- Open a page with the element as a site manager. An invalid file shows a notice in the WordPress dashboard.
- 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.
- Change each field and watch the page change. Add, copy, move and remove an item, Undo, Save draft, reload, Publish.
- 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).