Files

Example page with files

/content/projects/project-a
/content/projects/project-a/project.txt
/content/projects/project-a/image-1.jpg
/content/projects/project-a/image-2.jpg
/content/projects/project-a/image-3.jpg
/content/projects/project-a/project-info.pdf
/content/projects/project-a/project-data.xls
/content/projects/project-a/some-video.mp4

Supported file types

You can access the page's files using handy methods for each common file type:

Type	Extensions	API Method
Audio	aif, aiff, m4a, midi, mp3, wav	`$page->audio()`
Code	css, js, json, java, htm, html, php, rb, py, scss, xml, yaml, yml	`$page->code()`
Documents	csv, doc, docx, dotx, indd, md, mdown, pdf, ppt, pptx, rtf, txt, xl, xls, xlsx, xltx	`$page->documents()`
Images	ai, avif, bmp, gif, eps, ico, j2k, jp2, jpeg, jpg, jpe, png, ps, psd, svg, tif, tiff, webp	`$page->images()`
Videos	avi, flv, m4v, mov, movie, mpe, mpg, mp4, ogg, ogv, swf, webm	`$page->videos()`

Other file types are of course also supported.

When you are using .txt files for your content (as it is the default), you cannot upload other .txt files as they will be mistaken for content files. You can configure this via the content.extension config option.

Site files

Files cannot only be uploaded to a page, but also to the site object, i.e. directly into the /content folder. To upload images to the site object in the Panel, you have to create a files section in the site.yml blueprint.

Manually uploading files

You can add/upload files to a page manually by placing it into the corresponding page folder.

Note that if you upload files to a page and want to use them later in the Panel, you have to define files sections in your blueprints. Otherwise, these files will not show up.

Uploading files via the Panel

You can upload files via the Panel to pages that allow file uploads. To upload a file in the Panel, click on the Add button above the files section and select a file from your file system. If the file validates, it will be uploaded.

Linking to files in your content

Files can be linked or embedded in any field with KirbyTags or used in templates to build complex galeries, download sections, etc.

Rendering files in your templates

Kirby provides many ways to render files in your templates. Here are some examples:

Fetching all images of a page

<?php foreach($page->images() as $file): ?>
    <img src="<?= $file->url() ?>">
<?php endforeach ?>

Fetching a single file

<?php if($file = $page->file()): ?>
<?= $file->filename() ?>
<?php endif ?>

Fetching files from site

<?php foreach($site->images() as $file): ?>
    <img src="<?= $file->url() ?>">
<?php endforeach ?>

Fetching all images from subpages

<?php foreach($page->children()->images() as $file): ?>
    <img src="<?= $file->url() ?>">
<?php endforeach ?>

Filter images by template

<?php foreach($page->images()->template('gallery') as $file): ?>
    <img src="<?= $file->url() ?>">
<?php endforeach ?>

These are just some basic examples to give you an idea. You can filter and find files by type, template, by their meta data etc. More information on the available file and files methods in the Reference.

The default sorting order of files is based on their order in the file system. To retrieve files in the order they appear in the Panel, you can use $files->sortBy('sort'), where sort is the field that stores the sorting number from the Panel.

Adding meta data to your files

A meta data file is stored next to the file and named after the following pattern:

{filename}.txt

Some examples:

Media file	Meta data file
lake.jpg	lake.jpg.txt
infosheet.pdf	infosheet.pdf.txt
numbers.xls	numbers.xls.txt

Meta data files follow the same scheme for fields like the main text files for pages. Like with pages, the number of fields is not limited. The possibilities to add meta data to files are endless.

Example meta data file

lake.jpg.txt

Title: A day at the lake
----
Caption: We spent an entire day at the lake. The weather was nice.
----
Photographer: Ansel Adams' cat

Meta data files are automatically added or deleted when the associated file is added or deleted via the Panel.

When you delete a file manually from the file system, be sure to delete its meta data file, too, otherwise Kirby will not find the right blueprint/template and the page will not render properly.

Accessing meta data in templates

Meta data is available from each $file object in your templates and snippets.

project.php

<?php if($file = $page->image('lake.jpg')): ?>
  <figure>
    <img src="<?= $file->url() ?>" alt="<?= $file->title() ?>">
    <figcaption>
      <span class="caption">
        <?= $file->caption() ?>
      </span>
      <span class="photographer">
        <?= $file->photographer() ?>
      </span>
    </figcaption>
  </figure>
<?php endif ?>

Meta data blueprints for the Panel

Meta data fields for files to be used in the Panel are defined in file blueprints. They are stored in /site/blueprints/files.

Meta data blueprints are assigned to a files section using the template option.

A typical files blueprint looks like this:

title: Image

accept:
  mime: image/jpeg, image/png, image/svg+xml

fields:
  alt:
    label: Alt Text
    type: text
    width: 1/2
    required: true
  link:
    label: Link
    type: url
    width: 1/2
  caption:
    label: Caption
    type: textarea