Blueprint: Add Single Image

Good Morning,

I’m stuck and it’s probably super easy but I just can’t wrap my head around the files in blueprints.

I have a meta section in my blueprints with a cover image and a meta image. For each of them the user should just upload a single image, for example the cover image:

        type: files
        headline: Cover Image

in Kirby2 I was able to now simple retreive exactly this image by it’s name “coverImage”:


But when I look at the content file the “coverImage” is empty and I’m not able to retreive the image.

Neither through the documentation nor through the examples I was able to solve this. I think the blueprints and especially the files and the nesting of templates in blueprints etc. needs some work to be easier to grasp.


You are using a section here and a section doesn’t store anything in your content file.

What you need to do here is to assign a template (file blueprint) to this upload section and then fetch the file via the assigned template.

You have to create a file blueprint, and then reference this blueprint in your files section:

  type: files
  headline: Cover Image
  max: 1
  template: cover ## lets call it cover

The template name is stored in the file’s meta data.

Then in your template you can fetch this file like this:

if($coverImage = $page->files()->findBy('template', 'cover')) {
  echo $coverImage->url();

But just to have a complete example: How should the template then look like?

The file template? Can be just anything.

# /site/blueprints/files/cover.yml

title: cover

# optional accept option

accept: image/png

# optional fields

    label: Alt Text
    type: text

See the documentation. It must have a title, the rest can be an empty file if you don’t want to use any metadata

Alright - will try this now. I was just looking at the docs again. I think the confusing part is that there is no mention of templates in the blueprints section but an extra section for templates - I get the difference between templates and blueprint but there is no prominent mention of blueprint templates and how the work and relate to each other.

Haha, yes, the files thingys are called blueprints but the data field that stores it is called template, it’s one and the same thing.

One last question: I’m now able to retreive the image but I’m not able to upload it in the panel, just selecting one that I uploaded previously - is there a way to combine both? I don’t want to force the user to upload images first and then select them.

The you didn’t create an upload section but a field? Please post your complete blueprint.

title: Site
unlisted: true
    label: Pages
    icon: page
      - width: 1/3
            headline: Drafts
            type: pages
            status: draft
              - default
      - width: 1/3
            headline: Unlisted
            type: pages
            status: unlisted
      - width: 1/3
            headline: Listed
            type: pages
            status: listed
    label: Meta 
    icon: tag
        type: fields
            label: Page Owner
            type: users
            label: Page Description
            type: textarea
            maxlength: 150
            size: small
            buttons: false
            type: files
            label: Page Image
            template: metaImage
            max: 1

Oh, yes, that is a files field in a fields section.

The documentation really needs some work: no mention of an “upload section”. If I move the metaImage and make a section out of it I can upload it again but the image won’t get saved in the txt, right? So manual editing is tricky and there needs to be a meta file for the image in order to identify that the image is meant to be a meta image in this case.

That’s what I said above, a files/pages section doesn’t store anything. In that case the template must be stored in the metadata file, yes.

Whoeever designed it that way did’t have the user in mind… upload an image identify it by it’s name, save that name in the txt. What was the intention to design it that way so that I can’t upload a file if the file is a fields instead of an section, maybe it’s me but I can’t see any benefits?

1 Like

In Kirby 2 we had no way of separating different file types into different categories and assign different file blueprints for different meta data. For example, a PDF file would need different metadata than an image file. Also, you can now upload images for a gallery and separate them from other images you want to use for other purposes.

Instead of using different upload sections, you can also have a single general upload section where you upload everything, and then use files fields to select one or more files from the ones that have already been uploaded.

Also, a files field gives you extensive possibilities to filter images, even from all over the site. Adding an add button to such a field would make things very complex. Where should a new image be uploaded in that case? I’m not saying it would be impossible, but would then require an extra upload form where all that information goes into before the file could be stored. Or you would have to define in the blueprint what to do with that file.

I’d also love the option to upload files or create pages from a files/pages field and you can create a custom field with these options.

Totally understandable… but that way the possibility to lets say manage content through dropbox with a simple txt template and all assets in the same folder is not longer as easy as it was. Explaining users that they need to create extra txt files for each asset (wich differ by usecase) is nearly impossible and limits them to use the panel.

To you question where it should go: the same folder you’re currently creating the content.

I actually think that nothing has changed if you don’t use the Panel. The only problem that arises is when you mix using the Panel and not using the Panel. We are still creating content for the website in a text editor without ever using the Panel and nothing whatsoever has changed.

That does only make sense if your files field actually queries files of the current page. But the files in your files field might be from anywhere, maybe the parent, maybe a completely different page. Guess that could also be controlled via a blueprint setting.

There is already an issue in GitHub in the ideas repo:

Don’t make it to complicated: The files field can still query all files - just the upload should be in context of the current page.

I get all the usecases but think there should be a simpler fallback option.

And yes we have mixed users: some of them prefering using the panel and some using synced files.
We use kirby in an internal knowledge base. I need to probably creates something in the template that queries for either or.

E: +1 on that feature request.