Lucid.js / Variables

Introduction 🔗

Variables are dynamic placeholders in component templates which are swapped out with runtime data.

They take the format {{myvar}}, where myvar is the property to lookup in one of the following data sources.

Variable placeholders can sometimes look a little different from the above - for example if a filter method is specified. We'll come to those below.

The origin of the swap data is one of:

Incoming props from the parent component (if any)
The component's data object
Repeater data (see below)

We'll look at each of the three scenarios above in turn to see how variable parsing works.

Variables and props 🔗

Props are data passed from a parent component to a child component. These props are used to swap out any matching variable placeholders when the child component is rendered or re-rendered.

Suppose a parent component loaded the child component like so in its HTML template:

...
<Child someprop="hello, world!" />
...

...and the child component had the following in its HTML template:

<p>{{someprop}}</p>

...the variable would be replaced with "hello, wold!" when the component renders.

Variables and component data 🔗

Variables can also be swapped out for properties in the component's data object.

Suppose following the master component of a single-component app:

<h1>{{somevar}}</h1>
<script>
this.data.somevar = 'hello, world!';
</script>

As above, this would result in variable being replaced with "hello, world!". If the value of `this.data.somvar` ever changes later on, e.g. in response to user action, the output will automatically update.

This is true provided the instantiation param autoReprocess, which governs Lucid's reactivity policy, allows for auto-reparsing of output. If it doesn't (it does by default), output can be updated on future changes to data by calling this.reprocessOutput() (or this.ro()).

Variables and repeaters 🔗

For more info on repeaters, see Repeaters.

Repeaters are used to iteratively output elements or child components. In so doing, they can pass repeater data to the output using variables, just like above.

Suppose our master component changed to be the following:

<ul>
    <li>{{somevar}}</li>
</ul>
<script>
this.repeaters = {
    li: [{somevar: 'A'}, {someVar: 'B'}]
};
</script>

That would result in a list with two items, one containing the text "A" and another containing "B".

Repeaters also have access to two special types of variable, discussed below.

Filter methods 🔗

When outputting props or repeater data it's possible to first run data through filter methods to modify what gets output.

Filter methods can be stored either at app- or component-level:

App-level filter methods are declared in the methods instantiation param object
Component-level filter rmethods are declared in the component's JavaScript, on its this.methods object.

Where there are filter methods with the same name at both app- and component-level, Lucid will use the component-level method.

Wherever it is declared, a filter method can then be referenced in a variable template preceded by a pipe.

{{varName|filter()}}

...where filter() is the name of the method you registered when instantiating Lucid.

Filter methods should return the updated value to ultimately be used, and are automatically fed two params:

The value to be modified
A reference to the component object

Filter method caching 🔗

It's possible to cach filter method responses for like values. This is done by putting "1" or "true" inbetween the filter method's brackets. Suppose the following component:

<ul>
    <li>{{message|addNum(true)}}</li>
    <li>{{message|addNum(true)}}</li>
    <li>{{message|addNum()}}</li>
</ul>
<script>
this.methods = {
    addNum: string => string+' '+Math.floor(Math.random() * 100)
};
this.data.message = 'Hello';
</script>

There, we're feeding the same piece of component data to a component-level filter method. Output will be somthing like the below.

<li>Hello 14</li>
<li>Hello 14</li>
<li>Hello 35</li>

The first call to addNum() requests a cached value but, because it's the first call, there is none, so the value will be evaluated afresh.
The second call requests the cached value from the first call,
The third call wants a fresh value.

Filter method caching is supported for all data types of values passed to filter methods - even complex types.

Special variables 🔗

There are a handful of special variables.

Data relating to the current active route can be output or used as props via the special syntax $rd:*, where * is the segment (segment routes) or property (JSON routes) of the currently active route's data to output.

See Routes > Getting route data for a fuller explanation and example.

There are two special variables for use only with repeaters - $index and $value, which reference the index or value of the current item of the iteration, respectively.

These special variables can be run through filter methods just like any other variables.

Did I help you? Feel free to be amazing and buy me a coffee on Ko-fi!