From bfdc3a872dc63bdb376331329cab9e03f930a279 Mon Sep 17 00:00:00 2001 From: Frank Klaassen Date: Wed, 17 Oct 2018 15:24:56 +0200 Subject: [PATCH 1/6] Add docs for data parameter in alert component --- source/_components/alert.markdown | 47 +++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/source/_components/alert.markdown b/source/_components/alert.markdown index 033cd9188738..c9047e463c4f 100644 --- a/source/_components/alert.markdown +++ b/source/_components/alert.markdown @@ -60,6 +60,11 @@ done_message: if an alert notification was sent for transitioning from `off` to `on`. This can include a [template][template]. required: false type: string +title: + description: > + A title to be used for the notification if the notifier supports it. + required: false + type: string entity_id: description: The ID of the entity to watch. required: true @@ -87,6 +92,16 @@ skip_first: required: false type: boolean default: false +data: + description: > + Dictionary of extra parameters to send to the notifier. + required: false + type: dictionary +data_template: + description: > + emplate dictionary of extra parameters to send to the notifier. + required: false + type: dictionary notifiers: description: "List of `notification` components to use for alerts." required: true @@ -192,4 +207,36 @@ following notification. For example, if the garage door opens at 2:00, a notification will be sent at 2:15, 2:45, 3:45, 4:45, etc., continuing every 60 minutes. + +### {% linkable_title Additional parameters for notifiers %} + +Some notifiers support more parameters (e.g. to set text color or action + buttons). These can be supplied via the `data` (or `data_template` in case + it is a template) parameter: + +```yaml +# Example configuration.yaml entry +alert: + garage_door: + name: Garage is open + entity_id: input_boolean.garage_door + state: 'on' # Optional, 'on' is the default value + repeat: + - 15 + - 30 + - 60 + can_acknowledge: True # Optional, default is True + skip_first: True # Optional, false is the default + data: + data: + inline_keyboard: + - 'Close garage:/close_garage, Acknowledge:/garage_acknowledge' + notifiers: + - frank_telegram +``` + +This particular example relies on the `inline_keyboard` functionality of +Telegram, where the user is presented with buttons to execute certain actions. + + [template]: /docs/configuration/templating/ From a8efc527b6208a944d49ad3e7017de341c45fcc1 Mon Sep 17 00:00:00 2001 From: Frank Klaassen Date: Mon, 22 Oct 2018 08:31:41 +0200 Subject: [PATCH 2/6] Fix docs based on feedback --- source/_components/alert.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_components/alert.markdown b/source/_components/alert.markdown index c9047e463c4f..43ffc3841b8b 100644 --- a/source/_components/alert.markdown +++ b/source/_components/alert.markdown @@ -96,12 +96,12 @@ data: description: > Dictionary of extra parameters to send to the notifier. required: false - type: dictionary + type: list data_template: description: > emplate dictionary of extra parameters to send to the notifier. required: false - type: dictionary + type: list notifiers: description: "List of `notification` components to use for alerts." required: true @@ -210,7 +210,7 @@ sent at 2:15, 2:45, 3:45, 4:45, etc., continuing every 60 minutes. ### {% linkable_title Additional parameters for notifiers %} -Some notifiers support more parameters (e.g. to set text color or action +Some notifiers support more parameters (e.g., to set text color or action buttons). These can be supplied via the `data` (or `data_template` in case it is a template) parameter: From a58e05018d1ee780a8600764e0fe9f76375620dc Mon Sep 17 00:00:00 2001 From: Frank Klaassen Date: Thu, 1 Nov 2018 17:03:46 +0100 Subject: [PATCH 3/6] Alter docs --- source/_components/alert.markdown | 87 ++++++++++++------------------- 1 file changed, 32 insertions(+), 55 deletions(-) diff --git a/source/_components/alert.markdown b/source/_components/alert.markdown index 07d018e4aab4..0e090939c412 100644 --- a/source/_components/alert.markdown +++ b/source/_components/alert.markdown @@ -54,20 +54,11 @@ name: description: The friendly name of the alert. required: true type: string -<<<<<<< HEAD -done_message: - description: > - A message sent after an alert transitions from `on` to `off`. Is only sent - if an alert notification was sent for transitioning from `off` to `on`. This can include a [template][template]. - required: false - type: string title: description: > A title to be used for the notification if the notifier supports it. required: false type: string -======= ->>>>>>> next entity_id: description: The ID of the entity to watch. required: true @@ -95,18 +86,6 @@ skip_first: required: false type: boolean default: false -<<<<<<< HEAD -data: - description: > - Dictionary of extra parameters to send to the notifier. - required: false - type: list -data_template: - description: > - emplate dictionary of extra parameters to send to the notifier. - required: false - type: list -======= message: description: > A message to be sent after an alert transitions from `of` to `on` @@ -115,16 +94,19 @@ message: type: template done_message: description: > - A message sent after an alert transitions from `on` to `off` with - [template][template] support. Is only sent if an alert notification + A message sent after an alert transitions from `on` to `off` with + [template][template] support. Is only sent if an alert notification was sent for transitioning from `off` to `on`. required: false type: template ->>>>>>> next notifiers: description: "List of `notification` components to use for alerts." required: true type: list +data: + description: "Dictionary of extra parameters to send to the notifier." + required: false + type: list {% endconfiguration %} In this example, the garage door status (`input_boolean.garage_door`) is watched @@ -226,13 +208,35 @@ following notification. For example, if the garage door opens at 2:00, a notification will be sent at 2:15, 2:45, 3:45, 4:45, etc., continuing every 60 minutes. -<<<<<<< HEAD +### {% linkable_title Message Templates %} + +It may be desirable to have the alert notifications include information +about the state of the entity. +The following will show for a plant how to include the problem `attribute` +of the entity. + +```yaml +# Example configuration.yaml entry + office_plant: + name: Plant in office needs help + entity_id: plant.plant_office + state: 'problem' + repeat: 30 + can_acknowledge: True + skip_first: True + message: "Plant {{ states.plant.plant_office }} needs help ({{ state_attr('plant.plant_office', 'problem') }})" + done_message: Plant in office is fine + notifiers: + - ryans_phone + - kristens_phone +``` + +The resulting message could be `Plant Officeplant needs help (moisture low)`. ### {% linkable_title Additional parameters for notifiers %} -Some notifiers support more parameters (e.g., to set text color or action - buttons). These can be supplied via the `data` (or `data_template` in case - it is a template) parameter: +Some notifiers support more parameters (e.g. to set text color or action + buttons). These can be supplied via the `data` parameter: ```yaml # Example configuration.yaml entry @@ -258,31 +262,4 @@ alert: This particular example relies on the `inline_keyboard` functionality of Telegram, where the user is presented with buttons to execute certain actions. -======= -### {% linkable_title Message Templates %} - -It may be desirable to have the alert notifications include information -about the state of the entity. -The following will show for a plant how to include the problem `attribute` -of the entity. - -```yaml -# Example configuration.yaml entry - office_plant: - name: Plant in office needs help - entity_id: plant.plant_office - state: 'problem' - repeat: 30 - can_acknowledge: True - skip_first: True - message: "Plant {{ states.plant.plant_office }} needs help ({{ state_attr('plant.plant_office', 'problem') }})" - done_message: Plant in office is fine - notifiers: - - ryans_phone - - kristens_phone -``` - -The resulting message could be `Plant Officeplant needs help (moisture low)`. ->>>>>>> next - [template]: /docs/configuration/templating/ From 5fbb3749d9453abba082ca29588764625f30587b Mon Sep 17 00:00:00 2001 From: Frank Klaassen Date: Thu, 1 Nov 2018 17:23:12 +0100 Subject: [PATCH 4/6] Re-add suggestion --- source/_components/alert.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_components/alert.markdown b/source/_components/alert.markdown index 0e090939c412..7f109b5b3e28 100644 --- a/source/_components/alert.markdown +++ b/source/_components/alert.markdown @@ -235,7 +235,7 @@ The resulting message could be `Plant Officeplant needs help (moisture low)`. ### {% linkable_title Additional parameters for notifiers %} -Some notifiers support more parameters (e.g. to set text color or action +Some notifiers support more parameters (e.g., to set text color or action buttons). These can be supplied via the `data` parameter: ```yaml From 580b6b4e65498040e0011505a5b69ffda79107ba Mon Sep 17 00:00:00 2001 From: Frank Klaassen Date: Tue, 6 Nov 2018 09:25:42 +0100 Subject: [PATCH 5/6] Update docs with proper data parameter --- source/_components/alert.markdown | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/_components/alert.markdown b/source/_components/alert.markdown index 7f109b5b3e28..6f4252e16a9e 100644 --- a/source/_components/alert.markdown +++ b/source/_components/alert.markdown @@ -252,9 +252,8 @@ alert: can_acknowledge: True # Optional, default is True skip_first: True # Optional, false is the default data: - data: - inline_keyboard: - - 'Close garage:/close_garage, Acknowledge:/garage_acknowledge' + inline_keyboard: + - 'Close garage:/close_garage, Acknowledge:/garage_acknowledge' notifiers: - frank_telegram ``` From f64a65db17d66c59c5aefa65bbdd6f8b93f65f73 Mon Sep 17 00:00:00 2001 From: Frank Klaassen Date: Wed, 23 Jan 2019 20:39:42 +0100 Subject: [PATCH 6/6] Add mention of templateable title --- source/_components/alert.markdown | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/_components/alert.markdown b/source/_components/alert.markdown index 7076fdc73996..765d5c91312c 100644 --- a/source/_components/alert.markdown +++ b/source/_components/alert.markdown @@ -60,9 +60,10 @@ entity_id: type: string title: description: > - A title to be used for the notification if the notifier supports it. + A title to be used for the notification if the notifier supports it + with [template][template] support. required: false - type: string + type: template state: description: The problem condition for the entity. required: false @@ -290,4 +291,4 @@ alert: This particular example relies on the `inline_keyboard` functionality of Telegram, where the user is presented with buttons to execute certain actions. -[template]: /docs/configuration/templating/ \ No newline at end of file +[template]: /docs/configuration/templating/