Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/brunosabot/streamline-card
Streamline your Lovelace configuration with with a card template system.
https://github.com/brunosabot/streamline-card
custom-cards dashboard frontend hacktoberfest hacs home-assistant lovelace lovelace-custom-card
Last synced: 3 months ago
JSON representation
Streamline your Lovelace configuration with with a card template system.
- Host: GitHub
- URL: https://github.com/brunosabot/streamline-card
- Owner: brunosabot
- License: mit
- Created: 2024-08-07T18:14:35.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-09-30T07:07:48.000Z (3 months ago)
- Last Synced: 2024-09-30T19:03:38.386Z (3 months ago)
- Topics: custom-cards, dashboard, frontend, hacktoberfest, hacs, home-assistant, lovelace, lovelace-custom-card
- Language: JavaScript
- Homepage:
- Size: 285 KB
- Stars: 20
- Watchers: 0
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Streamline Card
Streamline your Lovelace configuration with with a card template system.
This card is for [Lovelace](https://www.home-assistant.io/lovelace) on [Home Assistant](https://www.home-assistant.io/).
We all use multiple times the same block of configuration across our lovelace configuration and we don't want to change the same things in a hundred places across our configuration each time we want to modify something.
`streamline-card` to the rescue! This card allows you to reuse multiple times the same configuration in your lovelace configuration to avoid repetition and supports variables and default values.
`streamline-card` is an adaptation of `decluttering-card` by [@brunosabot](https://github.com/brunosabot) which is not maintained anymore.
## Installation
### With HACS (Recommended)
This method allows you to get updates directly on the HACS main page
1. If HACS is not installed yet, download it following the instructions on [https://hacs.xyz/docs/use/download/download/](https://hacs.xyz/docs/use/download/download/)
2. Proceed to the HACS initial configuration following the instructions on [https://hacs.xyz/docs/configuration/basic](https://hacs.xyz/docs/configuration/basic)
3. On your sidebar go to `HACS`
4. Click on the three dots button at the top right corner then `Custom repositories`
5. Put the form:
- `https://github.com/brunosabot/streamline-card` as the repository
- `Dashboard` as the type
- Press `Add`
6. Now search for `Streamline Card` and then click on the button at the bottom right corner to download it
7. Go back on your dashboard and click on the icon at the right top corner then on `Edit dashboard`
8. You can now click on `Add card` in the bottom right corner and search for `Streamline Card`
If it's not working, try to clear your browser cache.
### Without HACS
1. Download these files: [streamline-card.js](https://raw.githubusercontent.com/brunosabot/streamline-card/main/dist/streamline-card.js)
2. Add these files to your `/www` folder
3. On your dashboard click on the icon at the right top corner then on `Edit dashboard`
4. Click again on that icon and then click on `Manage resources`
5. Click on `Add resource`
6. Copy and paste this: `/local/streamline-card.js?v=1`
7. Click on `JavaScript Module` then `Create`
8. Go back and refresh your page
9. You can now click on `Add card` in the bottom right corner and search for `streamline Card`
10. After any update of the file you will have to edit `/local/streamline-card.js?v=1` and change the version to any higher number
If it's not working, just try to clear your browser cache.`
## Configuration
### Defining your templates
First, you need to define your templates.
The templates are defined in an object at the root of your lovelace configuration. This object needs to be named `streamline_templates`.
#### With the yaml mode
> [!WARNING]
> The path are put here as examples. you might want to change them to match your needs.
>
> Also, you need to understand the principles of yaml and Home Assistant's includes to fully understand this version.
In your lovelace-dashboard.yaml file, you will find the following lines, adjusted to your needs:
```yaml
ui-example:
mode: yaml
title: My Example Dsahboard
icon: mdi:face-man
require_admin: false
show_in_sidebar: true
filename: lovelace/ui/ui-example.yaml
```
This will create a new dashboard named `ui-example` with the content of the file `lovelace/ui/ui-example.yaml`. This file name is very important because it is the place where you are going to put your templates.
The file will look like this:
```yaml
title: "My Example Dashboard"
views:
- !include ../views/example/first-view.yaml
streamline_templates: !include_dir_named ../streamline_templates/
```
or, if you want to inline all your templates:
```yaml
title: "My Example Dashboard"
views:
- !include ../views/example/first-view.yaml
streamline_templates:
my_first_template:
# ...
my_second_template:
# ...
```
#### With the UI Mode
> [!WARNING]
> Even if you are using the UI mode, you need to understand the principles of yaml to make streamline-card work.
When editing your dashboard in UI mode, you can find an option to edit it as a yaml file. For this, open the three dots menu at the top right of the dashboard and click on `Raw configuration editor`. This will open a panel where you can edit your dashboard as a yaml file.
In this file, just add at the top of the file the following lines:
```yaml
streamline_templates:
my_first_template:
# ...
my_second_template:
# ...
```
Next, you can get back to the UI mode and add new streamline-cards to your dashboard with the UI Editor.
#### Basic templates
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 instantiate a card which uses this template. If a variable is alone on it's line, enclose it in single quotes: `'[[variable_name]]'`.
You can also define default values for your variables in the `default` object.
For a card:
```yaml
streamline_templates:
default: # This is optional
- :
- :
[...]
card: # This is where you put your card config (it can be a card embedding other cards)
type: custom:my-super-card
[...]
```
For a Picture-Element:
```yaml
streamline_templates:
default: # This is optional
- :
- :
[...]
element: # This is where you put your element config
type: icon
[...]
```
Example in your `lovelace-ui.yaml`:
```yaml
resources:
- url: /local/streamline-card.js
type: module
streamline_templates:
my_first_template: # This is the name of a template
default:
- icon: fire
card:
type: custom:bubble-card
name: "[[name]]"
icon: "mdi:[[icon]]"
entity: "[[entity]]"
my_second_template: # This is the name of another template
card:
type: custom:vertical-stack-in-card
cards:
- type: horizontal-stack
cards:
- type: custom:bubble-card
entity: "[[entity_1]]"
- type: custom:bubble-card
entity: "[[entity_2]]"
```
#### Advanced templates
Every key of the template could be using a javascript expression. This could be useful if you want to condition the display of a card based on some advanced logic. Every key of the template that should be executed as JavaScript must end with `_javascript`.
For example, you can use this feature to display a different entity depending on a boolean status:
```yaml
streamline_templates:
my_advanced_template: # This is the name of a template
card:
type: custom:bubble-card
name: "[[name]]"
icon: "mdi:[[icon]]"
# This entity is a JavaScript expression
entity_javascript: "states[input_boolean.vacation_mode].state === 'on' ? 'weather.vacation_city' : 'sensor.home_city';"
```
If you have deep nested objects, you can use the same syntax everywhere:
```yaml
streamline_templates:
my_advanced_template: # This is the name of a template
card:
type: custom:bubble-card
name: "[[name]]"
icon: "mdi:[[icon]]"
sub_button:
- name: Min
# This icon is a JavaScript expression
icon_javascript: "states[input_boolean.vacation_mode].state === 'on' ? 'mdi:thermometer-off' : 'mdi:thermometer'"
entity: "[[entity]]"
attribute: forecast[0].templow
show_background: false
show_attribute: true
```
And if you have an array of simple items, you can also use the following syntax:
```yaml
streamline_templates:
my_advanced_template: # This is the name of a template
card:
type: custom:bubble-card
name: "[[name]]"
icon: "mdi:[[icon]]"
# This will create an array with the result of each JavaScript expression
example_javascript:
- "Math.random()"
- "Math.random()"
- "Math.random()"
```
Finally, you can combine classic variables and javascript expressions in the same template:
```yaml
streamline_templates:
my_advanced_template: # This is the name of a template
card:
type: custom:bubble-card
name: "[[name]]"
icon: "mdi:[[icon]]"
# This entity is a JavaScript expression using the toggle variable
entity_javascript: "states['[[toggle]]'].state === 'on' ? 'weather.vacation_city' : 'sensor.home_city';"
```
### Using the card
| Name | Type | Requirement | Description |
| --------- | ------ | ------------ | -------------------------------------------------------------- |
| type | string | **Required** | `custom:streamline-card` |
| template | object | **Required** | The template to use from `streamline_templates` |
| variables | list | **Optional** | List of variables and their value to replace in the `template` |
Example which references the previous templates:
```yaml
- type: custom:streamline-card
template: my_first_template
variables:
- name: Test Button
- icon: arrow-up
- type: custom:streamline-card
template: my_first_template
variables: Default Icon Button
- type: custom:streamline-card
template: my_second_template
variables:
- entity_1: switch.my_switch
- entity_2: light.my_light
```