Dynamic Blocks And Live-Data Sections
Dynamic blocks are page sections whose final output depends on both editorial configuration and runtime data.
This is where people often expect Coil to do more automatically than it actually does.
The Short Version
A dynamic block usually has three parts:
- editorial configuration stored as content
- runtime logic that resolves live data
- a template or fragment that renders the final output
If any one of those parts is missing, the block is not actually dynamic.
What Makes A Block Dynamic
A static block can often render directly from stored content:
- heading
- body text
- image
- CTA
A dynamic block needs additional runtime work.
Examples:
- featured products based on current catalog state
- upcoming events based on live schedules
- membership summary based on account state
- campaign banners driven by site, locale, or audience
- live admin or dashboard cards
The editor may choose that a block belongs on the page, but the runtime still has to resolve the actual data shown inside it.
The Three-Layer Model
1. Editorial configuration
This is the CMS-owned part.
Examples:
- block type is
featured_collection - collection handle is
spring-sale - title override is
Fresh arrivals - max items is
6
This tells Coil what the editor wants the section to do.
2. Runtime logic
This is the request-time part.
Examples:
- load six visible products from the current site catalog
- filter events by locale and publish state
- load the current customer membership status
- decide whether the current site should show the block at all
This logic usually lives in:
- official-module model shaping
- customer render-model hooks
- fragment handlers or extension handlers
3. Template or fragment rendering
This is the presentation layer.
Examples:
- render a product grid
- render an event list
- render a membership badge strip
The template only works once the runtime has shaped the final request-time values.
What Coil Does Not Do Automatically
Coil does not automatically:
- turn a block schema into a live data query
- populate a dynamic section just because an editor chose that block type
- infer which repository or API should back a block
- decide how block config maps to runtime queries
- dispatch fragment rendering for a block unless the runtime or handler path is wired explicitly
That work must be designed.
Example: Featured Products Block
Imagine a page builder lets editors place this block:
type = featured_collection
collection = spring-sale
limit = 6
title = Fresh arrivals
That config is not yet a rendered block.
The runtime still needs to:
- read the block instance
- resolve the current site and locale
- fetch the matching visible products
- shape a request-time model
- render the block template
Without that runtime step, the page only knows that the editor requested a featured collection. It does not know which six products to show.
Dynamic Blocks Vs Live-Data Sections
These terms are closely related but not identical.
- a dynamic block is a block-shaped editorial unit whose output depends on runtime logic
- a live-data section is the broader concept of any request-time section backed by live state
In practice, a live-data section often appears inside a dynamic block system, but it can also appear as a route-owned section outside a page builder.
Where The Data Should Live
Use this rule of thumb:
- content editors own layout choices and editorial configuration
- runtime code owns live data loading and state interpretation
- templates own final presentation
Do not push runtime data loading into content schema. Do not push editorial block configuration into low-level runtime code unless the page is entirely route-owned and not editor-driven.
Common Mistakes
Treating dynamic blocks as just another static CMS block
Static blocks and dynamic blocks are not the same operationally. Dynamic blocks require request-time logic.
Expecting page.blocks to include fully resolved live data automatically
Whether a block exposes only editorial config or a fully shaped live payload is a runtime contract, not an automatic platform guarantee.
Hiding all live behavior inside templates
Templates should render already-shaped data. They should not become the place where runtime data loading or dispatch logic is secretly implemented.