Query Language
Kirby comes with a blueprint query language that offers basically the same functionality as Kirby's PHP API with a simple dot notation.
Introduction
The query language adds a lot of flexibility when querying options for select, radio and checkboxes fields, for querying collections in Panel sections and to manipulate how information is displayed in the Panel.
If you are not familiar with Kirby's PHP API yet, you should learn more about it first. The query language is very close to it and will be confusing without the basics.
Syntax
PHP
$site->title()
$page->title()->lower()
$page->children()
$page->children()->filterBy("featured", true)
$site->find('notes')->children()->filterby('tags', 'ocean', ',')
$page->images()->template('image')
Query
site.title
page.title.lower
page.children
page.children.filterBy("featured", true)
site.find('notes').children.filterBy("tags", "ocean", ",")
page.images.template('image')
These are just a few examples. As you can see, it is very close to the PHP syntax. You don't need to relearn anything this way.
Blueprint example
There are two ways of using the query language in your blueprints.
1. To fetch data
In this example we use the query language to fetch options for a select field. You can fetch any collection of pages, files or users to be used as options.
# select field
mySelect:
label: My Select Box
type: select
options: query
query: site.children.listed
2. To create string templates
Another way to use the language is to create custom information for page or file lists. In this case we use the query language as part of our template syntax.
# pages section
published:
headline: Published Pages
type: pages
info: "Year: {{ page.year }}"
Querying options in fields
In various field types (tags, select, multiselect, checkboxes, radio, files, pages and related custom fields) you can use the query
option to query possible options, for example:
tags:
label: Tags
type: tags
options: query
query:
fetch: page.siblings
text: " {{ page.title}}"
value: " {{ page.uri}}"
mySelect:
label: My Select Box
type: select
options: query
query: site.children.listed.template('note') # get all children with the note template
Check out the docs for each of these fields in the Reference.
Querying the parent in pages and files sections
sections:
articles:
type: pages
headline: Blog Articles
parent: site.find("blog")
Querying an image in the image option
image:
query: page.images.template("cover").first
ratio: 1/1
cover: true
Querying information to display
info: "{{ page.from.toDate('d.m.Y') }} - {{ page.to.toDate('d.m.Y') }} / {{ page.location }}"
info: "{{ file.dimensions }}"
Extended query syntax
3.2.0
You can use array syntax and nested queries in Kirby's query syntax.
# arrays
query: site.index.filterBy("template", "in", ["note", "album"])
# nested queries
query: kirby.collection("some-collection").not(kirby.collection("excluded-collection"))