Including CSS/JS libraries

Prerequisites

• A Kirby Starterkit installed and running.
• Code editor to edit files

What we will be building

Let's say you've downloaded and installed Kirby's Starterkit, everything is running fine, but instead of having a list of images on the album pages, you want an image slider/carousel.

While a simple slider can be implemented with pure CSS, something more sophisticated usually means you need some kind of JavaScript, and if you don't want to develop that yourself, you'll usually fall back on an existing library.

In this recipe, I'll show you how to add the CSS and script files that come with such a library to the Starterkit.

We'll use Glider.js as an example, but the general steps are the same no matter which slider (or other) library you use:

1. Download the library files
2. Copy them to your project
3. Include the CSS file in the head tag
4. Include the JavaScript file in the head or before the closing body tag (as described in your library's documentation)
5. Add the required HTML markup if necessary
6. Initialize the script if necessary

Ready?

Step by step

Step 1: Download files

Visit Glider.js and download the latest release using the download button.

Step 2: Copy files to project

Copy the unzipped folder into the assets/js/ folder in the Starterkit, so that your file system now looks similar to this:

Step 3: Add styles

Now let's add the CSS file included with the library in the head tag of our document.

In your code editor, open the site/snippets/header.php file. Then we use the css() helper to create a link tag for the CSS file:

<?php if ($page->intendedTemplate()->name() === 'album'): ?>
<?= css('assets/js/Glider.js-master/glider.css') ?>
<?php endif ?>

This will create the following link tag when rendered:

<link href="https://yourdomain/assets/js/Glider.js-master/glider.css" rel="stylesheet">

Step 4: Add script

Open the site/snippets/footer.php snippet. Right before the closing /body tag, we use the js() helper function to load the JavaScript file:

<?php if ($page->intendedTemplate()->name() === 'album'): ?>
<?= js('assets/js/Glider.js-master/glider.js') ?>
<?php endif ?>

This will creat the following script tag when rendered:

<script src="https://yourdomain/assets/js/Glider.js-master/glider.js"></script>

The css()/js() helpers expect the path to the files as argument. If you put the folder somewhere else, adapt the path accordingly.

Step 5: Adapt the markup

We have to change the markup in the /site/templates/album.php template a bit (basically removing/replacing classes to get rid of the original layout, change the image format), so that we end up with this template:

<?php snippet('header') ?>
<article>
  <?php snippet('intro') ?>
  <div class="grid">
    <div class="column" style="--columns: 4">
      <div class="text">
        <?= $page->text() ?>
      </div>
    </div>
  <div class="column glider-contain" style="--columns: 8">
    <ul class="glider">
      <?php foreach ($gallery as $image): ?>
      <li>
        <a href="<?= $image->url() ?>">
          <figure>
            <img src="<?= $image->crop(800,400)->url() ?>" alt="<?= $image->alt()->esc() ?>">
          </figure>
        </a>
      </li>
      <?php endforeach ?>
    </ul>
    <button aria-label="Previous" class="glider-prev">«</button>
    <button aria-label="Next" class="glider-next">»</button>
    <div role="tablist" class="dots"></div>
  </div>
  </div>
</article>
<?php snippet('footer') ?>

Step 6: Initialize the slider

As our last step, we have to add a script tag in the footer to initialize the slider after including the library:

<?php if ($page->intendedTemplate()->name() === 'album'): ?>
    <?= js('assets/js/Glider.js-master/glider.js') ?>
    <script>
      new Glider(document.querySelector('.glider'), {
        slidesToShow: 1,
        dots: '.dots',
        draggable: true,
        arrows: {
          prev: '.glider-prev',
          next: '.glider-next'
        }
      });
    </script>
<?php endif ?>

As a finale step, add the following lines to /assets/css/templates/album.css to get rid of the scroll bar.

.glider {
  overflow: hidden;
}

And with this, we are done. Not particularly beautiful yet, but it works. Play around with the options to see what you can do with it. You will find this information in the documentation of the library.

A note on loading external libraries from CDN

Frontend libraries often contain links to CDNs from which you can load the required CSS/JS files. While this has certain advantages (like a user might already have a popular library cached by the browser) , you have much more control when you load the files from your own server. See also Please stop using CDNs for external Javascript libraries.

Related documentation

• Template specific JS files
• Template specific CSS files
• Art-directed blog posts
• Kirby loves CDN