---
title: Helpers
slug: helpers
icon: {"faIcon":"fa-solid fa-toolbox"}
createdAt: 2022-09-29T08:22:29.000Z
---

# Basic helpers

Basic helpers are the helpers that you will use commenly in your templates. Underneath you will find all the possible helpers.

## #if

You can use the `if` helper to conditionally render a block. If its argument returns `false`, `undefined`, `null`, `""`, `0`, or `[]`, Handlebars will not render the block. When using a `if` helper , you can specify a template section to run if the expression returns a falsy value. The section is marked by `else.`

```html
<div>
    {{#if Production.Completed }}
        This film is completed.
    {{else}}
        This film is still a work in progress.
    {{/if}}
</div>
```

## #unless

You can use the `unless` helper as the inverse of the `if` helper. Its block will be rendered if the expression returns a falsy value.

```html
<div>
    {{#unless Production.Completed }}
        This film is still a work in progress.
    {{else}}
        This film is completed.
    {{/unless}}
</div>
```

## #with

The `with`-helper allows you to change the evaluation context of template-part.

```html
<div>
    {{#with Person}}
        Dear {{FirstName}} {{LastName}},<br />
        <br />
        We look forward to meeting you at the festival.<br />
    {{/with}}
</div>
```

# List helpers

Use the list helpers to iterate over a list. You can filter lists that contain elements with a `key`property.
Inside the block, you can use `this` to reference the element being iterated over.

## #each

You can iterate over a list using the `each` helper.

```html
<div class="language">
    {{#each Texts.All }}
        {{#each TextTranslations }}
            {{#compare Language '==' 'en'}} {{ Html }} {{/compare}}
        {{/each}}
    {{/each}}
</div>
```

## #filter\_on\_key

Works the same as the `each` helper, but `filter_on_key` filters the list of elements on the property 'key'.

```html
<div>
    {{#filter_on_key Credits.All 'director' }} 
        {{Fullname}} 
    {{/filter_on_key}} 
</div>
```

## #find\_on\_key

This helper works the same as `filter_on_key`, but only returns the first matching element.

```html
<div>
    {{#find_on_key Credits.All 'director' }} 
        {{Fullname}} 
    {{/find_on_key}}
</div>
```

# Helpers for date comparison

You can use date comparison helpers to conditionally render a block, based on a date. These helpers are very useful to show todays screenings only, or future appointments.&#x20;

## #before\_current\_date

This helper returns elements (e.g. shows or appointments) before the current date.

```html
<h1>Shows in the past</h1>
<div>
    {{#each Shows.All }}
        {{#before_current_date StartOn}} 
           ...     
        {{/before_current_date }}
    {{/each}}
</div>
```

## #before\_on\_current\_date

This helper returns elements (e.g. shows or appointments) before or on the current date.

```html
<h1>Shows today and in the past</h1>
<div>
    {{#each Shows.All }}
        {{#before_on_current_date StartOn}} 
            ...        
        {{/before_on_current_date }}
    {{/each}}
</div>
```

## #on\_current\_date

This helper returns elements (e.g. shows or appointments) on a the current date.

```html
<h1>Your appointments today</h1>
<div>
    {{#each Appointments.All }}
        {{#on_current_date StartsOn}} 
            ...        
        {{/on_current_date }}
    {{/each}}
</div>
```

## #after\_current\_date

This helper returns elements (e.g. shows or appointments) after the current date.

```html
<h1>Your upcoming appointments</h1>
<div>
    {{#each Appointments.All }}
        {{#after_current_date StartsOn}} 
            ...        
        {{/after_current_date }}
    {{/each}}
</div>
```

## #after\_on\_current\_date

This helper returns elements (e.g. shows or appointments)  after or on the current date.

```html
<h1>Your upcoming appointments</h1>
<div>
    {{#each Appointments.All }}
        {{#after_on_current_date StartsOn}} 
            ...        
        {{/after_on_current_date }}
    {{/each}}
</div>
```

## #on\_specific\_date

This helper returns elements (e.g. shows or appointments) on a the specified date. The date to compare with must be specified as a second argument using the format YYYY/MM/DD.

```html
<h1>Shows January 13th</h1>
<div>
    {{#each Shows.All }}
        {{#on_specific_date StartOn "2023/01/13"}} 
            ...        
        {{/on_specific_date }}
    {{/each}}
</div>
```

# Helpers for creating program schedules

Fiona provides some helpers for creating visual program schedules. You can use these helpers for positioning screening blocks based on their start times.

## scaled\_time\_offset

Calculates an offset in pixels based on the difference between a start hour and an event date. It can be used to calculate the 'absolute left' of an event on a schedule. This helper needs three parameters: dateTime, fromHour, pixelsPerHour. The first parameter is the event startOn DateTime, the second parameter is the starting hour of the schedule (e.g. 10) and the third parameter is the number of pixels per hour.

```html
{{#each Shows.All }}
    <div class="show" style="left: {{scaled_time_offset General.StartOn 10 60 }}px;">
    </div>
{{/each}}
```

## scaled\_time\_length

