In this example, we will create a JSON representation of the
default template. After we are done, all pages with the
default template will also be available in JSON. We will see below how exactly that works.
A representation is defined by its representation template. For our JSON representation, let's create a file
default.json.php in our
/site/templates directory with the following content:
You can of course output anything in the representation template. As we are building a JSON representation in our example, the output should be valid JSON.
The response will automatically be sent with the content type
A content representation requires that the standard template with the base name is present. If you want to create a JSON representation
project.json.php, make sure that
project.php exists. If
project.php doesn't exist, Kirby will fall back to
default.json.php, and if that template doesn't exist either, return the error page.
That means, a content representation is always a variant of the standard template. If you don't need the standard template at all, you can use this instead of the representation to return the content type you need. In this case, send a header with the corresponding content type.
In most cases, you don't have to send a content type header manually, Kirby will do this for you based on the representation type (based on extension and/or content). If you use some custom extension, Kirby will assume a default content type of
text/html. In case you want to set a specific content type, you can do this with response types, for example:
Now that we have a representation template for our
default template, we can request all
default pages as a JSON file. To access the representation, add the name of the representation to the end of the URL.
https://yourdomain.com/about.json and so on.
If you use content representations on the homepage, the URL will become
https://yourdomain.com/.json (or whatever extension you use).
If the representation exists, the template will be loaded and Kirby will send a correct content type header if possible. If the representation doesn’t exist, the error page will be displayed like if you didn’t use content representations at all.
It is still possible to create pages that contain a dot in their URL. If you already have a page called
about.json for some reason, it will continue to work. You can get the JSON representation of that page at
https://example.com/about.json.json. Please keep in mind though that using dots in URLs is not recommended to avoid confusion.
The built-in PHP server has issues with dots in paths, unless they are part of a filename, and will throw an error. For this reason, you may have to explore other local development solutions when working with content representations.
You can also have dedicated controllers for each of your representations. If you create a controller with the name
default.json.php, it will be used for the JSON representation of the default template. If no dedicated representation controller exists, the standard controller (
site.php) will be used instead (if available).
You can create content representations in plugins by defining a template with the matching extension.
If you need a matching controller, you can create one via a plugin as well:
Controllers and templates from plugins get overridden automatically if they exist in the
controllers directories. You can use this behavior to provide default setups in a plugin and still give the option to overwrite them individually if needed.