Add Dynamic Blocks
This chapter connects stored editorial blocks to request-time data.
Replace The Page Record With A Dynamic Block
At this checkpoint, the page file should explicitly contain a dynamic block configuration:
content/pages/spring-sale.json
{
"id": "page-spring-sale",
"type": "landing_page",
"title": "Spring Sale",
"slug": "spring-sale",
"summary": "Fresh arrivals and seasonal offers for the new quarter.",
"settings": {
"page_type": "landing_page",
"template": "pages/landing-page",
"show_in_navigation": true,
"allow_indexing": true
},
"blocks": [
{
"kind": "instance",
"id": "featured-events-spring",
"block_type": "featured_events",
"label": "Upcoming events",
"fields": {
"heading": "Try the new range in person",
"limit": "3",
"city": "Bristol"
}
}
]
}
Replace crates/tutorial-app-backend/src/lib.rs
The customer backend should now turn that stored configuration into runtime data:
use coil_customer_sdk::{
BackendError, CustomerBackendPlugin, CustomerHookRegistry, RequestContext,
};
use std::collections::BTreeMap;
pub struct TutorialAppPlugin;
impl CustomerBackendPlugin for TutorialAppPlugin {
fn register(
&self,
_registry: &mut dyn CustomerHookRegistry,
) -> Result<(), coil_customer_sdk::BackendError> {
Ok(())
}
}
pub fn featured_events_block_model(
_request: &RequestContext,
) -> Result<Vec<BTreeMap<String, String>>, BackendError> {
Ok(vec![
BTreeMap::from([
("title".to_string(), "Bristol trail evening".to_string()),
("href".to_string(), "/events/bristol-trail-evening".to_string()),
]),
BTreeMap::from([
("title".to_string(), "Lake district gear clinic".to_string()),
("href".to_string(), "/events/lake-district-gear-clinic".to_string()),
]),
])
}
Add A Real Block Fragment
Keep the template contract explicit:
templates/blocks/featured-events.html
<section xmlns:coil="https://coil.rs" coil:fragment="block">
<p class="eyebrow" coil:text="${block.fields.heading}">Upcoming events</p>
<ul>
<li coil:each="event : ${block.runtime.events}">
<a href="#" coil:attr="href=${event.href}" coil:text="${event.title}">Event</a>
</li>
</ul>
</section>
At this point the dynamic-block checkpoint should be visible as three concrete files:
content/pages/spring-sale.json
crates/tutorial-app-backend/src/lib.rs
templates/blocks/featured-events.html
What Each File Is Doing
content/pages/spring-sale.json
This file still stores the editorial block instance.
The important fields are:
block_type = "featured_events"This tells the runtime which kind of block it is dealing with.fields.headingEditor-owned display copy.fields.limitEditor-owned configuration for how much live data to request.fields.cityEditor-owned filter criteria.
This file does not store the actual event list. It stores the configuration needed to ask runtime code for one.
crates/tutorial-app-backend/src/lib.rs
This file resolves request-time data.
The important function is featured_events_block_model(...).
That function takes the stored block configuration and returns live values that should only exist at request time:
- event titles
- event links
- any other derived runtime fields you need later
This is the point where customer-owned Rust turns stored editorial intent into live page data.
templates/blocks/featured-events.html
This file renders the combined contract.
The important split in the template is:
${block.fields.heading}editor-owned stored content${block.runtime.events}runtime-owned live data
That split is the key dynamic-block seam. The template does not query for events itself. It renders what the runtime has already prepared.
What Behavior This Enables
Once these files match:
- editors can place a dynamic block on a page without hard-coding live records into CMS content
- customer backend code can fetch or derive live data per request
- templates can render one stable block contract that mixes stored fields and runtime fields
- the app gains a clear schema/content/render-model handoff instead of hiding dynamic behavior in templates
Checkpoint
Run the app and verify one real block is now mixing:
cargo run -p tutorial-app-bin -- validate
cargo run -p tutorial-app-bin -- serve
- stored editorial config
- request-time live data
- fragment rendering