Pages section targeting specific folder (not page)

Kirby 3 Questions 🤔
1

We’re trying to create a pages section that lists all pages in a specific folder and allows you to add new pages in that folder. For example:

example/page-one/page.txt
example/page-two/page.txt

As far as I can tell, the only way to do that is to create an index page in the example folder and use that as the parent option in the pages section. However, we don’t need that index page and it has no purpose for this use-case. Is there a way to make a pages section look into a particular folder and add new pages to that folder?

On a related note, we’re looking at ways to create an index page with related child pages. For example, a team page with multiple person pages inside it. For this, we would need a persons section that is relative to the current team page where the section is placed. So if I’m on team-one/team.txt, adding a new person in the persons section should put it in the team-one folder. But if I’m viewing team-two/team.txt, a new person should go into that folder.

How can we specify the parent parameter for the pages section to use the current page the section is placed on?

2

Isn’t that the parent page?

To show children of the current page, you don’t set a parent. But maybe I don’t really understand your use case.

3

@pixelijn

Isn’t that the parent page?

Yes, but we want to have a collection of pages inside a specific folder without a parent page. So we just want example/page-one/page.txt and example/page-two/page.txt, but without having something like example/page-index.txt. The problem I have is that in order to have a pages section (for example, on my site.yml) blueprint where new pages will be added into the example folder, I need to specify a parent. And that parent needs to be a parent and can’t just be a folder. So I need to create the example/page-index.txt just to be able to specify the parent, even though I don’t need that page at all.

4

@pixelijn Thanks, that’s what we were missing! Pretty straightforward when you think about it, but it’s not mentioned in the docs as far as I can tell.

5

A folder is a page, with or without a content txt file.

1 Like
6

@pixelijn Thanks for this information! I thought that only the content files are considered pages by the system, not folders. Not sure this is mentioned anywhere in the docs.

But this means the only way to refer to a folder for the parent parameter in the pages section blueprint is to hardcode the folder name, right? Since there’s no txt file, querying by template is probably not going to work – right? So in this scenario, the pages section would break if someone (accidental or otherwise) renames that folder?

7

That’s true, but on the other hand, there is no reason not to give this parent page a content file you can find it by. In fact, unless you create this folder manually in the file system (which you probably did), the Panel will always create that content file for you.

So, what is your problem with adding a content file?

8

So, what is your problem with adding a content file?

I’m thinking in terms of what does and doesn’t go into version control. We’re currently working on a project template that we’re gonna use for multiple projects. This template is under version control, with the content folder excluded so that new versions of the code can be deployed cleanly without causing merge conflicts in the content folder. This causes a problem with sections that break unless a specific folder (or text file) exists in the content folder. This is why I would like to be able to create a pages section that isn’t tied to a specific page (which may or may not exist in a particular installation of the project), but to a particular folder location. Currently, at least the folder needs to exist, otherwise the section will display a nasty error. I would like a way to tell a section to just display pages in a particular folder, but not error out if that folder doesn’t exist. It could just show an empty list in this case – or create that folder when the section is first displayed, or the first time someone adds a page inside that section.

Anyway, I’m still getting used to how content is structured in Kirby, so I’m grateful for the explanations!

9

As I already explained above, a pages section by default has the current page or the site object as parent.

If you want to show children of a given pages in another location, e.g. show the children of page x in site, then you need to specify a parent. If the parent cannot be found, you get an error.

Don’t know what that is supposed to be?

10

Thanks, yes, I understand that the parent option always needs to resolve to a specific parent page now. My point is that this doesn’t always make sense. In particular, if I want to have a section with pages that represent some data that I’m going to use on other pages, but that won’t have a URL of their own and that don’t require a parent. Currently, I have to create the parent just so that Kirby is happy. It would be nice if I could create a pages section that just says ‘display the pages in that folder, and if that folder doesn’t exist, create it as soon as the first page is added to it’. Maybe this would need to be a separate property to parent, maybe folder or directory. This way, I wouldn’t have to worry about making sure that particular folder exists just so the interface doesn’t break.

