From b6e9d59ea8501552e88271f6338deaaa1dcbc768 Mon Sep 17 00:00:00 2001
From: Paulus Schoutsen <paulus@home-assistant.io>
Date: Mon, 10 Dec 2018 11:36:13 +0100
Subject: [PATCH] Update Lovelace docs (#7791)

---
 .../_includes/asides/lovelace_navigation.html |  11 +-
 source/lovelace/how-it-works.markdown         |  21 +++
 source/lovelace/index.markdown                | 166 +-----------------
 source/lovelace/tips.markdown                 |  46 +++--
 source/lovelace/yaml-mode.markdown            | 107 +++++++++++
 5 files changed, 162 insertions(+), 189 deletions(-)
 create mode 100644 source/lovelace/how-it-works.markdown
 create mode 100644 source/lovelace/yaml-mode.markdown

diff --git a/source/_includes/asides/lovelace_navigation.html b/source/_includes/asides/lovelace_navigation.html
index 589f838ee21..fd5b58c70ab 100644
--- a/source/_includes/asides/lovelace_navigation.html
+++ b/source/_includes/asides/lovelace_navigation.html
@@ -7,11 +7,20 @@
     <ul class='divided sidebar-menu'>
       <li>{% active_link /lovelace/ Introduction %}</li>
       <li>{% active_link /lovelace/changelog/ Changelog %}</li>
-      <li>{% active_link /lovelace/views/ Views %}</li>
       <li>{% active_link /lovelace/tips/ Tips and Tricks %}</li>
     </ul>
   </div>
 
+  <div class='section'>
+    <h1 class="title delta">Advanced</h1>
+    <ul class='divided sidebar-menu'>
+      <li>{% active_link /lovelace/how-it-works/ How it works %}</li>
+      <li>{% active_link /lovelace/yaml-mode/ YAML mode %}</li>
+      <li>{% active_link /lovelace/views/ Views %}</li>
+      <li><a href='https://developers.home-assistant.io/docs/en/lovelace_custom_card.html'>Custom Cards (for developers) <i icon='icon-external-link'></i></a></li>
+    </ul>
+  </div>
+
   <div class='section'>
     <h1 class="title delta">Cards</h1>
     <ul class='divided sidebar-menu'>
diff --git a/source/lovelace/how-it-works.markdown b/source/lovelace/how-it-works.markdown
new file mode 100644
index 00000000000..bef0e43c823
--- /dev/null
+++ b/source/lovelace/how-it-works.markdown
@@ -0,0 +1,21 @@
+---
+layout: page
+title: "How Lovelace Works"
+description: "Explains how Lovelace works under the hood."
+date: 2018-07-01 10:28 +00:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+---
+
+The old user interface relied solely on the state machine. This caused trouble as it meant that the state machine was now not only the source for device states, but also for user interface configuration. With Lovelace, we're taking a completely different approach. All user interface configuration will live in a separate file, controlled by the user.
+
+<p class='img'>
+<img
+  src='/images/lovelace/lovelace-ui-comparison.png'
+  alt='Diagram showing how states no longer contain UI configuration.'>
+Visual comparison of old configuration versus new configuration
+</p>
+
+<!-- source: https://docs.google.com/drawings/d/1O1o7-wRlnsU1lLgfdtn3s46P5StJjSL5to5RU9SV8zs/edit?usp=sharing -->
diff --git a/source/lovelace/index.markdown b/source/lovelace/index.markdown
index c8088bd0409..f849d8af8f9 100644
--- a/source/lovelace/index.markdown
+++ b/source/lovelace/index.markdown
@@ -10,174 +10,16 @@ footer: true
 redirect_from: /components/lovelace/
 ---
 
-<p class='note'>
-This is an experimental feature. Configuration might change in future versions.
-</p>
-
-Starting with Home Assistant 0.72, we're experimenting with a new way of defining your interface. We're calling it the Lovelace UI.
-
-The Lovelace UI is:
-
-- **Extremely fast**. We create the user interface when the UI configuration changes. When a state changes, we just make the UI represent the current state.
-- **Extremely customizable**. We have a new file for just configuration. In the past, we declined UI specific options because they did not fit in the state machine. They will fit in a configuration file for a user interface.
-- **Extremely extensible**. It's based on the web standard [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Don't like the built-in cards? Make your own! Custom cards are treated the same as built-in cards and are configured the same way. [Check the docs.](https://developers.home-assistant.io/docs/en/lovelace_custom_card.html)
-- **Making the backend faster**. With Lovelace, the backend will no longer need to maintain entities like groups for the sole purpose of showing them on the frontend.
+Lovelace is the name of the Home Assistant user interface. It is a fast, customizable and powerful way for users to manage their homes, working both on mobile and desktop.
 
 <div class='videoWrapper'>
 <iframe width="560" height="315" src="https://www.youtube.com/embed/6FX9_leiikw" frameborder="0" allowfullscreen></iframe>
 </div>
 
-<p class='note warning'>
-If you're not using Firefox 63+ or Chrome, please be sure to [read the FAQ](/lovelace/#faq) below.
-</p>
-
-## {% linkable_title How it works %}
-
-The old user interface relied solely on the state machine. This caused trouble as it meant that the state machine was now not only the source for device states, but also for user interface configuration. With Lovelace, we're taking a completely different approach. All user interface configuration will live in a separate file, controlled by the user.
-
-<p class='img'>
-<img
-  src='/images/lovelace/lovelace-ui-comparison.png'
-  alt='Diagram showing how states no longer contain UI configuration.'>
-Visual comparison of old configuration versus new configuration
-</p>
-
-<!-- source: https://docs.google.com/drawings/d/1O1o7-wRlnsU1lLgfdtn3s46P5StJjSL5to5RU9SV8zs/edit?usp=sharing -->
-
-## {% linkable_title Trying it out %}
-
-Create a new file `<config>/ui-lovelace.yaml` and add the following content. Adjust the entity names to entities that exist in your Home Assistant installation.
-
-As a super minimal example, here's the bare minimum you will need for this to work:
-
-```yaml
-title: My Awesome Home
-views:
-    # View tab title.
-  - title: Example
-    panel: true
-    # Makes the first card fill the view
-    cards:
-        # The markdown card will render markdown text.
-      - type: markdown
-        title: Lovelace
-        content: >
-          Welcome to your **Lovelace UI**.
-```
-
-A slightly more advanced example shows additional elements which can be used to customize your frontend.
-
-```yaml
-title: My Awesome Home
-# Include external resources
-resources:
-  - url: /local/my-custom-card.js
-    type: js
-  - url: /local/my-webfont.css
-    type: css
-
-# Optional background for all views. Check https://developer.mozilla.org/en-US/docs/Web/CSS/background for more examples.
-background: center / cover no-repeat url("/background.png") fixed
-# Exclude entities from "Unused entities" view
-excluded_entities:
-  - weblink.router
-views:
-    # View tab title.
-  - title: Example
-    # Unique id for direct access /lovelace/${id} and editing it from the UI.
-    id: example
-    # Optional background (overwrites the global background).
-    background: radial-gradient(crimson, skyblue)
-    # Each view can have a different theme applied. Theme should be defined in the frontend.
-    theme: dark-mode
-    # The cards to show on this view.
-    cards:
-        # The filter card will filter entities for their state
-      - id: peoplehome # Every card needs an ID, for it to be edited from the UI.
-        type: entity-filter
-        entities:
-          - device_tracker.paulus
-          - device_tracker.anne_there
-        state_filter:
-          - 'home'
-        card:
-          type: glance
-          title: People that are home
-
-        # The picture entity card will represent an entity with a picture
-      - type: picture-entity
-        image: https://www.home-assistant.io/images/default-social.png
-        entity: light.bed_light
-
-    # Specify a tab icon if you want the view tab to be an icon.
-  - icon: mdi:home-assistant
-    # Title of the view. Will be used as the tooltip for tab icon
-    title: Second view
-    cards:
-        # Entities card will take a list of entities and show their state.
-      - type: entities
-        # Title of the entities card
-        title: Example
-        # The entities here will be shown in the same order as specified.
-        # Each entry is an entity ID or a map with extra options.
-        entities:
-          - light.kitchen
-          - switch.ac
-          - entity: light.living_room
-            # Override the name to use
-            name: LR Lights
-
-        # The markdown card will render markdown text.
-      - type: markdown
-        title: Lovelace
-        content: >
-          Welcome to your **Lovelace UI**.
-```
-
-Now restart Home Assistant, navigate to `<YOUR HASS URL>/lovelace`. When you make changes to `ui-lovelace.yaml`, you don't have to restart Home Assistant or refresh the page. Just hit the refresh button at the top of the UI.
-
-## {% linkable_title IDs for cards and views %}
-If you want to edit your views and cards from the UI, every card and view needs an ID. This ID is used to save your config from the UI. 
-
-## {% linkable_title Configuration splitting %}
-`ui-lovelace.yaml` only supports basic configuration splitting. Only `!include` and `!secret` are supported, be aware that content that is included with `!include` and `!secret` can not be edited from the UI.
-
-## {% linkable_title Setting Lovelace as the Default UI %}
-Once you are ready to start using Lovelace UI as your main user interface, click on info, the "i" icon under 'Developer Tools" in the Home Assistant side-bar. Next, locate >>Set Lovelace as default page on this device<< under the Home Assistant version information and click it.
+Lovelace is not the default UI just yet, but we're really close. Once you are ready to start using Lovelace UI as your main user interface, click on info, the "i" icon under 'Developer Tools" in the Home Assistant side-bar. Next, locate >>Set Lovelace as default page on this device<< under the Home Assistant version information and click it.
 
 Note that this is a per-device setting and will need to be changed on each device you access the UI from.
 
-## {% linkable_title Custom Cards %}
+## {% linkable_title Discuss Lovelace %}
 
-It is possible to add your own custom cards to show up in the Lovelace UI. For more information, check [the developer docs](https://developers.home-assistant.io/docs/en/lovelace_custom_card.html).
-
-## {% linkable_title Current limitations %}
-
-This is the very very early version aimed at gathering feedback. Discussion and suggestions are welcome in the [ui-schema repository](https://github.com/home-assistant/ui-schema) and in the [chat](/join-chat/) in #lovelace.
-
-## {% linkable_title FAQ %}
-
-### {% linkable_title I am running Firefox but, custom cards like gauge-card look bad or don't load at all. How do I fix this? %}
-
-This is probably because your version of Firefox doesn't have custom components supported or enabled. Please upgrade to version 63 or higher, otherwise set `dom.webcomponents.customelements.enabled` and `dom.webcomponents.shadowdom.enabled` to `true` in `about:config`.
-
-### {% linkable_title Custom cards don't load on my iOS device? %}
-
-Home Assistant comes with two versions of the frontend. A compatibility mode for older devices and a modern mode. The custom cards need to target one mode and usually choose the modern mode. Before Home Assistant 0.76, we had an issue in the automation and script editor that prevented modern iOS and Mac devices running Safari from using the modern mode.
-
-If you can, resolve this issue by upgrading to Home Assistant 0.76 or later. If you are on an older version and don't mind that the automation and script editor don't work on iOS devices, you can force the new version via the configuration:
-
-```yaml
-frontend:
-  javascript_version: latest
-```
-
-### {% linkable_title I would like to add an image to my card, but I do not know where to put them. %}
-
-Given examples refer to `/local/example_image.jpg`. That means you should have `www` directory next to your HA `configuration.yaml`. An image kept in `HA_configuration_dir/www/example_image.jpg` will be shown after refreshing Lovelace page.
-
-Restart Home Assistant after creating the `www` directory. Otherwise, HA will not know that you created this directory.
-
-### {% linkable_title My `ui-lovelace.yaml` file suddenly has ID's added to all cards and views! %}
-
-In version 0.81.0 we started preparing for the ability to edit you Lovelace UI from the UI itself. To be able to do this every view and card should have a unique ID. If your cards or views didn't had an ID, Home Assistant would add a random one. This behaviour was changed in 0.81.1, Home Assistant will no longer change your configuration without asking first. You can edit the generated ID, the only restriction is that it is unique. You could even delete the IDs if you don't want to use the UI edit functionality.
+Lovelace is still under development and we're always looking at making things better. Discussion and suggestions are welcome in the [ui-schema repository](https://github.com/home-assistant/ui-schema) and in the [chat](/join-chat/) in #lovelace.
diff --git a/source/lovelace/tips.markdown b/source/lovelace/tips.markdown
index 26343753e2d..e0d2ac4431f 100644
--- a/source/lovelace/tips.markdown
+++ b/source/lovelace/tips.markdown
@@ -15,6 +15,25 @@ might help you when working with Lovelace.
 *Have a tip or trick of your own? Click the "Edit this page on GitHub" at the
 top of this page to share it with everyone!*
 
+## {% linkable_title Tips & Tricks %}
+
+### {% linkable_title Add your your own image to Lovelace %}
+
+Home Assistant allows you to make files in `<config dir>/www/example_image.jpg` available to Lovelace as  `/local/example_image.jpg`. When you create the `www` directory, you will need to once restart Home Assistant to pick it up. After that, any new file placed in the directory will automatically be available.
+
+### {% linkable_title Disable Click on Elements %}
+
+If you do not want an element to be clickable you can add `pointer-events: none`
+to the element's `style:` configuration. This is quite useful when building a
+[Picture Elements][picture-elements] card that will be viewed mostly in a
+mobile browser. (@Toast)
+
+### {% linkable_title Header Using Panel and Stacks %}
+
+You can create a header by using `panel: true` with nested
+[Vertical Stack][vertical-stack] and [Horizontal Stack][horizontal-stack]
+cards. See the code [here][header-stacks]. ([@dale3h])
+
 ## {% linkable_title Tools %}
 
 We have some amazing users that have created various tools to help you get
@@ -33,32 +52,7 @@ you with the ability to split your Lovelace configuration into multiple files.
 
 ### {% linkable_title Lovelace Config Generator (Jinja2 Script) %}
 
-The [Lovelace Jinja2 Script][lovelace-jinja] by [@skalavala] is a simple Jinja2 script that you run in the template editor to generate lovelace configuration based on the entities that are already setup. 
-
-<p class='note'>
-  Lovelace only has limited file splitting functionality, due to the fact that Home Assistant
-  will be writing directly to the `ui-lovelace.yaml` file.
-  
-  Only `!include` and `!secret` are supported at the moment.
-  
-  If you want to split your configuration you can use one of the tools listed above, but edits done with the UI will
-  be overwritten by those tools, so you should not use both.
-</p>
-
-## {% linkable_title Tips and Tricks %}
-
-### {% linkable_title Header Using Panel and Stacks %}
-
-You can create a header by using `panel: true` with nested
-[Vertical Stack][vertical-stack] and [Horizontal Stack][horizontal-stack]
-cards. See the code [here][header-stacks]. ([@dale3h])
-
-### {% linkable_title Disable Click on Elements %}
-
-If you do not want an element to be clickable you can add `pointer-events: none`
-to the element's `style:` configuration. This is quite useful when building a
-[Picture Elements][picture-elements] card that will be viewed mostly in a
-mobile browser. (@Toast)
+The [Lovelace Jinja2 Script][lovelace-jinja] by [@skalavala] is a simple Jinja2 script that you run in the template editor to generate lovelace configuration based on the entities that are already setup.
 
 [@dale3h]: https://github.com/dale3h
 [@thomasloven]: https://github.com/thomasloven
diff --git a/source/lovelace/yaml-mode.markdown b/source/lovelace/yaml-mode.markdown
new file mode 100644
index 00000000000..eaff16c8035
--- /dev/null
+++ b/source/lovelace/yaml-mode.markdown
@@ -0,0 +1,107 @@
+---
+layout: page
+title: "Lovelace YAML mode"
+description: "Advanced users can switch on the advanced YAML mode."
+date: 2018-07-01 10:28 +00:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+---
+
+It is possible to write your Lovelace config in YAML instead of via the UI. To do so, you will need to configure the Lovelace component to be in yaml mode:
+
+```yaml
+lovelace:
+  mode: yaml
+```
+
+Restart Home Assistant for the mode to be changed. Create a new file `<config>/ui-lovelace.yaml` and add the following content. Adjust the entity names to entities that exist in your Home Assistant installation.
+
+As a super minimal example, here's the bare minimum you will need for this to work:
+
+```yaml
+title: My Awesome Home
+views:
+    # View tab title.
+  - title: Example
+    panel: true
+    # Makes the first card fill the view
+    cards:
+        # The markdown card will render markdown text.
+      - type: markdown
+        title: Lovelace
+        content: >
+          Welcome to your **Lovelace UI**.
+```
+
+A slightly more advanced example shows additional elements which can be used to customize your frontend.
+
+```yaml
+title: My Awesome Home
+# Include external resources
+resources:
+  - url: /local/my-custom-card.js
+    type: js
+  - url: /local/my-webfont.css
+    type: css
+
+# Optional background for all views. Check https://developer.mozilla.org/en-US/docs/Web/CSS/background for more examples.
+background: center / cover no-repeat url("/background.png") fixed
+# Exclude entities from "Unused entities" view
+excluded_entities:
+  - weblink.router
+views:
+    # View tab title.
+  - title: Example
+    # Unique id for direct access /lovelace/${id} and editing it from the UI.
+    id: example
+    # Optional background (overwrites the global background).
+    background: radial-gradient(crimson, skyblue)
+    # Each view can have a different theme applied. Theme should be defined in the frontend.
+    theme: dark-mode
+    # The cards to show on this view.
+    cards:
+        # The filter card will filter entities for their state
+      - id: peoplehome # Every card needs an ID, for it to be edited from the UI.
+        type: entity-filter
+        entities:
+          - device_tracker.paulus
+          - device_tracker.anne_there
+        state_filter:
+          - 'home'
+        card:
+          type: glance
+          title: People that are home
+
+        # The picture entity card will represent an entity with a picture
+      - type: picture-entity
+        image: https://www.home-assistant.io/images/default-social.png
+        entity: light.bed_light
+
+    # Specify a tab icon if you want the view tab to be an icon.
+  - icon: mdi:home-assistant
+    # Title of the view. Will be used as the tooltip for tab icon
+    title: Second view
+    cards:
+        # Entities card will take a list of entities and show their state.
+      - type: entities
+        # Title of the entities card
+        title: Example
+        # The entities here will be shown in the same order as specified.
+        # Each entry is an entity ID or a map with extra options.
+        entities:
+          - light.kitchen
+          - switch.ac
+          - entity: light.living_room
+            # Override the name to use
+            name: LR Lights
+
+        # The markdown card will render markdown text.
+      - type: markdown
+        title: Lovelace
+        content: >
+          Welcome to your **Lovelace UI**.
+```
+
+Navigate to `<YOUR HASS URL>/lovelace`. When you make changes to `ui-lovelace.yaml`, you don't have to restart Home Assistant or refresh the page. Just hit the refresh button in the menu at the top of the UI.