function (context, options) {
  // TODO (1): read the "primaryId" named parameter, mirroring the utility line below.
  var primaryNavId = /* TODO: options.hash("primaryId") */;
  var utilityNavId = options.hash("utilityId");

  if (!primaryNavId || !utilityNavId) {
    log.warn("combineNav helper requires both 'primaryId' and 'utilityId' parameters");
    return "";
  }

  try {
    // TODO (2): pass primaryNavId into process(...), mirroring the utility line below.
    var primaryHtml = apis.getNavigation().process(parseInt(/* TODO: primaryNavId */, 10));
    var utilityHtml = apis.getNavigation().process(parseInt(utilityNavId, 10));

    return "<nav class=\"site-nav\">"
         +   "<div class=\"utility-nav\">" + utilityHtml + "</div>"
         +   "<div class=\"primary-nav\">" + primaryHtml + "</div>"
         + "</nav>";
  } catch (e) {
    log.error("Error processing navigation objects: " + e);
    return "";
  }
}

{{combineNav primaryId="259" utilityId="260"}}

function (context, options) {
  // TODO (1): read the "id" named parameter with options.hash(...).
  var navId = options.hash(/* TODO: "id" */);
  if (!navId) {
    log.warn("sectionAwareNav helper requires an 'id' parameter");
    return "";
  }

  try {
    var navHtml = apis.getNavigation().process(parseInt(navId, 10));

    // TODO (2): resolve the current section being published via the Publish API.
    var currentSection = apis.getSection()./* TODO: get() */;

    if (!currentSection.exists()) {
      log.warn("Current section could not be resolved");
      return navHtml;
    }

    // TODO (3): read the current section's depth in the tree.
    var level = currentSection./* TODO: getLevel() */;
    var wrapperClass = level <= 2 ? "nav-top-level" : "nav-sub-level";

    return "<div class=\"" + wrapperClass + "\">" + navHtml + "</div>";
  } catch (e) {
    log.error("Error processing section-aware navigation: " + e);
    return "";
  }
}

{{yournameSectionAwareNav id="259"}}

Sorting with Custom Helpers

A practical guide for Terminalfour administrators. This manual assumes you are already comfortable creating and editing Content Types, Content Layouts, and Page Layouts, and that you have written or edited at least one Custom Handlebars Helper before. If Custom Helpers are new to you, review the "Navigation Objects and Custom Helpers" module first, then come back here.

What you'll learn

• Why sorting belongs in the Custom Helper, not in your markup
• How JavaScript's Array.prototype.sort() and comparator functions work
• Three hands-on exercises: an alphabetical sort, a date sort, and sorting into a custom (non-alphabetical) order
• The small gotchas that trip people up: default string sorting and date parsing

Why sort inside a Custom Helper?

Handlebars is deliberately logic-light. It has no built-in "sort this list" expression, and that is by design: templates are for presentation, not data manipulation. When you need a list rendered in a particular order (news by date, events by date, links A to Z), the clean place to do that work is a Custom Helper, where you have the full Publish API and plain JavaScript at your disposal.

The pattern is always the same three steps:

1. Get your data (an array of items, usually from the Publish API via apis).
2. Sort the array with .sort() and a comparator that describes the order you want.
3. Build and return the output string.

The one rule of comparators

Every sort is driven by a comparator function that receives two items, a and b, and returns a number:

• a negative number means "a comes before b"
• a positive number means "a comes after b"
• zero means "leave their order unchanged"

Get that return value right and every kind of sort - text, number, date - follows the same shape. The exercises below each build one comparator.

A quick warning about the default sort. Calling .sort() with no comparator converts everything to strings and compares character codes. That is why [10, 2, 1].sort() gives you [1, 10, 2] - "10" sorts before "2" because the character "1" comes before "2". Uppercase letters also sort before lowercase ones. Always pass an explicit comparator.

Exercise 1 - Alphabetical sort (text)

Your first task is the most common sorting job of all: take the content items in a section and list them alphabetically by one of their elements. Rather than hard-code the order into the helper, you will pass in which element to sort on and which direction, so the same helper works for any content type.

Imagine a content type called Programme that already exists in your instance, with a Heading element (and others such as Name, Description). A section contains several Programme items. You want to output them A to Z by Heading. Because Heading is text, the reliable comparison tool is String.prototype.localeCompare(), which handles casing and accented characters correctly - far better than the < and > operators.

The helper reads two hash parameters so the call site stays in control:

• element - the name of the element to sort on (for example Heading)
• order - asc for A to Z, desc for Z to A

Create a Custom Helper named sortByElement and paste the code below. Complete the three TODOs. Each has its solution directly beneath it, commented out - uncomment those lines to reveal the answer.

