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.
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.
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 |
---|---|
extension |
comma-separated string or array |
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 |
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
...
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.
Since 4.0.0
En-/disable setting focus in Panel
By default, setting the focus point in the Panel is enabled for all viewable images with a Panel preview and disabled for all other files.
When a focus point is set, it will be used automatically when you crop an image.
You can change this via the focus
option in the file's blueprint:
focus: false
Since 4.0.0
Optimize uploaded images: create
In your file blueprints you can set resize and crop settings, which will be applied directly after the upload. This is great to avoid huge original files in the content folder.
title: Image
create:
width: 500
height: 500
crop: true
Convert image formats on upload
The create
option also allows you to define a target image format. Images uploaded in other formats (e.g. .jpg
or .png
) will be converted to the target format right after the upload.
create:
format: webp
If the file blueprint also accept non-image files, those will be skipped and their format/extension left untouched.
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
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
ratio
A freely selectable image ratio
image:
ratio: 16/9
Examples
You are not limited to the example ratios above. In fact, Kirby calculates the ratio for you as long as you enter it in the format a/b
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 |
---|---|
changeName |
true /false |
changeTemplate |
true /false since v4.0.0 |
delete |
true /false |
read |
true /false |
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
Since 4.0.0
Controlling accessibility for roles.
# 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.