Handlebars Training Manual

Last Modified:

13 Dec 2024

User Level:

Administrator

Version 8.3.19 and up

1. Updating the Page Layout

In this example, you will learn how to update several t4 tags contained within the page layout. The page layout has been prepared to use the Handlebars Content layout processor. However, several t4 tags remain in the page layout.

• Let's learn how to replace any t4 tags that point to CSS and/or JavaScript files and any Navigation Object t4 tags with the appropriate Handlebars code. 

Exercise 1.1: Replacing a t4 tag that references a CSS stylesheet in the media library

1. Go to Assets > Page Layouts.
2. Click your page layout name to edit it. (Use the Filter tool to search).  Open the </> Header code tab.
3. You will add the new Handlebars code below to the header code of the page layout.
4. Click on the </> Header code tab.
5. Let's replace the existing t4 tag which is used to reference a CSS file in the media library.

{{{media id="10858" layout="css/*"}}}

6. Click Save changes to save the changes to your page layout.
7. Update your preview to check the result.

Exercise 1.2: Replacing a t4 tag Link Menu Navigation Object that generates a navigation menu

1. Replace the t4 tag Link Menu Navigation Object that generates the top navigation menu.

{{nav name="T201 Training Site Example: Main/Top Link Menu" id="258"}}

2. Click Save changes to save the changes to your page layout.
3. Update your preview to check the result.

Exercise 1.3: Replacing a t4 tag that references a JavaScript file in the media library 

1. Click on the </> Footer code tab.
2. Replace the t4 tag that references the JavaScript file.

{{{media id="10861" layout="text/javascript"}}}

3. Click Save changes to save the changes to your page layout.
4. Update your preview to check the result.

2. Updating the "General Content" Content Type

In this example, you will learn how to switch from using the T4 Tag Content layout processor to using the Handlebars Content layout processor.

• You will convert the t4 tags used in the "General Content" Content Type with the appropriate Handlebars code.

Exercise 2.1: Updating the "text/html" content layout to use Handlebars

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it. (Use the Filter tool to search).  Open the Content layouts tab.
3. The Content layouts tab is an area to add Content Layout(s) for your Content Type. Click into the "text/html" default content layout to edit it.
4. Click into the General information tab.
5.  Name: "text/html" - this is the default Type set in the Channel. This ensures the content can be displayed.
6. File Extension: Default - unless this is used with a different File Extension. This requires other extensions being permitted in the Channel.
7. Syntax Type: HTML/XML – this determines which syntax is highlighted.
8. Content layout processor: Update the content layout processor to Handlebars Content.
9. Click Save changes to save the changes to your Content Type.
10. Update your preview to check the result.

Exercise 2.2: Replacing a t4 anchor tag with Handlebars

1. Click into the Content layouts tab.
2. Select the "text/html" content layout and open the </> Content layout code tab.
3. Replace the HTML anchor t4 tag. You can use the anchor Helper to achieve this.
4. Replace <t4 type="meta" meta="html_anchor" /> with the anchor Helper.

{{anchor}}
<h2><t4 type="content" name="Heading" output="normal" modifiers="striptags,htmlentities" /></h2>
<t4 type="content" name="Main body" output="normal" modifiers="medialibrary,nav_sections" />

5. Click Save changes to save the changes to your content layout.
6. Update your preview to check the result.

Do not use t4 tags to display the "Header" and "Main body" elements of the Content Type. Since you are using the Handlebars Content layout processor in this content layout you must use Handlebars code only as t4 tags will not work in this context.

Exercise 2.3: Replacing the "Heading" and "Main body" elements

1. Replace the "Heading" and "Main body" t4 tags to ensure these are displayed. You can use the publish Helper to achieve this.
2. Replace the "Heading" t4 tag with: {{publish element="Heading"}}
3. Replace the "Main body" t4 tag with: {{publish element="Main body"}}

{{anchor}}
<h2>{{publish element="Heading"}}</h2>
{{publish element="Main body"}}

4. Click Save changes to save the changes to your content layout.
5. Update your preview to check the result.

Exercise 2.4: Troubleshooting the "General Content" Content Type

1. Let's preview the page to see how the content is being displayed. Notice how the content inside your "Main body" element is being output to the page.

A key thing to note is that when using the publish Helper it will not process any HTML and instead will output the HTML encoded equivalent by default. If you need to output the data as HTML (for example, if you're using a HTML element, or if it's a Plain text element being used to output "Code") then you would use triple curly braces {{{}}} .

2. Add the triple curly braces {{{ }}} to wrap your HTML "Main body" element.
3. Click Save changes to save the changes to your content layout.
4. Update your preview to check the result.

{{anchor}}
<h2>{{publish element="Heading"}}</h2>
{{{publish element="Main body"}}}

3. Canonical URL

A canonical URL is the preferred version of a webpage's URL that you want search engines to index and prioritize. It helps avoid duplicate content issues when the same or similar content is accessible via multiple URLs.

Canonical URLs prevent duplicate content issues, they help search engines understand which version of a webpage should be considered the original thereby preventing SEO penalties for duplicate content. Also, by specifying a canonical URL, you ensure that all backlinks, page rank and other SEO signals are attributed to the preferred URL boosting SEO ranking.

• The canonicalURL Helper is used to output a Canonical URL meta tag on the page.
• Usually this would be used to output a <link> tag in the <head> of your HTML.
• Your page layout currently is missing a Canonical URL, let’s add one to the page layout of your website.

Exercise 3.1: Adding a Canonical URL to the page layout

1. Go to Assets > Page Layouts.
2. Click your page layout name to edit it. (Use the Filter tool to search).  Open the </> Header code tab.
3. You will add the new Handlebars code below to the header code of the page layout.
4. Click on the </> Header code tab.
5. Copy the code below to your clipboard, and paste it into the Header code:<link rel="canonical" href="{{canonicalURL}}" />
6. Click Save changes to save the changes to your page layout.
7. Update your preview to check the result.

Exercise 3.2: Testing the Canonical URL using a mirrored section

