Building a component based style guide for Kirby (3)

10.06.2025

This is the third (and for now the last) part of a series. Please read the first blog post to learn more about the concept of frontend components and the second article about how the style guide was set up in general.

Today I want to demonstrate how to build individual pages for each component, which can be used to add additional content or component variations and shouldn’t be part of the overview page.

Routing

To be able to access every component at its own URL we have to create a second route. In the end we will be able to visit mydomain.com/styleguide/my-module to see the details page. Since we handle routing outside the index.php file of our plugin, we have to add the new route there.

site/plugins/styleguide/routes.php

<?php

return [
  [
    // see previous blog post for first (main) route
  ],
  [
    'pattern' => 'styleguide/(:any)',
    'method' => 'get',
    'action' => function ($module) {
      if (kirby()->user()) {
        return new Page([
          'slug' => 'styleguide',
          'template' => 'styleguide_module',
          'parent' => kirby()->site()->homePage(),
          'content' => [
            'module' => esc($module),
          ],
        ]);
      }
      die;
    }
  ],
];

With Kirby route patterns you can register routes with dynamic parts. In this case, the (:any) placeholder represents the selected frontend component. It will be stored in the $module variable and passed to the page template. There it will be available as a new content method $page->content()->module().

Template

site/plugins/styleguide/templates/

<?php snippet('layout/html', slots: true) ?>

<section class="styleguide">
  <h1><?= $page->content()->module()->upper() ?></h1>
  <?php snippet('styleguide/' . $page->content()->module()->value()) ?>
</section>

<?php endsnippet() ?>

With the layout/html snippet we include the basic header and footer template, just like we did for the style guide overview page. The additional styleguide class can be used to add style guide specific CSS rules. Of course, you are free to use any HTML code you like.

In this example we add the name of the component as an uppercase headline. Afterwards we call the style guide component snippet with the dummy content we already used for the over view page dynamically.

Extending the style guide snippet

The last step is to extend this snippet with additional content.

sites/snippets/styleguide/teaser.php

<?php
  snippet('component/teaser', [
    'modifier' => 'teaser--featured',
    'headline' => 'This is a Teaser',
    'image' => '<img src="https://placehold.co/600x400" alt="Placeholder image" width="600" height="400" >',
    'text' => 'Et quis cillum Lorem irure eu. In irure officia labore Lorem irure esse adipisicing proident.',
    'url' => '#',
  ]);
?>

<?php if ($page->content()->module()->isNotEmpty()): ?>
  <h2>Additional Content</h2>
  <p>Here you can add additional content for the details page, because the <code>$page->content()->module()</code> field is empty on the overview page.</p>
<?php endif ?>

To make sure this content will only be visible on the detail page, we check if $page->content()->module() is not empty. Everything else will also be shown on the overview page.

More snippets?

Another option would be to move the additional content in another snippet and to call this snippet in the styleguide-module template dynamically, too.

Or if you want to show several variations of the teaser and re-use them elsewhere you could separate them into different snippets as well. There are no (snippet) limits.

Maybe I will pick up these ideas in another part of this series?! We’ll see.

Sources

Kirby route patterns

CMS Kirby PHP #Style guide #Routing

What do you think?

Let's discuss on Mastodon