From 8b9151f93b4d376a19b6786e0bd00421a87af5ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20Lov=C3=A9n?= Date: Mon, 25 Feb 2019 21:20:02 +0100 Subject: [PATCH] Version 0.4 --- README.md | 92 ++++++++++++++++++++++++++++++++++++++------------- card-tools.js | 2 +- 2 files changed, 70 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index fc74714..d7001fb 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -card-tools +card-tools version 0.4 ========== This is a collection of tools to simplify creating custom cards for [Home Assistant](https://home-assistant.io) # IMPORTANT -`card-tools` v. 0.3 and any plugins that require it works only with Home Assistant 0.86 or later. +`card-tools` v. 0.4 and any plugins that require it works only with Home Assistant 0.87 or later. ## Installation instructions @@ -12,6 +12,17 @@ If you see "Can't find card-tools. [...]" in your Home Assistant UI, follow thes To install `card-tools` follow [this guide](https://github.com/thomasloven/hass-config/wiki/Lovelace-Plugins). +The recommended type of this plugin is: `js` + + +### For [custom\_updater](https://github.com/custom-components/custom_updater) +```yaml +resources: +- url: /customcards/github/thomasloven/card-tools.js?track=true + type: js +``` + + ## User instructions That's all. You don't need to do anything else. @@ -29,16 +40,16 @@ To make sure `card-tools` is loaded before your plugin, wait for `customElements Example: ```js customElements.whenDefined('card-tools').then(() => { - + var cardTools = customElements.get('card-tools'); // YOUR CODE GOES IN HERE - class MyPlugin extends cardTools.litElement { + class MyPlugin extends cardTools.LitElement { setConfig(config) { this.name = config.name; } render() { - return cardTools.litHtml()` + return cardTools.LitHtml` ${this.name} `; } @@ -61,26 +72,31 @@ The following functions are defined: | Name | v >= | Description | | --- | --- | --- | -| `cardTools.v()` | 0.1 | Current `card-tools` version | +| `cardTools.version` | 0.4 | Current `card-tools` version | | `cardTools.checkVersion(v)` | 0.1 | Check that the current `card-tools` version is at least `v` | -| `cardTools.hass()` | 0.1 | Returns A `hass` state object. Useful for plugins that are *not* custom cards. If you need it, you'll know it | +| `cardTools.hass` | 0.4 | Returns A `hass` state object. Useful for plugins that are *not* custom cards. If you need it, you'll know it | | `cardTool.fireEvent(event, detail)` | 0.1 | Fire lovelace event `event` with options `detail` | -| `cardTools.litElement()` | 0.1 | A reference to the LitElement base class. | -| `cardTools.litHtml()` | 0.1 | A reference to the litHtml template function (requires Home Assistant 0.84 or later) | +| `cardTools.LitElement` | 0.4 | A reference to the LitElement base class. | +| `cardTools.LitHtml` | 0.4 | A reference to the litHtml template function (requires Home Assistant 0.84 or later) | | `cardTools.createCard(config)` | 0.1 | Creates and sets up a lovelace card based on `config` | | `cardTools.createElement(config)` | 0.1 | Creates and sets up a `picture-elements` element based on `config` | | `cardTools.createEntityRow(config)` | 0.1 | Creates and sets up an `entities` row based on `config` | -| `cardTools.deviceID()` | 0.1 | Kind of unique and kind of persistent identifier for the browser viewing the page | +| `cardTools.deviceID` | 0.4 | Kind of unique and kind of persistent identifier for the browser viewing the page | | `cardTools.moreInfo(entity)` | 0.1 | Brings up the `more-info` dialog for the specified `entity` id | | `cardTools.longPress(element)` | 0.1 | Bind `element` to the long-press handler of lovelace | | `cardTools.hasTemplate(text)` | 0.2 | Check if `text` contains a simple state template | | `cardTools.parseTemplate(text, [error])` | 0.2 | Parse a simple state template and return results | -| `cardTools.args()` | 0.3 | Returns URL parameters of the script from `resources:` | +| `cardTools.args(script)` | 0.3 | Returns URL parameters of the script from `resources:` | | `cardTools.localize(key)` | 0.3 | Returns translations of certains strings to the users language | +| `cardTools.lovelace`| 0.4 | A reference to a structure containing some information about the users lovelace configuration | +| `cardTools.popup(title, message, large)` | 0.4 | Open a popup window (simmilar to the more-info dialog) | +| `cardTools.closePopUp()` | 0.4 | Closes a popup window or more-info dialog | +| `cardTools.logger(message, script)` | 0.4 | Write a debug message to the browser console | > Another way to use the `card-tools` is to just copy the function you want, and paste it into your card. It requires a bit of more work, but may be more user friendly. -### v and checkVersion + +### version and checkVersion Those functions are just there to make sure the user has the right version of `card-tools`. I may add more functions later, and then you can make sure that those are supported by the version the user has. I recommend adding a check as soon as possible, such as in the `setConfig()` function of a custom card/element/entity row. @@ -99,15 +115,19 @@ This is provided for plugins that *aren't* cards, elements or entity rows. For t ```js ... - greeting.innerHTML = `Hi there, ${cardTools.hass().user.name}`; - cardTools.hass().connection.subscribeEvents((event) => {console.log("A service was called in Home Assistant")}, 'call-service'); + greeting.innerHTML = `Hi there, ${cardTools.hass.user.name}`; + cardTools.hass.connection.subscribeEvents((event) => {console.log("A service was called in Home Assistant")}, 'call-service'); ``` +### lovelace + +This object contains information about the users lovelace configuration. As a bonus `cardTools.lovelace.current_view` contains the index of the currently displayed view. + ### fireEvent This is mainly used as a helper for some other functions of `cardTools`, but it could be useful to fire a lovelace event sometime, such as `"config-refresh"` perhaps? Explore! -### litElement and litHtml +### LitElement, LitHtml and LitCSS Currently, the Home Assistant frontend is being converted to LitElement based elements, rather than Polymer based, since those are faster and easier to use. If you wish to make your element LitElement based, those may help. @@ -145,7 +165,7 @@ This can be used to open the more-info dialog for an entity. ```js render() { - return cardTools.litHtml` + return cardTools.LitHtml` @@ -163,7 +183,7 @@ Once an element has been bound to longpress, it will be able to receive `ha-clic ```js render() { - return cardTools.litHtml` + return cardTools.LitHtml`