ha-nunjucks 1.1.0 → 1.2.0

package/README.md

@@ -33,6 +33,21 @@ const renderedString = renderTemplate(this.hass, templateString);
 
 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 additional 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.
+
+```typescript
+import { renderTemplate } from 'ha-nunjucks';
+
+const context = {
+  foo: 'bar',
+  doThing(thing: string) {
+    return `doing ${thing}!`;
+  },
+};
+
+const renderedString = renderTemplate(this.hass, templateString, context);
+```
+
 ## Available Extensions
 
 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.
@@ -49,6 +64,18 @@ These variables just remap Python built-in constants to JavaScript ones.
 | False  | false      |
 | None   | null       |
 
+### [Frontend Data Hass Object](https://developers.home-assistant.io/docs/frontend/data/)
+
+The frontend data `hass` object has been exposed to users to call upon.
+
+Because entity IDs contain periods in them, it's better to access it using bracket notation like so:
+
+`{{ hass["states"]["light.sunroom_ceiling"]["state"] }}`
+
+You can also use dot notation for everything but the entity ID.
+
+`{{ hass.states["light.sunroom_ceiling"].state }}`
+
 ### [States](https://www.home-assistant.io/docs/configuration/templating/#states)
 
 Functions used to determine an entity's state or an attribute.
@@ -80,7 +107,7 @@ Functions that are not from the Home Assistant templating documentation
 [last-commit-shield]: https://img.shields.io/github/last-commit/Nerwyn/ha-nunjucks?style=for-the-badge
 [commits]: https://github.com/Nerwyn/service-call-tile-feature/commits/main
 [forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=for-the-badge
-[forum]: https://community.home-assistant.io/t/ha-nunjucks/
+[forum]: https://community.home-assistant.io/t/an-easy-way-to-add-templating-support-to-your-custom-front-end-projects/651621
 [license-shield]: https://img.shields.io/github/license/Nerwyn/service-call-tile-feature.svg?style=for-the-badge
 [maintenance-shield]: https://img.shields.io/badge/maintainer-Nerwyn-blue.svg?style=for-the-badge
 [github]: https://img.shields.io/github/followers/Nerwyn.svg?style=social

package/dist/renderTemplate.d.ts

@@ -3,6 +3,7 @@ import { HomeAssistant } from 'custom-card-helpers';
  * Render a Home Assistant template string using nunjucks
  * @param {HomeAssistant} hass The Home Assistant object
  * @param {string} str The template string to render
+ * @param {object} [context] Additional context to expose to nunjucks
  * @returns {string} The rendered template string if a string was provided, otherwise the unaltered input
  */
-export declare function renderTemplate(hass: HomeAssistant, str: string): string | number | boolean;
+export declare function renderTemplate(hass: HomeAssistant, str: string, context?: object): string | number | boolean;

package/dist/renderTemplate.js

@@ -7,13 +7,14 @@ const context_1 = require("./context");
  * Render a Home Assistant template string using nunjucks
  * @param {HomeAssistant} hass The Home Assistant object
  * @param {string} str The template string to render
+ * @param {object} [context] Additional context to expose to nunjucks
  * @returns {string} The rendered template string if a string was provided, otherwise the unaltered input
  */
-function renderTemplate(hass, str) {
+function renderTemplate(hass, str, context) {
     if (typeof str == 'string' &&
         ((str.includes('{{') && str.includes('}}')) ||
             (str.includes('{%') && str.includes('%}')))) {
-        str = (0, nunjucks_1.renderString)(structuredClone(str), (0, context_1.CONTEXT)(hass)).trim();
+        str = (0, nunjucks_1.renderString)(structuredClone(str), Object.assign(Object.assign({}, (0, context_1.CONTEXT)(hass)), context)).trim();
         if ([undefined, null, 'undefined', 'null', 'None'].includes(str)) {
             return '';
         }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ha-nunjucks",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Wrapper for nunjucks for use with Home Assistant frontend custom components to render templates",
 	"main": "./dist/index.js",
 	"scripts": {