BASICS: Understanding Blueprints

hey everyone,

i’m having some trouble understanding the relationship between Blueprints and Templates. i know that the Blueprints create forms in the panel… but how do you connect those forms with the Template?

for example, let’s say you want to replace the images in a slider from the panel. in static HTML it looks like this:



what are the next steps you would take?

really appreciate your time and help!

Well, first of all, there is no direct relation between a blueprint and a template. The blueprints are only relevant if you use the panel but you don’t need the panel to be able to use Kirby because you could just create the text files in any text editor.

So basically, a blueprint defines what a user can write into a text file and the template then pulls that information from that text file.

If you want the user to be able to add some images for a gallery via the panel, you would need to define a field in your blueprint that lets the user enter a list of images. One way of doing that would be a multi-select field (e.g. using the visual select plugin:, another a structure field (

In the template you would then pull that information from the text file via php, depending on what sort of field you have created.

If you use the selector field, for example, you would create a new field in your blueprint:

        label: Images
        type:  selector
        mode:  multiple
            - image

which would let the user select images from all the available images in the page folder:

In your text file, you would then end up with a comma separated list of images:

Gallery: 758px-sydney_skyline_at_dusk_-_dec_2008.jpg,forrest.jpg,green.jpg

Now, to pull that information in your template, you could use the following code:

$gallery = $page->gallery()->split(); //splits the comma separated list so you end up with an array that you can iterate through
foreach($gallery as $galleryImage) : ?>
<img src="<?php echo $page->images()->find($galleryImage)->url() ?>" />
<?php endforeach ?>

So much for the basics, hope it helps. You could of course first check if there are images selected and so forth …


thanks for the detailed response… it helps a lot! i got it to work… kind of haha.

so would you say that knowing PHP is the key to understanding how Kirby works? are there any other important languages or concepts that i should spend time learning? i’m very comfortable with HTML and CSS but i’m just beginning with Javascript and PHP…

You’re welcome. Knowing the basics of PHP (iterations, conditions, using variables) will help a lot but since Kirby comes with a lot of methods that make your PHP-life easier, you should get along quite easily. Some basic JS/JQuery is helpful as well.

For starters, I’d suggest to read the docs, especially the tutorials, that will give you a basic understanding of how it all works and then learn as you go along.

1 Like

hey @texnixe, i have a quick follow up question i was hoping you could help me with…

i’m looking at:

<?php foreach(page('projects')->children()->visible()->limit(3) as $project): ?>  

and trying to figure out exactly what’s going on… most importantly, where is $project being created/how do i create my own? also how does that relate to page('projects') ?

(this example is from the Starter Kit… i’m trying to make my own version of a teaser and archive)

page('projects')refers to the projects folder of the Starter kit. The projects folder contains three child folders project-a, project-b and project-c. So, page('projects')->children()->visible() fetches these child pages (or rather, only the visible ones) in a collection and the foreach loop than iterates through this collection. $project is just a variable for each of these single child project pages …