Reference

Guide

Pages

A pages select field that allows to select one or multiple related pages

The pages field allows you to select one or more related pages. It has a handy navigator to go through the entire site tree and select the pages you want

Example

fields:
  related:
    label: Related Pages
    type: pages

Field properties

Property Type Default Description
default

Default selected page(s) when a new page/file/user is created

disabled bool

If true, the field is no longer editable and will not be saved

empty

The placeholder text if none have been selected yet

help

Optional help text below the field

image

Image settings for each item

info string

Info text for each item

label

The field label can be set as string or associative array with translations

layout string list

Changes the layout of the selected files. Available layouts: list, cards

max int

The maximum number of allowed selected

min int

The minimum number of required selected

multiple bool true

If false, only a single one can be selected

query string

Optional query to select a specific set of pages

required bool

If true, the field has to be filled in correctly to be saved.

size string auto

Layout size for cards: tiny, small, medium, large or huge

text string

Main text for each item

translate bool true

If false, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.

when

Conditions when the field will be shown (since 3.1.0)

width string 1/1

The width of the field in the field grid. Available widths: 1/1, 1/2, 1/3, 1/4, 2/3, 3/4

Limit the selection

Multiple or single mode

If you only want to select a single page, set multiple mode to false (default is true)

fields:
  related:
    label: Related Pages
    type: pages
    multiple: false

Maximum number of pages

You can set the maximum number of pages that can be selected:

fields:
  related:
    label: Related Pages
    type: pages
    max: 3

Preview images

The default (preview) image is the first image in the folder. You can configure the (preview) image for each item using the image option:

image: page.image.findBy("name", "cover")

Preview image from assets folder

Since 3.2.0

You can also provide an image from the assets folder via a page model, for example as a fallback if the page has no images:

/site/models/album.yml
<?php

class AlbumPage extends Page
{
    public function previewImage()
    {
        if ($image = $page->images()->first()) {
          return $image;
        }
        if (file_exists(kirby()->root('assets') . "/assets/images/default.jpg")) {
            return new Asset("assets/images/default.jpg");
        }
        return false;

    }
}

And then in your blueprint

image: page.previewImage

For more fine-grained control you can set further options:

query

An image query, default page.image

image:
  query: page.children.first.image

cover

Whether or not the image will cover the available space.
Options: true, false (default)

image:
  cover: true

ratio

A freely selectable image ratio

image:
  ratio: 16/9

back

Set an image background.
Options: pattern (default), black, white

image:
  query: page.image.findBy("name", "cover")
  cover: true
  ratio: 1/1
  back: black

No image

If you don't want to show an image but the icon selected for the page, you can set the query option to false:

image:
  query: false

Kirby will then either show a default page icon or the icon defined in the page blueprint.

Info and text

The info and text properties allow you to define what information is shown for each selected item (and in the modal). You can use Kirby's query language to query any information you need.

Text

The text property shows the main information for the page, by defauult that is the page title. You can however either modify what is shown and how:

text: "{{ page.title.upper }}"
text: "{{ page.title }} | {{ page.description.excerpt(20) }}"

Info

With the info property, you can show additional information:

info: "{{ page.images.count }}"
info: "{{ page.tags }}"

How to use in templates/snippets

Single page

To convert a single page to a page object, use the toPage() method:

<?php if($relatedPage = $page->related()->toPage()): ?>
  <?= $relatedPage->title() ?>
<?php endif ?>

Multiple pages

To convert multiple pages to a pages collection, use the toPages() method:

<?php
$relatedPages =  $page->related()->toPages();
foreach($relatedPages as $relatedPage): ?>
  <?= $relatedPage->title() ?>
<?php endforeach ?>