Version 0.4
This commit is contained in:
parent
6e12de2156
commit
8b9151f93b
92
README.md
92
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`
|
||||
<paper-button
|
||||
@click="${cardTools.moreInfo("light.bed_light");}"
|
||||
>
|
||||
@ -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`
|
||||
<paper-button
|
||||
@click="${cardTools.moreInfo("light.bed_light");}"
|
||||
@ha-click="${console.log('I was clicked')}"
|
||||
@ -215,6 +235,8 @@ resources:
|
||||
|
||||
If called from `my-plugin.js` `cardTools.args()` will return the javascript object `{height: 5, flag: undefined, width: 10}`.
|
||||
|
||||
If called from a callback function, `cardTools.args` requires the parameter `script` in order to determine the current script. It should have the value of `document.currentScript`, but must be defined outside of the callback scope.
|
||||
|
||||
### localize
|
||||
Returns the translation of certain strings (defined by string keys) to the users language.
|
||||
|
||||
@ -226,17 +248,41 @@ Examples of keys:
|
||||
|
||||
More can be found by exploring `cardTools.hass().resources`.
|
||||
|
||||
### popup
|
||||
This function opens a dialog similar to the more-info dialog but with the title and message specified. Set `large` to `true` to attempt to open a wider dialog
|
||||
|
||||
### closePopUp
|
||||
This function closes a popup or more-info dialog.
|
||||
|
||||
### logger
|
||||
This function allows the user to enable a debug mode by adding `?debug` to the `url:` in their `resources` when importing your card. Messages printed with `cardTools.logger()` will only be shown if the debug mode is active.
|
||||
|
||||
The `script` parameter is required if `cardTools.logger` is called from within a callback function. See the description of `cardTools.args` for more information.
|
||||
|
||||
## Changelog
|
||||
|
||||
*0.2*
|
||||
- Added `parseTemplate()` function
|
||||
|
||||
*0.3*
|
||||
- `LitElement` renamed to `litElement`.
|
||||
- `cardTools.litElement()`, `cardTools.litHtml` and `cardtools.deviceID()` are now functions.
|
||||
- Updated recommendation for how to check if `card-tools` exists.
|
||||
- Added `hasTemplate()` to documentation.
|
||||
- Added `args()` function.
|
||||
- Added `localize()` function.
|
||||
- `LitElement` renamed to `litElement`
|
||||
- `cardTools.litElement()`, `cardTools.litHtml` and `cardtools.deviceID()` are now functions
|
||||
- Updated recommendation for how to check if `card-tools` exists
|
||||
- Added `hasTemplate()` to documentation
|
||||
- Added `args()` function
|
||||
- Added `localize()` function
|
||||
|
||||
*0.4*
|
||||
- `cardTools.LitElement` reintroduced. It is not a function
|
||||
- `cardTools.LitHtml` introduced. It is not a function
|
||||
- `cardTools.v()` removed and replaced with `cardTools.version` (kind of breaking, but I don't think anyone uses it...)
|
||||
- `cardTools.deviceID()` removed and replaced with `cardTools.deviceID` (kind of breaking, but I don't think anyone uses it...)
|
||||
- `cardTools.hass()` deprecated and replaced with `cardTools.hass`
|
||||
- `cardTools.LitCSS` added
|
||||
- `cardTools.lovelace` added
|
||||
- `cardTools.popup()` added
|
||||
- `cardTools.closePopUp()` added
|
||||
- `cardTools.logger()` added
|
||||
- Added `script` parameter to `cardTools.args`
|
||||
|
||||
---
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
customElements.define('card-tools',
|
||||
class {
|
||||
static get CUSTOM_TYPE_PREFIX() { return "custom:"}
|
||||
static get version() { return "0.3"}
|
||||
static get version() { return "0.4"}
|
||||
|
||||
static checkVersion(v) {
|
||||
if (this.version < v) {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user