# File blueprint File blueprints are located in `/site/blueprints/files` and control the Panel setup and form fields for individual file types. **** - Read more: **** 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 ```filesystem /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. ```filesystem /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. ```yaml title: Project Image ``` ### Translated titles The title can be translated by passing an array of translations with the matching language code as key: ```yaml 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 ```yaml accept: image/jpeg, image/png ``` ### Extended ```yaml 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: ```yaml 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: ```yaml 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. ## 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: ```yaml "site/blueprints/files/image.yml" focus: false ``` ## 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. ```yaml "site/blueprints/files/image.yml" 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. ```yaml "site/blueprints/files/image.yml" create: format: webp ``` If the file blueprint also accept non-image files, those will be skipped and their format/extension left untouched. ### Strip image metadata Image files can (and often do) carry so called EXIF metadata such as the date and time the image was taken, the camera make and model and the GPS geolocation. Especially the geolocation can be considered personal data and can be a risk to vulnerable individuals when published online. If the `create` option is enabled with any configuration, all newly uploaded images are passed through Kirby's thumb engine, which strips all metadata by default. If you only need the metadata stripping, you can enable it like so: ```yaml "site/blueprints/files/image.yml" create: strip: true ``` Please keep in mind that it is *not* possible to disable the stripping by setting the option to `false`. We will add this option in the future to add more control e.g. for use cases where you intend to work with the EXIF data on the site but still want to set other options to convert the format or reduce the image dimensions. ## `image` options The (preview) `image` blueprint option defines how any file with this blueprint will be presented, e.g. in a files section. ### `back` Sets the image background. ```yaml image: 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). ```yaml image: back: "purple-400" ``` Check out the list of our color properties for available options. ```yaml image: back: "#ff0000" ``` ```yaml 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: ```yaml image: back: "{{ file.myCustomBackColor }}" ``` ### `color` Sets the icon color. ```yaml image: query: false color: red-200 ``` ### `cover` Whether or not the image will cover the available space. Options: `true`, `false (default)` ```yaml image: cover: true ``` #### Examples | `cover: true` | `cover: false` | | - | - | |

| ### `ratio` A freely selectable image ratio ```yaml image: ratio: 16/9 ``` #### Examples | `ratio: 2/3` | `ratio: 1/1` | `ratio: 3/2` | `ratio: 16/9` | | - | - | - | - | |

| 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`** ### `query` Query an image to show as preview, for example, another version of the image, or a preview image for a PDF or video file. ```yaml image: query: page.images.findBy("name", "preview") cover: true ratio: 1/1 back: black ``` ## 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` | | `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

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

Since 5.0.0

View buttons

Kirby allows you to define what buttons to use for this file. To select which (default) buttons to show on a particular view you can set the buttons option in the corresponding blueprint:

buttons:
  settings: true

By setting the value to true, you can reference existing buttons (from the core or config.php file or even Panel area plugin extensions) by name and decide which ones to include and in what order.

Create a new button

You can now also define your own custom buttons directly in a blueprint:

buttons:
  settings: true
  social:
    icon: mastodon
    text: Mastodon
    link: "https://mastodon.social/@getkirby"
    theme: purple-icon

The available options are based on the k-view-button component. Check out the config option documentation for more details, e.g. in regard to available attributes or query support.

Disable all buttons

buttons: false

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