README.md

handlebars-concat

String, Array and Object concatenator helper for handlebars-rust

Quick Start

Developed and tested with handlebars-rust v4.4.0.
Versions 0.1.* are compatible with handlebars 4.
Versions 0.2.* are compatible with handlebars 5. (Thanks to campeis) Versions 0.3.* are compatible with handlebars 6.

Registration

    use handlebars::Handlebars;
    use handlebars_concat::HandlebarsConcat;
    
    let mut h = Handlebars::new();
    h.register_helper("concat", Box::new(HandlebarsConcat));

Behavior

The helper is looking for multiple arguments of type string, array or object. Arguments are being added to an output buffer and returned altogether as string.

The helper has few parameters modifying the behavior slightly. For example distinct=true eliminates duplicate values from the output buffer, while quotes=true in combination with single_quote=true wraps the values in quotation marks. See Parameters for more.

String

String arguments are added directly to the output buffer.
As of 0.1.3 strings could be handled in one of two ways:

1. By default strings are added to the output buffer without modification (other than the quotation mark modifiers).
2. If you add a block template and use the render_all parameter, strings will be passed as {{this}} to the block template.

The block template rendering is disabled by default for backward compatibility.

Array

Array arguments are iterated and added as individual strings to the output buffer.
As of 0.1.3 arrays could be handled in one of two ways:

1. By default array values are added as individual strings to the output buffer without modification (other than the quotation mark modifiers).
2. If you add a block template and use the render_all parameter, array values are passed as {{this}} to the block template.

The block template rendering is disabled by default for backward compatibility.

Object

Object arguments could be handled two different ways:

1. By default only the object keys are being used and the values are ignored.
2. If you add a block template the helper will use it to render the object value and
   concatenate it as string to the output buffer.

Object rendering results are subject to distinct, quotes and single_quote modifier parameters, just like strings and arrays.

Parameters

The helper accepts several hash arguments to modify the concatenation behavior:

• separator: Set specific string to join elements with. Default is ","
• distinct: Eliminate duplicates upon adding to output buffer
• quotes: Wrap each value in double quotation marks
• single_quote: Modifier of quotes to switch to single quotation mark instead
• render_all: Render all values using the block template, not just object values

Examples

Example with string literals:

{{concat "One" "Two" separator=", "}}

Result: One, Two

---

{{concat "One" "Two" separator=", " quotes=true}}

Result: "One", "Two"

---

Where s is "One", arr is ["One", "Two"] and obj is {"Three":3}

{{concat s arr obj separator=", " distinct=true}}

Result: One, Two, Three

---

Where s is "One", arr is ["One", "Two"] and obj is {"key0":{"label":"Two"},"key1":{"label":"Three"},"key2":{"label":"Four"}}:

{{#concat s arr obj separator=", " distinct=true}}{{label}}{{/concat}}

Result: One, Two, Three, Four

---

Where s is "One", arr is ["One", "Two"] and obj is {"key0":{"label":"Two"},"key1":{"label":"Three"},"key2":{"label":"Four"}}

{{#concat s arr obj separator=", " distinct=true render_all=true}}<{{#if label}}{{label}}{{else}}{{this}}{{/if}}/>{{/concat}}

Result: <One/>, <Two/>, <Three/>, <Four/>

---

License

This library (handlebars-concat) is open sourced under the BSD 2 License.