From 1676219f788a0cbbc8dfd90edf8668e967849ebb Mon Sep 17 00:00:00 2001 From: c727 Date: Fri, 29 Jun 2018 17:03:10 +0200 Subject: [PATCH] [wip] Lovelace next (>0.72.1) (#40) Lovelace next (>0.72.1) --- docs/lovelace_card_types.md | 83 ++++++++++++++++++++++++++++++------ docs/lovelace_custom_card.md | 47 ++++++++++++++++++-- docs/lovelace_index.md | 17 ++++---- 3 files changed, 123 insertions(+), 24 deletions(-) diff --git a/docs/lovelace_card_types.md b/docs/lovelace_card_types.md index 50e320b5..5dbcce6f 100644 --- a/docs/lovelace_card_types.md +++ b/docs/lovelace_card_types.md @@ -12,6 +12,13 @@ These cards are WIP and things may change. | type | string | **Required** | `camera-preview` | entity | string | **Required** | Entity id of `camera` domain +## Column + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| type | string | **Required** | `column` +| cards | list | **Required** | List of cards + ## Entities | Name | Type | Default | Description @@ -19,6 +26,7 @@ These cards are WIP and things may change. | type | string | **Required** | `entities` | entities | list | **Required** | Entity id's | title | string | Optional | Card title +| show_header_toggle | boolean | true | Button to turn on/off all entities ## Entity filter @@ -26,8 +34,7 @@ These cards are WIP and things may change. | ---- | ---- | ------- | ----------- | type | string | **Required** | `entity-filter` | filter | list | **Required** | See filter description -| card_config | object | `None` | Extra options to pass down to the card rendering the result. -| card | string | `entities` | Card to use to render the result. Follows same rules as card type. +| card | object | `{'type': 'entities'}` | Extra options to pass down to the card rendering the result. Filter options: @@ -37,20 +44,12 @@ Filter options: | state | string | Optional | Match entities that match state. Note, in YAML, make sure you wrap it in quotes to make sure it is parsed as a string. | entity_id | string | Optional | Filter entities by id, supports wildcards (`*living_room*`) -## Entity picture - -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| type | string | **Required** | `entity-picture` -| image | string | **Required** | URL of an image. -| entity | string | **Required** | Entity id to control via picture. - ## Glance | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | type | string | **Required** | `glance` -| entities | list | **Required** | Entity id's +| entities | list | **Required** | Entity id's or `{'entity': ''entity_id', 'title': 'title'}` | title | string | Optional | Card title ## History graph @@ -59,6 +58,8 @@ Filter options: | ---- | ---- | ------- | ----------- | type | string | **Required** | `history-graph` | entity | string | **Required** | Entity id of `history_graph` domain +| hours_to_show | integer | 24 | Hours to show +| refresh_interval | integer | 0 | Refresh interval in seconds ## Iframe @@ -84,12 +85,63 @@ Filter options: | type | string | **Required** | `media-control` | entity | string | **Required** | Entity id of `media_player` domain +## Picture elements + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| type | string | **Required** | `picture-elements` +| image | string | **Required** | URL of an image +| elements | list | **Required** | List of elements +| title | string | Optional | Card title + +Element types: + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| type | string | **Required** | `state-badge` +| entity | string | **Required** | Entity id +| style | object | **Required** | See "Style options" +| tap_action | string | more-info | Set to `toggle` to change state + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| type | string | **Required** | `state-text` +| entity | string | **Required** | Entity id +| style | object | **Required** | See "Style options" + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| type | string | **Required** | `service-button` +| service | object | **Required** | `{'domain': 'light', 'service': 'turn_on', 'data': {'entity_id': 'light.floor'}}` +| style | object | **Required** | See "Style options" +| title | string | optional | Button label + + +Style options (CSS): + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| left | string | **Required** | Position from left, `25%` +| top | string | **Required** | Position from top, `50%` +| ... | string | inherit | ... +| "--paper-item-icon-color" | string | inherit | Badge-icon off-color, `green` + +## Picture entity + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| type | string | **Required** | `picture-entity` +| entity | string | **Required** | Entity id to control via picture. +| image | string | optional| URL of an image. +| state_image | object | optional| `{'on': '/on.png', ... 'default': '/default.png'}` +| title | string | Optional | Card title + ## Picture glance | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | type | string | **Required** | `picture-glance` -| image | string | **Required** | URL of an image. +| image | string | **Required** | URL of an image | entities | list | **Required** | Entity id's | title | string | Optional | Card title @@ -100,6 +152,13 @@ Filter options: | type | string | **Required** | `plant-status` | entity | string | **Required** | Entity id of `plant` domain +## Row + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| type | string | **Required** | `row` +| cards | list | **Required** | List of cards + ## Weather forecast | Name | Type | Default | Description diff --git a/docs/lovelace_custom_card.md b/docs/lovelace_custom_card.md index 727ce471..6343d52e 100644 --- a/docs/lovelace_custom_card.md +++ b/docs/lovelace_custom_card.md @@ -11,6 +11,38 @@ You're not just limited to the cards that we decided to include in the Lovelace - Home Assistant will set the `hass` property when the state of Home Assistant changes (frequent). Whenever the state changes, the component will have to update itself to represent the latest state. - Home Assistant will call `getCardSize()` to request the size of the card. Size of the card is used for the automatic distribution of cards across columns. Both `config` and `hass` properties will be available. Defaults to `1` if function is not defined. +You define your custom card as a [custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). It's up to you to decide how to render your DOM inside your element. You can use Polymer, Angular, Preact or any other popular framework (except for React – [more info here](https://custom-elements-everywhere.com/)). + +```js +const element = document.createElement('some-custom-card'); +``` + +Home Assistant will call `setConfig(config)` when the configuration changes (rare). If you throw an exception if the configuration is invalid, an error card will render to notify the user. + +```js +try { + element.setConfig(config); +} catch (err) { + showErrorCard(err.message, config); +} +``` + +Home Assistant will set the `hass` property when the state of Home Assistant changes (frequent). Whenever the state changes, the component will have to update itself to represent the latest state. + +```js +element.hass = hass; +``` + +Your card can define a `getCardSize` method that returns the size of your card as a number. A height of 1 is equivalent to 50 pixels. This will help Home Assistant distribute the cards evenly over the columns. A card size of `1` will be assumed if the method is not defined. + +```js +if ('getCardSize' in element) { + return element.getCardSize(); +} else { + return 1; +} +``` + ## Defining your card Create a new file in your Home Assistant config dir as `/www/content-card-example.js` and put in the following contents: @@ -133,10 +165,11 @@ class WiredToggleCard extends LitElement { `; } - _toggle(state) { - this.hass.callService('homeassistant', 'toggle', { - entity_id: state.entity_id - }); + setConfig(config) { + if (!config.entities) { + throw new Error('You need to define entities'); + } + this.config = config; } // The height of your card. Home Assistant uses this to automatically @@ -144,6 +177,12 @@ class WiredToggleCard extends LitElement { getCardSize() { return this.config.entities.length + 1; } + + _toggle(state) { + this.hass.callService('homeassistant', 'toggle', { + entity_id: state.entity_id + }); + } } customElements.define('wired-toggle-card', WiredToggleCard); ``` diff --git a/docs/lovelace_index.md b/docs/lovelace_index.md index f8a0086e..980dd99b 100644 --- a/docs/lovelace_index.md +++ b/docs/lovelace_index.md @@ -27,11 +27,12 @@ The old user interface relied solely on the state machine. This caused trouble a Create a new file `/ui-lovelace.yaml` and add the following content: ```yaml -name: My Awesome Home +title: My Awesome Home views: - # The name of a view will be used as tab title. - # Might be used for other things in the future. - - name: Example + # View tab title. + - title: Example + # Optional unique id for direct access /lovelace/${id} + id: example # Each view can have a different theme applied. Theme should be defined in the frontend. theme: dark-mode # The cards to show on this view. @@ -57,10 +58,10 @@ views: card_config: title: Input booleans that are on - # Specify a tab_icon if you want the view tab to be an icon. - - tab_icon: mdi:home-assistant - # Name of the view. Will be used as the tooltip for tab icon - name: Second view + # Specify a tab icon if you want the view tab to be an icon. + - icon: mdi:home-assistant + # Title of the view. Will be used as the tooltip for tab icon + title: Second view cards: - type: entities title: Lots of Kitchen AC