jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-08 09:56:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Redirect lovelace docs

Browse Source
This commit is contained in:
Paulus Schoutsen 2018-07-07 23:03:51 +02:00
parent 66e9e6d898
commit 9daeff6b84
6 changed files with 12 additions and 209 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/lovelace_custom_card.md
View File

@ -1,23 +1,18 @@
---
title: "Custom Cards"
title: "Lovelace: Custom Cards"
---
You're not just limited to the cards that we decided to include in the Lovelace UI. You can build and use your own!
[Lovelace](https://www.home-assistant.io/lovelace/) is our new approach to defining your user interface for Home Assistant. We offer a lot of built-in cards, but you're not just limited to the ones that we decided to include in the Lovelace UI. You can build and use your own!
## API
- 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/)).
- Home Assistant will set the `config` property when the configuration changes (rare).
- 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/)).
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 on React here](https://custom-elements-everywhere.com/#react)).
```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.
Home Assistant will call `setConfig(config)` when the configuration changes (rare). If you throw an exception if the configuration is invalid, Lovelace will render an error card to notify the user.
```js
try {

96
docs/lovelace_index.md
View File

@ -3,98 +3,6 @@ title: "Lovelace UI"
sidebar_label: Introduction
---
> This is an experimental feature. Configuration might change in future versions.
This page has been moved to https://www.home-assistant.io/lovelace/
Starting with Home Assistant 0.72, we're experimenting with a new way of defining your interface. We're calling it the Lovelace UI.
The Lovelace UI is:
- **Extremely fast**. We create the user interface when the UI configuration changes. When a state changes, we just make the UI represent the current state.
- **Extremely customizable**. We have a new file for just configuration. In the past, we declined UI specific options because they did not fit in the state machine. They will fit in a configuration file for a user interface.
- **Extremely extensible**. It's based on the web standard [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Don't like the built-in cards? Make your own! Custom cards are treated the same as built-in cards and are configured the same way. [Check the docs.](lovelace_custom_card.md)
- **Making the backend faster**. With Lovelace, the backend will no longer need to maintain entities like groups for the sole purpose of showing them on the frontend.
Documentation is still in flux. Latest card descriptions can currently be found [here](https://github.com/ciotlosm/docs-lovelace).
## How it works
The old user interface relied solely on the state machine. This caused trouble as it meant that the state machine was now not only the source for device states, but also for user interface configuration. With Lovelace, we're taking a completely different approach. All user interface configuration will live in a seperate file, controlled by the user.
![Visual comparison of old configuration versus new configuration](/img/en/frontend/lovelace-ui-comparison.png)
<!-- source: https://docs.google.com/drawings/d/1O1o7-wRlnsU1lLgfdtn3s46P5StJjSL5to5RU9SV8zs/edit?usp=sharing -->
## Trying it out
Create a new file `<config>/ui-lovelace.yaml` and add the following content:
```yaml
title: My Awesome Home
views:
# 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.
cards:
# The entities card will take a list of entities and show their state.
- type: entities
# Title of the entities card
title: Example
# The entities here will be shown in the same order as specified.
entities:
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_livingroom
- input_boolean.switch_tv
# The filter card will filter available entities for certain criteria
# and render it as type 'entities'.
- type: entity-filter
# Filter criteria. They are all optional.
filter:
- domain: input_boolean
state: 'on'
# This config will be passed to the card rendering the filter results
card_config:
title: Input booleans that are on
# 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
entities:
# It is totally possible to render duplicates.
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
```
Add to your `configuration.yaml`:
```yaml
input_boolean:
switch_ac_kitchen:
name: AC kitchen
switch_ac_livingroom:
name: AC living room
switch_tv:
name: TV
```
Now restart Home Assistant, navigate to `<YOUR HASS URL>/lovelace`. When you make changes to `ui-lovelace.yaml`, you don't have to restart Home Assistant or refresh the page. Just hit the refresh button at the top of the UI.
## Current limitations
This is the very very early version aimed at gathering feedback. Discussion and suggestions are welcome in the [ui-schema repository](https://github.com/home-assistant/ui-schema).
## Change log
[See here](https://github.com/ciotlosm/docs-lovelace/blob/master/changelog.md)
<script>document.location = 'https://www.home-assistant.io/lovelace/';</script>

6
website/i18n/en.json
View File

@ -116,7 +116,7 @@
"internationalization_custom_component_localization": "Custom Component Localization",
"internationalization_index": "Internationalization",
"internationalization_translation": "Translation",
"lovelace_custom_card": "Custom Cards",
"lovelace_custom_card": "Lovelace: Custom Cards",
"lovelace_index": "Lovelace UI",
"maintenance": "Maintenance",
"misc": "Miscellaneous",
@ -133,7 +133,6 @@
"Entity Registry": "Entity Registry",
"Extending the frontend": "Extending the frontend",
"Custom UI": "Custom UI",
"Lovelace UI": "Lovelace UI",
"Developing a feature": "Developing a feature",
"Development 101": "Development 101",
"Creating Platforms": "Creating Platforms",
@ -144,7 +143,8 @@
"Intents": "Intents",
"asyncio": "asyncio",
"Hass.io Add-Ons": "Hass.io Add-Ons",
"Maintainer docs": "Maintainer docs"
"Maintainer docs": "Maintainer docs",
"Lovelace UI": "Lovelace UI"
},
"pages-strings": {
"Learn more using the [documentation on this site.](/test-site/docs/en/doc1.html)|no description given": "Learn more using the [documentation on this site.](/test-site/docs/en/doc1.html)",

5
website/sidebars.json
View File

@ -53,12 +53,9 @@
"frontend_add_websocket_api"
],
"Custom UI": [
"lovelace_custom_card",
"frontend_creating_custom_ui",
"frontend_creating_custom_panels"
],
"Lovelace UI": [
"lovelace_index",
"lovelace_custom_card"
]
},
"Extending HASS": {

5
website/versioned_docs/version-0.73.0/lovelace_custom_card.md
View File

@ -8,11 +8,6 @@ You're not just limited to the cards that we decided to include in the Lovelace
## API
- 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/)).
- Home Assistant will set the `config` property when the configuration changes (rare).
- 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

96
website/versioned_docs/version-0.73.0/lovelace_index.md
View File

@ -5,98 +5,6 @@ id: version-0.73.0-lovelace_index
original_id: lovelace_index
---
> This is an experimental feature. Configuration might change in future versions.
This page has been moved to https://www.home-assistant.io/lovelace/
Starting with Home Assistant 0.72, we're experimenting with a new way of defining your interface. We're calling it the Lovelace UI.
The Lovelace UI is:
- **Extremely fast**. We create the user interface when the UI configuration changes. When a state changes, we just make the UI represent the current state.
- **Extremely customizable**. We have a new file for just configuration. In the past, we declined UI specific options because they did not fit in the state machine. They will fit in a configuration file for a user interface.
- **Extremely extensible**. It's based on the web standard [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Don't like the built-in cards? Make your own! Custom cards are treated the same as built-in cards and are configured the same way. [Check the docs.](lovelace_custom_card.md)
- **Making the backend faster**. With Lovelace, the backend will no longer need to maintain entities like groups for the sole purpose of showing them on the frontend.
Documentation is still in flux. Latest card descriptions can currently be found [here](https://github.com/ciotlosm/docs-lovelace).
## How it works
The old user interface relied solely on the state machine. This caused trouble as it meant that the state machine was now not only the source for device states, but also for user interface configuration. With Lovelace, we're taking a completely different approach. All user interface configuration will live in a seperate file, controlled by the user.
![Visual comparison of old configuration versus new configuration](/img/en/frontend/lovelace-ui-comparison.png)
<!-- source: https://docs.google.com/drawings/d/1O1o7-wRlnsU1lLgfdtn3s46P5StJjSL5to5RU9SV8zs/edit?usp=sharing -->
## Trying it out
Create a new file `<config>/ui-lovelace.yaml` and add the following content:
```yaml
title: My Awesome Home
views:
# 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.
cards:
# The entities card will take a list of entities and show their state.
- type: entities
# Title of the entities card
title: Example
# The entities here will be shown in the same order as specified.
entities:
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_livingroom
- input_boolean.switch_tv
# The filter card will filter available entities for certain criteria
# and render it as type 'entities'.
- type: entity-filter
# Filter criteria. They are all optional.
filter:
- domain: input_boolean
state: 'on'
# This config will be passed to the card rendering the filter results
card_config:
title: Input booleans that are on
# 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
entities:
# It is totally possible to render duplicates.
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
- input_boolean.switch_ac_kitchen
```
Add to your `configuration.yaml`:
```yaml
input_boolean:
switch_ac_kitchen:
name: AC kitchen
switch_ac_livingroom:
name: AC living room
switch_tv:
name: TV
```
Now restart Home Assistant, navigate to `<YOUR HASS URL>/lovelace`. When you make changes to `ui-lovelace.yaml`, you don't have to restart Home Assistant or refresh the page. Just hit the refresh button at the top of the UI.
## Current limitations
This is the very very early version aimed at gathering feedback. Discussion and suggestions are welcome in the [ui-schema repository](https://github.com/home-assistant/ui-schema).
## Change log
[See here](https://github.com/ciotlosm/docs-lovelace/blob/master/changelog.md)
<script>document.location = 'https://www.home-assistant.io/lovelace/';</script>