Calculates a width in pixels based on a start and end DateTime. It can be used to calculate the 'width' style of an event on a schedule. The helper needs three parameters: a start DateTime, an end DateTime and the number of pixels per hour.  can only be used at [Schedule](https://docs.fiona-festival.com/schedule)&#x20;

```html
{{#each Shows.All }}
    <div class="show" style="width: {{scaled_time_length General.StartOn General.EndsOn 60 }}px;">
    </div>
{{/each}}
```

# Other helpers

## format\_value

Formats a value according to a data format. You can find formatting tips here [Formatting tips](https://docs.fiona-festival.com/formatting-tips)&#x20;

```html
<div>
    Info updated on: {{format_value Metadata.UpdatedOn 'dd MM yy'}}.
</div>
```

## br

This helper converts line ends to \<br />. Useful for formatting long texts.

```html
<div>
    {{br Review }}
</div>
```

## #compare

You can use the `compare` helper to conditionally render a block, based on a comparison. The first argument is the field to compare, the second argument  is the operator for the comparison. The third argument contains a fixed value to compare with. You can combine `compare` with an`else` block.&#x20;
For the operator, use...

- "==" for equal to
- "!=" for not equal to
- ">" for greater than
- "\<" for less than

```html
<div>
    {{#each Texts.All }}
        {{#each TextTranslations }}
            {{#compare Language '==' 'en'}} {{ Html }} {{/compare}}
        {{/each}}
    {{/each}}
</div>
```

## #compare\_numbers

Use the `compare numbers` to compare two numbers with each other. The first argument is the field to compare, the second argument  is the operator for the comparison. The third argument contains a fixed value to compare with. You can combine `compare numbers` with an`else` block.&#x20;
For the operator, use...

- "==" for equal to
- ">" for greater than
- "\<" for less than
- ">=" for less and equal to
- "\<=" for greater and equal to

```html
<div>
   {{#compare_numbers General.DueInDays ">" -3}}
         Your order is overdue by more than 3 days 
   {{/compare_numbers}}
</div>
```



## #contains

You can use the `contains` helper to conditionally render a block, based on a lookup of elements in a list. This helper expects 4 arguments:

- List of elements
- Name of the propery of the element you like to test
- Operator ("and" or "or")
- Values to test against, comma separated

```html
<!-- using operator "and" -->
<div>
    {{ #contains Production.ProductionCountries "Key" "and" "belgium,france"  }} 
        Your film is produced in Belgium and France. 
    {{ else }} 
        ...  
    {{ /contains }}
</div>

<!-- using operator "or" -->
<div>
    {{ #contains Production.ProductionCountries "Key" "or" "belgium,france"  }} 
        Your film is produced in Belgium or France. 
    {{ else }} 
        ...  
    {{ /contains }}
</div>

```

## #contains\_not

You can use the `contains_not` helper to conditionally render a block, based on missing lookup of elements in a list. This helper expects 4 arguments:

- List of elements
- Name of the propery of the element you like to test
- Operator ("and" or "or")
- Values to test against, comma separated

```html
<!-- using operator "or" -->
<div>
    {{ #contains_not Production.ProductionCountries "Key" "or" "belgium,france"  }} 
        Your film isn't produced in either Belgium or France. 
    {{ else }} 
        ...  
    {{ /contains }}
</div>

```

# Special place holders

## DocumentAdditionalNote

You may want to add a personal note to a mailing, each time you send an email to an individual person. If the `DocumentAdditionalNote`place holder is added to a template, a text field appears when sending the mailing. That way, you can add a personal note that replaces the placeholder.

```html
<div>
    ...
    Please note: 
    <p>
        {{DocumentAdditionalNote}}
    </p>
</div>
```

## DocumentCreatedOn

Use this placeholder to add the date, the report / mailing has been printed / send out.

```html
<div>
   This document was printed on {{format_value DocumentCreatedOn 'd MMMM yyyy - HH:mm' }}
</div>
```

## DocumentCreatedBy

Use this placeholder to add the name of the logged in user.

```html
<div>
    Dear guest,<br/>
    ....<br/>
    <br/>
    Kind regards<br/>
    {{DocumentCreatedBy}}
</div>
```

## DocumentAddressedTo

The name of the recipient of the mailing.

```html
<div>
    Dear {{DocumentAddressedTo}},<br/>
    ....<br/>
    <br/>
    Kind regards<br/>
    {{DocumentCreatedBy}}
</div>
```

## @index

Zero-based index for the current iteration step. Set by the `each` helper.

```html
<div>
{{#each Production.ProductionCountries }} 
    {{@index}}. {{ Text }}<br/>
{{/each}}
</div>
```

## @first&#x20;

Set to true by the `each` helper for the first step of iteration.

```html
<div>
{{#each Production.ProductionCountries }} 
    {{#if @first}}
         Main country of production: {{ Text }}.<br/>
    {{/if}} 
{{/each}}
</div>
```

## @last

Set to true by the `each` helper for the last step of iteration.

```html
<div>
{{#each Production.ProductionCountries }} 
    {{ Text }}{{#unless @last}}, {{/unless}}
{{/each}}
</div>
```