1. In your site structure mirror your "About" section into your "Life at T4U" section of your website.
2. Click into the blue actions button of your "About" section and select "Mirror branch". Then select your "Life at T4U" section in the pop-up modal.

3. Preview the mirrored "About" section from your "Life at T4U" section. The Canonical URL should output a link referencing the original URL of the "About" section.

4. Page Titles

In this example, you will learn how to output custom page titles in the title tag of your page layout. You will look at a variety of different options to do this.

• You will learn how to use the sectionName Helper to output the section name as the title of your page. Next, you will learn how to output a "Custom Page Title" by using a field from the SectionMetaDescription Content Type.
• On fulltext pages, you will output a content element from the page layout.
• Finally, you will build logic into your code to output the appropriate title depending on whether the element is populated and whether you are in a fulltext page or not.

Exercise 4.1: Displaying the section name

1. Go to Assets > Page Layouts.
2. Click your page layout name to edit it. (Use the Filter tool to search). Open the </> Header code tab.
3. Add the new Handlebars code below to the Header code of the page layout.
4. Click on the </> Header code tab.
5. Display the Section name using the sectionName Helper. To do this replace the [Name of page] placeholder with Handlebars code.

<title>[Name of page] - Terminalfour University</title>

6. Click Save changes to save the changes to your page layout.
7. Update your preview to check the result.

Exercise 4.2: Displaying a custom page title

In this exercise, you will use the section Helper to output a "Custom Page Title". This field is configured in the SectionMetaDescription Content Type and is available within the General tab of your sections.

1. Go to Assets > Page Layouts.
2. Click your page layout name to edit it. (Use the Filter tool to search). Open the </> Header code tab.
3. Add the new Handlebars code below to the Header code of the page layout.
4. Click on the </> Header code tab.
5. Display the "Custom Page Title" from the SectionMetaDescription Content Type using the section Helper. To do this replace the [Custom Page Title] placeholder with Handlebars code.

<title>[Custom Page Title] - Terminalfour University</title>

6. Click Save changes to save the changes to your page layout.
7. Update your preview to check the result.

Exercise 4.3: Using the if/else Helpers

1. Go to Assets > Page Layouts.
2. Click your page layout name to edit it. (Use the Filter tool to search). Open the </> Header code tab.
3. Add the new Handlebars code below to the Header code of the page layout.
4. Click on the </> Header code tab.
5. You can use the if Helper to check if the SectionMetaDescription has a field called “Custom Page Title” and whether it is set to a value. If so, output the title tag with the name of the “Custom Page Title” field.
6. Use the else Helper for when the “Custom Page Title” field is not set, in which case, you can display the section name using the sectionName Helper. Make sure to replace the [Custom Page Title] and [Section name] placeholders with Handlebars code.

In this example, you will need to use a subexpression for the first time, combining the if and section Helpers, notice the use of the parentheses when creating subexpressions.

