# Craft CMS Builder

# Overview

### Craft CMS Builder is a visual drag-and-drop template builder for Craft CMS 5.

#### What it does

\- Create page and partial templates in the Craft control panel  
\- Build layouts visually with Twig components (no HTML stored in the database)  
\- Assign templates to entries with the Builder Layout field  
\- Preview changes live in the visual editor  
\- Reuse partials as presets inside other templates  
\- Optionally set up a homepage Single with one click

#### Who this documentation is for

Site builders and content editors who work in the Craft CP. Developers looking for the SDK and custom components should see the developer documentation shipped with the plugin.

#### Main areas in the control panel

After install, open Builder from the Craft CP navigation:

\- Templates — list, create, copy, and open templates  
\- Visual editor — drag-and-drop layout editing with live preview  
\- Settings — homepage setup, license, and plugin options

#### How rendering works

Templates are stored as a component tree (JSON). On the front end, Builder renders that tree through Twig component templates. The database never stores rendered HTML — only structure, settings, and styles.

# Installation

#### Requirements

\- Craft CMS 5  
\- PHP version required by your Craft installation  
\- Composer

#### Install via Composer

From your Craft project root:

```
composer require comdev/builder
php craft plugin/install builder
```

#### After install

1\. Log in to the Craft control panel.  
2\. Open Builder in the CP navigation.  
3\. You may see an optional Create homepage prompt. You can complete it now or skip and run it later from Builder → Settings.

#### License

Enter your license key under Builder → Settings

\- License Key — your product key  
\- Enable remote license checks — turn on if checks against the license server are required  
\- License server URL — usually left at the default provided with the plugin

#### Config (optional)

Advanced options such as Matrix block → component mapping can be set in `config/builder.php` under `matrixBlockMap`. See plugin settings for a reminder of this option.

#### Verify install

\- Builder appears in the CP nav  
\- Builder → Templates opens without errors  
\- You can click New Template and save a blank page template

# Getting started

### First steps

1\. Install and enable the Builder plugin.  
2\. Open Builder in the control panel.  
3\. Optionally run Create homepage (recommended for new sites).  
4\. Create your first page template.  
5\. Open the visual editor and add sections and content.  
6\. Assign the template to an entry with a Builder Layout field.

### Homepage setup

Builder can wire your site root to a template automatically.

What Create homepage does:

\- Creates a Homepage Single section (`\_\_home\_\_`) if needed  
\- Adds a Builder Layout field  
\- Links the homepage entry to a starter template (or one you choose)  
\- Makes the site root use that Builder layout

