Skip to content

Commit

Permalink
Rename layout view_layout
Browse files Browse the repository at this point in the history
  • Loading branch information
@thomasloven
thomasloven committed Mar 18, 2021
1 parent e64d02d commit 4fab6d7
Showing 1 changed file with 48 additions and 41 deletions.
89 changes: 48 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
layout-card
===========
# layout-card

[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg)](https://github.com/custom-components/hacs)

Expand All @@ -8,6 +7,7 @@ Get more control over the placement of lovelace cards
For installation instructions [see this guide](https://github.com/thomasloven/hass-config/wiki/Lovelace-Plugins).

# IMPORTANT!

# Due to name collisions with other popuplar lovelace cards, the parameter `layout` will likely very soon be called something else.

## Quick Start
Expand All @@ -32,12 +32,12 @@ You should now have more, narrower, collumns of cards in your view.
![Quick Start](https://user-images.githubusercontent.com/1299821/111066590-11abef80-84c0-11eb-809b-2843fd8610d8.gif)
## Usage
### View Layouts
Layout-card adds four new view layout to lovelace.
- Masonry (`custom:masonry-layout`)
- Horizontal (`custom:horizontal-layout`)
- Vertical (`custom:vertical-layout`)
Expand All @@ -54,8 +54,7 @@ views:
layout:
width: 300
max_cols: 10
cards:
...
cards: ...
```

### Layout-card
Expand All @@ -68,8 +67,7 @@ layout_type: masonry
layout_options:
width: 300
max_cols: 10
cards:
...
cards: ...
```

`Layout-card` will take its `cards` and place them within itself according to the specified layout.
Expand All @@ -79,25 +77,29 @@ cards:
> Thus `layout-card` is of limited use expect in [panel mode](https://www.home-assistant.io/lovelace/dashboards-and-views/#panel).

### Card layout options
Some layout types accept options added to separate cards:

Some layout types accept options added to separate cards in a `view_layout` parameter:

```yaml
type: entities
entities:
- light.bed_light
layout:
view_layout:
column: 2
```

### Layout-break card

Layout card adds a special card called `layout-break` which can be used to change how some layouts work.

```yaml
type: custom:layout-break
```

## Layouts

Layout-card introduces four layouts.

- Masonry
- Horizontal
- Vertical
Expand All @@ -110,14 +112,14 @@ The first three are column based and work similarly:
- Any empty columns are removed.
- The remaining columns are placed centered on screen.

All column based layouts accept the following options:
All column based layouts accept the following `view_layout` options:

|Option|Values|Description|Default|
|---|---|---|---|
|`width`| number | Size in pixels of each column | 300 |
|`max_width` | number | Maximum width of a card | 1.5 * `width` if specified <br> otherwise 500 |
|`max_cols` | number | Maximum number of columns to show | 4 if sidebar is hidden <br> 3 if sidebar is shown |
|`rtl`| `true`/`false` | Place columns in right-to-left order | `false`|
| Option | Values | Description | Default |
| ----------- | -------------- | ------------------------------------ | ------------------------------------------------- |
| `width` | number | Size in pixels of each column | 300 |
| `max_width` | number | Maximum width of a card | 1.5 \* `width` if specified <br> otherwise 500 |
| `max_cols` | number | Maximum number of columns to show | 4 if sidebar is hidden <br> 3 if sidebar is shown |
| `rtl` | `true`/`false` | Place columns in right-to-left order | `false` |

> NOTE: If you're migrating from layout-card "1.0" (v16 - sorry about the version number confusion), this is significantly fewer options than you are used to. \
> The reason for this is twofold. \
Expand All @@ -129,13 +131,14 @@ All column based layouts accept the following options:
### Masonry layout

The masonry layout immitates the default layout of lovelace.

- Each card is assigned a height based on their contents. One height unit corresponds to roughly 50 pixels, but this may varry.
- When a card is placed in the layout, it is put in the first column which has a total height of less than `min_height` units. \
Otherwise it is put it the shortest column.
Otherwise it is put it the shortest column.

![Masonry Layout](https://user-images.githubusercontent.com/1299821/111067510-f2639100-84c4-11eb-9ce1-b40cf1f13772.png)

The masonry layout accepts the following options:
The masonry layout accepts the following `layout` options:
|Option|Values|Description|Default
|---|---|---|---|
|`min_height`| number | Minimum number of card height units in a column before the next one is considered | 5 |
Expand All @@ -148,11 +151,10 @@ The horizontal layout will add each card to the next column, looping back to the

A `layout-break` card will cause the next card to be places in the first column.

The horizontal layout accepts the following **card** layout options:
The horizontal layout accepts the following **card** `view_layout` options:
|Option|Values|Description|Default
|---|---|---|---|
|`column`| number | Which column to place the card in. Following cards will be placed in the next column. | |

|`column`| number | Which column to place the card in. Following cards will be placed in the next column. | |

### Vertical layout

Expand All @@ -162,22 +164,24 @@ The vertical layout will add each card to the same column as the previous one.

A `layout-break` card will cause the next card to be placed in the next column.

The vertical layout accepts the following **card** layout options:
The vertical layout accepts the following **card** `view_layout` options:
|Option|Values|Description|Default
|---|---|---|---|
|`column`| number | Which column to place the card in. Following cards will be placed in the same column. | |
|`column`| number | Which column to place the card in. Following cards will be placed in the same column. | |

### Grid layout

The grid layout will give you full controll of your cards by leveraging [CSS Grid](https://css-tricks.com/snippets/css/complete-guide-grid/).

The grid layout accepts any option starting with `grid-` that works for a Grid Container.

Furthermore, the special option `mediaquery` can be used to set grid options depending on currently matched [@media rules](https://www.w3schools.com/cssref/css3_pr_mediaquery.asp). This helps immensely in creating fully responsive layouts. \
Please see the example code accompanying the screen recording below.

For the card layout options. the grid layout accepts any css grid property starting with `grid-` that works for a Grid Item.
For the card `view_layout` options. the grid layout accepts any css grid property starting with `grid-` that works for a Grid Item.

![Grid Layout](https://user-images.githubusercontent.com/1299821/111082577-4d1edc00-8509-11eb-80d1-2ecbdea7a085.gif)

<details>
<summary>Yaml code</summary>

Expand All @@ -202,51 +206,51 @@ cards:
- type: entities
entities:
- entity: light.bed_light
title: '1'
title: "1"
show_header_toggle: false
layout:
view_layout:
grid-area: header
- type: entities
entities:
- entity: light.bed_light
title: '2'
title: "2"
show_header_toggle: false
layout:
view_layout:
grid-area: footer
- type: entities
entities:
- entity: light.bed_light
title: '3'
title: "3"
show_header_toggle: false
layout:
view_layout:
grid-area: sidebar
- type: entities
entities:
- light.bed_light
- light.ceiling_lights
- light.kitchen_lights
title: '4'
title: "4"
show_header_toggle: false
layout:
view_layout:
grid-area: main
```

</details>


## Card visibility
Individual cards can be displayed or hidden based on their `show:` layout option.

Individual cards can be displayed or hidden based on their `show:` `view_layout` option.

```yaml
- type: entities
title: Always show
...
layout:
view_layout:
show: always
- type: entities
title: Never show
...
layout:
view_layout:
show: never
```

Expand All @@ -255,37 +259,39 @@ The options `show: always` and `show: never` are honestly quite pointless... but
```yaml
type: entities
title: Never show
...
layout:
---
view_layout:
show:
mediaquery: <mediaquery>
```

This card will only be displayed if the [@media rule](https://www.w3schools.com/cssref/css3_pr_mediaquery.asp) `<mediaquery>` is a match.

Example:

```yaml
- type: markdown
content: |
This is only shown on screens more than 800 px wide
layout:
view_layout:
show:
mediaquery: "(min-width: 800px)"
- type: markdown
content: |
This is only shown on screens less than 400 px wide
layout:
view_layout:
show:
mediaquery: "(max-width: 400px)"
- type: markdown
content: |
This is only shown on touch screen devices
layout:
view_layout:
show:
mediaquery: "(pointer: coarse)"
```

## Use with entity filters

Layout card can be used with cards that populate an `entities:` list, like [Entity Filter](https://www.home-assistant.io/lovelace/entity-filter/) or [auto-entities](https://github.com/thomasloven/lovelace-auto-entities).

If no card type is explicitly specified for the entries, the [Entity](https://www.home-assistant.io/lovelace/entity/) card will be used.
Expand All @@ -310,4 +316,5 @@ Example:
![auto-entities](https://user-images.githubusercontent.com/1299821/111070882-019e0b00-84d4-11eb-8a00-86683d598c3e.png)

---

<a href="https://www.buymeacoffee.com/uqD6KHCdJ" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/white_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>

0 comments on commit 4fab6d7

Please sign in to comment.