Add headers & footers docs (#11824)

* Add headers & footers docs

* Add screenshots

* ✏️ Tweak

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

source/_includes/asides/lovelace_navigation.html

@@ -14,6 +14,7 @@
     <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/header-footer/ Headers & Footers %}</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'>Developing Custom Cards <i icon='icon-external-link'></i></a></li>

source/_lovelace/entities.markdown

@@ -67,6 +67,14 @@ format:
   required: false
   description: "How the state should be formatted. Currently only used for timestamp sensors. Valid values are: `relative`, `total`, `date`, `time` and `datetime`."
   type: string
+header:
+  required: false
+  description: Header widget to render. See [header documentation](/lovelace/header-footer/).
+  type: map
+footer:
+  required: false
+  description: Footer widget to render. See [footer documentation](/lovelace/header-footer/).
+  type: map
 tap_action:
   required: false
   description: Action to take on tap
@@ -280,6 +288,9 @@ Entity rows:
 type: entities
 title: Entities card sample
 show_header_toggle: true
+header:
+  image: 'https://www.home-assistant.io/images/lovelace/header-footer/balloons-header.png'
+  type: picture
 entities:
   - entity: alarm_control_panel.alarm
     name: Alarm Panel

source/lovelace/header-footer.markdown

@@ -0,0 +1,120 @@
+---
+title: "Headers & Footers for Lovelace cards"
+description: "Decorate your Lovelace cards with header and footer widgets."
+---
+
+Some Lovelace cards have support for header and footer widgets. These widgets fill up the whole available space in a card.
+
+## Picture header & footer
+
+Widget to show a picture as a header or a footer. A picture can have touch actions associated with it.
+
+<p class='img'><img src='/images/lovelace/header-footer/screenshot-picture-header.png' alt="Screenshot of an entities card with a picture header.">
+Screenshot of an entities card with a picture header.
+</p>
+
+```yaml
+type: picture
+image: 'https://www.home-assistant.io/images/lovelace/header-footer/balloons-header.png'
+```
+
+{% configuration header-footer %}
+type:
+  required: true
+  description: picture
+  type: string
+image:
+  required: true
+  description: The URL of an image.
+  type: string
+tap_action:
+  required: false
+  description: Action to take on tap
+  type: map
+  keys:
+    action:
+      required: true
+      description: "Action to perform (`more-info`, `toggle`, `call-service`, `navigate`, `url`, `none`)"
+      type: string
+      default: "`toggle`"
+    navigation_path:
+      required: false
+      description: "Path to navigate to (e.g. `/lovelace/0/`) when `action` defined as `navigate`"
+      type: string
+      default: none
+    url_path:
+      required: false
+      description: "Path to navigate to (e.g. `https://www.home-assistant.io`) when `action` defined as `url`"
+      type: string
+      default: none
+    service:
+      required: false
+      description: "Service to call (e.g. `media_player.media_play_pause`) when `action` defined as `call-service`"
+      type: string
+      default: none
+    service_data:
+      required: false
+      description: "Service data to include (e.g. `entity_id: media_player.bedroom`) when `action` defined as `call-service`"
+      type: string
+      default: none
+hold_action:
+  required: false
+  description: Action to take on tap-and-hold
+  type: map
+  keys:
+    action:
+      required: true
+      description: "Action to perform (`more-info`, `toggle`, `call-service`, `navigate`, `url`, `none`)"
+      type: string
+      default: "`more-info`"
+    navigation_path:
+      required: false
+      description: "Path to navigate to (e.g. `/lovelace/0/`) when `action` defined as `navigate`"
+      type: string
+      default: none
+    url_path:
+      required: false
+      description: "Path to navigate to (e.g. `https://www.home-assistant.io`) when `action` defined as `url`"
+      type: string
+      default: none
+    service:
+      required: false
+      description: "Service to call (e.g. `media_player.media_play_pause`) when `action` defined as `call-service`"
+      type: string
+      default: none
+    service_data:
+      required: false
+      description: "Service data to include (e.g. `entity_id: media_player.bedroom`) when `action` defined as `call-service`"
+      type: string
+      default: none
+double_tap_action:
+  required: false
+  description: Action to take on double tap
+  type: map
+  keys:
+    action:
+      required: true
+      description: "Action to perform (`more-info`, `toggle`, `call-service`, `navigate`, `url`, `none`)"
+      type: string
+      default: "`more-info`"
+    navigation_path:
+      required: false
+      description: "Path to navigate to (e.g. `/lovelace/0/`) when `action` defined as `navigate`"
+      type: string
+      default: none
+    url_path:
+      required: false
+      description: "Path to navigate to (e.g. `https://www.home-assistant.io`) when `action` defined as `url`"
+      type: string
+      default: none
+    service:
+      required: false
+      description: "Service to call (e.g. `media_player.media_play_pause`) when `action` defined as `call-service`"
+      type: string
+      default: none
+    service_data:
+      required: false
+      description: "Service data to include (e.g. `entity_id: media_player.bedroom`) when `action` defined as `call-service`"
+      type: string
+      default: none
+{% endconfiguration %}