handlebars/helpers/
mod.rs

Help
1use crate::context::Context;
2use crate::error::{RenderError, RenderErrorReason};
3use crate::json::value::ScopedJson;
4use crate::output::Output;
5use crate::registry::Registry;
6use crate::render::{do_escape, indent_aware_write, Helper, RenderContext};
7
8pub use self::helper_each::EACH_HELPER;
9pub use self::helper_if::{IF_HELPER, UNLESS_HELPER};
10pub use self::helper_log::LOG_HELPER;
11pub use self::helper_lookup::LOOKUP_HELPER;
12pub use self::helper_raw::RAW_HELPER;
13pub use self::helper_with::WITH_HELPER;
14
15/// A type alias for `Result<(), RenderError>`
16pub type HelperResult = Result<(), RenderError>;
17
18/// Helper Definition
19///
20/// Implement `HelperDef` to create custom helpers. You can retrieve useful information from these arguments.
21///
22/// * `&Helper`: current helper template information, contains name, params, hashes and nested template
23/// * `&Registry`: the global registry, you can find templates by name from registry
24/// * `&Context`: the whole data to render, in most case you can use data from `Helper`
25/// * `&mut RenderContext`: you can access data or modify variables (starts with @)/partials in render context, for example, @index of #each. See its document for detail.
26/// * `&mut dyn Output`: where you write output to
27///
28/// By default, you can use a bare function as a helper definition because we have supported `unboxed_closure`.
29/// If you have stateful or configurable helper, you can create a struct to implement `HelperDef`.
30///
31/// ## Define an inline helper
32///
33/// ```
34/// use handlebars::*;
35///
36/// fn upper(h: &Helper< '_>, _: &Handlebars<'_>, _: &Context, rc:
37/// &mut RenderContext<'_, '_>, out: &mut dyn Output)
38///     -> HelperResult {
39///    // get parameter from helper or throw an error
40///    let param = h.param(0).and_then(|v| v.value().as_str()).unwrap_or("");
41///    out.write(param.to_uppercase().as_ref())?;
42///    Ok(())
43/// }
44/// ```
45///
46/// ## Define block helper
47///
48/// Block helper is like `#if` or `#each` which has a inner template and an optional *inverse* template (the template in else branch). You can access the inner template by `helper.template()` and `helper.inverse()`. In most cases you will just call `render` on it.
49///
50/// ```
51/// use handlebars::*;
52///
53/// fn dummy_block<'reg, 'rc>(
54///     h: &Helper<'rc>,
55///     r: &'reg Handlebars<'reg>,
56///     ctx: &'rc Context,
57///     rc: &mut RenderContext<'reg, 'rc>,
58///     out: &mut dyn Output,
59/// ) -> HelperResult {
60///     h.template()
61///         .map(|t| t.render(r, ctx, rc, out))
62///         .unwrap_or(Ok(()))
63/// }
64/// ```
65///
66/// ## Define helper function using macro
67///
68/// In most cases you just need some simple function to call from templates. We have a `handlebars_helper!` macro to simplify the job.
69///
70/// ```
71/// use handlebars::*;
72///
73/// handlebars_helper!(plus: |x: i64, y: i64| x + y);
74///
75/// let mut hbs = Handlebars::new();
76/// hbs.register_helper("plus", Box::new(plus));
77/// ```
78///
79pub trait HelperDef {
80    /// A simplified api to define helper
81    ///
82    /// To implement your own `call_inner`, you will return a new `ScopedJson`
83    /// which has a JSON value computed from current context.
84    ///
85    /// ### Calling from subexpression
86    ///
87    /// When calling the helper as a subexpression, the value and its type can
88    /// be received by upper level helpers.
89    ///
90    /// Note that the value can be `json!(null)` which is treated as `false` in
91    /// helpers like `if` and rendered as empty string.
92    fn call_inner<'reg: 'rc, 'rc>(
93        &self,
94        _: &Helper<'rc>,
95        _: &'reg Registry<'reg>,
96        _: &'rc Context,
97        _: &mut RenderContext<'reg, 'rc>,
98    ) -> Result<ScopedJson<'rc>, RenderError> {
99        Err(RenderErrorReason::Unimplemented.into())
100    }
101
102    /// A complex version of helper interface.
103    ///
104    /// This function offers `Output`, which you can write custom string into
105    /// and render child template. Helpers like `if` and `each` are implemented
106    /// with this. Because the data written into `Output` are typically without
107    /// type information. So helpers defined by this function are not composable.
108    ///
109    /// ### Calling from subexpression
110    ///
111    /// Although helpers defined by this are not composable, when called from
112    /// subexpression, handlebars tries to parse the string output as JSON to
113    /// re-build its type. This can be buggy with numrical and other literal values.
114    /// So it is not recommended to use these helpers in subexpression.
115    fn call<'reg: 'rc, 'rc>(
116        &self,
117        h: &Helper<'rc>,
118        r: &'reg Registry<'reg>,
119        ctx: &'rc Context,
120        rc: &mut RenderContext<'reg, 'rc>,
121        out: &mut dyn Output,
122    ) -> HelperResult {
123        match self.call_inner(h, r, ctx, rc) {
124            Ok(result) => {
125                if r.strict_mode() && result.is_missing() {
126                    Err(RenderError::strict_error(None))
127                } else {
128                    // auto escape according to settings
129                    let output = do_escape(r, rc, result.render());
130
131                    indent_aware_write(&output, rc, out)?;
132
133                    Ok(())
134                }
135            }
136            Err(e) => {
137                if e.is_unimplemented() {
138                    // default implementation, do nothing
139                    Ok(())
140                } else {
141                    Err(e)
142                }
143            }
144        }
145    }
146}
147
148/// implement `HelperDef` for bare function so we can use function as helper
149impl<
150        F: for<'reg, 'rc> Fn(
151            &Helper<'rc>,
152            &'reg Registry<'reg>,
153            &'rc Context,
154            &mut RenderContext<'reg, 'rc>,
155            &mut dyn Output,
156        ) -> HelperResult,
157    > HelperDef for F
158{
159    fn call<'reg: 'rc, 'rc>(
160        &self,
161        h: &Helper<'rc>,
162        r: &'reg Registry<'reg>,
163        ctx: &'rc Context,
164        rc: &mut RenderContext<'reg, 'rc>,
165        out: &mut dyn Output,
166    ) -> HelperResult {
167        (*self)(h, r, ctx, rc, out)
168    }
169}
170
171mod block_util;
172mod helper_each;
173pub(crate) mod helper_extras;
174mod helper_if;
175mod helper_log;
176mod helper_lookup;
177mod helper_raw;
178mod helper_with;
179#[cfg(feature = "script_helper")]
180pub(crate) mod scripting;
181
182#[cfg(feature = "string_helpers")]
183pub(crate) mod string_helpers;
184
185#[cfg(test)]
186mod test {
187    use std::collections::BTreeMap;
188
189    use crate::context::Context;
190    use crate::error::RenderError;
191    use crate::helpers::HelperDef;
192    use crate::json::value::JsonRender;
193    use crate::output::Output;
194    use crate::registry::Registry;
195    use crate::render::{Helper, RenderContext, Renderable};
196
197    #[derive(Clone, Copy)]
198    struct MetaHelper;
199
200    impl HelperDef for MetaHelper {
201        fn call<'reg: 'rc, 'rc>(
202            &self,
203            h: &Helper<'rc>,
204            r: &'reg Registry<'reg>,
205            ctx: &'rc Context,
206            rc: &mut RenderContext<'reg, 'rc>,
207            out: &mut dyn Output,
208        ) -> Result<(), RenderError> {
209            let v = h.param(0).unwrap();
210
211            write!(out, "{}:{}", h.name(), v.value().render())?;
212            if h.is_block() {
213                out.write("->")?;
214                h.template().unwrap().render(r, ctx, rc, out)?;
215            }
216            Ok(())
217        }
218    }
219
220    #[test]
221    fn test_meta_helper() {
222        let mut handlebars = Registry::new();
223        assert!(handlebars
224            .register_template_string("t0", "{{foo this}}")
225            .is_ok());
226        assert!(handlebars
227            .register_template_string("t1", "{{#bar this}}nice{{/bar}}")
228            .is_ok());
229
230        let meta_helper = MetaHelper;
231        handlebars.register_helper("helperMissing", Box::new(meta_helper));
232        handlebars.register_helper("blockHelperMissing", Box::new(meta_helper));
233
234        let r0 = handlebars.render("t0", &true);
235        assert_eq!(r0.ok().unwrap(), "foo:true".to_string());
236
237        let r1 = handlebars.render("t1", &true);
238        assert_eq!(r1.ok().unwrap(), "bar:true->nice".to_string());
239    }
240
241    #[test]
242    fn test_helper_for_subexpression() {
243        let mut handlebars = Registry::new();
244        assert!(handlebars
245            .register_template_string("t2", "{{foo value=(bar 0)}}")
246            .is_ok());
247
248        handlebars.register_helper(
249            "helperMissing",
250            Box::new(
251                |h: &Helper<'_>,
252                 _: &Registry<'_>,
253                 _: &Context,
254                 _: &mut RenderContext<'_, '_>,
255                 out: &mut dyn Output|
256                 -> Result<(), RenderError> {
257                    write!(out, "{}{}", h.name(), h.param(0).unwrap().value())?;
258                    Ok(())
259                },
260            ),
261        );
262        handlebars.register_helper(
263            "foo",
264            Box::new(
265                |h: &Helper<'_>,
266                 _: &Registry<'_>,
267                 _: &Context,
268                 _: &mut RenderContext<'_, '_>,
269                 out: &mut dyn Output|
270                 -> Result<(), RenderError> {
271                    write!(out, "{}", h.hash_get("value").unwrap().value().render())?;
272                    Ok(())
273                },
274            ),
275        );
276
277        let mut data = BTreeMap::new();
278        // handlebars should never try to lookup this value because
279        // subexpressions are now resolved as string literal
280        data.insert("bar0".to_string(), true);
281
282        let r2 = handlebars.render("t2", &data);
283
284        assert_eq!(r2.ok().unwrap(), "bar0".to_string());
285    }
286}
handlebars/helpers/mod.rs

handlebars/helpers/
mod.rs
