liquidjs/docs/source/tutorials/parse-parameters.md

title

title
Parse Parameters

Access Raw Parameters

As covered in Register Filters/Tags, tag parameters are available on tagToken.args as a raw string. For example:

// Usage: {% random foo bar coo %}
// Output: "foo", "bar" or "coo"
engine.registerTag('random', {
  parse(tagToken) {
    // tagToken.args === "foo bar coo"
    this.items = tagToken.args.split(' ')
  },
  render(context, emitter) {
    // get a random index
    const index = Math.floor(this.items.length * Math.random())
    // output that item
    emitter.write(this.items[index])
  }
})

Here's a JSFiddle version: https://jsfiddle.net/ctj364up/2/

Parse Parameters as Values

Sometimes we need more dynamic tags and want to pass values to the custom tag instead of static strings. Variables in LiquidJS can be literal (string, number, etc.) or a variable from current context scope.

The following modified template also contains 3 values to random from, but they're values instead of static strings. The first one is string literal, second one is an identifier, third one is a property access sequence containing two identifiers.

{% random "foo" bar obj.coo %}

It can be tricky to parse all these cases manually, but there's a Tokenizer class in LiquidJS you can make use of.

const { Liquid, Tokenizer, evalToken } = require('liquidjs')
engine.registerTag('random', {
  parse(tagToken) {
    const tokenizer = new Tokenizer(tagToken.args)
    this.items = []
    while (!tokenizer.end()) {
      // here readValue() returns a LiteralToken or PropertyAccessToken
      this.items.push(tokenizer.readValue())
    }
  },
  * render(context, emitter) {
    const index = Math.floor(this.items.length * Math.random())
    const token = this.items[index]
    // in LiquidJS, we use yield to wait for async call
    const value = yield evalToken(token, context)
    emitter.write(value)
  }
})

Calling this tag in scope { bar: "bar", obj: { coo: "coo" } } yields exactly the same result as the first example. See this JSFiddle: https://jsfiddle.net/ctj364up/3/

{% note info Async and Promises %} Async calls in LiquidJS are implemented by generators directly, for we can call generators in synchronous manner so this tag implementation is also valid for renderSync(), parseAndRenderSync(), renderFileSync(). If you need to await a promise in tag implementation, simply replace await somePromise with yield somePromise and keep * render() instead of async render() will do the trick. See Sync and Async for more details. {% endnote %}

Parse Key-Value Pairs as Named Parameters

Named parameters become very handy when there are optional parameters or lots of parameters, in which case the order of parameters is not important. This is exactly what the Hash class was invented for.

{% random from:2, to:max %}

In the above example, we're trying to generate a random number in the range [2, max]. We'll use Hash to parse from and to parameters.

const { Liquid, Hash } = require('liquidjs')

engine.registerTag('random', {
  parse(tagToken) {
    // parse the parameters structure into `this.args`
    this.args = new Hash(tagToken.args)
  },
  * render(context, emitter) {
    // evaluate the parameters in `context`
    const {from, to} = yield this.args.render(context)
    const length = to - from + 1
    const value = from + Math.floor(length * Math.random())
    emitter.write(value)
  }
})

Rendering {% raw %}{% random from:2, to:max %}{% endraw %} in scope { max: 10 } will generate a random number in the range [2, 10]. See this JSFiddle: https://jsfiddle.net/ctj364up/4/