From 4fcec32a88ba71e1fd1ff1825c0b1fb4625249d7 Mon Sep 17 00:00:00 2001
From: Paulus Schoutsen <paulus@paulusschoutsen.nl>
Date: Tue, 9 Feb 2016 07:52:39 -0800
Subject: [PATCH] Update template switch docs

---
 source/_components/switch.template.markdown | 97 +++++++++++++++------
 1 file changed, 69 insertions(+), 28 deletions(-)

diff --git a/source/_components/switch.template.markdown b/source/_components/switch.template.markdown
index 847a47a26eb..ab789f34b9e 100644
--- a/source/_components/switch.template.markdown
+++ b/source/_components/switch.template.markdown
@@ -10,53 +10,94 @@ footer: true
 ha_category: Switch
 ---
 
-The `template` platform supports switches which breaks out `turn_on` and the `turn_off` service.
+The `template` platform creates switches that combine components.
+
+For example, if you have a garage door with a toggle switch that operates the motor and a sensor that allows you know whether the door is open or closed, you can combine these into a switch that knows whether the garage door is open or closed.
+
+This can simplify the gui, and make it easier to write automations. You can mark the components you have combined as `hidden` so they don't appear themselves.
 
 To enable Template switches in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
 # Example configuration.yaml entry
 switch:
-  platform: template
-  switches:
-    test_switch:
-      friendly_name: 'Slow script'
-      value_template: '{% raw %}{{ states.script.slow.state }}{% endraw %}'
-      turn_on:
-        service: script.turn_on
-        entity_id: script.slow
-      turn_off:
-        service: script.turn_off
-        entity_id: script.slow
+    platform: template
+    switches:
+        skylight:
+            friendly_name: 'Skylight'
+            value_template: {% raw %}'{{ states.sensor.skylight.state }}'{% endraw %}
+            turn_on:
+                service: switch.turn_on
+                entity_id: switch.skylight_open
+            turn_off:
+                service: switch.turn_on
+                entity_id: switch.skylight_close
 ```
 
 Configuration variables:
 
 - **switches** array (*Required*): List of your switches.
   - **friendly_name** (*Optional*): Name to use in the Frontend.
-  - **value_template** (*Optional*): Defines a [template](/getting-started/templating/) to extract a value from the payload.
-  - **turn_on** (*Required*): Contains the `service` and the `entity_id` which are involved.
-  - **turn_off** (*Required*):  Contains the `service` and the `entity_id` which are involved.
+  - **value_template** (*Required*): Defines a [template](/getting-started/templating/) to set the state of the switch.
+  - **turn_on** (*Required*): Defines an [action](/getting-started/automation/) to run when the switch is turned on.
+  - **turn_off** (*Required*): Defines an [action](/getting-started/automation/) to run when the switch is turned off.
 
 ## {% linkable_title Examples %}
 
-In this section you find some real life examples of how to use this sensor.
+In this section you find some real life examples of how to use this switch.
 
-### {% linkable_title Sun angle %}
+### {% linkable_title Copy switch %}
 
-This example shows how a skylight with a sensor which shows if it's open or closed and two momentary switches to operate the open and close is handled.
+This example shows a switch that copies another switch.
 
 ```yaml
 switch:
-  - platform: template
-      switches:
-        skylight:
-          value_template: "{% raw %}{{ states.sensor.skylight == 'tripped' }}{% endraw %}"
-          turn_on:
-            service: switch.turn_on
-            entity_id: switch.skylight_open
-           turn_off:
-             service: switch.turn_on
-             entity_id: switch.skylight_close
+    platform: template
+    switches:
+        copy:
+            value_template: {% raw %}'{{ states.switch.source.state }}'{% endraw %}
+            turn_on:
+                service: switch.turn_on
+                entity_id: switch.source
+            turn_off:
+                service: switch.turn_off
+                entity_id: switch.source
+````
+
+### {% linkable_title Toggle switch %}
+
+This example shows a switch that takes its state from a sensor, and toggles a switch.
+
+```yaml
+switch:
+    platform: template
+    switches:
+        blind:
+            friendly_name: 'Blind'
+            value_template: {% raw %}'{{ state }}'{% endraw %}
+            turn_on:
+                service: switch.toggle
+                entity_id: switch.blind_toggle
+            turn_off:
+                service: switch.toggle
+                entity_id: switch.blind_toggle
 ```
 
+### {% linkable_title Sensor and two switches %}
+
+This example shows a switch that takes its state from a sensor, and uses two momentary switches to control a device.
+
+```yaml
+switch:
+    platform: template
+    switches:
+        skylight:
+            friendly_name: 'Skylight'
+            value_template: {% raw %}'{{ states.sensor.skylight.state }}'{% endraw %}
+            turn_on:
+                service: switch.turn_on
+                entity_id: switch.skylight_open
+            turn_off:
+                service: switch.turn_on
+                entity_id: switch.skylight_close
+```