Compose pages and entries with reusable visual blocks.
What is the block builder?
The block builder (visual builder) lets editors compose layouts from reusable sections—hero banners, feature grids, FAQs, pricing tables, rich text, and more—without writing HTML. It works on Pages and on content entries when the content type has block builder enabled.
Enable block builder on a content type
- Go to Content → Content types.
- Edit the type.
- Check Enable block builder on entries (
supports_block_builder). - Save. New and existing entries show the Block builder panel on edit.
Pages include block builder by default on the page editor and dedicated builder screen.
Where to find the builder
| Host | Location |
|---|---|
| Page | Page edit → Block builder section, or Open full builder at /admin/pages/{id}/builder |
| Content entry | Entry edit → Block builder collapsible panel (after first save) |
Adding and editing blocks
- Click Add block to open the palette.
- Browse categories: Hero & headers, Content, Marketing, Social proof, Layout, Brand presets.
- Select a block type (e.g. Hero, FAQ, Features grid).
- Click Edit on a row to configure headline, body, images, JSON-driven grids, etc.
- Invalid JSON in structured fields is rejected on save with a clear error.
Reordering and actions
- Drag rows to reorder—order saves automatically on drop.
- Duplicate — Copy a block with its data.
- Delete — Remove a block (confirmation prompt).
- Save as pattern — Store the block configuration for reuse across pages or entries.
Common block types
| Block key | Purpose |
|---|---|
hero | Headline, subheadline, CTAs, optional background image |
features_grid | Grid of feature cards with icons |
content_type_cards | Latest entries from a content type as cards |
pricing_table | Pricing tiers with highlight column |
faq | Accordion questions and answers |
testimonials | Customer quotes with attribution |
cta_banner | Call-to-action strip with button |
rich_text | Freeform formatted content |
Saved patterns
Patterns appear at the top of the Add block palette. Save frequently used configurations (e.g. standard pricing layout) and insert them on any page or entry that supports the builder.
Storefront rendering
Published pages and entries render sections above or alongside custom fields. Theme templates output:
{% if content_entry_has_sections and content_entry_sections_html %}
<div class="theme-cms-sections">{{ content_entry_sections_html|raw }}</div>
{% endif %}Section HTML resolves from theme templates under themes/{theme}/views/sections/ with fallbacks from parent themes.
Pages vs entries
Use block builder on pages for one-off marketing layouts. Use on entries when a content type needs rich landing-style layouts per item (e.g. case studies, product detail enhancements) while keeping structured custom fields for metadata.
Troubleshooting
- Block builder panel missing on entry — Save the entry once; confirm type has block builder enabled.
- Sections not on live site — Entry must be published; check theme template includes sections output.
- JSON save error — Validate JSON in grid/FAQ fields; use double quotes for keys.
- Reorder not sticking — Ensure JavaScript is enabled; check for CSRF or session expiry.