Skip to content

Your first section

A section in SEK is a pair of files plus one line of registration:

  • a config (blocks/<handle>.yaml) that declares the section’s label, its template, and its fields;
  • a template (blocks/<handle>.php, or a Blade template in a Sage theme) that renders the saved values as HTML;
  • a registration: the section’s handle added to a post type’s sections: list, so the section becomes available in that post type’s editor.

This walkthrough builds one section (a small “promo” band with a headline and an intro paragraph) from nothing, and confirms it renders on the front end. It uses the starterkit-classic theme, whose worked hero section is the model we follow. Every step here has been reproduced live against that theme.

These are the only prerequisites. There are no hidden ones:

  • The SEK plugin is active.
  • The starterkit-classic theme is active and carries its .sek.yml (sections: blocks, postTypes: config/post-types).
  • The page post type is configured: config/post-types/main.yaml lists the sections a page may use.
  • The site is reachable, with pretty permalinks enabled (WordPress Settings → Permalinks, any non-plain structure). The editor and its REST calls require this.
  • Demo content is seeded. The starter showcase is usually already seeded; if not, use the Import Demo button in the SEK admin screen.

Create blocks/promo.yaml in the theme. The handle must match the file basename (promo), and templatePath is a dotted path to the template: blocks.promo resolves to blocks/promo.php.

wp-content/themes/starterkit-classic/blocks/promo.yaml
label: Promo
handle: promo
templatePath: blocks.promo
category: content
icon: layout
description: A small promo band with a headline and a short intro paragraph.
fields:
- label: Headline
handle: headline
type: text
description: The promo headline
validation:
- type: required
message: Headline is required
- label: Intro
handle: intro
type: wysiwyg
description: A short paragraph beneath the headline

Each field has a label (shown in the editor), a handle (the key the saved value is stored under), and a type (which field type renders the input). text and wysiwyg are two of the field types in the free download; the full set is in the field-types catalogue. Fields may also carry validation rules and type-specific options: see the configuration reference.

Create blocks/promo.php. The template receives two variables from the plugin:

  • $data: the saved field values, keyed by each field’s handle ($data['headline'], $data['intro']). Read them defensively with ?? '', because a value may not have been entered yet.
  • $sekAttr: an attribute string the section’s root element must echo. It renders a data-section-id marker inside the live-preview iframe and an empty string on the real front end, so live output is byte-identical to raw template output. Omit it and live preview cannot target this section.
<?php
if (! defined('ABSPATH')) {
exit;
}
?>
<section class="promo"<?= $sekAttr ?>>
<div class="mx-auto max-w-[72rem] px-8 py-16">
<h2><?= sek_text($data['headline'] ?? '') ?></h2>
<div><?= sek_text($data['intro'] ?? '') ?></div>
</div>
</section>

sek_text() is a plugin-provided global helper, used for text and WYSIWYG values; the starter kit’s theme also ships sek_image() for image field values and icon() for icon symbol names. The if (! defined('ABSPATH')) guard in the PHP form is the standard WordPress direct-access guard (a Blade view is not directly web-accessible the way a raw .php include is, so the Blade form omits it). See Handles & Blade templates for the full render contract, including how a Sage theme renders the same $data / $sekAttr pair through a Blade template instead of plain PHP.

A section config on disk is not yet available to any editor: it has to be listed for a post type. Open the page post-type config and add promo to the sections: list:

wp-content/themes/starterkit-classic/config/post-types/main.yaml
fields:
- label: Page Layout
handle: page_tabs
type: tabs
fields:
- label: Content
handle: content_tab
type: tab
fields:
- label: Page Sections
handle: content
type: sections
sections:
- hero
# ...existing handles...
- callout
- promo # ← add your handle

main.yaml is the config the Page editor loads (the file basename maps to the post-type slug; main is the page fallback). The sections: list is an allowlist scoped to the active theme: only handles whose blocks/<handle>.yaml exists resolve. That is why the config in Step 1 comes first.

Edit a Page (wp-admin → Pages, or a fresh post-new.php?post_type=page). A brand-new page opens the SEK editor in its empty state (nothing added yet, just the affordance to add a first section):

A brand-new page opened in the SEK editor before any section has been added: the empty state with only the “add first section” affordance visible.

  1. Open the add-section picker. Promo now appears alongside the starter kit’s own sections.

    The add-section picker opened from the editor, listing the available section types to insert.

  2. Add it. The section’s fields (Headline and Intro) render as inputs.

  3. Enter a headline and an intro paragraph.

  4. Update the page to save.

The values are stored as JSON in the page’s _sek_data meta: not in a separate table, and not as HTML. Only the values live in the database; the structure stays in your promo.yaml. That split is config as source of truth, SEK’s central idea.

View the page on the front end. The promo section renders through blocks/promo.php, with your headline and intro in place. Because the template echoed $sekAttr, the same section is also targetable by live preview while you edit.

That is a whole section, end to end: config → template → registration → edit → render. Everything else (more field types, nesting, conditional visibility, global sections) builds on this same pair-plus-registration shape.