Page Models

• The models directory
• Creating a page model
• Page models in the wild
• Overriding the Page class

A page model is an extended version of the default page object. You can create a page model for any type of page you have. By adding additional functionalities to your pages you can simplify your template code and have more powerful control over your page data.

The models directory

Page models go into /site/models. Please create the directory if it's not there yet. Page models are named exactly like the templates they belong to:

Kirby will automatically load the page model for your template if it can find one.

Creating a page model

A page model is a PHP class that extends Kirby's default page class. The class name corresponds with the name of the template and text file. So if your text file is called project.txt Kirby will look for a project.php model file with a ProjectPage class.

<?php

// For a content file called `project.txt`
// In general the class name is {{ProjectFileName}}Page

class ProjectPage extends Page {
  // all methods of the Page class are inherited and can be overridden here now.
}

This page model will be loaded every time Kirby encounters a page of the given type (so project in this example), whether it is in a template, a snippet or anywhere else.

Page models in the wild

A page model can be used for example to fetch a cover image for a project page. Fetching the right image in the template or snippet can be a couple of lines of code. It is cleaner to seperate this functionality into a page model.

The page model

The page model will make a method called cover() available for all your project pages. It will return the cover image, so you don't have to fetch it in the template code.

<?php
class ProjectPage extends Page {
  public function cover() {
    return $this->image('cover');
  }
}

Note, that you're using $this where you would usually use $page anywhere else in Kirby, because you are referring to the extended page class in this case.

In your templates

With such a page model you can now use the new cover method throughout all templates, snippets and controllers:

<h2>Latest Projects</h2>

<ul>
  <?php foreach(page('projects')->children()->visible()->limit(3) as $project): ?>
  <li>
    <a href="<?= $project->url() ?>">
      <img src="<?= $project->cover()->url() ?>" alt="<?= $project->title() ?>" />
    </a>
  </li>
  <?php endforeach ?>
</ul>

By creating the model and the cover method you don't have to repeat that code in every single snippet and template, in which you are dealing with projects. The cover method in this case is pretty short and simple, but imagine this with more complex queries for images or other data. As an additional benefit you can make changes that are reflected throughout all your templates and snippets in a single file.

Overriding the Page class

It is also possible to override the functionality of Kirby's page class. Be careful with this as it is possible to change Kirby's behaviour in unwanted ways!

A simple unintrusive example is to sort all images differently by default.

<?php

class ProjectPage extends Page {
  public function images() {
    return parent::images()->sortBy('sort', 'ASC');
  }
}

By calling parent::images() in this example we can refer to the original image method in Kirby's default page class in order to simply extend its functionalities.