Skip to content

Commit 6dd9e6a

Browse files
j9brownj9brown
committed
Update the documentation.
1 parent 7e64589 commit 6dd9e6a

File tree

1 file changed

+234
-71
lines changed

1 file changed

+234
-71
lines changed

‎README.md

Lines changed: 234 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -23,100 +23,267 @@ We all use multiple times the same block of configuration across our lovelace co
2323

2424
### Defining your templates
2525

26-
First, you need to define your templates.
26+
There are two ways to define your templates. You can use both methods together.
2727

28-
The templates are defined in an object at the root of your lovelace configuration. This object needs to be named `decluttering_templates`.
28+
#### Option 1. Create a template as a card with the visual editor or with YAML.
2929

30-
This object needs to contains your templates declaration, each template has a name and can contain variables. A variable needs to be enclosed in double square brackets `[[variable_name]]`. It will later be replaced by a real value when you instanciate a card which uses this template. If a variable is alone on it's line, enclose it in single quotes: `'[[variable_name]]'`.
30+
Add a *Custom: Decluttering template* card in any view of your dashboard to define your template,
31+
set variables with their default values, and preview the results with those defaults with the
32+
visual editor. The card type is `custom:decluttering-template` in YAML.
3133

32-
You can also define default values for your variables in the `default` object.
34+
You can place the template card anywhere and it will only visible when the dashboard is in edit mode.
35+
Each template must have a unique name.
3336

34-
For a card:
37+
**Example:**
3538

3639
```yaml
37-
decluttering_templates:
38-
<template_name>
39-
default: # This is optional
40-
- <variable_name>: <variable_value>
41-
- <variable_name>: <variable_value>
42-
[...]
43-
card: # This is where you put your card config (it can be a card embedding other cards)
44-
type: custom:my-super-card
45-
[...]
40+
type: custom:decluttering-template
41+
template: follow_the_sun
42+
card:
43+
type: entity
44+
entity_id: sun.sun
4645
```
4746
48-
For a Picture-Element:
47+
#### Option 2. Create a template at the root of your lovelace configuration.
48+
49+
Open your dashboard's YAML configuration file or click on the *Raw configuration editor* menu item
50+
in the dashboard.
51+
52+
The templates are defined in an object at the root of your lovelace configuration. This object is
53+
named `decluttering_templates` and it contains your template declarations. Each template must have
54+
a unique name.
55+
56+
**Example:**
4957

5058
```yaml
59+
title: Example Dashboard
5160
decluttering_templates:
52-
<template_name>
53-
default: # This is optional
54-
- <variable_name>: <variable_value>
55-
- <variable_name>: <variable_value>
56-
[...]
57-
element: # This is where you put your element config
61+
follow_the_sun:
62+
card:
63+
type: entity
64+
entity_id: sun.sun
65+
touch_the_sun:
66+
row:
67+
type: button
68+
entity: sun.sun
69+
action_name: Boop
70+
hello_sunshine:
71+
element:
5872
type: icon
59-
[...]
73+
icon: mdi:weather-sunny
74+
title: Hello!
75+
style:
76+
color: yellow
77+
views:
6078
```
6179

