Global and Local Media Storage in Kirby CMS

Transcript

0:00 · Hello and welcome to moinframe. My name is Justus and today we take a look at the media storage in Kirby CMS. In Kirby, all media files are stored inside each pages folder. A simple concept with huge performance advantages and the concept is perfect for articles or very specific pages. But if you work with images that are frequently used on more than one page, you might need to upload the same image multiple times. At this time, a global media page might come in handy. But having all assets in one page has its disadvantages, too.

0:36 · So, how about we use a combination of local and global media storage? Let's see how we can do it. First of all, I have to give credit to Sebastian from Juno who shared this concept in one of the first Kirby Hamburg meetings. So big shout out for Juno and Sebastian. So first we create a page for our media. Let's call this uh global media.

1:07 · So new folder in our content folder called global media and use the same name for our blueprint. So, global media dot txt. We can set in the title global media just to make it pretty. All right.

1:27 · So, next we need the blueprint and I've added that here for the site pages blueprint and there is global media.l. Um, this is just a default blueprint with one section for images. So right now we are just storing images in the global media file. Um I have added the permissions to make sure that it's not like duplicatable or movable because this side should be a static uh yeah settings side just to hold all the media that is globally available.

1:58 · We also need to take the template output into consideration. And in this case, we don't want the page to be reachable at all because it just stores the media, right? So, we can add a global uh route in our config. Here it is.

2:19 · And this will just uh return 404 for global media. So, the complete route is not available for our um visitors. And the next thing is we want a method to decide whether a specific file field should interact with the global or with the local media pool. So a good way to do this is through a page method in a plug-in. And I have created a plugin inside plugins called project helper. And in here you can see we are extending the page methods with our own method which is called media page.

2:47 · And in here we can define templates or template names which should use the local storage and if it's not in here it will always use the global storage. So for example my notes here in this starter kit I want those to be independent. So all uploaded files for a node should be in the node folder itself. But pages like about should work on a global scale. So now we need to implement this method to let our files fields know this exists in our existing file fields.

3:22 · For example, the cover field here. We need to make sure that this uploads to the correct page. So for uploads, we want to make sure that the parent, so the page it is uploaded to always references the page media page method that will decide whether it's the local or the global storage. And for the query, we also want the media page. So we can say page dot media page. This will give us our storage page. Images template images file. We doing the same for all file fields.

4:01 · So uh for example here I have added it in the uh image block as well. So this query is using the media page and the uploads field is page media page. For easy access to the media page, I have added a little helper here in the panel menu.

4:23 · Um, this is using my plug-in Kirby panel menu and it generates the sidebar for the panel. And in here, I have added our global media page under the label media with the icon images. In the panel, we have our media page right here in the sidebar now.

4:38 · And now, let's up upload some images. going to the about us page and this is using a blog here an image blog and I want to change the image here put in a new image hit upload and since this is the can save and since this is the about us page it's not in the template of note so this should use our global storage and here it is our image so now I can move to another page uh let's say one note remove this here and this should still use the local media folder. So, uploading an image again. Hit upload.

5:16 · And if we click on this image, we can see it's still in the exploring the universe folder. And our media folder has still one image. And that's it for today. Are you already using a different concept for media storage?

5:37 · Share it in the comments. Be sure to leave a like and subscribe. And I will see you next time. Bye.

Kirby's approach to file storage is beautifully simple: every file lives inside its page folder. It's fast, it's clean, and it works great for page-specific content like article images. But when you have images that are used frequently on multiple pages, you end up uploading the same file over and over.

A global media page can fix that, but going fully global has its own downsides. So how about a combination of both? That's exactly what we're looking at today.

This concept was shared by Sebastian from JUNO during one of the first Kirby Meetups in Hamburg. Big shout out to them.

Setting Up the Global Media Page

First, create a new folder in your content directory:

content/globalmedia/globalmedia.txt

Then create a matching blueprint. The blueprint is straightforward, just one section for images:

title: Global Media
options:
   extends: permissions/default
   delete: false
   preview: false
   duplicate: false
   changeStatus: false
   changeSlug: false
   move: false
status:
  unlisted: Published
sections:
  images:
    type: files
    layout: table
    search: true
    size: tiny
    template: image

We lock down the options so editors can't accidentally duplicate or move the page. It's a utility page, not content.

Blocking the Frontend Route

Since this page only stores media, it shouldn't be reachable on the frontend. Add a route to your config.php:

return [
  "routes" => [
    [
      "pattern" => "/globalmedia",
      "method" => "GET",
      "action" => function () {
        return;
      }
    ]
  ]
];

Now visiting /globalmedia returns a 404.

The Page Method: Local or Global?

We need a way to decide, e.g. per template, whether file uploads should go to the page itself or to the global media page.

Create a plugin (e.g. site/plugins/project-helper) and add a page method:

Kirby::plugin('project/helper', [
  'pageMethods' => [
    'mediaPage' => function () {
      $mediaPage = page('globalmedia');
      if (!V::in($this->intendedTemplate(), ['note'])) return $mediaPage ?? $this;
      return $this;
    }
  ]
]);

The idea: templates listed in the array, note in this case, keep their files locally. Everything else uses the global media page. So a note stores its images in its own folder, but a page like "About" pulls from the shared pool.

Wiring Up File Fields

Now update your file fields to use this method. For example, a cover field from the starterkit:

cover:
  type: files
  multiple: false
  query: page.mediaPage.images.template('image')
  uploads:
    parent: page.mediaPage
    template: image

The uploads.parent tells Kirby where to store new uploads, and the query tells the field where to look for existing files. Both point to page.mediaPage, which returns either the page itself or the global media page.

Do the same for image blocks or any other file fields where this applies.

Quick Access in the Panel

For convenience, add the global media page to your panel sidebar. I'm using the Kirby Panel Menu plugin for this, which generates a sidebar menu.

return [
"panel" => [
  "menu" => fn($kirby) => panelMenu($kirby)
    ->site()
    ->page('Media', 'globalmedia', ['icon' => 'images'])
    ->area('users')
    ->area('system')
    ->toArray()
  ]
];

With everything in place, each template gets the storage strategy that makes sense for it.

The beauty of this approach is that you define the rules once in the plugin, and every file field across your site respects them automatically.