Skip to content

Kirby 3.6.1

File blueprint

File blueprints are located in /site/blueprints/files and control the Panel setup and form fields for individual file types.

In each files section you can use the template option to determine which template will be used for each file within that section. For example, you can create a files section to which users can only upload images and which have a given set of fields, and another section for PDF files with another set of fields.

Blueprint location

  • /site/blueprints/files

Default file blueprint

To create the same set of fields for all file types, you can setup a default.yml that is used whenever no custom file template is configured.

  • /site/blueprints/files/default.yml

Title

The title is required. It will appear in the file view to indicate the selected template for the current file.

title: Project Image

Translated titles

The title can be translated by passing an array of translations with the matching language code as key:

title:
    en: Project Image
    de: Projekt Bild

Accept

The accept option defines a set of rules which should be validated whenever a file with this type is created. This is perfect to allow only certain MIME types or file extensions, or check for the file size and the image dimensions.

The accept option can either be a simple string for a list of accepted MIME types, or an array of multiple accept validation rules:

Simple

accept: image/jpeg, image/png

Extended

accept:
    extension: jpg, png
    maxheight: 200
    orientation: landscape
Option Value Added in
extension comma-separated string or array Kirby 3.5.0
mime e.g. image/jpeg, comma-separated or array
maxheight int in px
maxsize int in bytes
maxwidth int in px
minheight int in px
minsize int in bytes
minwidth int in px
orientation landscape/square/portrait
type comma-separated string or array Kirby 3.5.0

You can combine the extension, mime and type checks. If more than one of these three options is set, all constraints need to match for a file to be valid.

If you don't set the mime option, the valid MIME types for the frontend upload input are auto-detected from the configured extension or type options. You can however override this behavior by setting the mime option as well, for example to define MIME types that are compatible with all browsers while still protecting the uploads based on the extension and/or file type:

accept:
    mime: image/*
    type: image

In this example, Kirby will generate a file upload input with an accept="image/*" attribute and will then validate both the MIME type and the detected file type on the server after the file is uploaded.

If no type restrictions (extension, mime or type) are defined in the file blueprint, Kirby will limit the accepted uploads to the types image, document, archive, audio and video by default. This protects your site against unexpected uploads like code files that could be used to attack the server or the visitors' browsers.

You can disable the automatic types and allow all uploads like this:

accept: true

# or:
accept:
    mime: null
    orientation: square
    ...

Please only allow all uploads if all Panel users can be trusted completely as it will be possible to upload files that could be used to attack the server or the visitors' browsers.

Image options

Since 3.6.0

The image options for files can now be defined directly in their own blueprint. This significantly simplifies the setup of sections as they all inherit the image settings. You can still set image settings in sections the good old way if needed.

site/blueprints/files/document.yml
image:
  back: blue-200
  icon: 📝

Support for queries

Panel preview image options now all support our powerful queries:

site/blueprints/files/document.yml
image:
  back: "{{ file.myCustomBackColor }}"

Custom colors

back and color options for Panel preview images now support shorthands for core CSS color variables as well as HEX codes or other native CSS color properties (e.g. even gradients):

CSS color property shorthands

image:
  back: "purple-400"

Check out the list of our color properties for available options.

Hex codes

image:
  back: "#ff0000"

CSS rules

image:
  back: "linear-gradient(90deg, rgba(2,0,36,1) 0%, rgba(9,9,121,1) 35%, rgba(0,212,255,1) 100%);"

Options

With options, you can control all the file actions that should or should not be available for this particular file type. The option dropdown for files will adjust accordingly.

Option Value Added in
changeName true/false
delete true/false
read true/false Kirby 3.4.0
replace true/false
update true/false

Each option can be set on a per user role for fine-grained permissions, for example:

options:
  delete:
    admin: true
    editor: false

Or using a wildcard to change the default for all roles:

options:
  update:
    *: false
    editor: true

Examples

You can find examples of file blueprints in the samples section.