ha-nunjucks v1.3.0

ha-nunjucks

A wrapper for nunjucks for use with Home Assistant frontend custom components to render templates instanteneously at HTML render time. This repository offers an easy way for developers to add templating support to Home Assistant custom cards.

What is nunjucks?

Nunjucks is a templating engine for JavaScript that is heavily inspired by jinja2. Home Assistant uses jinja2 to process templates in card configurations on the backend, so the syntax of jinja2 and Nunjucks is virtually the same. This makes it an excellent alternative to Home Assistant core jinja2 templating for custom cards.

While some Home Assistant native cards support templating for certain fields, implementing proper Home Assistant jinja2 template support in custom cards can be difficult. Additionally Home Assistant jinja2 templates are processed by the Python backend, and can take several seconds to render. Nunjucks templates are processed by the frontend using the frontend hass object before your custom card's HTML is rendered, making nunjucks templating synchronous, instanteous. and much faster than traditional jinja2 templates.

Usage

Install using npm:

npm install ha-nunjucks

Then import renderTemplate from ha-nunjucks and provide it with the hass object and a template string you want to process.

import { renderTemplate } from 'ha-nunjucks';

const renderedString = renderTemplate(this.hass, templateString);

That's it! The result of renderTemplate is the rendered template for you to use. In unit and integration testing render time is under 1 ms and shouldn't cause any latency in your projects.

Rather than rendering templates on the backend, nunjucks renders templates on the frontend. This repository uses the Home Assistant object present in all custom cards to read entity state data.

You can also provide context to the renderTemplate function to pass to nunjucks if you want to make additional variables or project specific functions available to your users for use in templates.

import { renderTemplate } from 'ha-nunjucks';

const context = {
  foo: 'bar',
  doThing(thing: string) {
    return `doing ${thing}!`;
  },
  config: {
    entity: 'foo.bar',
    attribute: 'baz_bah',
  },
};

const renderedString = renderTemplate(this.hass, templateString, context);

Return Types

renderTemplate will return a string unless the result is true or false (not case sensitive), in which case it will return a boolean.

When the return type is expected to be a number, end users should cast these values using the nunjucks int or float filters to prevent undesired behavior caused by JavaScript forcing operations between disparate variable types. Numbers are not returned by default to prevent leading and trailing zeroes from being truncated from numerical strings.

renderTemplate will return an empty string for strings that may have been cast from nullish non-numerical values, such as undefined, null, and None (case sensitive).

Available Extensions

The vast majority of the Home Assistant template extensions have been implemented into this package. If there are functions that you use that are not currently supported or don't behave exactly like their jinja2 versions, please make a feature request or try adding it to the project yourself and create a pull request.

Template extensions can be functions, tests, filters, and/or constants. Functions are called like a regular programming function, such as states() or floors(). Filters are added to the end of a string using a pipe character like 123.45 | int or "light.lounge" | state_attr("brightness"). Tests are functions which return booleans and can be used in an if statement like if "foo" is string_like, not to be confused with functions that return booleans and can be used in if statements like if is_state("light.lounge", "on"). Contants are static values, and are just called as is like {{ True }} or {{ pi }}.

In addition to the template extensions implemented in this package, you also have access to the nunjucks builtin functions and filters. Read the nunjucks templating documentation for more information.

Python Constants

These just remap Python built-in constants to JavaScript ones.

Frontend Data Hass Object

The frontend data hass object has been exposed to users to call upon.

Because entity IDs contain periods in them, you cannot use dot notation when accessing an entity's state object using it. You have to use bracket notation like so:

{{ hass.states["light.sunroom_ceiling"].state }}

For convenience, the hass.states object is rebuilt as a separate object that can be accessed with dot notation. Because of JavaScript limitations not allowing for functions and object to share the same name, it has been named _states.

{{ _states.light.sunroom_ceiling.state }}

You do have to use bracket notation for arrays within state objects.

{{ _states.light.sunroom_ceiling.attributes.supported_color_modes[0] }}

States

Functions used to determine an entity's state or an attribute.

State Translated

Groups

Entities

Devices

Floors

Areas

Entities For An Integration

Labels

NOTE: Labels are not available in the hass object and must be retrieved asynchronously from the Home Assistant backend the first time renderTemplate is called. Since this package is otherwise synchronous, this can cause a race condition where no labels are found the first time renderTemplate is run. This generally resolves itself once the template re-renders.

Immediate If

A shorthand for an if else statement.

Time

NOTE:

• JS Date does not support time precision below 1 millisecond, while Python datetime supports microsecond precision. Microsecond arguments are not available for these methods.
• JS Date is not as good at handling timezones as Python datetime. Be careful about timezone differences! You can try to account for this using the utc flags and/or by including a timezone offset in a datetime string to parse using as_datetime or strptime.
• Including time extensions in your templates does not cause them to refresh more regularly by themselves, although they will still update whenever the hass object does. If you are a developer, you have to implement this behavior yourself in your custom cards.

In addition to these functions, you have access to a datetime library which emulates the Python datetime module in TypeScript. You can instantiate date, time, datetime, and timedelta objects using the dt object. You can then access it's class methods using these objects. To use the static method and constants of these classes, you can reference them directly without prefixing them with dt. See the README in the datetime repository linked above for more information on how to use it.

To/From JSON

Distance

Contains

Numeric

Complex Type Checking

Type Conversions

Iterating Multiple Objects

Regular Expressions

NOTE: The format of regular expressions in nunjucks is different than jinja2. You may want to read the Nunjucks and MDN documentation.

Miscellaneous

Functions that are not from the Home Assistant templating documentation.