README

Automatically assign templates to your uploaded files

⚡ Ready for Kirby 5!

This plugin automatically assigns file templates to your uploaded files, based on the respective file type. This way it does not matter, which file type you upload from which field or section – the template assigned will always be the same. This is especially handy, when you use a single files section per page, that stores all the different file types used on the page.

Important

Requires at least Kirby 4.0 and PHP 8.2

🚀 How to use

Set up your configuration (see next section) first. The plugin will then run after each uploaded file (file.create:after hook) and assign the configured template automatically.

If you add the plugin to an existing project, you can run the auto-templates command from the CLI. It will iterate over every file in every page and assign the template according to the configuration:

$ php vendor/bin/kirby auto-templates

image.png: image
video.mp4: video

> All files updated

By default, existing template assignments will not be touched. To change that, run the command with --force/-f or set the forceOverwrite option globally in your config.php (see below).

⚙️ Config

The plugin works in an opt-in manner: It does nothing except you tell it to.

// site/config/config.php

'presprog.auto-file-templates' => [
  // Do nothing (default)
  'autoAssign' => false,

  // OR automatically assign a file template for every file type
  'autoAssign' => true,

  // OR only assign templates to some file types (ignore file types other than `image` and `video`
  'autoAssign' => [
      'image' => true,
      'video' => true,
  ],

  // OR define a specific template for just some file types and let the plugin decide for the others
  'autoAssign' => [
      'image' => 'my-custom-image-blueprint',
      'video' => true, // => 'video'
  ],

  // OR handle more advanced use-cases in callable yourself (assign different file templates for vector and raster images)
  'autoAssign' => [
      'image' => function(\Kirby\Cms\File $file) {
          return match (F::extension($file->filename())) {
              'svg'   => 'vector',
              default => 'image',
          };
      },
  ],

  // Overwrite existing template assignments (default: false)
  'forceOverwrite' => true,
],

With autoAssign = true, each file type will get the identically named file blueprint assigned as template:

* The Kirby core file types archive, audio, document, image and video and your custom file type extensions are supported out-of-the-box.

💻 How to install

Install this plugin via Composer (recommended):

composer require presprog/kirby-auto-file-templates

Or download the ZIP file from GitHub and unpack it to site/plugins/kirby-auto-file-templates

Or as Git submodule

git submodule add https://github.com/presprog/kirby-auto-file-templates.git site/plugins/auto-file-templates

✅ To do

• Add multi-language support

📄 License

MIT License Copyright © 2025 Present Progressive

Made by Present Progressive for the Kirby community.