I guess this has turned into a feature request, but I wasn’t sure if it was when I opened this thread :slight_smile:

Anyway, thanks for the responses.

11

In particular, if I want to have a section with pages that represent some data that I’m going to use on other pages, but that won’t have a URL of their own and that don’t require a parent .

This doesn’t make much sense to me. Since it’s a pages section, by definition, those are pages, and even if you don’t want to have a parent, they will, by definition, have at least one and that’s the main content folder.

If you want to have some sort of separate content folder used to store extra data the best solution is to create a dedicata parent page that you can call it whatever you want and use that as a main parent.

OR you can just do parent : site and store everything at the top level inside the content folder. But to me that feels messy

12

Yeah, since a folder is considered a page even without a data file (as I have learned in this thread), the only way to have a collection of pages in a dedicated location is to have a parent folder (page). The only thing I disagree with is that the section displays an error if that folder doesn’t exist, instead of just creating it or showing the list as empty. That puts some pressure on the developer to make sure that the target folder always exists on every target environment, which isn’t always easy, as mentioned above.

I understand that this is not possible with the way the parent property works. This could be a query looking for an arbitrary page independent of a specific folder location, so creating a folder if no page could be found is not possible. This is why I proposed introducing an alternative property (like folder) to point a section to a specific folder path instead of an arbitrary query. This way, that folder could be created on the fly if it doesn’t exist, so there’s no chance of a section breaking and displaying an error message just because that specific folder doesn’t exist for any reason.

As I said, this has definitely turned out to be a feature request.

13

I’m still struggling to understand what is your use case.

If what you want is a centralised location where you can always create new pages and be sure that the parent folder is always there, you can already do it by setting up the parent as parent : site

This will store everything inside the /content folder that has to exist otherwise kirby won’t function properly.

If instead you want multiple locations, at different levels, then i don’t see why you can’t use whatever is the current page you’re deling with and use that as a parent page.

This way, that folder could be created on the fly if it doesn’t exist, so there’s no chance of a section breaking and displaying an error message just because that specific folder doesn’t exist for any reason.

Honestly, if this is your concern, the best solution is set up a custom startetkit and always have a /data folder or whatever you want to call it present in there.

Kirby already requires a few things to be always present so you miught as well add this one that solves all your issues.

14

This will store everything inside the /content folder that has to exist otherwise kirby won’t function properly.

Yes, and I don’t want that. I want to have a sensible, hierarchical folder structure, and put specific contents in specific folders.

If instead you want multiple locations, at different levels, then i don’t see why you can’t use whatever is the current page you’re deling with and use that as a parent page.

I want to display this section in the site blueprint, but still have the section display pages from a particular folder. Currently, this is only possible with the parent parameter for the pages section.

Honestly, if this is your concern, the best solution is set up a custom startetkit and always have a /data folder or whatever you want to call it present in there.

Yes, that’s exactly what we’re doing. It’s not quite as straightforward in the context of version control – we have to separate starter/demo contents and ‘live’ contents, so that changes to the live contents don’t cause merge conflicts. We have solved this by creating a content-demo/ folder that gets copied into the content/ folder (if this one doesn’t exist) using a Composer installation hook. This way, we can provide starter content that can be freely changed without conflicting with git.

However, there’s still a chance that a particular folder might be renamed or deleted for any reason, and this will cause an ugly error in the panel that can’t be resolved from within the panel. My suggestion above would allow me to create a more resilient pages section that will work no matter what.

I’m a big fan of separating configuration and content, which is very important if you’re working with version control. Having a piece of configuration (the blueprint) explicitly rely on the presence of a given piece of content (the folder) and break if that piece of content is modified or missing is, in my opinion, an antipattern. As I said, it’s a feature request, and not the most important one. But it would be nice to have.