Custom Theme

Walkthrough

1. 1

   The directory layout

   Each theme is a flat folder under themes/. index.json registers which templates exist; the matching <Name>.template.html files render them. Sample pages live under master/sample/<category>/ — the gallery and the in-builder Change Theme modal both read from there.

   Tree Copy

   themes/example-mini/
   ├── index.json                       # 1 — config + brand variables
   ├── Block.template.html              # 2 — block frame (the file most buyers edit)
   ├── Page.template.html               # 3 — page wrapper
   ├── master/
   │   └── sample/
   │       └── email/
   │           └── HelloThere.json      # 4 — a minimal sample page
   └── README.md                        # not read by the builder; for the buyer
   
   # Production themes also ship Grid · Cell · Heading · P · Image · Button
   # · Alert · Menu · Divider · etc. — copy themes/default/ for the full set.

2. 2

   Define brand variables in index.json

   A _brand block is a buyer convention — not part of the BuilderJS schema. Templates read it via the EJS render context (configData._brand) and weave the values into the inline style string. Change one line here, every block on every page reflavors.

   JSON Copy

   {
     "name": "example-mini",
     "title": "Example Brand",
     "_brand": {
       "primary":    "#5b21b6",
       "primary_fg": "#ffffff",
       "accent":     "#a855f7"
     },
     "pages":     ["Page"],
     "templates": ["Block", "Grid", "Cell", "Heading", "P", "Image", "Button"]
   }

3. 3

   Edit Block.template.html — the highest-leverage file

   EJS server-side. formatter.toStyleStringAll() emits the format properties bound by the controls panel; you can append your own CSS to apply brand-wide styling. Below: a 4 px brand-primary stripe on every block — one of the smallest visible diffs against the default theme.

   EJS Copy

   <%
   var brand = (typeof configData !== 'undefined' && configData && configData._brand) || {};
   var brandStripe = brand.primary ? ('border-left:4px solid ' + brand.primary + ';') : '';
   %>
   <div style="<%- formatter.toStyleStringAll() %><%- brandStripe %>">
       <%- elements %>
   </div>

4. 4

   Register the new theme in ThemeRegistry

   Open demo/backend/_lib/ThemeRegistry.php and add a row to the SEED constant under the matching category (standard / extended / page). The gallery + Change Theme modal pick it up on next reload — no DB, no rebuild.

   PHP Copy

   private const SEED = [
       'standard' => [
           // …existing rows…
           ['dir' => 'example-mini', 'name' => 'Hello There', 'sample' => 'master/sample/email/HelloThere'],
       ],
       // 'extended', 'page' — same shape
   ];