ha-nunjucks 0.0.1 → 0.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,17 +10,23 @@
|
|
|
10
10
|
|
|
11
11
|
<a href="https://www.buymeacoffee.com/nerwyn" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-blue.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
|
|
12
12
|
|
|
13
|
-
A wrapper for nunjucks for use with Home Assistant frontend custom components to render templates. This repository offers an easy way for developers to add templating support to Home Assistant custom cards.
|
|
13
|
+
A simple wrapper for [nunjucks](https://www.npmjs.com/package/nunjucks) for use with Home Assistant frontend custom components to render [templates](https://www.home-assistant.io/docs/configuration/templating/). This repository offers an easy way for developers to add templating support to Home Assistant custom cards.
|
|
14
14
|
|
|
15
15
|
## What is nunjucks?
|
|
16
16
|
|
|
17
17
|
[Nunjucks](https://mozilla.github.io/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 for Home Assistant templating for custom cards.
|
|
18
18
|
|
|
19
|
-
While some Home Assistant native cards support templating for certain fields, implementing proper Home Assistant jinja2 template support in custom cards is difficult. The only custom module that manages to do so (AFAIK) is card-mod, and it's
|
|
19
|
+
While some Home Assistant native cards support templating for certain fields, implementing proper Home Assistant jinja2 template support in custom cards is difficult. The only custom module that manages to do so (AFAIK) is card-mod, and it's implementation is hard to port to other projects. This project offers a much easier plug and play solution to adding template support to custom cards.
|
|
20
20
|
|
|
21
21
|
## Usage
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
Install using npm:
|
|
24
|
+
|
|
25
|
+
```shell
|
|
26
|
+
npm install ha-nunjucks
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Then import `renderTemplate` from `ha-nunjucks` and provide it with the `hass` object and a template string you want to process.
|
|
24
30
|
|
|
25
31
|
```typescript
|
|
26
32
|
import { renderTemplate } from 'ha-nunjucks';
|
|
@@ -28,11 +34,11 @@ import { renderTemplate } from 'ha-nunjucks';
|
|
|
28
34
|
const renderedString = renderTemplate(this.hass, templateString);
|
|
29
35
|
```
|
|
30
36
|
|
|
31
|
-
Rather than rendering templates on the backend,
|
|
37
|
+
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.
|
|
32
38
|
|
|
33
39
|
## Available Extensions
|
|
34
40
|
|
|
35
|
-
The catch to this approach of rendering jinja2/nunjucks templates is that we have to reimplement all of the [Home Assistant template extension](https://www.home-assistant.io/docs/configuration/templating/#home-assistant-template-extensions) functions and filters.
|
|
41
|
+
The catch to this approach of rendering jinja2/nunjucks templates is that we have to reimplement all of the [Home Assistant template extension](https://www.home-assistant.io/docs/configuration/templating/#home-assistant-template-extensions) functions and filters. If there are functions or filters that you use that are not currently supported, please make a feature request or try adding it to the project yourself and create a pull request.
|
|
36
42
|
|
|
37
43
|
So far a subset of the Home Assistant template extension functions have been implemented as documented below.
|
|
38
44
|
|
|
@@ -70,9 +76,9 @@ A shorthand for an if else statement.
|
|
|
70
76
|
|
|
71
77
|
Functions that are not from the Home Assistant templating documentation
|
|
72
78
|
|
|
73
|
-
| Name | Arguments
|
|
74
|
-
| ----------- |
|
|
75
|
-
| match_media |
|
|
79
|
+
| Name | Arguments | Description |
|
|
80
|
+
| ----------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
81
|
+
| match_media | mediaquery | Returns the boolean result of the provided [CSS media query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries). |
|
|
76
82
|
|
|
77
83
|
[last-commit-shield]: https://img.shields.io/github/last-commit/Nerwyn/ha-nunjucks?style=for-the-badge
|
|
78
84
|
[commits]: https://github.com/Nerwyn/service-call-tile-feature/commits/main
|