Skip to content

Blade templating & the render pipeline

Handles & Blade templates already covers the render contract every template receives ($data and $sekAttr) and shows the plain-PHP and Blade forms of a single template. This page goes one level deeper: how the plugin walks a whole page’s sections to build that output, the two render modes a theme can choose between, the helpers a template leans on, and how live preview keeps a rendered page in sync as an editor makes changes.

Rendering funnels through one service, SectionRenderService, with two public entry points:

  • renderSection($templatePath, $values, $sekAttr): the per-section primitive. Renders exactly one section’s template with the values and $sekAttr marker you give it. This is what live preview’s fragment updates call.
  • render($postId, $valuesRecord): the whole-page primitive. Walks a post’s resolved config tree and its stored (or in-flight) values together, recursively, and returns the concatenated HTML for every section instance on the page (no theme wrap, no <html> envelope). This backs the POST /sek/v1/render-content/{postId} REST route and any other consumer that wants raw sections-body HTML (an SEO plugin reading rendered content, for instance).

Both funnel through the same inner dispatch, so a section renders identically whichever entry point reaches it.

A theme template that wants the page’s sections as a single piece of markup calls the sek_render_sections() template tag, which is built on a third, page-level method, renderPage(). It wraps every top-level section in <div data-sek-sections>, the wrapper live preview looks for. See The sek_render_sections() template tag.

render()’s walker is driven entirely by each field’s type discriminator, never by a fixed list of “where sections can live”: the same principle reconciliation follows on the editor side. At every level of a post’s config tree:

  • a sections or children field’s stored instances are each resolved to their section config by handle, rendered, and then recursed into (a section can itself contain sections, to any depth);
  • a tabs field’s stored value is a map keyed by tab handle, and each tab’s own fields are recursed into using that tab’s values;
  • every other field type is a leaf: nothing to recurse into.

An instance whose handle doesn’t match any known section config (an orphan, usually a section type that was later removed from the theme) is silently skipped, mirroring the same orphan-skip behaviour reconciliation uses. A disallowed or unresolvable templatePath, or a template that throws, doesn’t fail the whole page: it renders an inline <div class="sek-preview-error"> in that section’s place with the reason, and rendering continues for the rest of the page.

A theme’s templates can be plain PHP includes (as in starterkit-classic) or Blade views rendered through Sage/Acorn’s view(). This is a per-install choice, made once through the sek/render_mode filter. The default is 'classic', so a theme with plain-PHP templates needs no code at all. A Sage/Acorn theme opts in to Blade by registering the filter, usually in app/filters.php:

add_filter('sek/render_mode', fn () => 'sage');

Only the literal 'sage' selects Blade; any other return value falls back to 'classic'. The opt-in matters because the classic branch looks for a .php file at the dotted path under the theme directory (blocks.hero becomes blocks/hero.php), and a Blade theme keeps its templates as .blade.php views. Without the filter that lookup finds nothing, so every section the plugin renders comes out as the inline sek-preview-error div in place of its markup, with a “Template render failed” message. That holds for the editor’s live preview updates, for sek_render_sections(), and for the render-content REST route. On the two server-rendered paths (the template tag and the REST route) the message also names the unresolvable template path; a live preview update shows the bare “Template render failed”.

Both branches are handed the exact same two keys (data and sekAttr), so a template written against the contract in Handles & Blade templates works identically either way; only the file extension and templating syntax differ (blocks/hero.php with <?= ... ?> vs blocks/hero.blade.php with {{ }}/{!! !!}). The classic branch resolves templatePath to an absolute .php file strictly inside the active theme directory (rejecting .. traversal, absolute paths, and anything outside the theme root) before including it.

Only paths under the two allowed prefixes, blocks. and sections., are ever rendered: a templatePath outside that allowlist is rejected before either render branch runs.

Both branches produce the same output for the same input. Here’s a section further down the page (a CTA section) rendered live through the Blade branch on the premium showcase:

A Fieldwork section (e.g. a CTA section) rendered live on the premium showcase (starterkit, Sage/Blade, built), after scrolling.

Template helpers and shortcode pass-through

Section titled “Template helpers and shortcode pass-through”

Two globals come from the plugin and are available wherever it runs, without a theme needing to define them:

  • sek(): the plugin’s SectionRenderer instance. Its imageTag() and imageUrl() methods resolve an attachment id to an <img> tag or its URL, handling an empty/missing id gracefully (returning '').

  • sek_text($value): renders a text/textarea/WYSIWYG/shortcode value through WordPress’s do_shortcode(), then through an apply_filters('sek_text_value', ...) hook a theme can use to layer its own sanitisation. This mirrors core’s the_content filter chain: shortcode expansion happens at render time, with no additional escaping. Save-time sanitisation (wp_filter_post_kses, only for users without unfiltered_html) is a separate, earlier step.

    A shortcode field’s stored value is a compound shape, { tag, atts, content? }; sek_text() composes that into a real [tag attr="value"]content[/tag] string (attribute keys/values escaped via sanitize_key()/esc_attr()) before expanding it, so a shortcode field and a plain string both pass straight through sek_text() the same way.

A theme typically wraps sek()’s methods in its own convenience helpers: starterkit-classic ships sek_image()/sek_image_url() (thin wrappers around sek()->imageTag()/imageUrl()) and its own theme-owned icon() for resolving an icon field’s symbol name to inline SVG. Those wrappers are theme code, not part of the plugin’s contract; a theme is free to shape them differently or skip them and call sek() directly.

Live preview renders a theme’s own templates inside an iframe and keeps them current as an editor edits: without ever wrapping a template’s output in plugin-owned markup. The whole guarantee rests on $sekAttr: it’s an empty string on a live page and a data-section-id marker only inside the preview iframe, so live output is byte-identical to what the template produces with no plugin involved at all. A theme opts in with three things:

  1. {!! $sekAttr !!} on every top-level element of a section template (multi-root templates carry it on all their roots).

  2. data-sek-sections on the element wrapping a page’s section list, so the preview client knows where sections live in the DOM.

  3. Two optional lifecycle hooks, only if a section owns interactive JavaScript that needs to re-run after its markup is swapped:

    window.sekInit(container) // after new section DOM is live
    window.sekDestroy(container) // before outgoing section DOM is removed

    container is always a temporary wrapper <div> scoped to the mutation (query inside it, never the whole document), and sekInit must be idempotent (checked via a data-sek-initialized-style marker), because the preview client may call it more than once on the same DOM.

The full theme-author contract (multi-root templates, batch ordering across a mixed update, the jQuery post-load legacy rider, the teardown-registry pattern for window/document-level listeners, and the unmarked-template fallback behaviour) is documented in the plugin’s own theme-author guide, shipped alongside the plugin at section-editor-kit/docs/live-preview-theme-guide.md. Read it in full before wiring interactive JavaScript into a section template. For what live preview looks like from the content-editor’s side, see Live preview in the editor track.