{{#if (section field="Custom Page Title")}}
  <title>[Custom Page Title] - Terminalfour University</title>
{{else}}
  <title>[Section name] - Terminalfour University</title>
{{/if}}

7. Click Save changes to save the changes to your page layout.
8. Update your preview to check the result.

Exercise 4.4: Using the fulltext Helper (Block level variant)

Before You Start

Let's add some sample content using the "News Item" Content Type.

1. On the Site Structure screen, click on the name of your "News" section.
2. The General information about this section screen appears, select the Content types tab.
3. Using the Filter feature, locate your Content Type.
4. Select the radio button to enable your Content Type for either the branch or section:
    a. Enabled (branch): the Content Type can be used in this section as well as all its sub-sections.
    b. Enabled (section): the Content Type can be used in this section only.
5. Click Save changes to confirm your selection. You can now use the "News Item" Content Type to add content to your section.
6. Add a "News Item" to your "News" section of your website. Feel free to use this Lorem Ipsum generator. 

The fulltext Helper has both a standard and block level variant. It behaves differently depending on which is used.

The fulltext Helper when used in a standard expression outputs a link to the fulltext page of a given content type. You will learn to use this variant in an upcoming exercise.

The fulltext Helper when used in a block level expression, which you will use in this exercise, allows you to know if you are viewing a fulltext page.

1. Go to Assets > Page Layouts.
2. Click your page layout name to edit it. (Use the Filter tool to search). Open the </> Header code tab.
3. Add the new Handlebars code below to the Header code of the page layout.
4. Click on the </> Header code tab.
5. Let's add the fulltext Helper to the code to output the appropriate title when you are in a fulltext page. Update the code by outputting the "Headline" element within the title tag only when in a fulltext page. Replace the [Headline] placeholders below by using the publish Helper. 

{{#fulltext}}

  {{#if (section field="Custom Page Title")}}
    <title>{{section field="Custom Page Title"}} | [Headline] - Terminalfour University</title>
  {{else}}
    <title>{{sectionName}} | [Headline] - Terminalfour University</title>
  {{/if}}

{{/fulltext}}

A great benefit of using the fulltext Helper as a block level expression in Page Layouts is that you have access to the elements of the Content Type which is something that isn't possible using t4 tags. This allows you to use the publish Helper to output the "Headline" element of the fulltext Content Type.

6. Let's now handle the case when you are not in a fulltext page, to do this you can make use of the else Helper to add an else condition. Add the original code that you wrote in Exercise 4.3: Using the if/else Helpers inside of the else block:

{{#fulltext}}

  {{#if (section field="Custom Page Title")}}
    <title>{{section field="Custom Page Title"}} | [Headline] - Terminalfour University</title>
  {{else}}
    <title>{{sectionName}} | [Headline] - Terminalfour University</title>
  {{/if}}

{{else}}

  {{#if (section field="Custom Page Title")}}
    <title>{{section field="Custom Page Title"}} - Terminalfour University</title>
  {{else}}
    <title>{{sectionName}} - Terminalfour University</title>
  {{/if}}

{{/fulltext}}

Note that by adding an else condition to the fulltext Helper, you are now also creating a nested if within your logic.

7. Click Save changes to save the changes to your page layout.
8. Update your preview to check the result.

5. Preview Helper

The preview Helper is used to determine whether or not the page is currently being previewed or not. It allows you to output content only in Preview.

• You will learn how to use the preview Helper to output the channel name, section name and publish URL when in Preview.

Exercise 5.1: Using the preview Helper

1. Go to Assets > Page Layouts.
2. Click your page layout name to edit it. (Use the Filter tool to search).  Open the </> Header code tab.
3. You will add the new Handlebars code below to the header code of the page layout.
4. Click on the </> Header code tab.
5. Let's use the preview Helper to determine if we are in Preview and output a simple message. Replace the placeholders below with Handlebars code.

[Open the preview Helper]
  <p>You are in preview.</p>
[Close the preview Helper]

6. Click Save changes to save the changes to your page layout.
7. Update your preview to check the result.

Exercise 5.2: Using the channelName, sectionName and publishURL Helpers

1. Display the channel name, section name and publish URL. Use the channelName, sectionName, and publishURL Helpers to achieve this. Replace the [Channel name], [Section name] and [publish URL] placeholders with Handlebars code.

{{#preview}}
  <p><strong>Channel name:</strong> [Channel name]</p>
  <p><strong>Section name:</strong> [Section name]</p>
  <p><strong>Publish URL:</strong> [publish URL]</p>
{{/preview}}

2. Click Save changes to save the changes to your page layout.
3. Update your preview to check the result.

Exercise 5.3: Adding an else condition to the preview Helper 

1. Add an else condition to the preview Helper and display a link to the published URL.

[Open the preview Helper]
  <p><strong>Channel name: </strong> [Channel name]</p>
  <p><strong>Section name: </strong> [Section name]</p>
  <p><strong>Publish URL:</strong><a href="[publish URL]"> [publish URL]</a></p>
[else]
  <p><strong>This is the published page.<strong></p>
[Close the preview Helper]

2. Click Save changes to save the changes to your page layout.
3. Publish your site to check the published output.

Exercise 5.4: Adding styling to the Preview

1. Copy the code below into your page layout.

<div class="row">
  <div class="small-12 columns text-left hide-for-small-only" >
    <div class="panel callout">
      {{#preview}}
        <p><strong>Channel name:</strong> {{channelName}}</p>
        <p><strong>Section name:</strong> {{sectionName}}</p>
        <p><strong>Publish URL:</strong><a href="{{publishURL}}"> {{publishURL}}</a></p>
      {{else}}
        <p><strong>This is the published Page.</strong></p>
      {{/preview}}
     </div>
   </div>
</div>
<style>
  .panel.callout {
  background-color: lightcyan;
  border-color: darkblue;
  margin-top: 1rem;
  }
</style>

2. Click Save changes to save the changes to your page layout.
3. Update your preview to check the result.

Exercise 5.5: Adding a warning message to the Preview

You may want to display a placeholder "warning" message when in preview only, a possible use case is an alert informing of functionality that may not be available in preview. 

1. Let's add a warning message to the display. Copy the code below into your page layout.

<div class="row">
  <div class="small-12 columns text-left hide-for-small-only" >
    <div class="panel callout">
      {{#preview}}
        <p><strong>Channel name:</strong> {{channelName}}</p>
        <p><strong>Section name:</strong> {{sectionName}}</p>
        <p><strong>Publish URL:</strong><a href="{{publishURL}}"> {{publishURL}}</a></p>
    </div>
  </div>
</div>
<div class="row">
  <div class="small-12 columns text-left hide-for-small-only" >
    <div class="alert-box alert warning">
      <p>Sorry, Content Type: "Program Compare" is not available in preview.</p>
    </div>
  </div>
</div>
{{else}}
      <p><strong>This is the published Page.</strong></p>
    </div>
  </div>
</div>
{{/preview}}
<style>
  .panel.callout {
  background-color: lightcyan;
  border-color: darkblue;
  margin-top: 1rem;
  }
</style>

2. Click Save changes to save the changes to your page layout.
3. Update your preview to check the result.

6. Updating the "News Item" Content Type

In this example, you will get additional practice converting a Content Type to use Handlebars. You will use the "News Item" Content Type and update the content layouts with the Handlebars code required.

• You will learn how to create a link to a fulltext page and how to format dates using Handlebars.
• Additionally, you will learn to use the media and mediaId Helpers to output images. 

Exercise 6.1: Updating the "text/html" content layout to use Handlebars

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it. (Use the Filter tool to search).  Open the Content layouts tab.
3. The Content Layout tab is an area to add Content Layout(s) for your Content Type. Click into the "text/html" content layout to edit it.
4. Click into the General information tab.
5.  Name: "text/html" - this is the default Type set in the Channel. This ensures the content can be displayed.
6. File Extension: Default - unless this is used with a different File Extension. This requires other extensions being permitted in the Channel.
7. Syntax Type: HTML/XML – this determines which syntax is highlighted.
8. Content layout processor: Update the content layout processor to Handlebars Content.
9. Content Layout code: this determines the output for your content. If you have created the HTML already, you can start by pasting that into the code field as displayed below.

Exercise 6.2: Updating the "text/html" content layout

1. Click into the Content layouts tab.
2. Select the "text/html" content layout and open the </> Content layout code tab.
3. Replace the "Headline" element t4 tag only. You can use the publish Helper to do this. You will replace the fulltext link in an upcoming exercise.

<h3>
  <a href="<t4 type="content" name="Name" output="fulltext" use-element="true" filename-element="Headline" modifiers="striptags,htmlentities" />">
<t4 type="content" name="Headline" output="normal" modifiers="striptags,htmlentities" /></a>
</h3>

4. Replace the "Release date" element t4 tag. You can use the publish Helper to do this.

<em><strong><t4 type="content" name="Release date" output="normal" date_format="EEEE, MMMM d, yyyy" /></strong></em>

5. Replace the "Teaser" element t4 tag. You can use the publish Helper to do this.

<p><t4 type="content" name="Teaser" output="normal" modifiers="striptags,htmlentities" /></p>

6. Click Save changes to save the changes to your content layout.
7. Update your preview to check the result.

Exercise 6.3: Creating the Fulltext link

In the previous exercise (Exercise 4.4: Using the fulltext Helper (Block Level Variant)), you learned how to use the block level variant of the fulltext Helper. To create a fulltext link, however, you can use the fulltext Helper but in a standard level expression instead.

1. Click into the Content layouts tab.
2. Select the "text/html" content layout and open the </> Content layout code tab.
3. To generate a fulltext link update the "Headline" element using the fulltext Helper. The linkText option of the fulltext Helper should be the "Headline" element. Replace the [fulltext] placeholder with Handlebars code.

<h3>[fulltext]</h3>

4. Click Save changes to save the changes to your content layout.
5. Update your preview to check the result.

Exercise 6.4: Formatting a date element

If you output a Date element using the publish Helper like this:

<em><strong>{{publish element="Release date"}}</strong></em>

You'd get an output in the following format (Standard ISO Date format):

Mon, 10 Sep 2024 11:35:00 IST

There is also a second Helper called dateElement that works like so:

{{dateElement element="Date element"}}This will output in a slightly different format:

2024-09-20T09:30:10Z[Etc/UTC]The difference is that the dateElement Helper outputs a date in such a format that can be accepted into the dateFormat Helper. You can use the dateFormat Helper to define a date format and pass in the dateElement Helper (which provides the date in the required structure for the dateFormat Helper to function).

Note that the dateFormat Helper accepts two arguments: (dateToFormat and formatToUse)

{{dateFormat dateToFormat formatToUse}}

1. Click into the Content layouts tab.
2. Select the "text/html" content layout and open the </> Content layout code tab.
3. Output the "Release date" element using the dateFormat and dateElement Helpers. Replace the [Release date] placeholder with Handlebars code.

You can reference different date formats here: T4 Tags: Format Dates

<em><strong>[Release date]</strong></em>

4. Click Save changes to save the changes to your content layout.
5. Update your preview to check the result.

Exercise 6.5: Updating the "text/fulltext" content layout to use Handlebars

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it. (Use the Filter tool to search).  Open the Content layouts tab.
3. The Content Layout tab is an area to add Content Layout(s) for your Content Type. Click into the "text/fulltext" content layout to edit it.
4. Click into the General information tab.
5.  Name: "text/fulltext" - this is the default Type set in the Channel. This ensures the content can be displayed.
6. File Extension: Default - unless this is used with a different File Extension. This requires other extensions being permitted in the Channel.
7. Syntax Type: HTML/XML – this determines which syntax is highlighted.
8. Content layout processor: Update the content layout processor to Handlebars Content.
9. Content Layout code: this determines the output for your content. If you have created the HTML already, you can start by pasting that into the code field as displayed below.

Exercise 6.6: Updating the "text/fulltext" content layout

1. Click into the Content layouts tab.
2. Select the "text/fulltext" content layout and open the </> Content layout code tab.
3. Replace the "Headline" element t4 tag. You can use the publish Helper to do this.

<h2><t4 type="content" name="Headline" output="normal" modifiers="striptags,htmlentities" /></h2>

4. Replace the "Release date" element t4 tag. Make sure to add the correct formatting. You can use the dateFormat and dateElement Helpers to do this.

You can reference different date formats here: T4 Tags: Format Dates

<em><strong><t4 type="content" name="Release date" output="normal" date_format="EEEE, MMMM d, yyyy" /></strong></em>

5. Replace the "Image" element t4 tag. You can use the publish Helper to do this.

<div>
  <t4 type="content" name="Image" output="normal" formatter="image/normal" />
</div>

6. Replace the "Teaser" element t4 tag. You can use the publish Helper to do this.

 <p><t4 type="content" name="Teaser" output="normal" modifiers="striptags,htmlentities" /></p>

7. Replace the "News story" element t4 tag. You can use the publish Helper to do this.

<t4 type="content" name="News story" output="normal" modifiers="medialibrary,nav_sections" />

8. Click Save changes to save the changes to your content layout.
9. Update your preview to check the result.

Exercise 6.7: Using the media and mediaId Helpers

In this exercise, you will learn how to use the media and mediaId Helpers to apply a different layout to the image in the content layout. 

Note that when you output a Media element using the publish Helper like you are doing here, the media element will be output using the standard media layout selected in the UI. If you needed to enforce a specific alternate Media layout you can use the mediaId Helper alongside the media Helper to do so.

For this exercise, you need to use the media Helper to output a piece of Media with an explicit layout:

{{{media id="123" layout="image/alternative"}}}

You will then use the mediaId Helper to pass in the id of your "Image" element to the media Helper. It would work like so:

{{{media id=(mediaId element="Media element") layout="text/alternative"}}}

1. Click into the Content layouts tab.
2. Select the "text/fulltext" content layout and open the </> Content layout code tab.
3. Let's apply a different layout to the image in the content layout by using the media and mediaId Helpers. Let's use the alternate layout: "Image with caption". Replace the [Image] placeholder with Handlebars code.

<h2>{{publish element="Headline"}}</h2>
<em><strong>{{dateFormat (dateElement element="Release date") "EEEE, MMMM d, yyyy"}}</strong></em>
<div>
  [Image]
</div>
<p>{{publish element="Teaser"}}</p>
{{{publish element="News story"}}}

4. Click Save changes to save the changes to your content layout.
5. Update your preview to check the result.

7. Display Image Based on Element

In this example, you will learn how to provide a fallback image depending on whether an image element has been set. You will use the "News Item" Content Type and update the content layout with the Handlebars code required.

• If the "Image" element of the Content Type is set, then display the image, otherwise display a default fallback image.
• You can use a simple ifSet Helper to check if the image is set.

Exercise 7.1: Adding an image to the "text/html" content layout

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it. (Use the Filter tool to search).  Open the Content layouts tab.
3. The Content Layout tab is an area to add Content Layout(s) for your Content Type. Click into the "text/html" content layout to edit it.
4. Copy/paste the code below into your content layout. This code adds the "Image" element and some wrapper divs to position the image alongside the "Headline", "Release date" and "Teaser" elements.
5. Replace the [Image], [fulltext], [Release date] and [Teaser] placeholders with Handlebars code.

<div class="row">
  <div class="large-3 columns">
    [Image]
  </div>
  <div class="large-9 columns">
    <h3>[fulltext]</h3>
    <em><strong>[Release date]</strong></em>
    <p>[Teaser]</p>
  </div>
</div>

6. Click Save changes to save the changes to your page layout.
7. Update your preview to check the result.

Exercise 7.2: Using the ifSet Helper

1. Click into the Content layouts tab.
2. Select the "text/html" content layout and open the </> Content layout code tab.
3. The ifSet Helper allows you to check whether the "Image" element is set. If the "Image" element is set display it.

{{#ifSet element="Image"}}
  {{{media id=(mediaId element="Image") layout="Image with caption"}}}

4. Otherwise if the "Image" element is not set, display a fallback image.
5. You need to retrieve the id for the fallback image from the media library. In this exercise, you will use the image with id 10966 already in the media library.

{{else}}
  {{{media id="10966"}}}
{{/ifSet}}

6. Click Save changes to save the changes to your page layout.
7. Update your preview to check the result.

Exercise 7.3: Updating the "text/fulltext" content layout

Let's update the code in the "text/fulltext" content layout to also display the fallback image when needed.

1. Click into the Content layouts tab.
2. Select the "text/fulltext" content layout and open the </> Content layout code tab.
3. The ifSet Helper allows you to check whether the "Image" element is set. If the "Image" element is set display it, otherwise if the "Image" element is not set, display the fallback image. Replace the [Open ifSet], [else] and [Close ifSet] placeholders with Handlebars code.

[Open ifSet]
  {{{media id=(mediaId element="Image") layout="Image with caption"}}}
[else]
  {{{media id="10966" layout="Image with caption"}}}
[Close ifSet]

8. Working With Lists

In the following examples, you will learn how to work with lists and display them on the page. You will learn to use the selected and list Helpers and the different variables that can be used within lists in Handlebars.

• Generally when working with elements based off of lists you would loop over the elements in a list and decide your output.
• You will learn how to take the selected values from a list and output them as HTML unordered lists (<ul>).
• In the following exercises, you will focus on learning how to use the in-built Helpers list and selected to work with lists.

Two in-built Helpers

There are two built in Helpers for working with lists in Handlebars. The "list" Helper and the "selected" Helper.

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.

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.

The list and selected Helpers are both used in order to help with the output of List elements:

• Select Box
• Check Box
• Radio Button
• Multi-select List
• Multiple Select
• Cascading List

Both the list and selected Helpers are designed to be used alongside the built-in each block expression with Handlebars.

Using the list Helper as an example:

{{#each (list element="List Content Element")}}
    <p>{{name}} - {{value}}</p>
{{/each}}

The above code is looping over every element in the list whether it is selected by the user or not and outputting the name and value in paragraphs.

However, there are a lot more variables available to use than just {{name}} and {{value}}. With both the list and selected Helpers we have the following variables available to us:

• listId - The Id of the list that this entry belongs to.
• entryId - The Id of this list entry.
• name - The name of this list entry.
• value - The value of this list entry.
• sequence - The sequence of this entry in the list.
• language - The language of the list entry.
• selected - true if the list entry is selected, false otherwise.
• hasSubList - true if the entry contains a sub-list.
• subList - A reference to the sub-list, if one is present.
• subListId - the Id of the sub-list, if present.

In addition to the variables relating to each list entry returned, there are a number of variables made available to give the developer more information about the position of each entry in the list.

• @first - true if this is the first entry in the list/array.
• @last - true if this is the last entry in the list/array.
• @odd - true if this this entry has an odd index. Note that the array is zero-indexed.
• @even - true if this this entry has an even index. Note that the array is zero-indexed.
• @index - Returns the index of this entry within the list/array.

These allow us full control over how the lists should be output.

Using the selected Helper

• Let's build an example where you will learn how to use the selected Helper.
• In this example, you will use the selected Helper and iterate not through the whole list but rather only through the selected items and display them.

Exercise 8.1: Adding a list element to the "General Content" Content Type

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it. (Use the Filter tool to search).  Open the Content layouts tab.
3. Select the Elements tab.
4. Click the Add element button to add the new list select element as per the table below:
   1. Name: Give your List element a descriptive name. (e.g. "Select degree programs")
   2. Description: Give your List element a description.
   3. Type: Choose "Multi-select List".
   4. List used for values: Select "T205 Program Categories" from the available list options.

Exercise 8.2: Using the each and selected Helpers

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it. (Use the Filter tool to search).  Open the Content layouts tab.
3. Click into the Content layouts tab.
4. Choose to edit your "text/html" content layout.
5. Use the each and selected Helpers to iterate through the selected items in the list only and use the "name" variable to output the name of each item in the list.

{{#each (selected element="Select degree programs")}}
  {{name}}
{{/each}}

Exercise 8.3: Using the @first and @last variables

1. Open an unordered list (<ul>) if in the first iteration of the loop. Use the if Helper and the @first variable.
2. Wrap the name of the list item with <li></li> tags.
3. Close the unordered list (</ul>) if in the last iteration of the loop. Use the if Helper and the @last variable.

{{#each (selected element="Select degree programs")}}
  [Open the unordered list <ul>]
  [Output the name of the list item]
  [Close the unordered list </ul>]
{{/each}}

4. Click Save changes to save the changes to your content layout.
5. Update your preview to check the result.

Note: You can make use of the ~ (tilde) character in Handlebars expressions to tell Handlebars to ignore the whitespace and output everything on a single line.

Using the list Helper

• In this second example, let's use the list Helper to display the whole list and additionally display the items that have been selected in bold.

Exercise 8.4: Using the list Helper

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it. (Use the Filter tool to search).  Open the Content layouts tab.
3. Click into the Content layouts tab.
4. Choose to edit your "text/html" content layout.
5. Use the each and list Helpers to iterate through all the items in the list.
6. Open an unordered list (<ul>) if in the first iteration of the loop. Use the if Helper and the @first variable.
7. Wrap the name of the list item with <li></li> tags.
8. Close the unordered list (</ul>) if in the last iteration of the loop. Use the if Helper and the @last variable.

[Iterate through all the items in the list]
  {{#if @first}}
    <ul>
  {{/if}}
  <li>{{name}}</li>
  {{#if @last}}
    </ul>
  {{/if}}
[Close the each Helper]

9. Click Save changes to save the changes to your content layout.
10. Update your preview to check the result.

Exercise 8.5: Using the selected Helper

1. Let's wrap each selected item in the list with a <strong> tag to display selected items in bold. Use the selected Helper with an if Helper to achieve this.

[Iterate through all the items in the list]
  [Open the unordered list <ul>]
  [Output the name of the list item, if the item is selected display it in bold]
  [Close the unordered list </ul>]
[Close the each Helper]

2. Click Save changes to save the changes to your content layout.
3. Update your preview to check the result.

9. Embedding Content Layouts

In the following example, you will learn how to embed content layouts using the embed Helper.

• You will learn how to output a different content layout based on what value a user has selected in a list.
• You will add a list element to choose a specific content layout to be applied to the "News Item" Content Type.
• The user can only choose a single item in the list (e.g. they're not using a Multi-select list or a Checkbox). You will then use the choice selected to output the corresponding layout.

Exercise 9.1: Creating the "Standard" content layout

• The "Standard" content layout will only output the "Headline", "Release date" and "News story" elements of the "News Item" Content Type.

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it (Use the Filter tool to search).
3. Open the Content layouts tab and click Add content layout.
4. Fill in the General information tab.
   1.  Name: "text/standard-layout".
   2. File Extension: Default - unless this is used with a different File Extension. This requires other extensions being permitted in the Channel.
   3. Syntax Type: HTML/XML – this determines which syntax is highlighted.
   4. Content layout processor: Update the content layout processor to Handlebars Content.
5. Click into the Content layout code tab.
6. Copy the code below as your "Standard" content layout code.

<h3>{{{fulltext linkText=(publish element="Headline")}}}</h3>
<em><strong>{{dateFormat (dateElement element="Release date") "EEEE, MMMM d, yyyy"}}</strong></em>
<p>{{publish element="Teaser"}}</p>

7. Click Save changes to save the changes to your content layout.

Exercise 9.2: Using the abbreviate Helper

Note: Handlebars has several String Manipulation Helpers available. You will use the abbreviate Helper in this exercise, you can learn about some of these other Helpers here: String Manipulation Helpers

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it (Use the Filter tool to search).
3. Click into the Content layouts tab and then into the "text/standard-layout" content layout.
4. Add the abbreviate Helper to output only the first 50 characters of the "Teaser" element. Replace the [Teaser] placeholder with Handlebars code.

<h3>{{{fulltext linkText=(publish element="Headline")}}}</h3>
<em><strong>{{dateFormat (dateElement element="Release date") "EEEE, MMMM d, yyyy"}}</strong></em>
<p>[Teaser]</p>

5. Click Save changes to save the changes to your content layout.

Exercise 9.3: Embedding the "Standard" content layout using the embed Helper

1. Update the "text/html" content layout of the "News Item" Content Type. Use the embed Helper to embed the "Standard" content layout you created in the previous exercise.

[Embed the "text/standard-layout"]

2. Click Save changes to save the changes to your content layout.
3. Update your preview to check the result.

Snippet Helper

It's quite common to use the SectionMetaDescription Content type to create layouts for code or information that you want to be available in every section.

This is often used alongside a Related Content navigation object that looks in the current section for content with an alternate layout.

With the snippet Helper you can now pull in a layout from the SectionMetaDescription Content type without the need to create any navigation objects.

Used like:

{{snippet layout="text/section-meta-layout"}}

Exercise 9.4: Adding a list element to the "News Item" Content Type

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it. (Use the Filter tool to search).
3. Open the Elements tab.
4. Click the Add element button to add the new list select element as per the table below:
   1. Name: Give the element a descriptive name.
   2. Description: Give your select list a description.
   3. Type: Choose "Select Box".
   4. List used for values: Select "T205 Content Layout Types" from the available list options.

Exercise 9.5: Adding the "Enhanced" content layout

• The "Enhanced" content layout will add the "Image" element depending on whether it is set.
• Additionally, let's make the "Image" element a link to the fulltext news page using the fulltext Helper.
• To further differentiate the "Enhanced" layout, you will add a different layout to the image and some styling to the panel that contains the elements.

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it (Use the Filter tool to search). 
3. Open the Content layouts tab and click Add content layout.
4. Fill in the General information tab.
   1.  Name: "text/enhanced-layout".
   2. File Extension: Default - unless this is used with a different File Extension. This requires other extensions being permitted in the Channel.
   3. Syntax Type: HTML/XML – this determines which syntax is highlighted.
   4. Content layout processor: Update the content layout processor to Handlebars Content.
5. Click into the Content layout code tab.
6. Copy the code below as your "Enhanced" content layout code.

<div class="row panel callout radius">
  <div class="large-3 columns">
    {{#ifSet element="Image"}}
      {{{fulltext linkText=(media id=(mediaId element="Image") layout="Image thumbnail")}}}
    {{else}}
      {{{fulltext linkText=(media id="10966" layout="Image thumbnail")}}}
    {{/ifSet}}
  </div>
  <div class="large-9 columns">
    <h3>{{{fulltext linkText=(publish element="Headline")}}}</h3>
    <em><strong>{{dateFormat (dateElement element="Release date") "EEEE, MMMM d, yyyy"}}</strong></em>
    <p>{{publish element="Teaser"}}</p>
  </div>
</div>

7. Click Save changes to save the changes to your content layout.

Exercise 9.6: Updating the "text/html" content layout

1. Use the each and selected Helpers to retrieve the selected value in the list.

{{#each (selected element="News display")}}
{{/each}}

2. You can use the eq Helper to check the value of the list selected ("Standard Layout") and the embed Helper to then embed the appropriate layout, "standard-layout", this must be the name of the content layout defined in the Content Type.

There are a number of Helpers to allow you to compare values:
eq - Tests if two values are equal
neq - Tests if two values are not equal
gt - Tests if one value is greater than another
gte - Tests if one value is greater than or equal to another
lt - Tests if one value is less than another
lte - Tests if one value is less than or equal to another
and - Tests if values are true (you can pass two or more arguments)
or - Tests if any values are true (you can pass two or more arguments)
not - If the provided input is false then the block will not be processed

Arguments are space separated when passed to Handlebars expressions (as opposed to comma separated).

{{#eq (publish element="Greeting") "Hello"}}
    <p>Hello to you too!</p>
{{else}}
    <p>You didn't say "Hello".</p>
{{/eq}}

{{#lt 5 8}}
    <p>5 is indeed less than 8.</p>
{{else}}
    <p>This will never be published because 5 is always less than 8.</p>
{{/lt}} 

{{#each (selected element="News display")}}
  {{#eq value "Standard Layout"}}
    [Embed the "text/standard-layout"]
  {{/eq}}

3. You can use the eq Helper to check the value of the list selected ("Enhanced Layout") and the embed Helper to then embed the appropriate layout, "enhanced-layout", this must be the name of the content layout defined in the Content Type.

{{#each (selected element="News display")}}
  {{#eq value "Standard Layout"}}
    [Embed the "text/standard-layout"]
  {{/eq}}
  [Check if the value of the list item is "Enhanced Layout"]
    [Embed the "text/enhanced-layout"]
  [Close the eq Helper]
{{/each}}

4. Click Save changes to save the changes to your content layout.
5. Update your preview to check the result.

10. Wrapper Content Type

In this example, you will build an Accordion Content Type to learn how to work with sequences of content items of the same type.

• Allows a sequence of content items of the same type to be wrapped in markup.
• Used for sliders, accordions, tabs, card groups and other repeatable items.

first and last Helpers

The first Helper will be true when the content item is the first piece of content in a section.

{{#first}}
   <h1>First content item in the section</h1>
{{/first}}The last Helper will be true when the content item is the last piece of content in a section.

{{#last}}
   <footer>Last content item in the section</footer>
{{/last}}

firstOfType and lastOfType Helpers

These Helpers let you know if an item of content is the first and last of its type in a section:

{{#firstofType}}
  Only output if first of this content type in section
{{/firstOfType}}{{#lastOfType}}
  Only output if last of this content type in section}}
{{/lastOfType}}

firstInSequence and lastInSequence Helpers

Perhaps more flexible though, are these Helpers which allow you to determine if an item of content is the first and last of its type in an uninterrupted sequence of content in a section.

The firstInSequence Helper will be true when the content item is the first piece of content using this Content Type in an uninterrupted sequence of content in a section.

{{#firstInSequence}}
  Only output if first of this content type in an uninterrupted sequence in this section
{{/firstInSequence}}

The lastInSequence Helper will be true when the content item is the last piece of content using this Content Type in an uninterrupted sequence of content in a section.

{{#lastInSequence}}
  Only output if last of this content type in an uninterrupted sequence in this section
{{/lastInSequence}}

Let's build an example to demonstrate the use of these Helpers. In the following example, you will build an accordion component that displays FAQs.

Exercise 10.1: Setting up the jQuery UI Library

The accordion component is generated using the jQuery UI Library. In order to use this library, you will need to upload three files into your media library and then target them using Handlebars in your page layout. These files have been previously uploaded to the media library, let's learn how to reference them using Handlebars in the page layout.

1. Go to Content > Media Library.
2. Click into "T205 Training Site Example" and then into Developer Assets.
3. Click into the CSS and JavaScript folders to retrieve the corresponding ids of the required libraries.
4. Go to Assets > Page Layouts.
5. Click your page layout name to edit it. (Use the Filter tool to search).  Open the </> Header code tab.
6. Use the media Helper to create the link to the jQuery UI CSS file.

{{{media id="10925" layout="css/*"}}} <!-- jQuery UI CSS-->

7. Open the </> Footer code tab.
8. Use the media Helper to create the link to the jQuery UI file.

{{{media id="10926" layout="text/javascript"}}} <!-- jQuery UI JS -->

9. Use the media Helper to insert the jQuery accordion script that generates the accordion component.

{{{media id="11787" layout="text/javascript"}}} <!-- jQuery UI Accordion Script -->

10. Click Save changes to save the changes to your page layout.

Exercise 10.2: Adding logic to the page layout

In this exercise, let's improve the page layout by linking to the jQuery UI library CSS and JS files only when you are in the "FAQ" section of your site, which is the only section that needs to display an accordion and therefore make use of this library.

1. Go to Assets > Page Layouts.
2. Click your page layout name to edit it. (Use the Filter tool to search).  Open the </> Header code tab.
3. Use the eq and sectioName Helpers to insert the jQuery UI CSS file into the header of the page layout only when in the "FAQ" section.

{{#eq (sectionName) "FAQ"}}
  {{{media id="10925" layout="css/*"}}} <!-- jQuery UI CSS -->
{{/eq}}

4. Use the eq and sectioName Helpers to insert the jQuery UI JS and jQuery UI accordion script files into the footer of the page layout only when in the "FAQ" section.

{{#eq (sectionName) "FAQ"}}
  {{{media id="10926" layout="text/javascript"}}} <!--jQuery UI JS -->
  {{{media id="11787" layout="text/javascript"}}} <!--jQuery UI Accordion Script -->
{{/eq}}

5. Click Save changes to save the changes to your content layout.
6. Update your preview to check the result.

Exercise 10.3: Creating the "Accordion" Content Type

1. Go to Assets > Content Types > Create content type.
2. Fill in the General content type information:
   1. Name: enter a name here. This should suggest what type of content it is used for.
   2. Description: describe in more detail when to use this Content Type.
   3. Minimum user level: if you wish to restrict who can use this content type, you can set a level here. If content types are created in groups, a user must be a member of the group as well as meet the minimum user level criteria to use the Content Type.
   4. Enable direct edit: decide if direct edit can be used for this content type.
   5. Mark as eForm: If checked, this allows your Content Type to collect eForm data.
   6. Workflow: if relevant, enable a workflow for content created using this content type.
   7. Primary group: Select your group. This allows you to select the group which is permitted to use this content type. Click Toggle shared groups to share the content type with more than one group.
3. Select the Elements Tab.
4. Each content type has a Name element by default. This is used to name the content and is typically not displayed on the published site. 
5. Add the other elements you need by filling in the information as outlined in the table below. Click add element to begin filling in the details for each element.
6. Once you have added all your elements, click Save changes. The Content Layout tab opens.

Use the firstInSequence and lastInSequence Helpers to ensure the accordion is surrounded appropriately with a wrapper div.

Exercise 10.4: Creating the "text/html" content layout

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it. (Use the Filter tool to search).  Open the Content layouts tab.
3. Click into the Content layouts tab.
4. Choose to edit your "text/html" content layout.
5. In the Content layout code tab of your "text/html" content layout add the code as per below:
6. Use the firstInSequence Helper to embed the "text/before" content layout at the beginning of the accordion. Then embed your "text/middle" content layout. Finally, use the lastInSequence Helper to embed the "text/after" content layout at the end of the accordion.

{{#firstInSequence}}
  [Embed the text/before content layout]
{{/firstInSequence}}

[Embed the text/middle content layout]

{{#lastInSequence}}
  [Embed the text/after content layout]
{{/lastInSequence}}

7. Click Save changes to save the changes to your content layout.

Exercise 10.5: Creating the "text/before" content layout

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it (Use the Filter tool to search).
3. Open the Content layouts tab and click Add content layout.
4. Fill in the General information tab.
   1.  Name: "text/before".
   2. File Extension: Default - unless this is used with a different File Extension. This requires other extensions being permitted in the Channel.
   3. Syntax Type: HTML/XML – this determines which syntax is highlighted.
   4. Content layout processor: Update the content layout processor to Handlebars Content.
5. Click into the Content layout code tab.
6. Copy the code below as your "text/before" content layout code.
7. Since the "Accordion Component Heading" element is not a required element use the ifSet Helper to output it only if it has been set.
8. Make sure to replace the [Open ifSet], [Accordion Component Heading] and [Close ifSet] placeholders with Handlebars code.

[Open ifSet] 
<h2>[Accordion Component Heading]</h2>
[Close ifSet]
<div id="accordion"> <!-- open #accordion -->

8. Click Save changes to save the changes to your content layout.

Exercise 10.6: Creating the "text/middle" content layout

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it (Use the Filter tool to search).
3. Open the Content layouts tab and click Add content layout.
4. Fill in the General information tab.
   1.  Name: "text/middle".
   2. File Extension: Default - unless this is used with a different File Extension. This requires other extensions being permitted in the Channel.
   3. Syntax Type: HTML/XML – this determines which syntax is highlighted.
   4. Content layout processor: Update the content layout processor to Handlebars Content.
5. Click into the Content layout code tab.
6. Copy the code below as your "text/middle" content layout code.
7. Make sure to replace the [Accordion Heading] and [Accordion Body] placeholders with Handlebars code.

<h3>[Accordion Heading]</h3>
<div>[Accordion Body]</div>

8. Click Save changes to save the changes to your content layout.

Exercise 10.7: Creating the "text/after" content layout

1. Go to Assets > Content Types.
2. Click your Content Type name to edit it (Use the Filter tool to search). 
3. Open the Content layouts tab and click Add content layout.
4. Fill in the General information tab.
   1.  Name: "text/after".
   2. File Extension: Default - unless this is used with a different File Extension. This requires other extensions being permitted in the Channel.
   3. Syntax Type: HTML/XML – this determines which syntax is highlighted.
   4. Content layout processor: Update the content layout processor to Handlebars Content.
5. Click into the Content layout code tab.
6. Copy the code below as your "text/after" content layout code.

</div> <!-- close #accordion -->
<div>
  <a href="#" class="button">Collapse All</a>
  <a href="#" class="button">Expand All</a>
</div>

7. Click Save changes to save the changes to your content layout.

Let's add some sample content using the "Accordion" Content Type.

1. On the Site Structure screen, click on the name of your "FAQ" section.
2. The General information about this section screen appears, select the Content types tab.
3. Using the Filter feature, locate your Content Type.
4. Select the radio button to enable your content type for either the branch or section:
    a. Enabled (branch): the Content Type can be used in this section as well as all its sub-sections.
    b. Enabled (section): the Content Type can be used in this section only.
5. Click Save changes to confirm your selection. You can now use the "Accordion" Content Type to add content to your section.
6. Add at least two "Accordion Items" to your "FAQ" section of your website. Feel free to use this Lorem Ipsum generator. 

8. Update your preview to check the result.

Exercise 10.8: Updating the "text/html" content layout

Because this is so much shorter and easier to work with than the Programmable layout equivalent you should consider avoiding embedding alternate layouts altogether to improve performance and instead, do something like:

{{#firstInSequence}}
  {{#ifSet element="Accordion Component Heading"}}
    <h2>{{publish element="Accordion Component Heading"}}</h2>
  {{/ifSet}}
  <div id="accordion"> <!-- open #accordion -->
{{/firstInSequence}}

<h3>{{publish element="Accordion Heading"}}</h3>
<div>{{{publish element="Accordion Body"}}}</div>

{{#lastInSequence}}
  </div> <!-- close #accordion -->
  <div>
    <a href="#" class="button">Collapse All</a>
    <a href="#" class="button">Expand All</a>
  </div> 
{{/lastInSequence}}

8. Click Save changes to save the changes to your content layout.
9. Update your preview to check the result.

Feedback Survey

• Congratulations on completing the Terminalfour Handlebars training course!
• Please click on the image below to open our on-line survey and provide your feedback.