Cacao Kit

Demo & Semi Documentation

How blocks are resolved


Kirby stores a blocks field as JSON. An image block holds a file UUID like file://BYXR0pvumEbfTknP, and a link in a text block points to a permalink like /@/page/…. Neither means anything to a frontend, so Cacao Kit resolves them in the backend, and every block arrives ready to render.

One query for the catch-all route

For every page it renders, the catch-all route sends a KQL query with the same select. That select holds page.blocks.toResolvedBlocks and page.layouts.toResolvedLayouts, two field methods of Kirby Headless. They turn the field into blocks or layouts and run three resolvers over each block: one for files, one for pages, and the custom resolvers in site/config/blocks-resolver.php.

A lit tent under trees and a starry sky
This block only stores a file UUID – the backend sent a srcset.

Images

Which fields the file resolver handles is configurable; out of the box, it is the image field of the image block. The defaultResolvers entry in the same config file decides what a file turns into: URL, width, height, srcset, and alt text.

Custom resolvers

A custom resolver is keyed <block>:<field> and replaces the value of that field. text:text turns permalinks into paths: this link to the about page is stored as a permalink and arrives as a plain path. It keeps working when the page's slug changes.

cards:cards gives each card a responsive image and a link. notes-grid:notes goes one step further: the block stores no content, and the resolver fills it with the listed notes – title, path, date, and a cover thumbnail, in the requested language. That is why the notes grid on the home page costs no extra request.