Working with Lists

NAV IS OUTPUT

Generally when working with elements based off of lists you would loop over the elements in a list and decide your output.

In-built Helpers

There are several built in helpers for working with lists in Handlebars. The "list" Helper and the "selected" Helper offer full control of list output.

List Helper

It allows you to loop over every item in a list. You have access to helpful variables that let you know whether the list item was selected by the user, whether there's a sublist, whether the list item is first or last, and many more. Check the docs for full information.

It's used like:

{{#each (list element="List Content Element")}}
  {{#if @first}}
    <ul>
  {{/if}}

  <li>{{#if selected}}<strong>{{/if}}{{name}}{{#if selected}}</strong>{{/if}}</li>

  {{#if @last}}
    </ul>
  {{/if}}
 
{{/each}}

The above code will loop over the whole list and make the selected items bold.

  • Advanced Diploma
  • Associate
  • Online Course
  • Postgraduate
  • Short Course
  • Undergraduate
  • Vocational Education

selected Helper

The selected helper works in a very similar way but instead of looping over the whole list, it just loops over the selected items in the list.

It's used like:

{{#each (selected element="List Content Element")}}
  {{#if @first}}
    <ul>
  {{/if}}

  <li>{{name}}</li>

  {{#if @last}}
    </ul>
  {{/if}}
 
{{/each}}

The above code will loop over the selected items in a list and make s HTML list from the selected values.

  • Online Course
  • Postgraduate

selectedNames and selectedValues Helpers

The selectedNames and selectedValues helpers (introduced in 8.4.0) are a shorthand to allow you to simply output the selected items in a list.

By default it outputs the selected list "name" separated by a comma and a space.

There are three parameters:

  1. The list element (required)
  2. A parameter named "separator" where you can pass a custom separator (optional - defaults to ", ")
  3. A paramerer named "level-separator" where you can pass a separator to be output between parent and child list items (optional - defaults to ">")

It's used like:

Output Selected List Names

{{selectedNames element="Checkbox"}}

Output Selected List Values

{{selectedValues element="Checkbox"}}

Associate, Online Course, Postgraduate

associate, online-course, postgraduate

Custom Helpers

Some custom helpers were created to make dealing with lists a bit easier.

Below is an example of the Custom Helper selectedContains.

selectedContains Helper

This custom helper allows you to check whether the user selected names (or values) from a list contains a specified string.

By default it checks if the string matches the "name" of a selected list item.

If you'd like to see the underlying code from this Custom Helper you can check out this doc on Confluence.

There are three parameters:

  1. The list element (required)
  2. A parameter named "string_to_check" that contains the string you want to compare (required)
  3. A parameter named "field_to_compare" where you can pass whether you want to compare against the list "name" or "value" (optional - defaults to "name")

It's used like:

{{#selectedContains (selected element="Checkbox") string_to_check="string to check" }}
  True!
{{else}}
  False!
{{/selectedContains}}

selectedContains - example when true

{{#selectedContains (selected element="Checkbox") string_to_check="Online Course" }}
  YES! - the user has selected Online Course.
{{else}}
  NO! - the user has NOT selected Online Course.
{{/selectedContains}}

The user has selected the following list items:
Advanced Diploma, Associate, Online Course, Postgraduate, Short Course

YES! - the user has selected Online Course.

selectedContains - example when false

{{#selectedContains (selected element="Checkbox") string_to_check="Online Course" }}
  YES! - the user has selected Online Course.
{{else}}
  NO! - the user has NOT selected Online Course.
{{/selectedContains}}

The user has selected the following list items:
Advanced Diploma, Associate, Postgraduate, Undergraduate, Vocational Education

NO! - the user has NOT selected Online Course.

selectedContains - example of checking values rather than names

{{#selectedContains (selected element="Checkbox") string_to_check="online-course" field_to_check="value" }}
  YES! - the user has selected online-course.
{{else}}
  NO! - the user has NOT selected online-course.
{{/selectedContains}}

The user has selected the following list items:
advanced-diploma, associate, online-course, postgraduate, undergraduate

YES! - the user has selected online-course.

selectedContains - example when invalid

No string to compare is passed so an error is returned

{{#selectedContains (selected element="Checkbox") }}
  YES! - the user has selected Online Course.
{{else}}
  NO! - the user has NOT selected Online Course.
{{/selectedContains}}

The user has selected the following list items:
Advanced Diploma, Associate, Postgraduate, Undergraduate, Vocational Education

No string passed to compare