[![screen2.png](https://wiki.comdev.eu/uploads/images/gallery/2026-07/scaled-1680-/screen2.png)](https://wiki.comdev.eu/uploads/images/gallery/2026-07/screen2.png)

#### Run it from the prompt

After install, a prompt may appear on the Templates screen:

\- Choose an existing template, or create a new starter template  
\- Click Create homepage  
\- Or click Skip for now

#### Run it later

1\. Go to Builder → Settings  
2\. Under Homepage, click Create homepage  
3\. Confirm Allow Admin Changes is enabled in Craft (required to create the section and field)

#### After homepage is configured

From Builder → Settings you can:

\- Edit the homepage entry  
\- View the site  
\- Re-run homepage setup if you need to reset the wiring

### Recommended workflow

1\. Create page templates for full layouts (home, about, landing pages).  
2\. Create partials for reusable blocks (headers, CTAs, footers).  
3\. Style each template in the visual editor Theme panel.  
4\. Attach templates to entries via the Builder Layout field.  
5\. Publish and check the front end.

# Create template

Templates are Builder layouts stored as Craft elements. There are two types:

\- Page — full page layouts assigned to entries  
\- Partial — reusable section presets you can insert into other templates

#### Create a new template

1\. Go to Builder → Templates.  
2\. Click New Template.  
3\. Fill in the fields:

##### Title

Required. Letters, numbers, and spaces only.

Examples: Home, About Us, Landing Hero

##### Type

\- Page — use for complete pages  
\- Partial — use for reusable blocks shown when browsing presets in the editor

##### Description

Optional. Especially useful for partials so editors understand what the preset is for when browsing in the visual editor.

##### Enabled

Turn off to keep a template draft-like / unavailable where disabled layouts are filtered out.

4\. Click Save.

After the first save you can open the visual editor from the template edit screen.

#### Open the visual editor

From the template edit page, click Open visual editor.

Or from the Templates list, click Edit visually next to a template.

#### Advanced: component tree (JSON)

On the template edit screen you can edit the Component tree (JSON) directly. Most users should use the visual editor instead. The JSON field is useful for copy/paste, debugging, or advanced edits.

#### Tips

\- Start with a Page template and a Section, then drop Headline, Text, Image, and Grid inside it.  
\- Use Partials for repeating patterns (promo strip, FAQ block, team row).  
\- Keep titles clear — they appear in the Templates list and in the Builder Layout field dropdown.

# Visual Editor

The visual editor is where you build and style a template with live preview.

#### Open the editor

From Builder → Templates:

\- Click Edit visually on a row, or  
\- Open a template and click Open visual editor

#### Editor layout

Typical panels:

\- Component palette — available sections and elements  
\- Canvas / preview — live preview of the layout  
\- Settings — fields for the selected component  
\- Theme — colors and typography for this template

#### Build a layout

1\. Drag a Section (or a preset like Hero, CTA, FAQ) onto the canvas.  
2\. Drop elements inside the section: Headline, Text, Image, Grid, Button, Menu, HTML, etc.  
3\. Click a component to edit its settings.  
4\. Reorder by dragging.  
5\. Save when ready.

#### Hierarchy basics

\- Sections and layout components (Header, Footer, Hero, etc.) hold structure.  
\- Elements (Headline, Text, Image, …) live inside Section or Grid.  
\- Grid creates columns; place elements (or grid items) inside columns.

Example structure:

Section  
 → Headline  
 → Grid (2 columns)  
 → Text  
 → Image  
 → Button

#### Live preview

The editor uses AJAX preview so changes appear without a full page reload. Always save before leaving if you want to keep edits.

#### Theme panel

Theme colors and typography are set per template in the Theme panel (not in global plugin settings).

Adjust theme values for the current template, then preview and save.

#### Partials in the editor

Saved Partial templates appear as presets you can insert into a Page template. Use descriptions on partials so they are easy to identify when browsing presets.

#### Tips

\- Prefer Section + elements over raw HTML unless you need custom markup.  
\- Use Grid for multi-column layouts.  
\- Keep Header/Menu and Footer as consistent patterns (or partials) across pages.  
\- Use presets (Hero, CTA, FAQ, Pricing, Team) as starting points, then customize.

# Components

##### Builder ships with built-in Twig components. You drag them in the visual editor; each has its own settings panel.

#### Sections and layout

| Component | Notes |  
|-----------|--------|  
| Section | Generic container; accepts nested elements |  
| Header | Layout area (e.g. for Menu) |  
| Footer | Layout area |  
| Hero | Section preset |  
| CTA | Call-to-action preset |  
| FAQ | FAQ preset |  
| Pricing | Pricing preset |  
| Team | Team preset |

#### Elements

Place these inside a Section or Grid:

| Component | Purpose |  
|-----------|---------|  
| Grid | Multi-column container |  
| Headline | Heading (H1–H6) |  
| Text | Body paragraph |  
| Image | Image / asset |  
| Button | Link button |  
| Menu | Navigation links |  
| HTML | Raw HTML when needed |  
| Craft Field | Display a Craft entry field value |

##### Working with Grid

1\. Add a Grid inside a Section.  
2\. Set columns in Grid settings.  
3\. Drop content into each column / grid item.

##### Menu

Use Menu inside a Header (or Section) to build navigation links (label + URL items).

##### Craft Field

Use Craft Field when the layout should pull live entry data (title, custom fields, etc.) instead of static text. This is useful for entry-driven pages.

##### HTML

HTML is an escape hatch for custom markup. Prefer built-in components when possible so styling and structure stay consistent.

##### Custom components

Developers can register additional components via the Builder SDK or by adding component folders. That is covered in the developer SDK documentation, not this user guide.

# Partials

##### Partials are reusable Builder templates of type Partial. They act as section presets you can insert into page templates in the visual editor.

#### When to use a partial

\- Shared header or footer blocks  
\- Recurring CTA strips  
\- FAQ or pricing blocks reused on several pages  
\- Any layout fragment you want to maintain in one place and insert elsewhere

#### Create a partial

1\. Go to Builder → Templates → New Template.  
2\. Set Type to Partial.  
3\. Add a clear Title and Description (description helps when browsing presets).  
4\. Save, then open the visual editor.  
5\. Build the block (usually a Section with nested elements).  
6\. Save.

#### Insert a partial into a page

1\. Open a Page template in the visual editor.  
2\. Browse saved presets / partials in the editor UI.  
3\. Insert the partial into the layout.  
4\. Adjust surrounding content and save the page template.

#### Filter partials in the list

On Builder → Templates, use the Partials filter to show only partial templates. Use Search to find them by name.

#### Best practices

\- Name partials by purpose: Site Header, Footer Links, Promo Banner.  
\- Write a short description for each partial.  
\- Prefer small, focused partials over one large “kitchen sink” preset.  
\- After changing a partial source, check pages that use that pattern — depending on how the preset was inserted, you may need to update page templates that already contain a copy of the structure.

# Assign Templates to Entries

##### Use the Builder Layout field to connect a Craft entry to a Builder template.

#### Add the field

1\. Go to Settings → Fields in Craft.  
2\. Create a new field of type Builder Layout.  
3\. Add the field to the entry type(s) that should use Builder templates.

If you used Create homepage, Builder may already have created and assigned this field for the homepage Single.

#### Select a template on an entry

1\. Edit an entry.  
2\. Find the Builder Layout field.  
3\. Choose a template from the dropdown (Page templates).  
4\. Save the entry.

You can also open or create templates from links provided in the field UI when available (Open visual editor / Create new template).

#### Front-end output

Your front-end Twig should render the Builder field (or layout) using Builder’s Twig helpers, for example via `craft.builder` render methods configured in your project templates.

If homepage setup was used, the site root is already wired to render the assigned Builder template.

#### Tips

\- Create the Page template first, then assign it on the entry.  
\- Use one Builder Layout field per entry type unless you have a specific multi-layout design.  
\- Disabled templates may not appear as expected — keep production templates Enabled.

# Theme and styling

#### Per-template theme

Theme colors and typography are configured per template in the visual editor Theme panel — not in the global plugin settings screen.

1\. Open a template in the visual editor.  
2\. Open the Theme panel.  
3\. Adjust colors, fonts, and related theme options.  
4\. Preview on the canvas.  
5\. Save the template.

#### Why per-template?

Different pages can use different brand treatments (landing page vs blog vs campaign) without changing a single global theme for the whole site.

#### Component styles

Individual components may also expose style-related settings in their settings panel (spacing, alignment, etc., depending on the component). Use Theme for overall look; use component settings for local tweaks.

#### Front-end CSS

Builder can output theme CSS variables for a layout. Your project templates may include theme CSS via Builder’s Twig helpers so the front end matches the editor.

#### Tips

\- Set Theme early on a starter template, then duplicate that template for consistent branding.  
\- Prefer Theme tokens over one-off HTML/CSS in the HTML component.  
\- After theme changes, hard-refresh the front end if you have aggressive browser or CDN caching.

# Troubleshooting

#### Builder does not appear in the CP

\- Confirm the plugin is installed: `php craft plugin/install builder`  
\- Check that your user group has permission to access the Builder CP section  
\- Clear Craft caches and reload the CP

#### Create homepage fails

\- Enable Allow Admin Changes in Craft (required to create sections/fields)  
\- Ensure you have permission to manage sections and fields  
\- Check the Craft log for validation errors  
\- Try again from Builder → Settings → Create homepage

#### Template will not save

\- Title may only contain letters, numbers, and spaces  
\- Avoid special characters in the title  
\- Check for JSON errors if you edited the Component tree (JSON) manually

#### Visual editor preview is blank or outdated

\- Save the template and reopen the editor  
\- Hard-refresh the browser  
\- Clear Craft caches  
\- Check the browser console and Craft logs for AJAX/preview errors

#### Front end does not show the layout

\- Confirm the entry has a Builder Layout field with a template selected  
\- Confirm the template is Enabled  
\- Confirm your front-end Twig renders the Builder field/layout  
\- For homepage: confirm homepage setup completed and the `\_\_home\_\_` entry is linked

#### Partial not listed as a preset

\- Confirm Type is Partial (not Page)  
\- Confirm the partial is Enabled  
\- Add a Description so it is easier to identify when browsing  
\- Refresh / reopen the visual editor

#### License status unexpected

\- Re-enter the License Key under Builder → Settings  
\- Confirm Enable remote license checks and License server URL if remote checks are required  
\- Save settings and reload

#### Still stuck

Collect:

\- Craft CMS version  
\- Builder plugin version  
\- Steps to reproduce  
\- Relevant lines from `storage/logs`

Then contact support with that information.