Controllers
Templates should contain as little code as possible to separate logic and form. With template controllers you can add more logic to your templates without messing up your markup.
Stay in control with controllers
Controllers are a great way to move logic for your templates into a separate file.
TL;DR
- Use a controller for the logic of your templates.
- Any data returned by a controller’s function is available everywhere in the corresponding template.
- A controller must have the same file name as the corresponding template file.
- Save controllers in
/site/controllers
.
The controllers directory
Controllers go into /site/controllers
. Create the directory if it's not there yet. Controllers are named exactly like the templates they belong to:
Template | Controller |
---|---|
/site/templates/article.php | /site/controllers/article.php |
Kirby will automatically load the controller for your template if it can find one.
General site controller
You can also use a general site controller called site.php
which you put into your /site/controllers
folder like any other page controller. Such a general site controller is useful if multiple templates share the same logic, while they don't need any template specific logic. It works like a normal page controller but will only be applied to templates that do not have a specific page controller. It will not be loaded in addition to a template-specific controller.
If you want to share logic between multiple templates and still add template specific logic in a dedicated page controller, check out the Shared controllers recipe.
Creating a controller
The basic code for a controller is very simple. It's an anonymous function that should return the variables that you want to pass to the template as an associative array.
In this case the $foo
and $bar
variables will be available in the corresponding template.
Accessing Kirby objects in your controller
Like in templates, you can access the $site
, $page
, $pages
and $kirby
objects by loading them as arguments to the anonymous function. Kirby will magically inject the right objects for you:
A single object
Multiple objects
Order doesn't matter
A real world example
A typical example where a controller can come in handy is a blog template. Fetching the right articles can take a couple lines of code and it's much nicer to wrap these in a controller. So let's create /site/templates/blog.php
and /site/controllers/blog.php
The controller
The controller will take care of fetching the right articles and add pagination to them. It will then pass the $articles
and $pagination
variables to the template to keep it clean.
The template
With such a controller, the template can be super clean. A foreach loop for the articles and the prev/next pagination and you're done.
Arguments from the router
If you work with additional routes and you want to access the arguments from the router in your controller, you can use Kirby's route()
method to access an array of router arguments.
Arguments from $page->render()
in route
When using the $page->render()
method to return a page in a route, you can send an array of additional data with it:
In the controller, you can load each variable that you passed to the render()
method in the route into the controller's anonymous function and then work with it.
The properties defined in the $data
array are exposed to templates as global variables, so in use cases where you do not need them in a controller, you can use them directly.