Better handling of collections of files and images

Kirby 2 Solved ✅
1

Hi!

There’s one thing about Kirby that always gets me because I expect it to be super easy to do with Kirby’s API, but when I get around to building it, it turns out to be not quite as simple:

Working with collections of files and images, especially across several pages and when they have to be merged.

Today, it took me quite a lot of googling and searching in this forum to figure out how to get a collection of all files in a page, including those of its children (& their children, & theirs…)

It’s extremely easy to get one level of files from a page: $page->files(), and if you want to output files in the order they’re nested, it’s no problem to loop over children (or index) of a page to do this.

But if you’re after a big collection of files that you can filter, search, limit or shuffle independently, there’s not much in Kirby’s API that helps you with that.

Eventually, the following two forum topics helped me finish my task, but the current solution breaks some beloved functions like Kirby’s $files->shuffle() and is not documented outside the forum.

So, to wrap this up: It would be great if dealing with multi-level file/image collections was possible in a more Kirby-ish way. :smile:

Some suggestions:

  • There could be something like $pages->files(), which would return all files from the pages collection. Then it would be easy to get all nested files or images of any page like this: $page->index()->files().
  • Easier merging & adding of collections, for example like so: $images->add($moreImages)

Another note:
The cheatsheet entries for $site->images(), $site->files() etc. are so short that they can easily be mis-understood:

Returns a $files collection with all files in /content

It’s quite easy to wrongly assume this to mean that it returns all files within /content, even those nested in subpages. Obviously it’s not what it does, so a more specific description would be welcome. :grin:

Thanks!

PS: Actually, this should probably extend to pages collections as well. For example, $pages->add() is not in the cheatsheet, and the stuff discussed in Showing all posts from different folders (merging collections) - #8 by texnixe could also be kirbyfied somehow (merge($pages, $morePages)) & would deserve a mention in the cheatsheet.

2

Random wild guess how this could be realized at the moment:

$images = new Collection(a::merge($images->data, $moreImages->data));
3

Thanks, that saves me a foreach loop compared to the previous solution. :smile:

I’d still like to campaign for a solution that’s more in line with the rest of Kirby’s API and can be added to the docs, as I’d imagine it to be a quite common need, and I’m always surprised not to find anything about these things in the cheatsheet.

4

I agree, if we had a way to easily combine collections while preserving sorting, shuffling etc., that would definitely make things a lot easier. :+1:

1 Like
5

What would be a good name for this in the collection class?

public function combine($collection2) {
    $collection = clone $this;
    $collection->data = a::merge($collection->data, $collection2->data);
    return $collection;
  }
1 Like
6

I think we could use merge as the method name to keep it consistent with other Kirby (Toolkit) methods.

7

I’m in for merge as well.

8

Yea, I was a little hesitant, cause merge is used rather as a static method in the toolkit so far.

9

Opened up two PR as ideas for $files->merge($moreFiles) and $pages->files() – not sure if they are really useful though.

1 Like
10

Cool :smile:

Merge sounds good. Will that also work for page collections, or only for files?

11

That would work also for pages collections as it’s a change on the collection class from the toolkit.

12

Awesome, thanks for these! :smile:

They’ll definitely come in handy.

13

…aaand they’ve already been merged / implemented. This is seriously great, I’m looking forward to 2.2!

Thanks again :slight_smile:

1 Like