# Files section List, edit and upload files **** - Read more: - Source: **** The files section can be used to show any combination of files for the current page, any other page in your site or even all files of your site. Using a files section, you can execute the following operations on files (if not forbidden or impossible because of other settings): - upload files - replace a file - delete a file - rename a file - change the order number of files (if sorted manually) - change the template of a file
## Example ```yaml "/site/blueprints/pages/project.yml" title: Project sections: gallery: label: Gallery type: files template: gallery ``` ## Section shortcuts For simple sections that are only used once per blueprint, you can use shortcuts. In its most basic form, a `files` section consists of the section type as name, and `true` as its value. ```yaml sections: files: true ``` This will add a `files` section with all default properties. These shortcuts can be extended with other section properties as needed, for example: ```yaml sections: files: label: My Files template: cover ``` Keep in mind that the same section name can only be used once per blueprint. ## Section properties The files section has multiple options to control what kind of files should be displayed, how they should be displayed and what happens if a new file is uploaded.
Name Type Default Description
batch bool false Activates the batch delete option for the section
columns array null Columns config for layout: table
create bool true Option to switch off the upload button
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
template string null Filters all files by template and also sets the template, which will be used for all uploads
text mixed '{{ file.filename }}' Setup for the main text in the list or cards. By default this will display the filename.
## Label The label will be displayed above the files section. You can pass a simple headline as a string or you can provide translations for multiple languages, if you have an international editing team. ### Single language ```yaml label: Gallery ``` ### Multiple languages ```yaml label: en: Gallery de: Galerie es: Galería ``` ### Placeholders You can inject information from the current page into the label with template placeholders using our query language. ```yaml label: "{{ page.title }} Gallery" ``` ## Upload button You can disable the upload button in a files section with the `create` option. This is useful for query-based sections where uploads wouldn't show up in the list. ```yaml files: type: files query: page.files create: false ``` ## Layout The files 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 file types without thumbnails like PDFs, excel files, or any other docs. It can also be quite helpful for long galleries that would take up too much space as cards. ```yaml layout: list ```
### Cards layout The `card` layout is great for all kinds of images. ```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: alt: true dimensions: true ``` Each column can be customized with additional settings: ##### Label ```yaml layout: table columns: alt: label: Alt Text ``` ##### Translated label ```yaml layout: table columns: alt: label: en: Alternative Text de: Alternativ Text ``` ##### Alignment Text alignment can be left (default), center or right. ```yaml layout: table columns: dimensions: label: Dimensions align: right ``` ##### Width The column width can be set via the `width` property. You can use the usual fractions: ```yaml layout: table columns: dimensions: label: Dimensions 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: "{{ file.date.toDate('d.m.Y') }}" ``` ##### 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 html: true value: "{{ file.someSafeHTML }}" ``` ##### Mobile Set the `mobile` option to `true` for a column to be visible in the mobile view. ```yaml layout: table columns: alt: label: Alt mobile: true ``` ##### Type So far we offer three different column types, you can use to improve the preview of your data. | type | description | | - | - | | `text` | This is the standard column type | | `url` | If the value is a URL, you can convert the value to a link with this type | | `tags` | If the value is a comma-separated list of values or an array, you can use this type to show the value as tags. | ## File information You can fine-tune the display text and additional information for every file in the list with the `text` and `info` options. ### `text` By default the filename is shown in the list for every file. You can use our template syntax with query language to fetch any information from the file and display that instead of the filename. ```yaml text: "{{ file.alt }}" ``` ### `info` If you want to display additional information for each file, like a caption, category or any other field value, you can use the template syntax with query language in the `info` option. ```yaml info: "{{ file.dimensions }}" ``` ## Restricting uploads to certain file types If you want to restrict what types of files can be uploaded to the given section, assign a file template using the `template` property. In your file template, set the `accept` option. See the docs about file blueprints. By default, Kirby supports the following files types. To upload file types not supported out of the box by Kirby, you can register new file types with the `fileTypes` extension in a plugin. ## Batch delete files When managing many files, it can be tedious to delete them one by one. Adding `batch: true`, allows you to select multiple files and delete them at once. ```yml gallery: type: files batch: true ``` ## Preview images The (preview) image for each item in the list is by default what is configured in the respective file blueprint. However, you can customize these further for your section with the same options as in the file blueprint: ```yaml type: files image: back: pattern cover: true ``` ## Empty state With the `empty` option you can define the message which is displayed when no files are listed in the section. ```yaml empty: No documents yet ``` ## Filtering files ### `parent` By default, the current page is being used as the parent to find files for the list. With this option, any page on your site can be the parent of the section. ```yaml parent: site.find("galleries") ``` ### `query` The files section supports a query option to filter files using our query string syntax. Manual sorting will be disabled for sections with a query. ```yaml images: type: files label: Images query: page.images template: image documents: type: files label: Documents query: page.documents template: document ``` ### Template You can define which template each file in the list must have. This `template` option will also be applied to any new file that gets uploaded. Blueprints for file templates can be setup in `/site/blueprints/files`. ```yaml template: cover ``` In combination with the `query` property, use the `uploads` option to set the file blueprint that will be assigned at upload. ## Sorting ### `sortBy` You can sort the list of files by a given field in descending or ascending order. ```yaml sortBy: filename desc ``` You can pass PHP sorting type flags, for example to make sorting work with special language specific characters. ```yaml sortBy: filename SORT_LOCALE_STRING sortBy: filename asc SORT_LOCALE_STRING ``` The `sortBy` option will automatically switch off manual sorting. ### `sortable` You can switch off manual sorting entirely with the `sortable` option. ```yaml sortable: false ``` ### `flip` Use the `flip` option to enable/disable reverse sorting (default is `false`): ```yaml sortBy: filename flip: true ``` ## Limits ### `limit` The `limit` property sets how many files 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 files, that will be allowed in this section. After the maximum is reached, the upload button will be hidden and no more files can be uploaded. ```yaml max: 10 ``` ### `min` You can also define the minimum number of files, that need to be added in order to make the parent 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: gallery: type: files search: true ``` ## Fetching files in the frontend Through a section, you upload files to a page, either the current page or another parent page. Contrary to a files field, the file does not become part of the content, i.e. it is not referenced in the content file. If you assign a file template to a particular section, you can filter by this template when fetching files in the frontend. Assuming a files section like the following which uploads images to the current page and assigns a template called `gallery`: ```yaml sections: gallery: type: files template: gallery ``` You can then fetch those files in the frontend like this: ```php images()->template('gallery'); ?> ```