CMS Page Builder Model
This page explains the public page-builder boundary in Coil.
Use it when you need to answer questions like:
- what is the difference between a page type and a page record?
- what is a block definition versus a block instance?
- where does
page.blockscome from? - what part is editorial content versus request-time runtime shaping?
The Model In One Sentence
Coil separates:
- content schema
- stored content instances
- request-time render-model shaping
Those are three different layers.
If you need the conceptual version first, read Content schema vs content instances.
Layer 1: Content Schema
Schema defines what editors are allowed to create.
Typical schema concepts:
- page types
- block types
- field definitions
- allowed block lists
- validation rules
Schema is not a page instance.
Layer 2: Content Instances
Instances are the records that actually exist.
Typical instance concepts:
- a specific page record
- the page’s slug and publication state
- the ordered list of blocks on that page
- the field values stored on each block
Instances are where real editorial choices live.
Layer 3: Request-Time Render Model
At request time, Coil still has to shape a template-facing model.
That model may include:
- page metadata
- block instances
- live data resolved from block config
- customer or module-owned request context
This is where templates get their final values.
Page Type Vs Page Instance
Page type
A page type is a schema concept.
Examples:
homelanding_pagearticle
It defines:
- which fields exist
- which blocks are allowed
- which fields are required
Page instance
A page instance is a content record.
Examples:
home-ukspring-saleabout-us
It carries real values such as:
- title
- slug
- status
- site or locale targeting
- ordered block instances
- page settings
Structured Page Settings
Page settings are part of the content instance, not an afterthought hidden in the template.
Examples of page settings:
- page type
- template or layout hint
- SEO title
- SEO description
- navigation visibility
- indexing options
These settings are still editorial data. They are not infrastructure config, and they are not the same thing as request-time render-model shaping.
Block Definition Vs Block Instance
Block definition
A block definition is schema.
Examples:
heropromo_gridfaqfeatured_collection
It defines the fields and validation rules for that kind of block.
Block instance
A block instance is content.
Examples:
- the homepage hero for the UK site
- a
featured_collectionblock forspring-sale - an FAQ block containing five questions
It carries the real field values chosen by editors.
In a structured page-builder model, block instances should usually be treated as ordered structured records, not one large free-form HTML blob.
What page.blocks Means
page.blocks is a request-time render-model contract.
That is important because it is not guaranteed by schema alone.
For page.blocks to exist in a rendered page, Coil needs:
- a route that resolves to a page
- stored page and block instances
- runtime shaping that exposes those blocks into the render model
If any one of those is missing, page.blocks does not appear automatically.
Shared Blocks And Reusable Sections
If your content system supports reusable sections, treat them as content instances or content-backed references, not as schema.
Examples:
- a reusable newsletter signup panel
- a reusable promo strip
- a reusable trust-and-delivery footer section
The important rule is the same:
- the reusable block definition is schema
- the reusable saved block is content
- the rendered output is request-time model data
In practice, that often means a page contains a mix of:
- page-local structured block instances
- shared block references
Dynamic Blocks
Dynamic blocks add one more layer: live data resolution.
For example, an editor may configure:
- block type:
featured_collection - collection:
new-arrivals - limit:
8
That stored block is still not the final UI.
The runtime must resolve the live product list and shape the request-time model.
For that pattern, read Dynamic blocks and live-data sections.
What Coil Does Not Do Automatically
Coil does not automatically:
- create page instances because a page type exists
- create block instances because a block type exists
- populate
page.blocksbecause a schema allows blocks - resolve live data for dynamic blocks without runtime logic
- map every stored field into a template contract by default
You still need explicit request-time shaping.
For that pipeline, read Render pipeline and model composition.
Safe Mental Model
Use this mental model:
- schema tells editors what they may create
- content instances store what they did create
- request-time shaping decides what templates can render
If you keep those layers separate, the CMS boundary stays understandable.