Kirby CMS: how to return Blocks as HTML?

Question

I'm playing with Kirby CMS and using it as a headless CMS. I'm using Blocks field to handle rich content. In the API, this field is returned as an array of objects:

[
    {
        "content": {
            "level": "h2",
            "text": "test"
        },
        "id": "02d4a71b-cd02-4382-a78c-84ff1e68324b",
        "isHidden": false,
        "type": "heading"
    }
]

Which is great, I think. But in my case, it's annoying, as I should do all the rendering by myself.

Is there a way, or an option, to tell Kirby to render this field as HTML content?

I know there is a $blocks->toHtml() method, but I'm using a standalone React frontend, so I can't use this in my JSX.

score 1 · Answer 1 · answered Nov 12 '21 at 07:15

You don't have to use the Kirby API directly in order to get content from your Kirby site. Kirby has a few different ways to respond to an ajax request - and that response can be in any format, such as JSON, an HTML snippet, or anything else. Here are a couple of the most often-used ways to achieve what you want.

CUSTOM ROUTE

You could define a custom route, which is like a 'custom api point', that your React interface could send requests to, and which would respond with the block list as an HTML snippet, as required. You could set your route at a URL like:

https://example.com/block-api

In your route, you could then use the toHTML() method, or a snippet(), or any other method, to convert the blocks into HTML that you can then send back as a string in your response.

In your route definition, you could also use a pattern that would allow you to (optionally) request a single block by ID. Your custom route URL for that would look something like this - where the last segment is the block ID:

https://example.com/blocks-api/02d4a71b-cd02-4382-a78c-84ff1e68324b

CUSTOM CONTENT REPRESENTATION

When you try to reach a page in your Kirby site via its normal URL, Kirby will put the page's content into your page's template, and return it as an HTML document. That is the 'default' behaviour. You can, however, override that.

You can define a custom content representation for your page, which tells Kirby that you want to receive the content of your page in a 'different format' - such as JSON, XML, or anything you wish. That 'different format' can even be just an HTML snippet. All you need to do is define a new template for it.

In your case, you could create a content representation that tells Kirby to return a fully-formatted HTML snippet of your blocks only - by creating a template called something like "mypage.blocks.php", with just the HTML for the blocks in it. So, if to access the page normally we'd go to URL...:

https://example.com/mypage

...to get your 'blocks' custom content representation for that page, you'd now go to:

https://example.com/mypage.blocks

Your custom content representation can have its own controller, too. This is useful if you want to get Kirby to send you the HTML code of just one single block, instead of all blocks on the page. You could use a query parameter in your URL to tell the controller which block you want the HTML for. The controller would then check the URL for the query parameter, and if the parameter is there, it returns only the required block. This would enable your React app to get the HTML code for just a single block on the page, by sending a request to an URL like:

https://example.com/mypage.blocks?id=02d4a71b-cd02-4382-a78c-84ff1e68324b

Kirby CMS: how to return Blocks as HTML?

1 Answers1

CUSTOM ROUTE

CUSTOM CONTENT REPRESENTATION