How Builder works (technical overview)
👉Tip: We recommend first reading our high level overview of Builder for the foundation that this builds on
How is Builder structured?
Builder is structured by models. You can make models for Pages, Sections, and Data
Use Pages to Build to manage entire pages, like:
- Homepage
- Content pages (about, partners, etc)
- Blog pages
- Landing pages
Use Sections to Build and parts around your site or app
- Announcement bars
- Product detail descriptions
- Collection heros
- Cart upsells
Use targeting to show different content on different pages and to different users
Use Data to control structured data like
- Navigation links
- Product data
- Blog post authors
Structuring your site
One of the easiest ways to get started is to add landing page building to your site. Once you have that, you can start adding editable sections across your site, and use targeting to choose the right content for the right users
Here are some examples we recommend for how to structure various pages on your site
How is the data structured?
Builder uses a simple JSON data structure like the below. It is a tree of "blocks" which are the components our SDKs will render for you with the options provided in the UIs
{
"blocks": [
{
"component": {
"name": "Text",
"options": {
"text": "Hello world!"
}
}
}
]
}
How does the visual editor work?
Our editor loads your site in an iframe. You need to provide the URL for our editor to open. This page will need to have a Builder SDK integrated so we can discover where it is, any settings provided, and pass messages to it.
When a Builder SDK sees it is loaded in our editor, instead of showing the default content, it waits on a message from the Builder webapp of what content to display. We message down the JSON and send patches as edits are made of what to render differently (component added, input changed, etc) and the SDK will render the updates accordingly
You can also register your own components to be used in the editor. When you do this Builder keeps a map of component names to references, and messages the webapp what components exist and what inputs they take. Under the hood, the built in components (like Image, Text, Columns, etc) work the same way and are open source
// This code is in your app. Can be the same components you already use
import { Builder } from '@builder.i/react';
const Heading = (props) => <h1>{props.text}</h1>
Builder.registerComponent(Heading, {
name: 'heading',
inputs: [{ type: 'string', name: 'text' }]
})
Internally, we keep a map like:
const componentMap = {}
componentMap['heading'] = Heading
And then when we render the content for you, we iterate over the blocks and render the components and inputs via your farmework/SDK of choice, like:
// Simplified example
export const BuilderComponent = (props) => (
props.blocks.map(component => {
let Component = componentMap[component.name];
return <Component {...component.options } />
})
)
Hosting
Builder pushes content to your site or app via APIs. You control your site, code, and hosting - we only pass content within your own setup for you
Can I extend Builder funtionality with my own code?
Absolutely. Besides being able to register your own components in the editor and change settings, you can also customize Builder deeply via plugins