Kirby's docs explain visible and invisible pages quite nicely. However there is some confusion among Kirby users about the differences between those two types of pages and how to deal with them, especially with the invisible pages.
I'd like to explain the differences and give you a short overview how to deal with the pages using Kirby's API from your templates. You'll see that visible and invisible pages act pretty similarly.
Every page in a Kirby-powered site sits in its own folder. The name of the folder defines the URL slug to access the page.
For instance this blog post resides in a folder named:
This page is a second-level page (there is the blog-level above). That means this page is a child of the blog page/level while the blog is this page's parent. Every other page on the same level is a sibling to this page (as the folder starts with 14 you can assume that there are at least 13 other pages below the blog folder).
Therefore the core concept of Kirby's page visibility involves an attribute named
children(). This attribute returns an array of all pages that are children to the current page whether they are visible or invisible. If the current page doesn't have any children this attribute still exists but it returns an empty array.
In a typical Kirby template one can load all children of the current page using a simple API call:
<ul> <?php foreach($pages->children() as $item): ?> <li><?php echo $item->title() ?></li> <?php endforeach ?> </ul>
There are two additional method calls in Kirby's API,
invisible(). These two methods act like filters to the children attribute:
visible()method filters out all invisible children.
invisible()method filters out all visible children.
To only return visible child pages:
<ul> <?php foreach($pages->children()->visible() as $item): ?> <li><?php echo $item->title() ?></li> <?php endforeach ?> </ul>
To only return invisible child pages:
<ul> <?php foreach($pages->children()->invisible() as $item): ?> <li><?php echo $item->title() ?></li> <?php endforeach ?> </ul>
The simple rule is:
- If the folder starts with a number the page is visible (
- If the folder does not start with a number the page is invisible (
Sorting visible pages
All visible pages somewhere in the "page tree" have a natural sort order: they're sorted alphanumerically using the prepended number from the folder name.
If two or more folders on the same level have the same number prepended to the folder name then the remaining string part of the folder is taken into account.
content/1-about-me content/2-customers content/2-portfolio content/3-contact
Sorting invisible pages
Sorting invisible pages is even simpler: there is not number prepended - just the pure name of the folder gets sorted alphabetically.
content/contact content/download content/products
While visible and invisible pages have their natural sort order built in you can easily sort a collection of pages per any other field.
For instance if your blog posts have a field Date you can sort them in descending chronological order with the newest posts first (for using fields in content text files see Docs > Adding content > Text files > Fields).
<ul> <?php foreach($pages->children()->visible()->sortBy('date', 'desc') as $item): ?> <li><?php echo $item->title() ?></li> <?php endforeach ?> </ul>
Visibility != accessibility
After all what does visible or invisible mean? Does invisible mean visitors cannot access this page?
The simple answer is: No. Every Kirby page can be accessed, regardless of its visibility. A visitor to your site can even access an invisible page if the URL is known to her (sure, there are ways to do access control in Kirby but this is not bound to page visibility).
At a glance
If you compare visible and invisible pages you'll see that there isn't much difference.
|sort order||by number, then folder name||by folder name|
|sort by other criteria||yes||yes|
|URL slug||folder name without number||folder name|
|can be freely accessed||yes||yes|
When to use visible, when invisible pages?
The decision when to use visible or invisible pages depends strongly on your personal working style concerning your website.
For parts of your website that have a "logical order of appearance" use visible pages, for instance different main sections of your website:
This way you can easily sort and re-sort these sections just by renaming the folders.
PLUS: if you use a ready-made theme for Kirby the theme can automatically build the main menu for you with all your visible pages.
If you have pages in your website that don't need to appear in a (~ one) fixed order then invisible pages might help you. Any pre-built menu functionality will not include these pages but you can search, query, filter, sort, flip, etc. these pages at your own option.
Have a look at the field structure of Kirby's content text files and the corresponding API docs.
I hope this post gives an initial insight into Kirby's visible and invisible pages. If there are questions left just post an comment.