File blueprint

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

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.

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

You can combine the extension, mime and type checks. If a mime type is specified, the extension and type options are ignored for the browser. Extensions and types, however, are still used to validate an uploaded file on the server. 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 as well as the default Kirby file types. If the intersection is empty, an empty string is used for the accept attribute in the uploader.

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.

Allow all file types

If you want to allow the upload of any file type (including code files), you can disable Kirby's default upload type restriction like this:

accept: true

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

focus: false

title: Image
create:
  width: 500
  height: 500
  crop: true

create:
  format: webp

image options

The (preview) image blueprint option defines how any page with this blueprint will be presented, e.g. in a files section.

back

Sets the image background.

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

Examples

back: pattern	back: black	back: white

Custom colors

The back and color options for also support shorthands for the core CSS color variables as well as HEX codes or other native CSS color properties (e.g. even gradients).

image:
  back: "purple-400"

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

image:
  back: "#ff0000"

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

Support for queries

This option also support our powerful queries:

image:
  back: "{{ file.myCustomBackColor }}"

color

Sets the icon color.

image:
  query: false
  color: red-200

cover

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

image:
  cover: true

Examples

cover: true	cover: false

ratio

A freely selectable image ratio

image:
  ratio: 16/9

Examples

ratio: 2/3	ratio: 1/1	ratio: 3/2	ratio: 16/9

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.

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

# Page is not accessible and not visible for all roles except admins.
options:
  access:
    *: false
    admin: true
  list:
    *: false
    admin: true

Examples

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