Image sorting does not work

I’m using the current Kirby release and am trying to create a simple gallery. However, when attempting to sort via

$gallery = $page->images()->filterBy("template", "gallery")->sortBy("sort");

the resulting order is not as manually set in the panel. Having read this issue, I found out that the sort order should be stored in the metadata file. It is not, however. I’m using a file blueprint called “gallery” for adding a caption field.

My understanding is that the “sort” entry should be added automatically by Kirby. Despite having manually sorted and saved the changes, the only data in the image metadata .txt files is

Caption: Some text here

----

Template: gallery

The panel however does keep the order, even when refreshing the browser. Apparently the order is saved elsewhere. In the page file, as it appears. However, this way the sorting in the panel and in the output are entirely different.

What am I missing?

The sort entry is indeed added to the file metadata text file when you sort files in a files section. Could you please post you blueprint? Maybe you are using a files field instead of a section?

Here you go:

title: Photographer
preset: page

status:
  draft: Draft
  listed: Published

fields:
  type:
    type: text
    width: 1/2
    required: true
  area:
    type: text
    width: 1/2
    required: true
  gallery:
    type: files
    template: gallery
    uploads: gallery
    info: "{{ file.dimensions }}"

sidebar:
  cover:
    type: files
    headline: Cover
    layout: cards
    template: cover
    uploads: cover
    min: 1
    max: 1
    image:
      ratio: 425/600
      cover: true
    info: "{{ file.dimensions }}"

I don’t understand what you mean by “section”. I followed the samples in the Kirby docs to get to this blueprint.

Ok, it’s as I thought:

gallery in your blueprint is a files field. It’s like a select field, but particularly for files. The filename of each file that you select there is stored in the page content file, and their sorting depends not on the sort field (which doesn’t exist in this case) but on the order in which they are stored in the select field.

However, you are not fetching the files that are stored in that field, but all image with the template “gallery” from the page, no matter if they are stored in your field or not.

To fetch only the files that are stored in your gallery field, you have to fetch the field value and convert it into a files collection using the toFiles() field method:

$files = $page->gallery()->toFiles();
if ( $files->isNotEmpty() ) :
  foreach ( $files as $file ) {
  // do something with file
  }
endif;

Sorting number are only applied via a files section, in your blueprint cover is files section, not a files field. A section does not store anything in your page content. If you had more than one file in this cover section, you could sort the files, whereupon a sorting number would be stored in the file meta data.

See also: https://getkirby.com/docs/cookbook/setup/kirby-in-a-nutshell#sections-or-fields

Thanks. But adapting to your PHP code does not change anything. The sorting is still not as in the panel. So I guess I need to add a section.

Why is there not a single mention of sections and their importance in the blueprint documentation? I would expect any sorting that is applied in the panel to be reflected in the output by default. Otherwise, what’s the point of being able to sort?

Indeed, after I changed the blueprint as follows

title: Photographer
preset: page

status:
  draft: Draft
  listed: Published

sections:
  meta:
    type: fields
    fields:
      type:
        type: text
        width: 1/2
        required: true
      area:
        type: text
        width: 1/2
        required: true
  gallery:
    type: files
    template: gallery
    uploads: gallery
    info: "{{ file.dimensions }}"

sidebar:
  cover:
    type: files
    headline: Cover
    layout: cards
    template: cover
    uploads: cover
    min: 1
    max: 1
    image:
      ratio: 425/600
      cover: true
    info: "{{ file.dimensions }}"

the sort entry gets written to the metadata text file and sorting works as expected.

Thanks for pointing me in the right direction. However, this is highly confusing and not at all clear for a newcomer. The documentation really isn’t explicit about this when I think it probably should be very much so.

Additionally, it’s rather misleading that the portfolio sample shows the gallery in sidebar, which, as I understand it, is a section in itself. Then again, it uses just fields. Then again, a sidebar is a special kind of section. This does so much unexplained “magic” it really only makes sense after you already mastered Kirby’s structure.

In a page preset, the sidebar is a column, not a section. But the way you’ve set it up doesn’t really make sense.

A page preset only has fields and the sidebar, with the fields in the main column that is created automatically and the sidebar, which is a named column.

I understand it can be confusing, I personally never use the presets unless I really need a standard setup. It needs a while to completely get it, but in return you get a very flexible setup.

Thanks again. How about an example of a correctly implemented version of my blueprint? I worked off the samples to get something off the ground, as I suppose most new users do. It would be helpful to have those thoroughly annotated and explained or better yet, to start with something way simpler. As you see, it’s easy to get it somehow working but not quite right because you don’t know about the magic requirements.

I’m used to work off documentation. Yours is alright for looking up stuff but not really suited for learning something actionable right away. Starting off, I don’t care about layouts, sections and their special meanings. I just need a minimal example that works, some pointers and will expand from there on my own.

I hope this makes sense to you, as you’re clearly highly proficient in Kirby’s ways. On the other hand, I’m a senior-level developer writing web software for 15+ years now and didn’t get it by reading the available documentation.