function (context, options) {

  // Read the call-site parameters. {{{sortByElement element="Heading" order="asc"}}}
  var elementName = options.hash("element");
  var order       = options.hash("order") || "asc";

  if (!elementName) {
    log.warn("sortByElement: no 'element' parameter was passed");
    return "";
  }

  // Get the content items in the current section (a Java list).
  var contentList = apis.getSection().listContent();

  // TODO 1: Build a plain JavaScript array of items, each holding the sort
  //         value (the chosen element, as text) and the heading to display.
  //         Read an element's text value with:
  //         apis.getContent().get(id).getElement(elementName).toTextElement().process()
  // -------------------------------------------------------------------
  // SOLUTION 1 (uncomment the block below):
  // var items = [];
  // for (var i = 0; i < contentList.length; i++) {
  //   var contentItem = apis.getContent().get(contentList[i].getId());
  //   var value = contentItem.getElement(elementName).toTextElement().process();
  //   items.push({ value: value, item: contentItem });
  // }
  // -------------------------------------------------------------------

  // TODO 2: Sort the array alphabetically by value, honouring the order
  //         parameter. localeCompare with { sensitivity: "base" } gives a
  //         human-friendly A to Z; flip the sign when order is "desc".
  // -------------------------------------------------------------------
  // SOLUTION 2 (uncomment the block below):
  // items.sort(function (a, b) {
  //   var result = a.value.localeCompare(b.value, undefined, { sensitivity: "base" });
  //   return order === "desc" ? -result : result;
  // });
  // -------------------------------------------------------------------

  // TODO 3: Build an HTML list of the sorted values and return it.
  // -------------------------------------------------------------------
  // SOLUTION 3 (uncomment the two lines below):
  // var rows = items.map(function (x) { return "<li>" + x.value + "</li>"; });
  // return "<ul>" + rows.join("") + "</ul>";
  // -------------------------------------------------------------------

  // Remove this line once you have completed the TODOs above.
  return "Not implemented yet";
}

Call it from a layout with:

{{{sortByElement element="Heading" order="asc"}}}

Expected result: the section's Programme items listed A to Z by their Heading value. Switch the call to order="desc" and the same list comes back Z to A - without touching the helper code.

What to notice:

• All the ordering logic lives in one comparator; the order parameter just flips its sign. That is the whole trick to making a sort reversible.
• Element values from the Publish API arrive as text, so localeCompare is exactly the right tool. The { sensitivity: "base" } option keeps mixed-case headings in the order a human reader expects, rather than pushing lowercase entries to the end.
• Because the element name is a parameter, the same sortByElement helper sorts by Name, Heading, or any other text element - you decide at the call site.

Exercise 2 - Date sort (publish date / event date)

Now sort the section's content items by a Date element instead of a text one. Just like Exercise 1, you pass in which element to read and which direction to sort, so the same helper works for any content type that has a date field.

Sorting by date is the same comparator pattern as sorting text, with one extra step: you must turn each date value into something numeric before you compare. The easiest approach is to build a JavaScript Date from the element's value and call .getTime(), which gives you a millisecond number. Subtract those and you have your comparator.

Reading a Date element from the Publish API is slightly different from reading text: use getElement(name).toDateElement().getDate(). That returns the date value, and calling .toString() on it gives you a string you can hand to new Date(...).

The helper reads two hash parameters:

• element - the name of the Date element to sort on (for example Start Date)
• order - asc for soonest first, desc for most recent first

Create a Custom Helper named sortByDate and complete the three TODOs.

function (context, options) {

  // Read the call-site parameters. {{{sortByDate element="Start Date" order="asc"}}}
  var elementName = options.hash("element");
  var order       = options.hash("order") || "asc";

  if (!elementName) {
    log.warn("sortByDate: no 'element' parameter was passed");
    return "";
  }

  // Get the content items in the current section (a Java list).
  var contentList = apis.getSection().listContent();

  // TODO 1: Build a plain JavaScript array of items, each holding the date value
  //         as a JS Date, plus a label to display. Read a Date element with:
  //         apis.getContent().get(id).getElement(elementName).toDateElement().getDate()
  //         Call .toString() on that value and pass it to new Date(...).
  //         For the label, read the item's Name element as text.
  // -------------------------------------------------------------------
  // SOLUTION 1 (uncomment the block below):
  // var items = [];
  // for (var i = 0; i < contentList.length; i++) {
  //   var contentItem = apis.getContent().get(contentList[i].getId());
  //   var rawDate = contentItem.getElement(elementName).toDateElement().getDate();
  //   var label   = contentItem.getElement("Name").toTextElement().process();
  //   items.push({ date: new Date(rawDate.toString()), label: label });
  // }
  // -------------------------------------------------------------------

  // TODO 2: Sort the array by date, honouring the order parameter.
  //         Subtract the two getTime() values for ascending (soonest first),
  //         and flip the sign when order is "desc".
  // -------------------------------------------------------------------
  // SOLUTION 2 (uncomment the block below):
  // items.sort(function (a, b) {
  //   var result = a.date.getTime() - b.date.getTime();
  //   return order === "desc" ? -result : result;
  // });
  // -------------------------------------------------------------------

  // TODO 3: Build an HTML list. Show each label next to its date.
  // -------------------------------------------------------------------
  // SOLUTION 3 (uncomment the two lines below):
  // var rows = items.map(function (x) { return "<li>" + x.label + " - " + x.date.toDateString() + "</li>"; });
  // return "<ul>" + rows.join("") + "</ul>";
  // -------------------------------------------------------------------

  // Remove this line once you have completed the TODOs above.
  return "Not implemented yet";
}

