# Pages section List and edit subpages **** - Source: **** ## What is a pages section? A pages section lists the children of a given parent or a set of pages defined by a query. Pages sections also let you do the following operations (if not forbidden or impossible because of other settings): - create a new page - delete a page - change the status of a page - move a page - duplicate a page - change the page slug - change the page template - change the order number
## Example ```yaml title: Shop sections: drafts: label: Drafts type: pages status: draft templates: product published: label: Published Products type: pages status: listed templates: product ``` (screencast: https://www.youtube.com/watch?v=rVcg4SlAh-A poster: youtube-section.jpg title: A closer look at pages sections text: Show subpages as cards or list, add additional info for each page, control the card design – there are hardly any limits.)

Sections do not store anything in the content file, which means that you cannot fetch content from a section in your templates like you would from field content.

 ## Section shortcuts For simple sections that are only used once per blueprint, you can use shortcuts. In its most basic form, a `pages` section consists of the section type as name, and `true` as its value. ```yaml sections: pages: true ``` This will add a `pages` section with all default properties. These shortcuts can be extended with other section properties as needed, for example: ```yaml sections: pages: label: Main Pages status: all ``` Keep in mind that the same section name can only be used once per blueprint. ## Section properties The pages section has multiple options to control what kind of pages should be displayed, how they should be displayed and what happens if a new page is added.
Name Type Default Description
batch bool false Activates the batch delete option for the section
columns array null Columns config for layout: table
create mixed null Optional array of templates that should only be allowed to add or false to completely disable page creation
empty mixed null Sets the text for the empty state box
flip bool false Enables/disables reverse sorting
headline mixed null The headline for the section. This can be a simple string or a template with additional info from the parent page.
help mixed null Sets the help text
image mixed null Image options to control the source and look of preview
info mixed null Optional info text setup. Info text is shown on the right (lists, cardlets) or below (cards) the title.
label mixed null The label for the section. This can be a simple string or a template with additional info from the parent page. Replaces the headline prop.
layout string 'list' Section layout. Available layout methods: list, cardlets, cards, table.
limit int 20 Sets the number of items per page. If there are more items the pagination navigation will be shown at the bottom of the section.
max int null Sets the maximum number of allowed entries in the section
min int null Sets the minimum number of required entries in the section
page int null Sets the default page for the pagination.
parent string null Sets the query to a parent to find items for the list
query string null Filters pages by a query. Sorting will be disabled
rawvalues bool false Whether the raw content file values should be used for the table column previews. Should not be used unless it eases performance issues in your setup introduced with Kirby 4.2
search bool false Enable/disable the search in the sections
size string 'auto' The size option controls the size of cards. By default cards are auto-sized and the cards grid will always fill the full width. With a size you can disable auto-sizing. Available sizes: tiny, small, medium, large, huge, full
sortBy string null Overwrites manual sorting and sorts by the given field and sorting direction (i.e. date desc)
sortable bool true Enables/disables manual sorting
status string '' Filters pages by their status. Available status settings: draft, unlisted, listed, published, all.
template arrayorstring null Filters the list by single template.
templates mixed null Filters the list by templates and sets template options when adding new pages to the section.
templatesIgnore mixed null Excludes the selected templates.
text mixed '{{ model.title }}' Setup for the main text in the list or cards. By default this will display the title.
## Label The label will be displayed above the pages section. You can pass a simple label as a string or you can provide translations for multiple languages, if you have an international editing team. ### Single language ```yaml label: Articles ``` ### Multiple languages ```yaml label: en: Articles de: Artikel es: Artículos ``` ### Placeholders You can inject information from the current page into the label with template placeholders using our query language. ```yaml label: "Articles for {{ page.title }}" ``` ## Layout The pages can either be displayed as a simple list or as cards with preview images. The list view is the default view. ### List layout (default) The `list` layout is perfect for more text-heavy pages, like articles, link lists, simple pages, etc. ```yaml layout: list ```
### Cards layout The `card` layout is great for media-heavy pages, like galleries, products, projects, etc. ```yaml layout: cards ```

