Creating your first panel widget

In this tutorial, we'll build a simple information widget for your panel from scratch.

Make your panel stand out!

Kirby's panel is incredibly simple to use and yet can be extended with great features! Today we'll build your first panel widget together. The goal will be to display static information for the dashboard user.

Requirements

The only thing you need to do before you work your way through this tutorial is to have Kirby installed with the panel. You can download the widget directly below.

Download tutorial files

 

Introduction

There's a great article in the Kirby Documentation about panel widgets. You don't need to read it for this tutorial but if you find this tutorial interesting, you'll find the docs interesting as well!

Let's get started. We'll call our widget siteinfo. That means we must create a php file with the same name inside a folder with the same name inside the site/widgets folder. This folder doesn't exist by default so you'll probably have to create it. Let's sum up. You should have this: site/widgets/siteinfo/siteinfo.php

Step 1 - The barebones widget code

Let's create the simplest widget code we can. Again you should definitely read the docs on widgets once you're done with this to see all the possible options.
Our widget code is composed of a title, and an accompanying html block. We could technically put the html in there directly, but it is much cleaner to separate it in its own file. That's why we're using Kirby's tpl::loadfunction to load our template file. Here the template file is called template.php. Let's create it in the next step!

site/widgets/siteinfo/siteinfo.php

<?php
return array(
  'title' => 'Site Information',
  'html' => function() {
    return tpl::load(__DIR__ . DS . 'template.php');
  }
);

Step 2 - A simple template

Let's use this template to display some simple textual information. This can come in handy when handing over a project to a customer. You're absolutely free to style your template however you want by adding inline style, or by using a custom panel CSS. We're using Kirby's default widgets styling here.

site/widgets/siteinfo/template.php

<div class="text">
  This site was built by: <a href="https://macotuts.com">MaCoTuts</a><br>
  If you need help, contact us at <a href="mailto:hi@macotuts.com">hi@macotuts.com</a><br><br>
  Everything you need to know about entering content is <a href="https://getkirby.com/docs/content/text" >in this guide.</a><br><br>
</div>

Step 3 - Adding something useful

We're taking things a step further now. We're going to pass an array of data to our template.
In our case, we're listing all the pages of the site that are invisible and exclude the error page. Can you guess how we're going to use this ?

site/widgets/siteinfo/siteinfo.php

<?php
return array(
  'title' => 'Site Information',
  'html' => function() {
    return tpl::load(__DIR__ . DS . 'template.php', array(
      'drafts' => panel()->site()->index()->invisible()->not('error')
    ));
  }
);

Step 4 - The final template

Alright let's use that data! Our goal is to list all "drafts" in the widget. This means displaying a list of invisible pages. Now there's already a great list of pages in Kirby's default history widget. Because we don't like to reinvent code that's already beautiful, we're going to copy the code from that widget, located at panel/app/widgets/history

Notice that we're using if($drafts->count() == 0): instead of the if(!empty($drafts)). The rest is exactly the same, where we replaced $history by $drafts.

site/widgets/siteinfo/template.php

<div class="text">
  This site was built by: <a href="https://macotuts.com">MaCoTuts</a><br>
  If you need help, contact us at <a href="mailto:hi@macotuts.com">hi@macotuts.com</a><br><br>
  Everything you need to know about entering content is <a href="https://getkirby.com/docs/content/text" >in this guide.</a><br><br>
  <strong>Your unpublished pages:</strong><br>
</div>

<div class="dashboard-box">
  <?php if($drafts->count() == 0): ?>
    <div class="text">You don't have any drafts... Start writing today!</div>
  <?php else: ?>
    <ul class="dashboard-items">
      <?php foreach($drafts as $item): ?>
        <li class="dashboard-item">
            <a title="<?php __($item->title()) ?>" href="<?php __($item->url('edit')) ?>">
              <figure>
                <span class="dashboard-item-icon dashboard-item-icon-with-border"><?php echo $item->icon('') ?></span>
                <figcaption class="dashboard-item-text"><?php __($item->title()) ?></figcaption>
              </figure>
            </a>
        </li>
      <?php endforeach ?>
    </ul>
  <?php endif ?>
</div>

Conclusion

That's it! You have a beautiful widget for your next project! You can add excluded pages to the list if you need to by listing them in the not() filter: ->not('error','login','private')
What will you build in your widget?

Stay tuned!

Want to always know the latest Maco news? Subscribe and receive the newsletter straight in your inbox. No spam guarantee!

Write a comment