Creating a single child page: Pages section or Pages field?

Kirby 3 Solved ✅
1

Hi there! This might be simple and maybe I’m just tired right now, but no harm in asking.

I’m building the blueprints for a site where some pages (let’s say a product page) needs to have an image gallery. Galleries for these products tend to be large: 20 to 50 images.

I’m a bit reluctant to have all those images as files of the product page itself. Main reasons:

  • Using a Section of type files could be awkward, because products also have a primary “cover” image, so I would need to filter out that specific image based on what is selected in another field in the page.
  • Using a Field of type files to represent the image gallery in the panel: then the full list of images uploaded in the page’s folder is not visible to editors, and this can lead to stale images accumulating as editors upload images and then remove them from the files field (which doesn’t remove the files themselves).

I think it might be more manageable if I create one of several child pages using a gallery template. The structure would look like:

products/
    some-product/
        product.txt
        cover.jpg
        gallery/
            gallery.txt
            image-1.jpg
            image-2.jpg

I’m just not sure how to represent the product’s gallery (or galleries) in the panel page for the product.

  • I can use a Section of type pages to list child pages with the template gallery, and allow creating new ones.

    • Pros: It works great.
    • Cons: I wanted to have this UI in a column, and I’m not finding a way to put a section in a column.

  • I can use a Field of type pages.

    • Pros: easy to fit in a column.
    • Cons: by default it shows me a page picker with the full site index, and I don’t know how to restrict to child pages. What’s more, when clicking the Add button, it shows the same page navigator with the full page index, and I don’t know how to tell it to create the page as a child of the current page.

Is there a way to put a Section in a column? Or to make a files Field act more like a files Section?

2

I found an answer in this topic: Is it possible to nest a column within a column? - #2 by texnixe

It is possible to have sections in a column. My mistake was doing something like this:

columns:
  sidebar:
    fields:
      # Config for the fields
      # …
    sections:
      gallery:
        type: pages
        # Config for the pages section
        # …

Turns out that when you use a fields key in a column, that’s a shortcut for creating a sections structure with an entry of type fields. When you want to have both fields and non-fields sections in a column, you need to be more explicit and declare everything as sections:

columns:
  sidebar:
    sections:
      stuff:
        type: fields
        # config for the fields section
        # …
      gallery:
        type: pages
        # config for the pages section
        # …

So that makes sense.

If I’m allowed a tiny rant: maybe that’s the programmer in me, and others have different preferences, but I wish Kirby didn’t have so many shortcuts in its Blueprint parsing (like deriving the section type from keys, optional sections key…). Because when the implicit conditions for using a shortcut are not met, then everything breaks and you don’t get an error or any guidance.

3

I agree these shortcuts can be confusing, but they were introduced based on user feedback, because to some users it seemed kind of redundant to have:

sections:
  fields:
    type: fields
    fields:
      #....
4

It’s always the tension, when experts want shortcuts to work faster but newcomers need explicit APIs to understand what they’re doing.

That tension could be lessened somewhat with something like Blueprint validation, so that you know when you’ve used the shortcut wrong.

My other suggestion would be to change the Blueprint samples to not use shortcuts, only the longform YAML configs. I lost hours because I copy-pasted bits of those samples and understood them as defining fields, when the bits I had copied were defining sections. If those samples had used the longform configs, I would have learned the difference between fields and sections much faster.

1 Like
5

What exactly are you referring to? Where do these use shortcuts?

6

A few I found:

Blog example

  1. /site/blueprints/pages/article.yml uses an implicit fields section in the main column.

Events example

  1. /site/blueprints/pages/event.yml uses an implicit fields section (“fields” key at the root)

Portfolio example

  1. /site/blueprints/pages/projects.yml uses implicit sections (“drafts” and “listed” keys at the root)
  2. /site/blueprints/pages/project.yml uses an implicit fields section (“fields” key at the root)
  3. /site/blueprints/pages/project.yml uses a sidebar key at the root, with implicit sections (“cover” and “gallery” keys). Also I think having a sidebar key at the root which is not a section with a type currently breaks in Kirby 3? Might be a leftover from Kirby 2?

Shop example

  1. /site/blueprints/pages/shop.yml uses implicit sections (“drafts” and “listed” keys at the root, which inherit a type: pages property).
  2. /site/blueprints/pages/product.yml uses an implicit fields section, plus a sidebar section which I think is not compatible with Kirby 3 (I think it broke when I tried to copy-paste it in a page blueprint)?

Team example

  1. /site/blueprints/layouts/default.yml uses an implicit fields section in the “content” tab.
  2. /site/blueprints/pages/team-member.yml uses an implicit fields section.
  3. /site/blueprints/pages/team-member.yml uses a sidebar key at the root, which I think doesn’t work in Kirby 3? (It broken when I copy-pasted this example.) That also uses an implicit fields section.
7

Ok, thanks, @fvsch!

8

But, at the root level, it is not necessary to use sections, so the fields key at the root and even within columns is absolutely fine in my opinion, and I’m rather reluctant to change those occurrences. In fact, the fields key at the root was the same in Kirby 2 before there were even any sections. To use sections for these basic examples would only complicate the blueprints.

9

Well, I’ve shared my difficulties and my opinion. Could be that others don’t run into the same issues and I’m an outlier.

10

I seriously doubt that :). Blueprints are really powerful, but all the different options can get confusing at times, I fully understand that.

The basic rule is like this:

  1. If you have only fields within a layout unit (root, tab, column), you don’t need sections.
  2. If you want to mix fields and sections (pages section, files section, info section) in a layout unit (root, tab, column), you need to wrap your fields in a fields section.
1 Like