Call it from a layout with:

{{{sortByDate element="Start Date" order="asc"}}}

Expected result: the section's items listed by their Start Date, soonest first. Switch the call to order="desc" and the most recent date comes first instead - without touching the helper code.

What to notice:

• Never compare dates with subtraction until they are numbers. new Date(...).getTime() is what turns a date into a millisecond value the comparator can subtract.
• A Date element is read with toDateElement().getDate(), not toTextElement(). That is the one difference from Exercise 1; everything else - the parameters, the reversible comparator, the list output - is the same shape.
• As in Exercise 1, the order parameter simply flips the comparator's sign, so one helper covers both ascending and descending.

Exercise 3 - Custom order (reordering a content report's "Content" column)

The first two exercises put things in a calculated order - A to Z, or earliest date. But sometimes there is no rule to calculate; you simply want a specific, hand-picked order that suits how the content reads. This exercise tackles exactly that, using a real report helper.

The helper below builds a table of every content item in a section. Its Content column lists each element as Name of the element: value. Those element names come from contentItem.getElements(), which hands them back in alphabetical key order - so the column always reads like this:

Academic Program: ...
Date: ...
Description: ...
End Date: ...
Heading: ...
Main body: ...
Name: ...
Start Date: ...
Video: ...

Alphabetical is rarely the order a reader wants. "Name" and "Heading" probably belong at the top; "Start Date" should sit next to "End Date", not be separated by "Main body". The fix is to sort the keys array into an order you define before the loop that prints them.

The technique: keep an array that lists the element names in your preferred order, then sort keys by each key's index in that array. Comparing those index numbers is just a numeric sort - subtract one position from the other, exactly the a - b shape the comparator rule describes.

Paste the helper below into a new Custom Helper (for example contentReport), point it at a section that uses a content type with these elements, and complete the TODOs. The report-building TODOs (1-22) are already filled in so you can focus on the sorting TODOs, labelled S1 and S2.

function (context, options) {

  //10. Add a new column labeled "Content".
  let contentReport = `<table class="table-striped">
                       <thead>
                         <tr>
                           <th>Content Id</th>
                           <th>Content Type Id</th>
                           <th>Expiry Date</th>
                           <th>Last Modified Date</th>
                           <th>Publish Date</th>
                           <th>Version</th>
                           <th>Content</th>
                          </tr>
                        </thead>`;

  //1. Get the content as a list by providing the section Id.
  let contentList = apis.getSection().listContent(context);

  // S1. TODO: Define the order you want the elements to appear in.
  //     List the element names exactly as they appear (spaces and casing matter).
  //     Any element NOT in this list will be handled by the comparator in S2.
  // -------------------------------------------------------------------
  // SOLUTION S1 (uncomment the block below):
  // const elementOrder = [
  //   "Name",
  //   "Heading",
  //   "Description",
  //   "Main body",
  //   "Academic Program",
  //   "Start Date",
  //   "End Date",
  //   "Date",
  //   "Video"
  // ];
  // -------------------------------------------------------------------

  for (let i = 0; i < contentList.length; i++) {

    //2. Get the content Id.
    let contentId = contentList[i].getId();

    //3. Get the Content Item.
    let contentItem = apis.getContent().get(contentId);

    //4. Get the Content Type Id.
    let contentTypeId = contentItem.getContentTypeId();

    //5. Get the expiry date.
    let expiryDate = contentItem.getExpiryDate();

    //6. Get the last modified date.
    let lastModified = contentItem.getLastModified();

    //7. Get the publish date.
    let publishDate = contentItem.getPublishDate();

    //8. Get the version.
    let version = contentItem.getVersion();

    //11. Get the elements.
    let elements = contentItem.getElements();

    //12. Convert the keys of the elements to an array and store them in keys.
    const keys = elements.keySet().toArray();

    // S2. TODO: Sort the keys into your preferred order (from S1) instead of alphabetical.
    //     Sort by each key's position in elementOrder. indexOf returns the position,
    //     or -1 when the key is not listed. Subtracting the two positions is a plain
    //     numeric sort.
    //     Tip: the || fallback below keeps any unlisted elements in alphabetical order
    //     at the end, instead of jumping to the front because indexOf returned -1.
    // -----------------------------------------------------------------
    // SOLUTION S2 (uncomment the block below):
    // keys.sort(function (a, b) {
    //   let posA = elementOrder.indexOf(a);
    //   let posB = elementOrder.indexOf(b);
    //   if (posA === -1) posA = elementOrder.length;
    //   if (posB === -1) posB = elementOrder.length;
    //   return (posA - posB) || a.localeCompare(b);
    // });
    // -----------------------------------------------------------------

    //Variable used to store the content.
    let content = '';

    //Iterate through the elements in the (now sorted) key order.
    for (let j = 0; j < keys.length; j++) {

      //Look the element up by its key so it stays paired with the sorted order.
      let element = elements.get(keys[j]);

      //14. Check if the element is a date element.
      if (element.isDateElement()) {
        //15. Get the value of the Date element. Format: <p>Key: Value</p>
        content += `<p>${keys[j]}: ${element.toDateElement().getDate().toString()}</p>`;
      }

      //16. Check if the element is a text element.
      else if (element.isTextElement()) {
        //17. Get the value of the text element. Format: <p>Key: Value</p>
        content += `<p>${keys[j]}: ${element.toTextElement().process()}</p>`;
      }

      //19. Check if the element is a list element.
      else if (element.isListElement()) {
        //20. Get the list entries.
        let entries = element.toListElement().getValue().getEntries();
        //Variable used to store the selected item in the list.
        let selected;
        //21. Iterate through the list entries and store the selected value.
        for (let k = 0; k < entries.length; k++) {
          if (entries[k].isSelected()) {
            selected = entries[k].getValue();
          }
        }
        //22. Get the value of the list element. Format: <p>Key: Value</p>
        content += `<p>${keys[j]}: ${selected}</p>`;
      }

    }

    //18 + 9. Build the report row by inserting the variables.
    contentReport += `<tr>
                        <td>${contentId}</td>
                        <td>${contentTypeId}</td>
                        <td>${expiryDate}</td>
                        <td>${lastModified}</td>
                        <td>${publishDate}</td>
                        <td>${version}</td>
                        <td>${content}</td>
                      </tr>`;

  }

  contentReport += `</table>`;

  return contentReport;
}

Call it from a layout with (pass the section Id you want to report on):

{{{contentReport 8536}}}

Expected result: before you complete S1 and S2, the Content column reads alphabetically - Academic Program, Date, Description, End Date, Heading, Main body, Name, Start Date, Video. After uncommenting both solutions it follows your list instead: Name, Heading, Description, Main body, Academic Program, Start Date, End Date, Date, Video.

What to notice:

• The two nested loops now share the sorted keys array, and we fetch each element with elements.get(keys[j]) so the value always matches the key we are printing. The original code read values[i] by position, which would fall out of step the moment you reorder the keys - this is the small but important change that makes sorting safe here.
• indexOf drives the whole thing: it turns "where should this element go" into a number, and once you have numbers you are back to an ordinary numeric comparator.
• The || a.localeCompare(b) fallback means you do not have to list every element name. Anything you leave out simply lands at the end in alphabetical order, so the report never breaks if a new element is added to the content type later.

Taking it further

All three exercises read live content from the Publish API and sort it with a comparator you control. The comparator is always the part that decides the order - swap it out and the same helper produces a different arrangement. Here is the Exercise 1 shape again for quick reference, sorting the current section's items alphabetically by their Name element:

function (context, options) {

  // 1. Get the content items in the current section.
  var list = apis.getSection().listContent();

  // 2. Map each one to a small object holding just what you need to sort and display.
  var items = [];
  for (var i = 0; i < list.length; i++) {
    var item  = apis.getContent().get(list[i].getId());
    var title = item.getElement("Name").toTextElement().process();
    items.push({ title: title, raw: item });
  }

  // 3. Sort with the same comparator pattern you practised above.
  items.sort(function (a, b) {
    return a.title.localeCompare(b.title, undefined, { sensitivity: "base" });
  });

  // 4. Build and return your markup.
  var rows = items.map(function (x) { return "<li>" + x.title + "</li>"; });
  return "<ul>" + rows.join("") + "</ul>";
}

Change the comparator and you change the order - everything else stays the same.

Quick reference

• Text, A to Z: a.localeCompare(b, undefined, { sensitivity: "base" })
• Date, soonest first: new Date(a).getTime() - new Date(b).getTime()
• Custom order: orderArray.indexOf(a) - orderArray.indexOf(b) (guard the -1 case)
• Reverse any sort: negate the comparator result (as the order parameter does), swap a and b, or call .reverse() afterwards
• Never rely on a bare .sort() - always pass a comparator