Skip to content

Handles & Blade templates

Handles are the identifiers that stitch SEK together. A handle is a stable, machine-readable name (for a section type, for a field) and the same handle is used at every layer: the config file, the registration list, the stored value, and the template. Nothing addresses anything by its human label; everything addresses by handle.

A section type’s handle must match its file basename and the entry that registers it:

  • blocks/hero.yaml declares handle: hero.
  • The file is hero.yaml (basename hero).
  • A post-type config lists - hero under sections: to make it available.

All three must agree. If the handle, the filename, and the registration entry don’t match, the section won’t resolve.

A section config points at its template with templatePath, written as a dotted path:

handle: hero
templatePath: blocks.hero # → blocks/hero.php

blocks.hero resolves to blocks/hero.php in a plain-PHP theme like starterkit-classic, or to the corresponding Blade view in a Sage theme. The dotted form is the same view-path convention Laravel and Sage’s Blade use, so it reads naturally in either kind of theme.

Whatever the template language, SEK hands every section template exactly two variables:

  • $data: an associative array of the section’s saved values, keyed by each field’s handle. A field with handle: headline is read as $data['headline']. Always read defensively ($data['headline'] ?? ''): a value may be empty or not yet entered.
  • $sekAttr: an attribute string that the section’s root element must echo. It emits a data-section-id marker only inside the live-preview iframe and an empty string on the real front end. Echoing it is what makes a section targetable by live preview; because it is empty on live pages, the plugin never wraps or alters your markup and live output is byte-identical to raw template output.

starterkit-classic renders the contract with plain PHP short-echo tags:

<?php
if (! defined('ABSPATH')) {
exit;
}
?>
<section class="hero"<?= $sekAttr ?>>
<h1><?= sek_text($data['headline'] ?? '') ?></h1>
<div><?= sek_text($data['intro'] ?? '') ?></div>
</section>

The contract renders identically wherever it runs: a plain-PHP theme like starterkit-classic and a Sage/Blade theme produce byte-identical frontend output from the same $data/$sekAttr pair. The difference between the two theme kinds is the template code shown in the PHP/Blade tabs above, not the rendered result, so one rendered example is enough. Here’s the hero section rendered live on the free, plain-PHP showcase; a Sage/Blade showcase run through the same section would produce the same markup:

The Fieldwork demo page rendered live on the free showcase: the hero section near the top of the page.

Templates lean on small helpers so they read consistently and escape correctly. They come from two places:

  • sek_text(): text and WYSIWYG values. This is a plugin-provided global: it is available wherever the plugin runs, and themes deliberately do not redefine it.

  • sek_image(): an image field’s stored {id, url, alt, thumbnail} object → an <img> (or its URL).

  • icon(): an icon field’s symbol name → the inline SVG glyph.

    sek_image() and icon() are theme helpers: the starter kit defines them in its inc/helpers.php and they delegate to the plugin for the actual attachment/image resolution. A theme can adjust or add to these.

For plain attribute values, use WordPress’s own esc_html() / esc_attr(). The invariant the plugin owns is the $data + $sekAttr pair (and the sek_text() global); the image/icon rendering helpers are the theme’s to shape.

Labels are for humans and can change freely: rename “Headline” to “Title” in the config and nothing breaks, because the stored value and the template both key on the headline handle, not the label. Handles are the contract; labels are presentation. This is also why reconciliation matches saved values to config by handle: change a handle and the old value becomes a lost value rather than silently attaching to the wrong field.