Page Builder gives merchants drag-and-drop content - but its real power is extensibility: custom content types that let editors add your components (a store-locator card, a buying-guide embed, a promotional countdown) without touching code. Built well, they feel native. Built badly, they break on upgrade. Here is the anatomy.
The Four Files
A content type is declared, not coded in the traditional sense:
view/adminhtml/pagebuilder/content_type/acme_promo_countdown.xml- the declaration: fields, appearance, form sectionsview/adminhtml/web/template/content-type/acme-promo-countdown/preview.html- the admin preview (Knockout template)view/adminhtml/web/template/content-type/acme-promo-countdown/master.html- the storefront output templateview/adminhtml/web/js/content-type/acme-promo-countdown/preview.jsandmass-converter.js- the glue: preview logic and the conversion between form data and stored attributes
The XML drives everything: declare content_type with its form (the edit panel), appearances, and how each field maps to attributes in the master template.
Fields and the Master Template
Fields declared in the XML become Knockout-observable data. The master template renders them with attribute bindings:
<div attr="data.main.attributes" ko-style="data.main.style" css="data.main.css">
<h2 html="data.title.content"></h2>
<countdown date="data.target_date.content"></countdown>
</div>
The mass converter serialises field values into the stored HTML’s data attributes; Page Builder’s persistence is HTML with data-pb-style and friends, not a database schema. Respect that: the master template’s output is what gets saved into CMS content.
The Rules That Keep You Upgrade-Safe
- Never edit core content type files - extend via your own content type or the documented appearance-extension points
- Keep rendering in templates, logic in preview/converter JS; the storefront must render from stored HTML alone, with no admin JS
- Follow the core examples:
Magento_PageBuilder’s banner and products types are the reference implementations - copy their structure - Test content portability: Page Builder content moves between environments as HTML; hardcoded environment-specific URLs in your templates will break on migration
When to Build One
A custom content type earns its build cost when editors will use it repeatedly: brand-specific components, structured promos, anything an editor currently hand-codes in raw HTML blocks. For one-off layouts, teach editors to compose the built-in types instead - row, column, banner, HTML cover more than most teams realise.
The payoff is editorial independence: marketing ships rich, on-brand content without developer tickets, and developers stop being the CMS. That division of labour is exactly what Page Builder was built for - custom content types just extend it to your brand’s components.