Helpers

Helpers are like functions. You can use them to add logic and other robust features to your templates. Helpers are always prefixed with @ so you won't confuse them with variables or sections.

The syntax for helpers in Dust.js is as follows:

{! Inline helper !}
{@helper attribute="value"/}
{! Block helper !} {@helper attribute="value"} ... {/helper}

Inline helpers only output data. They're similar to self-closing HTML tags and they must end with a slash + closing curly bracket.

Block helpers provide a context so you can put HTML, variables, and other helpers inside them. Each block must end with a matching {/helper} tag. For example:

{! Gets the next post and outputs the title !}
{@getNextPost}
  {#post}
    The post title is: {title}<br>
  {/post}
{/getNextPost}

Built-in Helpers

Dust.js ships with a handful of core helpers that aren't documented on this page:

  • {@eq} – strictly equal to
  • {@ne} – not strictly equal to
  • {@gt} – greater than
  • {@lt} – less than
  • {@gte} – greater than or equal to
  • {@lte} – less than or equal to
  • {@math} – perform a mathematical operation
  • {@contextDump} – dump all data from the current context

Please see the official documentation to learn how to use these helpers.

Theme Helpers

{@bodyClass}

Outputs one or more classes that should be applied to the element.

Attributes: none

Examples:

<body class="{@bodyClass/}">

{@content}

Outputs the post content. If no post is specified, the current post context will be used. Must appear with editable="true" exactly one time in every post template.

Attributes:

  • editable – must appear exactly one time in every post template. Used to tell Postleaf which content block is editable.

Examples:

{@content/}
{@content editable="true"/}

{@dynamicImage}

Generates a signed URL for a dynamic image.

Attributes:

  • src (required) – the URL of the image to process.
  • width – Resize proportionally to fit inside this this width.
  • height – Resize proportionally to fit inside this height.
  • crop – The crop coordinates after resizing occurs. Use: {x1},{y1},{x2},{y2}
  • thumbnail – Creates a thumbnail of the exact size. Use: {width} or {width},{height}
  • rotate – The angle of rotation, from 0 to 360.
  • flip – Flip the image horizontally or vertically. Use: h, v, or both
  • grayscale – Set to true to desaturate the image.
  • colorize – Colorize the image. Use: {red},{green},{blue} where each value is 0 to 100%.
  • blur – Apply a blur to the image using this argument as the blur radius.
  • colors – Reduce the image to this many of colors. Uses a dithering effect.
  • quality – The quality of the resulting image. The higher the quality, the larger the file size. The lower the quality, the smaller the file size. Quality has no affect on lossless image formats such as PNG and GIF. Default is 75.

Examples:

{@dynamicImage src="/uploads/2017/03/image.jpg" width="100"/}
{@dynamicImage src="/uploads/2017/03/image.jpg" grayscale="true" blur="10" rotate="90"/}

{@excerpt}

Attributes:

  • content – a string of HTML content to obtain the excerpt from. If omitted, the current post context will be used.
  • paragraphs – the number of paragraphs to use in the excerpt (default 1).
  • words – the number of max number of words to return in the excerpt.
  • tags – a comma-separated list of HTML tags to allow. If omitted, a default list list of tags suitable for an excerpt will be used.

Generates an excerpt. If no content is specified, the current post context will be used.

Examples:

{@excerpt/}
{@excerpt content="<p>...</p>" paragraphs="2" words="50" tags="a,em,strong"/}

{@foot}

Outputs required foot data. This helper must be included just before the </body> tag in every template.

Attributes: none

Examples:

{@foot/}

{@getAdminMenu}

Gets all admin menu items. This helper is used internally by the admin panel.

Attributes: none

Examples:

{@getAdminMenu}
{#groups}
{#items}
<a href="{link}">{label}</a>
{/items}
{/groups}
{/getAdminMenu}

{@getAuthors}

Gets one or more authors.

Attributes:

  • id – the id of a single author to fetch.
  • email – the email of a single author to fetch.
  • username – the username of a single author to fetch.
  • sortBy – the property to sort results by (id, name, email, username, createdAt).
  • sortOrder – the sort order. Use asc for ascending or desc for descending.
  • count – the maximum number of items to return.
  • offset – the offset from which to return items.

Examples:

{@getAuthors count="10" offset="0" sortBy="name" sortOrder="desc"}
  {#authors}
    {name} {email}
  {:else}
    No authors
  {/authors}
{/getAuthors}

{@getElements}

Parses HTML content and returns elements that match the specified selector. Useful for many purposes, including finding an image to display as a visual excerpt or parsing elements or attributes. If no content is specified, the current post context will be used.

Attributes:

  • content – the HTML content to parse. If omitted, the current post context will be used.
  • selector – The CSS selector to use.
  • count – The max number of elements to return.
  • offset – The offset from which to return elements.

Examples:

{@getElements content="<p>...</p>" selector="img" count="1" offset="0"}
  {#elements}
    Name: {name}
    Attr: {attributes.src}
    HTML: {html}
  {:else}
    No matches
  {/elements}
{/getElements}

{@getNextPost}

Gets the next post. If no post is specified, the current post context will be used.

Attributes:

  • post – the target post object. If omitted, the current post context will be used.
  • previous – set to true to return the previous post instead of the next post.

Examples:

{@getNextPost}
  {#post}
    {title}
  {:else}
    No next post
  {/post}
{/getNextPost}

{@getNextPost post=post previous="true"}
  ...
{/getNextPost}

{@getPosts}

Gets one or more posts.

Attributes:

  • id – the id of a single post to fetch.
  • slug – the slug of a single post to fetch.
  • sortBy – the property to sort results by (id, slug, title, createdAt).
  • sortOrder – the sort order. Use asc for ascending or desc for descending.
  • count – the maximum number of items to return.
  • offset – the offset from which to return items.

Examples:

{@getPosts count="10" offset="0" sortBy="name" sortOrder="desc"}
  {#posts}
    {title}
  {:else}
    No posts
  {/posts}
{/getPosts}

{@getRelatedPosts}

Gets posts that are related to the source post. If no post is specified, the current post context will be used.

Attributes:

  • post - the target post object.
  • count - the max number of items to return.
  • offset - the offset from which to return items.

Examples:

{@getRelatedPosts}
  {#posts}
    {title}
  {:else}
    No related posts
  {/posts}
{/getRelatedPosts}

{@getRelatedPosts post=post count="10" offset="0"}
  ...
{/getRelatedPosts}

{@getTags}

Gets one or more tags.

Attributes:

  • id – the id of a single tag to fetch.
  • slug – the slug of a single tag to fetch.
  • sortBy – the property to sort results by (id, slug, name, createdAt).
  • sortOrder – the sort order. Use asc for ascending or desc for descending.
  • count – the maximum number of items to return.
  • offset – the offset from which to return items.

Examples:

{@getTags slug="favorites"}
  {#tags}
    {name}
  {:else}
    No tags
  {/tags}
{/getTags}

{@getTags count="10" offset="0" sortBy="name" sortOrder="desc"}
  ...
{/getTags}

{@head}

Outputs required head data.

Attributes:

  • jsonLD – set to false to disable JSON-LD output.
  • openGraph – set to false to disable OpenGraph output.
  • twitterCard – set to false to disable Twitter Card output.

Examples:

{@head/}
{@head jsonLD="false" openGraph="false" twitterCard="false"/}

{@navigation}

Gets the site's navigation.

Attributes: none

Examples:

{@navigation}
  <a class="{?isCurrent}current{/isCurrent}" href="{@url path=link/}">
    {label}
  </a>
{/navigation}

{@postClass}

Outputs one or more classes that should be applied to posts in your theme.

Attributes:

  • post – the target post object. If no post is specified, the current post context will be used.

Examples:

<article class="{@postClass/}">

{@postCount}

Returns the number of posts for a given author or tag. Posts can be filtered by any of the available flags using a true or false value. If an argument is omitted, the flag will be ignored.

  • author – set to a username to only count posts from that author.
  • tag – set to a tag slug to only count posts with that tag.
  • status – set to draft, published, pending, or rejected to only count posts with that status.
  • isFeatured – set to true to only count featured posts.
  • isPage – set to true to only count pages.
  • isSticky – set to true to only count sticky posts.
  • isPublic – set to true to only count posts that are publicly visible.

Examples:

{@postCount/}
{@postCount author="bob"/}
{@postCount tag="favorites"/}
{@postCount author="bob" tag="favorites"/}
{@postCount isPublic="true"/}

{@isPublic}

Determines if a post is publicly visible (i.e. published but not scheduled).

Attributes:

  • post – the target post object. If no post is specified, the current post context will be used.

Examples:

{@isPublic}
  Post is public
{:else}
  Post is not public
{/isPublic}

{@readingTime}

Returns the approximate number of minutes to read the specified content. If no content is specified, the current post context will be used.

Attributes:

  • content – the content to use to estimate the reading time.
  • wordsPerMinute – the number of words per minute to base the calculation on (default 225).

Examples:

{@readingTime/}
{@readingTime content="Lorem ipsum..."/}
{@readingTime wordPerMinute="225"/}

{@title}

Outputs the post title. If no post is specified, the title will be fetched from the current context. Must appear with editable="true" exactly one time in every post template.

Arguments:

  • editable – must appear exactly one time in every post template. Used to tell Postleaf which title block is editable.

Examples:

{@title/}
{@title editable="true"/}

Utility Helpers

{@date}

Outputs a date in the specified format.

Attributes:

  • date - the date to output. If omitted, the current date and time will be used.
  • format - the format to use to output the date. Format can be any format supported by Moment.js. If omitted, YYYY-MM-DD HH:mm:ss will be used.
  • relative - Set to true to output a relative date (e.g. "7 days ago").
  • timeZone - the time zone to convert the date to. If omitted, the time zone configured in settings will be used.

Examples:

{@date date=publishedAt format="YYYY-MM-DD"/}
{@date date="2017-01-02 12:00:00" format="ddd, hA"/}
{@date date=publishedAt format="relative"/}

{@dateCompare}

Compares two dates.

Attributes:

  • key – The first date to compare.
  • value – The second date to compare.
  • operand – The type of comparison to perform. Can be <, <=, >, >=, between, or = (default).

Examples:

{@dateCompare key=publishedAt operand="<" value="now"}
Date is in the past.
{:else}
Date is in the future.
{/dateCompare}
{@dateCompare key=publishedAt operand="between" start="2016-01-01" end="2016-12-31"}
...
{/dateCompare}

Notes:

{@formatBytes}

Formats bytes into a more readable format.

Attributes:

  • bytes – the target size in bytes.

Examples:

{@formatBytes bytes="32000000"/}
==> 32MB

{@formatNumber}

Formats a number.

Attributes:

  • number – the target number.
  • places – number of decimal places to use (default 0).
  • decimal – the decimal separator (default .)
  • thousands – the thousands separator (default ,)

Examples:

{@formatNumber number="25000"/}
{@formatNumber number="50.75" places="2"/}
{@formatNumber number="25000" decimal="," thousands=" "/}

{@formatUrl}

Formats a URL based on the specified arguments. If no arguments are set, only the hostname will be displayed.

Attributes:

  • url – the URL to format.
  • protocol – set to true to show the protocol, e.g. https:// (default false).
  • hostname – set to true to output the hostname (default true).
  • path – set to true to output the path (default false).
  • search – set to true to output the query (search) string, e.g. ?page=2 (default false).
  • hash – set to true to output the hash, e.g. #hash (default false).

Examples:

{@formatUrl url="https://example.com/"/}
==> example.com

{@formatUrl url="https://example.com/path/to/page.html" path="true" /}
==> example.com/path/to/page.html

{@i18n}

Outputs a localized language term.

Attributes:

  • term – the key of the desired language term.
  • type – the type of key. Can be term (default), symbol, or meta.
  • [placeholders] – If a term has a [placeholder], you can set its value by adding an attribute with the same name as the placeholder.

Examples:

{@i18n term="term"/}
{@i18n term="term_with_[this]_[that]" this="place" that="holders"/}
{@i18n term="decimal" type="symbol"/}
{@i18n term="thousands" type="symbol"/}
{@i18n term="name" type="meta"}
{@i18n term="term_with_[this]" this="<code>HTML</code>" allowHtml="true"/}

{@in}

Checks an array or a CSV string for the given value.

Attributes:

  • key – the key to check for.
  • value – the values to check. Can be an array or a comma-separated string.

Examples:

{@in key=User.role value="editor,contributor,admin"}
Key is in value
{:else}
Key is not in value
{/in}

{@plural}

Returns a plural or non-plural string based on a number.

Attributes:

  • count – the target count.
  • none – the output when count is zero.
  • one – the output when count is one.
  • many – the output when count is greater than one. Use % as a placeholder for count.

Examples:

{@plural count="2" none="No posts" one="One post" many="% posts"/}

{@postleafVersion}

Outputs the current Postleaf version number.

Attributes: none

Examples:

{@postleafVersion/}

{@truncateWords}

Truncates text after a certain number of characters or words.

Attributes:

  • text – the text to truncate.
  • chars – the max number of characters to output (default 140). Only used if words isn't set.
  • words – the max number of words to output.
  • append – optional string to append if the text is longer than the max (default )

Examples:

{@truncateWords text="Lorem ipsum..." chars="140"/}
{@truncateWords text="Lorem ipsum..." words="20" append="…"/}

{@url}

Generates a URL. You should always use this helper when outputting URLs. This is the only way to guarantees that URLs will be correct when themes, settings, or environmental variables change.

Attributes vary depending on the type of URL you're generating:

  • type – the type of URL to generate (default raw). 
    • admin – generates a URL to the admin panel.
    • api – generates a URL to the API.
    • author – generates a URL to an author page. Set the page attribute to link to a specific page.
    • blog – generates a link to the blog. The blog URL will not be the same as the homepage if a custom homepage is used. Set the page attribute to link to a specific page.
    • feed – generates a feed URL. Set the format attribute to json or rss (default) to change the feed format.
    • post – generates a post URL. The slug attribute is required for this type of URL.
    • raw – generates a raw URL to the website.
    • search – generates a URL to a search page. Set the page attribute to link to a specific page. Set the search attribute to set a search query.
    • tag – generates a link to a tag page. The slug attribute is required for this type of URL. Set the page attribute to link to a specific page.
    • theme – generates a URL to the current theme's folder. Set the path attribute to append a path (useful for linking to images, scripts, stylesheets, etc.)
  • path – a path to append to the URL. Only supported for raw, admin, api, and theme types.
  • absolute – set to true to output an absolute URL.
  • query – a query string to append to the URL.
  • hash – a hash to append to the URL.

Examples:

{@url/}
{@url path="/path/to/file.ext"/}
{@url type="theme" slug="assets/js/script.js"/}
{@url type="post" slug="post-slug"/}
{@url type="tag" slug="tag-slug"/}
{@url type="search" search="some query"/}
{@url type="author" username="bob" page="2"/}

{@urlCompare}

Compares two URLs.

Attributes:

  • to – a URL. If omitted, the current URL will be used.
  • url – the URL to compare against.

Examples:

{@urlCompare url="/path/to/compare"/}
...
{/urlCompare}
{@urlCompare url="/path/to/compare" to="/another/path"}
...
{/urlCompare}
{@urlCompare url="/path/to/compare"/}
...
{:else}
...
{/urlCompare}