Rework lovelace views page

source/lovelace/views.markdown

@@ -9,88 +9,118 @@ sharing: true
 footer: true
 ---
 
-These are exactly as before, tab views with icons or text that help you manage large dashboards with many entities. The views have now deep-links like `/lovelace/0`. You can also assign your own [custom IDs](/lovelace/views/#custom-id).
-
-- Using custom id in view, for [nicer navigation paths](/lovelace/views/#custom-id) in URLs.
-- Using [icons](/lovelace/views/#icons) instead of text.
-- Using a card to [fill a complete view](/lovelace/views/#panel-view), just like panels.
-- Using [themes](/lovelace/views/#themes) in views.
-
-| Name | Type | Default | Description
-| ---- | ---- | ------- | -----------
-| title | string | Optional | Text title of the view
-| id | string | number | The id to use in URL path of this view
-| icon | string | Optional | The material design icon for the view, uses this instead of title
-| panel | boolean | false | Marks view as a panel reusing the first card in the list
-
-<p class='img'>
-<img src='/images/lovelace/lovelace_views.gif' alt='Screenshot of views'>
-Screenshot of views.
-</p>
+To display cards on the UI you have to define them in views. Views sort cards in columns based on their `card size`. If you want to group some cards you have to use `stack` cards.
 
-## {% linkable_title Icons %}
+<p class="img">
+  <img src="/images/lovelace/lovelace_views.png" alt="Views toolbar">
+  Use titles and icons to describe the content of views.
+</p>
 
-You can use icons instead of text for your view tabs. The title in the example will be used as a tooltip.
+{% configuration views %}
+views:
+  required: true
+  description: A list of view configurations.
+  type: list
+  keys:
+    title:
+      required: true
+      description: The title or name.
+      type: string
+    cards:
+      required: true
+      description: Cards to display in this view.
+      type: list
+    id:
+      required: false
+      description: IDs are used in the URL, more info below.
+      type: string
+      default: view index
+    icon:
+      required: false
+      description: Icon-name from Material Design Icons.
+      type: string
+    panel:
+      required: false
+      description: Renders the view in panel mode, more info below.
+      type: boolean
+      default: "false"
+    background:
+      required: false
+      description: Style the background using CSS, more info below.
+      type: string
+    theme:
+      required: false
+      description: Themes view and cards, more info below.
+      type: string
+{% endconfiguration %}
+
+## {% linkable_title IDs %}
+
+You can link to one view from another view by its ID. For this use cards that support navigation (`navigation_path`). Do not use special characters in IDs.
 
 ### {% linkable_title Example %}
 
+View config:
+
 ```yaml
-views:
-  - icon: mdi:settings
-    title: Debugging
+- title: Living room
+  # the final path is /lovelace/living_room
+  id: living_room
 ```
 
-## {% linkable_title Panel view %}
+Picture card config:
+
+```yaml
+- type: picture
+  image: /local/living_room.png
+  navigation_path: /lovelace/living_room
+```
+
+## {% linkable_title Icons %}
 
-This type of view uses the first card in the `cards` list to expand it to ocuppy the complete view space, similar to panels. One very good practical use will be for floor plan type of cards.
+If you define an icon the title will be used as a tooltip.
 
 ### {% linkable_title Example %}
 
 ```yaml
-views:
-  - icon: mdi:settings
-    id: debug
-    title: Floorplan
-    panel: true
-    cards:
-      - type: picture-elements
-        image: /local/floorplans/main.jpg
-        elements:
-          - type: state-icon
-            tap_action: toggle
-            entity: light.ceiling_lights
+- title: Garden
+  icon: mdi:flower
 ```
 
-## {% linkable_title Themes %}
+## {% linkable_title Panel mode %}
 
-You can also set a [theme](/frontend/#themes) per view. Theme is currently only partially usable (font color works).
+This renders the first card on full width, other cards in this view will not be rendered. Good for cards like `map`, `stack` or `picture-elements`.
+
+### {% linkable_title Example %}
 
 ```yaml
-views:
-  - icon: mdi:heart
-    id: debug
-    title: Home
-    theme: dark-mode
+- title: Map
+  panel: true
+  cards:
+    - type: map
+      entities:
+        - device_tracker.demo_paulus
+        - zone.home
 ```
 
-## {% linkable_title Custom ID %}
+## {% linkable_title Backround %}
 
-You can now assign a custom ID to a view, for nicer navigation paths in URLs. This id allows you to deep-link navigation to this view from cards that allow `navigation_path`. 
+Style the background of views using [CSS](https://en.wikipedia.org/wiki/Cascading_Style_Sheets). For wallpapers you probably want to use the example below, more options can be found [here](https://developer.mozilla.org/en-US/docs/Web/CSS/background).
 
 ### {% linkable_title Example %}
 
-View:
-
 ```yaml
-views:
-  - icon: mdi:settings
-    id: debugging
+- title: Living room
+  background: center / cover no-repeat url("/local/background.png") fixed
 ```
 
-Picture card:
+## {% linkable_title Themes %}
+
+Set a separate [theme](/components/frontend/#themes) for the view and its cards.
+
+### {% linkable_title Example %}
 
 ```yaml
-- type: picture
-  image: /local/debug.jpg
-  navigation_path: /lovelace/debugging
+- title: Home
+  theme: happy
 ```