Cardlets layout

The cardlets layout is great for nice visual previews of files, while your text content is still representend decently.

layout: cardlets
### Table layout The table layout has the highest information density. Columns can be fully customized and make it perfect if you need to show multiple values at once for better overview and scannability.
```yaml layout: table ``` The table layout will show the preview image together with a title and info column based on your text and info settings. You can switch off those automatic columns with `image: false`, `text: false` and `info: false` if you want to introduce your own columns. #### Columns Custom table columns can be defined with the `columns` option. ```yaml layout: table columns: subheading: true date: true ``` Each column can be customized with additional settings: ##### Label ```yaml layout: table columns: subheading: label: Subheading ``` ##### Translated label ```yaml layout: table columns: subheading: label: en: Subheading de: Unterüberschrift ``` ##### Alignment Text alignment can be left (default), center or right. ```yaml layout: table columns: subheading: label: Subheading align: right ``` ##### Width The column width can be set with the `width` property. You can use the usual fractions: ```yaml layout: table columns: info: false subheading: label: Subheading width: 1/3 title: width: 1/3 date: width: 1/6 tags: width: 1/6 ``` ##### Value By default, the table cells contain the field value matching the column name. You can customize the value with a string template. ```yaml layout: table columns: date: label: Date value: "on {{ page.date.toDate('d.m.Y') }}" type: text ``` If the page actually has a `date` field of type `date`, Kirby will automatically use the date field preview component for this column. However, this will clash with your custom value. This is why we also set `type: text`. ##### HTML Values are converted to safe HTML by default. This is the most secure way to handle content in your Panel. If you know what you are doing and you want to render HTML in a table cell, you can use the html option to stop HTML from being auto-encoded. ```yaml layout: table columns: html: label: HTML type: html value: "{{ page.someSafeHTML }}" ``` ##### Mobile Set the `mobile` option to `true` for a column to be visible in the mobile view. ```yaml layout: table columns: subheading: label: Subheading mobile: true ``` ##### Type To display different content, you can use column types to improve the preview of your data, e.g. `text`, `url`, `tags`. Check out the [field previews in our Lab](https://lab.getkirby.com/public/lab/components/fieldpreviews/array) to get an overview of the various previews that can be used as column types. ##### Customizing default columns ```yaml layout: table info: "{{ page.slug }}" columns: title: label: Custom title label info: label: Custom slug label width: 10rem ``` ## Page information You can fine-tune the display text and additional information for every page in the list with the `text` and `info` options. ### `text` By default the page title is shown in the list for every page. You can use our template syntax with query language to fetch any information from the page and display that instead of the title. ```yaml text: " {{ page.title.upper }}" ``` ### `info` If you want to display additional information for each page, like a date, year, category or any other field value, you can use the template syntax with query language in the `info` option. ```yaml info: " {{ page.date.toDate('Y-m-d') }}" ``` ## Preview images The (preview) image for each item in the list is by default what is configured in the respective page blueprint. However, you can customize these further for your section with the same options as in the page blueprint: ```yaml type: pages image: query: page.cover.toFile icon: 📝 back: blue-700 color: white cover: true ``` ## Empty state With the `empty` option you can define the message which is displayed when no pages are listed in the section. ```yaml empty: No articles yet ``` ## Filtering pages ### Parent By default, the current page is being used as the parent to find children for the list. With this option, any page on your site can be the parent of the section ```yaml parent: site.find("blog") ``` ### `query` The pages section supports a query option to filter the pages that are shown in a section using our query string syntax. Manual sorting will be disabled for sections with a query. ```yaml videoPosts: type: pages label: Video posts query: page.childrenAndDrafts.filterBy('category', 'video') template: article otherPosts: type: pages label: Other posts query: page.childrenAndDrafts.filterBy('category', '!=', 'video') template: article ``` The query option cannot only be used in the context of a single page, but you can also query the complete site index if that makes sense, for example in `site.yml`: ```yaml siteIndex: type: pages query: site.index(true).notIn(['error']) create: default ``` ### Status You can filter the list of pages by their status. The available status values are | Status | Description | | - | - | | `draft` | Only drafts will be shown | | `listed` | Only listed pages (with a sorting number) will be shown | | `unlisted` | Only unlisted pages (without a sorting number) will be shown | | `published` | Listed and unlisted pages will be shown | | `all (default)` | Drafts, listed and unlisted pages will be shown | ```yaml status: draft ``` Note that an "Add" button for new pages will only be available if you use either `status: draft` or `status: all`. ### Templates You can define a list of templates that will be available when adding new pages to the section. It will also be used to filter pages to be contained in the list. #### Single template ```yaml template: article ``` #### Multiple templates ```yaml templates: - project - article ``` If only one template is available when [adding a new page](#add-button), the template select will be hidden in the dialog (except when the [`debug` option](/docs/reference/system/options/debug) is active). ## "Add" button Editors can add new pages to the section with the "Add" button in the top right corner. | `status: all` | `status: draft` | `status: listed` | `status: unlisted` | | - | - | - | - | | + Add | + Add | | | The add button will only show up if the status option is set to `draft` or `all` ### Why? New pages are always added as draft. If the "Add" button showed up in sections that only show listed or unlisted pages, the "Add" button would lead to a confusing interaction for editors, as the new page would not show up in the section. ## Batch delete pages When managing many pages, it can be tedious to delete them one by one. Adding `batch: true`, allows you to select multiple pages and delete them at once. ```yml notes: type: pages batch: true ``` ## Sorting ### `sortBy` You can sort the list of pages by one or more fields/properties in descending or ascending order. ```yaml sortBy: date desc sortBy: date desc title asc sortBy: status desc year desc ``` You can pass PHP sorting type flags, for example to make sorting work with special language specific characters. ```yaml sortBy: title SORT_LOCALE_STRING sortBy: title asc SORT_LOCALE_STRING ``` The `sortBy` option only has an effect on the display order inside this section in the Panel. Because all pages will always be sorted by the field/property you defined, manual drag and drop sorting inside the section is disabled. However each page can still have its own sorting number, which can be controlled via the page status dialog. If you don't need or want the custom sorting numbers, you need to disable them with the `num` option of the child page blueprint. ### `flip` Use the `flip` option to enable/disable reverse sorting (default is `false`): ```yaml sortBy: title flip: true ``` ### `sortable` You can switch off manual sorting entirely with the `sortable` option. ```yaml sortable: false ``` ## Limits ### `limit` The limit property sets how many pages will be shown per page. If there are more entries in the section, the pagination navigation will be shown at the bottom of the section. ```yaml limit: 20 ``` ### `max` You can define a maximum number of pages, that will be allowed in this section. After the maximum is reached, the add button will be hidden and no more pages can be added. ```yaml max: 10 ``` ### `min` You can also define the minimum number of pages, that need to be added in order to make the page valid. ```yaml min: 2 ```

Conditional sections

Like conditional fields, sections can be shown/hidden based on the value of a given field (i.e. if a toggle is checked, a select field is at a certain option, etc.).

The condition for displaying the section is set with the when option. In the when option you define a field name as the key and the required value of that field. In the following example, the each section type is shown based on a different value of the postType field:

sections:
  content:
    type: fields
    fields:
      postType:
        type: select
        options:
          - Gallery
          - Image
          - Text
  gallery:
    type: files
    template: gallery-image
    layout: cards
    size: tiny
    when:
      postType: Gallery
  image:
    type: files
    template: single-image
    max: 1
    layout: cards
    when:
      postType: Image
  text:
    type: fields
    fields:
      text:
        type: textarea
      tags:
        type: tags
    when:
      postType: Text
## Search
Section search is disabled by default. You can use the `search` option to enable it. ```yaml sections: drafts: type: pages search: true ``` (screencast: https://youtu.be/rC9Up05WVnI poster: youtube-bookmarks.jpg title: Build a bookmark tool text: An example how to build a nice overview with the table layout in the pages section showing all relevant columns.)