Skip to content

Commit 0ed6e37

Browse files
piitayapiitaya
committed
Update docs
1 parent 57ac65e commit 0ed6e37

File tree

8 files changed

+140
-58
lines changed

8 files changed

+140
-58
lines changed

‎README.md

Lines changed: 44 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,14 @@ Mushroom mission is to propose easy to use components to build your [Home Assist
1818

1919
### Features
2020

21-
- 🛠 Editor for **all cards** and and **all options** (no need to edit `yaml`)
22-
- 😍 Icon picker
23-
- 🖌 Color picker
24-
- 🚀 0 dependencies : no need to install another card.
25-
- 🌈 Based on Material UI colors
26-
- 🌓 Light and dark theme support
27-
- 🎨 Optional theme customization
28-
- 🌎 Internationalization
21+
- 🛠 Editor for **all cards** and and **all options** (no need to edit `yaml`)
22+
- 😍 Icon picker
23+
- 🖌 Color picker
24+
- 🚀 0 dependencies : no need to install another card.
25+
- 🌈 Based on Material UI colors
26+
- 🌓 Light and dark theme support
27+
- 🎨 Optional theme customization
28+
- 🌎 Internationalization
2929

3030
The goal of Mushroom is not to provide custom card for deep customization. You can use the excellent [UI Lovelace Minimalist][ui-lovelace-minimalist] and [Button card][button-card] plugins for this.
3131

@@ -46,20 +46,19 @@ _or_
4646
3. Search for "Mushroom"
4747
4. Click the download button. ⬇️
4848

49-
5049
### Manual
5150

5251
1. Download `mushroom.js` file from the [latest release][release-url].
5352
2. Put `mushroom.js` file into your `config/www` folder.
5453
3. Add reference to `mushroom.js` in Dashboard. There's two way to do that:
55-
- **Using UI:** _Settings_ → _Dashboards_ → _More Options icon_ → _Resources_ → _Add Resource_ → Set _Url_ as `/local/mushroom.js` → Set _Resource type_ as `JavaScript Module`.
56-
**Note:** If you do not see the Resources menu, you will need to enable _Advanced Mode_ in your _User Profile_
57-
- **Using YAML:** Add following code to `lovelace` section.
58-
```yaml
59-
resources:
60-
- url: /local/mushroom.js
61-
type: module
62-
```
54+
- **Using UI:** _Settings_ → _Dashboards_ → _More Options icon_ → _Resources_ → _Add Resource_ → Set _Url_ as `/local/mushroom.js` → Set _Resource type_ as `JavaScript Module`.
55+
**Note:** If you do not see the Resources menu, you will need to enable _Advanced Mode_ in your _User Profile_
56+
- **Using YAML:** Add following code to `lovelace` section.
57+
```yaml
58+
resources:
59+
- url: /local/mushroom.js
60+
type: module
61+
```
6362
6463
## Usage
6564
@@ -74,29 +73,35 @@ All the Mushroom cards can be configured using Dashboard UI editor.
7473
7574
Different cards are available for differents entities :
7675
77-
- 🚨 [Alarm card](docs/cards/alarm-control-panel.md)
78-
- 🔔 [Chips card](docs/cards/chips.md)
79-
- 🌡 [Climate card](docs/cards/climate.md)
80-
- 🪟 [Cover card](docs/cards/cover.md)
81-
- 🪄 [Entity card](docs/cards/entity.md)
82-
- 🕳 [Empty card](docs/cards/empty.md)
83-
- 💨 [Fan card](docs/cards/fan.md)
84-
- 💧 [Humidifier card](docs/cards/humidifier.md)
85-
- 💡 [Light card](docs/cards/light.md)
86-
- 🔒 [Lock card](docs/cards/lock.md)
87-
- 📺 [Media card](docs/cards/media-player.md)
88-
- 🔢 [Number card](docs/cards/number.md)
89-
- 🙋 [Person card](docs/cards/person.md)
90-
- 📑 [Select card](docs/cards/select.md)
91-
- 🛠 [Template card](docs/cards/template.md)
92-
- ✏️ [Title card](docs/cards/title.md)
93-
- 📦 [Update card](docs/cards/update.md)
94-
- 🧹 [Vacuum card](docs/cards/vacuum.md)
76+
- 🚨 [Alarm card](docs/cards/alarm-control-panel.md)
77+
- 🔔 [Chips card](docs/cards/chips.md)
78+
- 🌡 [Climate card](docs/cards/climate.md)
79+
- 🪟 [Cover card](docs/cards/cover.md)
80+
- 🪄 [Entity card](docs/cards/entity.md)
81+
- 🕳 [Empty card](docs/cards/empty.md)
82+
- 💨 [Fan card](docs/cards/fan.md)
83+
- 💧 [Humidifier card](docs/cards/humidifier.md)
84+
- 💡 [Light card](docs/cards/light.md)
85+
- 🔒 [Lock card](docs/cards/lock.md)
86+
- 📺 [Media card](docs/cards/media-player.md)
87+
- 🔢 [Number card](docs/cards/number.md)
88+
- 🙋 [Person card](docs/cards/person.md)
89+
- 📑 [Select card](docs/cards/select.md)
90+
- 🛠 [Template card](docs/cards/template.md)
91+
- ✏️ [Title card](docs/cards/title.md)
92+
- 📦 [Update card](docs/cards/update.md)
93+
- 🧹 [Vacuum card](docs/cards/vacuum.md)
94+
95+
### Legacy cards
96+
97+
Some cards are considered as legacy and are not available in the card picker :
98+
99+
- 🛠 [Legacy Template card](docs/cards/legacy-template.md)
95100
96101
### Badges
97102
98103
A [template badge](docs/badges/template.md) is available if you're using at least Home Assistant 2024.8.
99-
104+
100105
### Theme customization
101106
102107
Mushroom works without theme but you can add a theme for better experience by installing the [Mushroom Themes](https://github.com/piitaya/lovelace-mushroom-themes). If you want more information about themes, check out the official [Home Assistant documentation about themes][home-assitant-theme-docs].
@@ -159,9 +164,9 @@ If you want to help translating Mushroom, you can translate it directly from you
159164
2. Check that you have the latest Mushroom version on HACS
160165
3. Check that you have the latest Mushroom version by checking the browser console
161166
4. Clear your cache :
162-
- delete mushroom resources (https://my.home-assistant.io/redirect/lovelace_resources/)
163-
- uninstall Mushroom from HACS
164-
- reinstall Mushroom from HACS
167+
- delete mushroom resources (https://my.home-assistant.io/redirect/lovelace_resources/)
168+
- uninstall Mushroom from HACS
169+
- reinstall Mushroom from HACS
165170

166171
### My card mod configuration doesn't work.
167172

‎docs/cards/legacy-template.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Template card
2+
3+
![Template light](../images/legacy-template-light.png)
4+
![Template dark](../images/legacy-template-dark.png)
5+
6+
## Description
7+
8+
A template card allows you to build a custom card. You can use `entity` as a variable for the entity set on the card e.g. `{{ states(entity) }}`.
9+
10+
## Configuration variables
11+
12+
All the options are available in the lovelace editor but you can use `yaml` if you want.
13+
14+
| Name | Type | Default | Description |
15+
| :-------------------- | :-------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |
16+
| `entity` | string | Optional | Entity for template and actions |
17+
| `icon` | string | Optional | Icon to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/) \*. |
18+
| `icon_color` | string | Optional | Icon color to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
19+
| `primary` | string | Optional | Primary info to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
20+
| `secondary` | string | Optional | Secondary info to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
21+
| `badge_icon` | string | Optional | Badge icon to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
22+
| `badge_color` | string | Optional | Badge icon color to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
23+
| `picture` | string | Optional | Picture to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
24+
| `multiline_secondary` | boolean | `false` | Enables support for multiline text for the secondary info. |
25+
| `layout` | string | Optional | Layout of the card. Vertical, horizontal and default layout are supported |
26+
| `fill_container` | boolean | `false` | Fill container or not. Useful when card is in a grid, vertical or horizontal layout |
27+
| `tap_action` | action | `none` | Home assistant action to perform on tap |
28+
| `hold_action` | action | `none` | Home assistant action to perform on hold |
29+
| `double_tap_action` | action | `none` | Home assistant action to perform on double_tap |
30+
| `entity_id` | `string` `list` | Optional | Only reacts to the state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. |
31+
32+
#### Notes
33+
34+
\* You can render weather svg icons using [weather state](https://developers.home-assistant.io/docs/core/entity/weather/#recommended-values-for-state-and-condition) as icon :
35+
36+
- weather-clear-night
37+
- weather-cloudy
38+
- weather-fog
39+
- weather-lightning
40+
- weather-lightning-rainy
41+
- weather-partlycloudy
42+
- weather-pouring
43+
- weather-rainy
44+
- weather-hail
45+
- weather-snowy
46+
- weather-snowy-rainy
47+
- weather-sunny
48+
- weather-windy
49+
- weather-windy-variant

‎docs/cards/template.md

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -11,23 +11,29 @@ A template card allows you to build a custom card. You can use `entity` as a var
1111

1212
All the options are available in the lovelace editor but you can use `yaml` if you want.
1313

14-
| Name | Type | Default | Description |
15-
| :-------------------- | :-------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |
16-
| `entity` | string | Optional | Entity for template and actions |
17-
| `icon` | string | Optional | Icon to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/) \*. |
18-
| `icon_color` | string | Optional | Icon color to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
19-
| `primary` | string | Optional | Primary info to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
20-
| `secondary` | string | Optional | Secondary info to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
21-
| `badge_icon` | string | Optional | Badge icon to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
22-
| `badge_color` | string | Optional | Badge icon color to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
23-
| `picture` | string | Optional | Picture to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
24-
| `multiline_secondary` | boolean | `false` | Enables support for multiline text for the secondary info. |
25-
| `layout` | string | Optional | Layout of the card. Vertical, horizontal and default layout are supported |
26-
| `fill_container` | boolean | `false` | Fill container or not. Useful when card is in a grid, vertical or horizontal layout |
27-
| `tap_action` | action | `none` | Home assistant action to perform on tap |
28-
| `hold_action` | action | `none` | Home assistant action to perform on hold |
29-
| `double_tap_action` | action | `none` | Home assistant action to perform on double_tap |
30-
| `entity_id` | `string` `list` | Optional | Only reacts to the state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. |
14+
| Name | Type | Default | Description |
15+
| :----------------------- | :-------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16+
| `entity` | string | Optional | Entity for template, actions and card features |
17+
| `area` | string | Optional | Entity for template and card features |
18+
| `icon` | string | Optional | Icon to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/) \*. |
19+
| `color` | string | Optional | Color to render. Used for icon, background effect and some card features. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
20+
| `picture` | string | Optional | Picture to render. It will replace the icon. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
21+
| `primary` | string | Optional | Primary info displayed in the. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
22+
| `secondary` | string | Optional | Secondary info to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
23+
| `badge_icon` | string | Optional | Badge icon to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
24+
| `badge_text` | string | Optional | Badge text to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
25+
| `badge_color` | string | Optional | Badge color to render. May contain [templates](https://www.home-assistant.io/docs/configuration/templating/). |
26+
| `multiline_secondary` | boolean | `false` | Enables support for multiline text for the secondary info. |
27+
| `vertical` | boolean | Optional | Displayed the icon and the content verticaly or not |
28+
| `tap_action` | action | `none` | Home assistant action to perform on tap |
29+
| `hold_action` | action | `none` | Home assistant action to perform on hold |
30+
| `double_tap_action` | action | `none` | Home assistant action to perform on double_tap |
31+
| `icon_tap_action` | action | `none` | Home assistant action to perform on icon tap |
32+
| `icon_hold_action` | action | `none` | Home assistant action to perform on icon hold |
33+
| `icon_double_tap_action` | action | `none` | Home assistant action to perform on icon double_tap |
34+
| `features` | action | `none` | Card features to displayed on the card |
35+
| `features_position` | string | `bottom` | Where the card features should be displayed. I can be either `bottom` or `inline`. When using inline, only the first feature is displayed. |
36+
| `entity_id` | `string` `list` | Optional | Only reacts to the state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. |
3137

3238
#### Notes
3339

‎docs/images/template-dark.png renamed to ‎docs/images/legacy-template-dark.png

File renamed without changes.

‎docs/images/template-light.png renamed to ‎docs/images/legacy-template-light.png

File renamed without changes.

‎src/cards/template-card/template-card-config.ts

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import {
1212
import { ActionConfig, actionConfigStruct, LovelaceCardConfig } from "../../ha";
1313
import { LovelaceCardFeatureConfig } from "../../ha/panels/lovelace/card-features/types";
1414
import { lovelaceCardConfigStruct } from "../../shared/config/lovelace-card-config";
15+
import { layoutStruct } from "../../utils/layout";
1516

1617
export type TemplateCardConfig = LovelaceCardConfig & {
1718
entity?: string;
@@ -46,6 +47,10 @@ export type TemplateCardConfig = LovelaceCardConfig & {
4647
* @deprecated Use color instead
4748
*/
4849
icon_color?: string;
50+
/**
51+
* @deprecated Use vertical instead
52+
*/
53+
layout?: string;
4954
};
5055

5156
export const templateCardConfigStruct = assign(
@@ -81,5 +86,6 @@ export const templateCardConfigStruct = assign(
8186
entity_id: optional(union([string(), array(string())])),
8287
// Backwards compatibility from legacy template card
8388
icon_color: optional(string()),
89+
layout: optional(string()),
8490
})
8591
);

‎src/cards/template-card/template-card-editor.ts

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,8 +74,16 @@ export class TemplateCardEditor
7474
assert(config, templateCardConfigStruct);
7575
this._config = config;
7676
if (this._config.icon_color) {
77-
this._config.color = this._config.icon_color;
7877
delete this._config.icon_color;
78+
if (!this._config.color == null) {
79+
this._config.color = this._config.icon_color;
80+
}
81+
}
82+
if (this._config.layout) {
83+
delete this._config.layout;
84+
if (!this._config.vertical == null) {
85+
this._config.vertical = this._config.layout === "vertical";
86+
}
7987
}
8088
}
8189

‎src/cards/template-card/template-card.ts

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -221,8 +221,16 @@ export class Template extends LitElement implements LovelaceCard {
221221
...config,
222222
};
223223
if (this._config.icon_color) {
224-
this._config.color = this._config.icon_color;
225224
delete this._config.icon_color;
225+
if (!this._config.color == null) {
226+
this._config.color = this._config.icon_color;
227+
}
228+
}
229+
if (this._config.layout) {
230+
delete this._config.layout;
231+
if (!this._config.vertical == null) {
232+
this._config.vertical = this._config.layout === "vertical";
233+
}
226234
}
227235
}
228236

0 commit comments

Comments
 (0)