62-
Example in your `lovelace-ui.yaml`:
63-
```yaml
64-
resources:
65-
- url: /local/decluttering-card.js
66-
type: module
80+
**Syntax:**
6781

82+
```yaml
6883
decluttering_templates:
69-
my_first_template: # This is the name of a template
70-
default:
71-
- icon: fire
72-
card:
73-
type: custom:button-card
74-
name: '[[name]]'
75-
icon: 'mdi:[[icon]]'
84+
<template name>:
85+
<template content>
86+
[...]
87+
```
7688

77-
my_second_template: # This is the name of another template
78-
card:
79-
type: custom:vertical-stack-in-card
80-
cards:
81-
- type: horizontal-stack
82-
cards:
83-
- type: custom:button-card
84-
entity: '[[entity_1]]'
85-
- type: custom:button-card
86-
entity: '[[entity_2]]'
89+
### Adding content to your templates
90+
91+
You can make decluttering templates for cards, entity rows, and picture elements. Each content type
92+
has a different syntax and can be used in different places.
93+
94+
#### [Card](https://www.home-assistant.io/dashboards/cards/)
95+
96+
A decluttering template can hold a standard dashboard card, custom card, or another decluttering card.
97+
It is particularly useful for complex cards such as stacks, grids, and tiles.
98+
99+
**Example:**
100+
101+
```yaml
102+
type: custom:decluttering-template
103+
template: follow_the_sun
104+
card:
105+
type: entity
106+
entity_id: sun.sun
107+
```
108+
109+
**Syntax:**
110+
111+
```yaml
112+
type: custom:decluttering-template
113+
template: <template_name>
114+
card:
115+
# This is where you put your [Card](https://www.home-assistant.io/dashboards/cards/) configuration (it can be a card embedding other cards)
116+
type: <card_type>
117+
[...]
118+
default:
119+
# An optional list of variables and their default values to substitute into the template
120+
- <variable_name>: <variable_value>
121+
- <variable_name>: <variable_value>
122+
[...]
123+
```
124+
125+
#### [Entities card](https://www.home-assistant.io/dashboards/entities/) row
126+
127+
A decluttering template can hold an Entities card row such as a Button row or a Conditional row.
128+
129+
**Example:**
130+
131+
```yaml
132+
type: custom:decluttering-template
133+
template: touch_the_sun
134+
row:
135+
type: button
136+
entity: sun.sun
137+
action_name: Boop
138+
```
139+
140+
**Syntax:**
141+
142+
```yaml
143+
type: custom:decluttering-template
144+
template: <template_name>
145+
row:
146+
# This is where you put your [Entities card](https://www.home-assistant.io/dashboards/entities/) row
147+
type: <element_type>
148+
[...]
149+
default:
150+
# An optional list of variables and their default values to substitute into the template
151+
- <variable_name>: <variable_value>
152+
- <variable_name>: <variable_value>
153+
[...]
154+
```
155+
156+
#### [Picture elements card](https://www.home-assistant.io/dashboards/picture-elements/) element
157+
158+
A decluttering template can hold a Picture elements card element such as an Icon or an Image.
159+
160+
**Example:**
161+
162+
```yaml
163+
type: custom:decluttering-template
164+
template: hello_sunshine
165+
element:
166+
type: icon
167+
icon: mdi:weather-sunny
168+
title: Hello!
169+
style:
170+
color: yellow
171+
```
172+
173+
**Syntax:**
174+
175+
```yaml
176+
type: custom:decluttering-template
177+
template: <template_name>
178+
element:
179+
# This is where you put your [Picture elements card](https://www.home-assistant.io/dashboards/picture-elements/) element configuration
180+
type: <element_type>
181+
[...]
182+
default:
183+
# An optional list of variables and their default values to substitute into the template
184+
- <variable_name>: <variable_value>
185+
- <variable_name>: <variable_value>
186+
[...]
187+
```
188+
189+
#### Variables
190+
191+
Templates can contain variables. Each variable will later be replaced by a real value when you
192+
instantiate a card which uses this template.
193+
194+
A variable needs to be enclosed in double square brackets `[[variable_name]]`. If a variable is alone
195+
on its line, enclose it in single quotes: `'[[variable_name]]'`.
196+
197+
You can also define default values for your variables in the `default` object. The visual editor uses the
198+
provided default values to render the preview.
199+
200+
**Example:**
201+
202+
```yaml
203+
type: custom:decluttering-template
204+
template: touch_anything
205+
row:
206+
type: button
207+
entity: '[[what]]'
208+
action_name: '[[how]]'
209+
default:
210+
what: sun.sun
211+
how: 'Boop'
87212
```
88213

89214
### Using the card
90215

91-
| Name | Type | Requirement | Description
92-
| ---- | ---- | ------- | -----------
93-
| type | string | **Required** | `custom:decluttering-card`
94-
| template | object | **Required** | The template to use from `decluttering_templates`
95-
| variables | list | **Optional** | List of variables and their value to replace in the `template`
216+
If your template content is a card, add a *Custom: Decluttering card* to your dashboard
217+
to instantiate your template, set variables, and preview the results with the visual editor.
218+
The card type is `custom:decluttering-template` in YAML.
219+
220+
If your template content is an Entities card row, first add a *Entities card* to your dashboard or
221+
open an existing one. Then switch to the code editor and add a new item to the `entities`
222+
list in YAML as shown below.
223+
224+
If your template content is an Picture elements card element, first add a *Picture elements* to your
225+
dashboard or open an existing one. Then switch to the code editor and add a new item to the
226+
`elements` list in YAML as shown below.
227+
228+
You can also use templates in different places than they were intended. For example, an
229+
Entities card row or Picture elements card element can be displayed as a card in the dashboard but
230+
it might not look right.
231+
232+
**Example which references the previous templates:**
96233

97-
Example which references the previous templates:
98234
```yaml
99-
- type: custom:decluttering-card
100-
template: my_first_template
101-
variables:
102-
- name: Test Button
103-
- icon: arrow-up
104-
105-
- type: custom:decluttering-card
106-
template: my_first_template
107-
variables: Default Icon Button
108-
109-
- type: custom:decluttering-card
110-
template: my_second_template
111-
variables:
112-
- entity_1: switch.my_switch
113-
- entity_2: light.my_light
235+
type: vertical-stack
236+
cards:
237+
# A card
238+
- type: custom:decluttering-card
239+
template: follow_the_sun
240+
# An Entities card
241+
- type: entities
242+
entities:
243+
# An entity row
244+
- type: custom:decluttering-card
245+
template: touch_the_sun
246+
# An entity row with variables using default values
247+
- type: custom:decluttering-card
248+
template: touch_anything
249+
# An entity row with variables using specified values
250+
- type: custom:decluttering-card
251+
template: touch_anything
252+
variables:
253+
- what: sensor.moon_phase
254+
- how: 'Kiss'
255+
# A Picture elements card
256+
- type: picture-elements
257+
elements:
258+
- type: custom:decluttering-card
259+
template: hello_sunshine
260+
style:
261+
top: 50%
262+
left: 33%
263+
- type: custom:decluttering-card
264+
template: hello_sunshine
265+
style:
266+
top: 50%
267+
left: 66%
114268
```
115269

270+
**Syntax:**
271+
272+
| Name | Type | Requirement | Description
273+
| ---- | ---- | ------- | -----------
274+
| type | string | **Required** | `custom:decluttering-card`
275+
| template | object | **Required** | Name of your template
276+
| variables | list | **Optional** | List of variables and their values to replace in the template content
116277

117278
## Installation
118279

119-
### Step 1
280+
### Using HACS
281+
282+
[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=custom-cards&repository=decluttering-card&category=lovelace)
283+
284+
### Manually
285+
286+
#### Step 1
120287

121288
Save [decluttering-card](https://github.com/custom-cards/decluttering-card/releases/download/latest/decluttering-card.js) to `<config directory>/www/decluttering-card.js` on your Home Assistant instanse.
122289

@@ -127,7 +294,7 @@ wget https://raw.githubusercontent.com/custom-cards/decluttering-card/master/dis
127294
mv decluttering-card.js /config/www/
128295
```
129296

130-
### Step 2
297+
#### Step 2
131298

132299
Link `decluttering-card` inside your `ui-lovelace.yaml` or Raw Editor in the UI Editor
133300

@@ -137,10 +304,6 @@ resources:
137304
type: module
138305
```
139306

140-
### Step 3
141-
142-
Add a custom element in your `ui-lovelace.yaml` or in the UI Editor as a Manual Card
143-
144307
## Troubleshooting
145308

146309
See this guide: [Troubleshooting](https://github.com/thomasloven/hass-config/wiki/Lovelace-Plugins)

0 commit comments

Comments
 (0)