There comes a time in your life where you no longer accept wasting time on tedious tasks. Some of us are masters of efficiency, writing scripts to automate tasks. Some of us find tools to do it for us. At ZURB, we use Panini to save time, deliver organized code, and repeat ourselves less. Using Data and Handlebars Helpers in Panini go a long way to setting us up for success and we’ll show you how. Last week we covered using Panini’s front matter and variables. This week we’ll build on that by learning about using Panini’s Handlebars’ helpers and data. Let’s get started!

There’s a lot of really cool stuff here, so this lesson is an intro to Panini’s helpers and data. Next week we’ll put all we’ve learned about Panini together and show some advanced examples.

With a Little Help from My Friends

In Handlebars, helpers can be used to bring logic into your pages, so you can do things like dictate what conditions your content is displayed in or iterate through lists of data. Handlebars ships with some built-in helpers, such as {{#each}}, {{#if}} and {{#unless}}, and Panini adds a few more. Here is how helpers work:

• A Handlebars helper call is a simple identifier, and can have parameters (separated by space).
• Each parameter is a Handlebars expression.
• Handlebars helpers can be accessed from any context in a template.

Let’s take a look at all the helpers built into Panini:

The {{#if}} helper

The if helper is native to Handlebars and allows you to create a condition statement. You can choose whether a particular code is included or not depending on a boolean value. For example, we can conditionally add or exclude a hero unit like so:

A helper uses the Handlebars curly brackets along with a #

The if helper needs an identifier to know what it refers to. In this case we’ll use a variable called hero. Then in the front matter of a page, we can define the conditional to show or hide the component:

We can set this to true or false. If you leave it out, Panini will assume it’s a false and not include the component.

The {{#ifpage}} helper

The ifpage helper is a custom Panini helper that allows you to create a conditional based on the pages you’d like the component to be included on. You use it like this:

Notice that you do not need the file extension of the page (.html) or any file paths. Panini will find the pages. Using this helper, you can chain together multiple pages like so:

The ifpage helper is useful if you have very few pages that you’d like the HTML to be included into. If you’d like the component to be on most of the pages but restrict it from a few, then the unlesspage helper would be better.

The {{#unlesspage}} helper

You can include HTML with the unlesspage helper and choose what pages you’d like to exclude like this:

So in this example, hero will show on all pages except index, about, and contact.

The {{#ifequal}} helper

Ifequal is another Panini specific helper that allows you to compare two values. Since Panini is aware of the layouts you are using, you can use the layout helper along with ifequal to include HTML based on the layout it will end up in. For example, The Foundation site has one footer partial but four different sets of links, descriptions, and colors.

Instead of making four footer partials to maintain, we can use one with the ifequal helper.

This is handy because now we only have to maintain one footer and it can be different for each microsite’s layout. You can use ifequal with any built in variable like page and layout or any custom variable. There’s many more use cases for the ifequal helper that we’ll show in the next lesson.

The {{#repeat}} helper

Sometimes when you’re scaffolding your project, you may not have real content to work with or you just need to get something coded fast. In order to save time and avoid pasting repeated content multiple times, Panini has a handy repeat helper. Let’s say we’re building a gallery of 12 cards. We can wrap our repeated element in the repeat helper to have it iterate as many times as we need.

The repeat helper is a real time saver. You would likely remove it when you have real content to add or if you are using data. With data there is a similar helpd called the each helper.

The {{#each}} helper

We can use{{#each}} much like the repeat helper but along with data. The each helper will iterate through a component and print out the HTML for each object in our data. It looks like this:

This will repeat the <li> and HTML within as many times as there is available data in the {{link}} and {{text}} variables. We’ll take a look at how data plays into this below.

The {{#code}} and {{#markdown}} helpers

Data is Reusable Content

Data may sound like some something really technical, but it’s essentially content that can be used in your markup and reused as needed. Using data in your projects presents some immediate benefits:

• Reusing data across many pages: Data can be stored in a file and called upon in different components or scenarios to fill in your pages.
• Less repeating yourself: No more copying/pasting content in multiple places so you can produce more quality code faster.
• Sets you up for implementation with dynamic data: When you use data with Panini, you’re HTML will be structured in a way that fit’s nicely with other systems like Ember or generic Handlebars. You would have already figured out the naming and data structure in the front end.

You can define data in front matter or in a separate file. For our previous example, we’ll define the data in front matter:

These variables can be anything you want.

So in the front matter of our page, we can define the data for nav. Data can be written in json or YAML syntax. We’ll use YAML for this example to keep it simple. Each highlighted block below is called an object.

There are two objects in the example above. Since the <li> is wrapped in the each helper, it will repeat the <li> two times in this case and inject the link and text for each where the variables are called.

Let’s say we’d like to use this data globally. We’ll create a file in the data folder and add our data there.

YAML files have a .yml file extension and json uses .json. In this example we created a global.yml file that we’ll add multiple set’s of data in. You can also create multiple data pages if you have lots of data and want to stay organized. Once you have a data page, you can reference it in your each helper like so:

To link up the data to the file, we’ll add the file-name before the variable with a . like: {{#each global.main-nav}}

Again this is just an intro to Panini’s helpers. Next week we’ll put all we’ve learned about Panini together and show some advanced examples.

---