Skip to content

Handlebars.java Helpers

Handlebars.java provides built-in helpers that extend the templating capabilities, making HTML templates dynamic and easier to manage. SØAD Framework also includes custom helpers to further enhance your templates. This chapter explains the most common helpers and custom SØAD-specific helpers available.

Helper Quick Reference

Helper Category What it does
if, unless Built-in Conditional blocks that render or skip markup based on a truthy value.
each Built-in Iterates over collections and renders children for every item.
eq, neq Logical Compare two values for equality or inequality inside inline conditions.
gt, gte, lt, lte Logical Evaluate greater-than and less-than comparisons without writing Java code.
and, or, not Logical Combine boolean expressions to keep template logic concise.
ref_lookup Data Fetch a labeled value from a referenced table or object using a key.
select, option Form Generate dropdown elements populated from tables, collections, or filters.
dateFmt Formatting Render dates using any java.time-style format pattern.
in Logical Check whether a value exists in an array, list, or delimited string.
html Formatting Sanitize rich text, expose basic formatting, and auto-link URLs.
session Context Read an attribute directly from the current HTTP session.
get Context Access keys in ctx.output that contain spaces or special characters.
i18n Localization Resolve a translation key from the active locale resource bundle.

Built-in Handlebars Helpers

Below are basic built-in Handlebars helpers commonly used:

1. Conditional Helpers

  • if: Conditionally renders content.
{{#if loggedIn}}
  <p>Welcome back, {{username}}!</p>
{{/if}}
  • unless: Inverse of if.
{{#unless loggedIn}}
  <p>Please log in.</p>
{{/unless}}

2. Iteration Helper

  • each: Iterates over a collection.
<ul>
  {{#each items}}
    <li>{{this}}</li>
  {{/each}}
</ul>

3. Logical Helpers

  • eq: Checks equality.
{{#eq role "admin"}}
  <p>Admin Panel</p>
{{/eq}}

{{#if (eq role "admin")}}
  <p>Admin Panel</p>
{{/if}}

For more information on the Handlebars templating language and available features, visit the official documentation at https://jknack.github.io/handlebars.java/.

SØAD Custom Helpers

SØAD provides additional custom helpers to simplify common tasks:

1. ref_lookup

Lookup a value from a database table using a given key.

{{ref_lookup key table="tableName"? refs="object"? label="name"? value="id"?}}

Parameters:

  • table: The name of the database table to query.
  • refs: The object containing the key to look up. If table is not specified, then refs must be provided.
  • label: The column to retrieve from the table. Defaults to name. For more than one column, use a pipe-separated list (e.g., label="name|email").
  • value: The column to match against the provided key. Defaults to id. This column is typically the primary key of the table.

Example Usage

{{ref_lookup user.id table="user" label="login_id" value="id"}}

This will look up the login_id for the user with the specified id in the user table.

{{#each users}}
  <p>{{ref_lookup this.id table="user_details" label="full_name" value="user_id"}}</p>
{{/each}}

This iterates over a list of users and retrieves the full_name from the user_details table for each user.

2. select and option

Generate dropdown menus (<select>) and their options.

{{select table="tableName"? refs="object"? filter=""? id=""? name=""? class=""? label="name" value="id" selected=context? required="true"? readonly? sel_text=""?}}

Parameters:

  • table: The name of the database table to query.
  • refs: The object containing the key to look up. If table is not specified, then refs must be provided.
  • filter: Optional filter to apply to the query. e.g., filter="active=1".
  • id: The ID of the <select> element.
  • name: The name of the <select> element.
  • class: CSS class for the <select> element.
  • label: The column to display as the option text. Defaults to name.
  • value: The column to match against the provided key. Defaults to id.
  • selected: The value to pre-select in the dropdown.
  • required: If set to true, the dropdown will be required.
  • readonly: If set, the tag will turn to label.
  • sel_text: Text to display when no option is selected. Defaults to "Please Select".

Generate <option> elements based on the specified table or object.

{{option table="tableName"? refs="object"? filter=""? label="name" value="id" selected=context? required="true"? sel_text=""?}}

Uses the same parameters as select, but generates individual <option> elements instead of a full <select>. This is useful when you need to customize the <select> tag.

Example Usage

{{select table="countries" selected=selected_country label="name" value="code"}}

<select id="sel_country" name="country_code" class="form-select" data-live-search="true" required>
    {{option table="countries" selected=selectedCountry label="name" value="code"}}
</select>

3. dateFmt

Format a date object into a human-readable format.

{{dateFmt registration_date "yyyy-MM-dd"}}

Formats the registration_date into a day/month/year format. If no format is specified, it defaults to dd/MM/yyyy.

4. in

Check if a value exists within a list or a string.

{{#if (in user_role_id allowed_roles)}}
  <p>Access Granted</p>
{{else}}
  <p>Access Denied</p>
{{/if}}

5. html

Sanitize HTML content, convert newlines to <br> and generate anchor for links.

<div>{{html content}}</div>

6. session

Access session attributes.

<p>User ID: {{session "user_id"}}</p>

7. get

Retrieve values from ctx.output by keys containing special characters or spaces.

<p>{{get "complex key-name"}}</p>

8. i18n

Internationalization helper to fetch localized strings. This helper retrieves strings from the i18n resource files (messages.properties) based on the current locale or __locale__ value from session attributes. To use this helper, you need to have a messages.properties file in your resources directory with the appropriate key-value pairs.

{{i18n "welcome.message"}}

Properties files example:

messages.properties
welcome.message=Welcome to SØAD
messages_ms.properties
welcome.message=Selamat datang ke SØAD

To set the locale, you can use the __locale__ session attribute:

request = ctx.getRequest()
request.getSession(True).setAttribute("__locale__", "ms")

Refer to the Multi-language Support section for more details on how to set up and use i18n in SØAD.