Visible and invisible pages in Kirby

|

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.

Creating pages

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:

content/01-blog/14-kirby-about-visible-and-invisible-pages

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, visible() and invisible(). These two methods act like filters to the children attribute:

  • The visible() method filters out all invisible children.
  • The 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>

Define visibility

The simple rule is:

  • If the folder starts with a number the page is visible (/content/01-hello-word).
  • If the folder does not start with a number the page is invisible (/content/contact).

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

Advanced sorting

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).

Example:

<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.

what? visible invisible
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:

  • 01-about
  • 02-products
  • 03-customers
  • 04-blog
  • 05-contact

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.

blog comments powered by Disqus