LCARdS

Appearance

Template System ​

Unified template evaluation for all LCARdS cards and text fields.

Overview ​

All dynamic text in LCARdS is processed by UnifiedTemplateEvaluator. It orchestrates four distinct sub-evaluators in a fixed priority order. Cards create a single evaluator instance and call evaluateAsync() on any string.

Key Classes ​

ClassFileRole
UnifiedTemplateEvaluatorcore/templates/UnifiedTemplateEvaluator.jsOrchestrator — runs all four evaluators in order
LCARdSCardTemplateEvaluatorcore/templates/LCARdSCardTemplateEvaluator.jsHandles JS [[[...]]] and token {...} templates
DataSourceTemplateEvaluatorcore/templates/DataSourceTemplateEvaluator.jsHandles {ds:name} and {datasource:name.key}
HATemplateEvaluatorcore/templates/HATemplateEvaluator.jsSends Jinja2 to HA server for evaluation
TemplateDetectorcore/templates/TemplateDetector.jsFast type detection — avoids unnecessary evaluator calls
TemplateParsercore/templates/TemplateParser.jsTokenises complex mixed-content strings

Template Types & Syntax ​

1 — JavaScript [[[...]]] ​

yaml
text: "[[[return entity.state.toUpperCase()]]]"
text: "[[[return Math.round(entity.attributes.brightness / 2.55) + '%']]]"

Evaluation context includes: entity, hass, config, theme, states.

2 — LCARdS Tokens {...} ​

yaml
text: "{entity.state}"
text: "{entity.attributes.friendly_name}"
text: "{theme:palette.moonlight}"
text: "{config.name}"

3 — DataSource {ds:...} ​

yaml
text: "{ds:sensor_name}"               # main buffer value
text: "{ds:sensor_name.celsius:.1f}"   # processor buffer with format spec
text: "{datasource:temp.rolling_avg}"  # explicit long prefix

4 — Jinja2 {{...}} / {% %} ​

yaml
text: "{{states('sensor.temp')}} °C"
text: "{% if is_state('light.kitchen','on') %}On{% else %}Off{% endif %}"

Jinja2 is asynchronous — evaluated by HA server via WebSocket.

Evaluation Order ​

A single string may contain multiple template types. They are evaluated sequentially:

  1. JavaScript [[[...]]] replaced first (synchronous)
  2. Token {...} replaced (synchronous)
  3. DataSource {ds:...} replaced (synchronous — reads latest buffer value)
  4. Jinja2 {{...}} sent to HA (async — awaited before render)

Creating an Evaluator ​

javascript
import { UnifiedTemplateEvaluator } from '../core/templates/UnifiedTemplateEvaluator.js';

const evaluator = new UnifiedTemplateEvaluator({
  hass: this.hass,
  context: {
    entity: this.hass.states[this.config.entity_id],
    config: this.config,
    hass: this.hass,
    theme: window.lcards.core.themeManager.getCurrentTheme()
  },
  dataSourceManager: window.lcards.core.dataSourceManager
});

const result = await evaluator.evaluateAsync(template);

See Also ​