Handlebars

The Handlebars output method builds a block's HTML from a template with the control values written into it, and the conditionals and loops of the Handlebars syntax around them.

Basic usage

{{#if control_name}}
  <div class="message">
    {{control_name}}
  </div>
{{/if}}

Available helpers

In addition to default Handlebars helpers, Lazy Blocks provides custom helpers for WordPress-specific functionality.

Every helper except truncate returns a plain string, which Handlebars escapes. Write {{helper ...}} for text and {{{helper ...}}} when the helper produces markup you want rendered.

truncate

Truncates text to a specified length.

{{truncate control_name 100 "true"}}

The cut walks back to the last space before the limit, so a word is kept whole. A run of characters with no space in it is cut at the limit itself. A string already shorter than the limit comes back untouched. This is the one helper whose output is left unescaped, and only when it truncates, so a cut string is printed as markup while an untouched one is escaped.

compare

Compares values for conditional rendering.

{{#compare price ">" 100}}
  <span class="premium">Premium Item</span>
{{/compare}}

typeof compares PHP's type name of the first value with the second, as in {{#compare control_name "typeof" "array"}}. Dropping the operator is allowed, and {{#compare a b}} compares with ===. An operator outside the list makes the comparison false, so the {{else}} branch runs.

math

Performs mathematical operations.

<div class="price">
  ${{math price "*" quantity}}
</div>

Any other operator prints nothing, so a typo in the operator leaves an empty spot rather than an error.

date_i18n

Formats dates using WordPress localization.

<time datetime="{{control_date}}">
  {{date_i18n "F j, Y" control_date}}
</time>

do_shortcode

Processes WordPress shortcodes.

{{{do_shortcode "my_shortcode" this}}}

A content key in the passed object becomes the shortcode's inner content. The block's own code fields, data and hash are dropped, and an array value is encoded as JSON before it reaches the shortcode attribute.

wp_get_attachment_image

Outputs WordPress image with proper srcset.

{{{wp_get_attachment_image image_control "large"}}}

The first argument takes an Image control value or a bare attachment ID. An image added by URL has no id, and the helper falls back to a plain <img> tag built from its url.

var_dump

Dumps a value while you are building the block.

{{{var_dump control_name}}}

The helper returns PHP's var_dump() output as a plain string, so {{var_dump control_name}} shows it escaped and {{{var_dump control_name}}} renders it as markup. Nothing gates it, not WP_DEBUG and not a capability, so a block published with it dumps the value to logged-out visitors on the front end. Take it out before the block goes live.

Adding custom helpers

Create your own Handlebars helpers:

function my_custom_handlebars_helper($handlebars) {
    $handlebars->registerHelper('format_price', function($price) {
        return '$' . number_format($price, 2);
    });
}
add_action('lzb/handlebars/object', 'my_custom_handlebars_helper');

Usage:

<div class="price">
  {{format_price product_price}}
</div>

See lzb/handlebars/object for the object the action passes and for when it fires.