276 lines
No EOL
11 KiB
HTML
276 lines
No EOL
11 KiB
HTML
<!doctype html>
|
||
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
|
||
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
|
||
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
|
||
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
|
||
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||
<title>Templating - Home Assistant</title>
|
||
<meta name="author" content="Paulus Schoutsen">
|
||
<meta name="description" content="Instructions how to use the templating feature of Home Assistant.">
|
||
|
||
<meta name="viewport" content="width=device-width">
|
||
<link rel="canonical" href="https://home-assistant.io/getting-started/templating/">
|
||
|
||
<meta property="fb:app_id" content="338291289691179">
|
||
<meta property="og:title" content="Templating">
|
||
<meta property="og:site_name" content="Home Assistant">
|
||
<meta property="og:url" content="https://home-assistant.io/getting-started/templating/">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:description" content="Instructions how to use the templating feature of Home Assistant.">
|
||
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.png">
|
||
|
||
<meta name="twitter:card" content="summary">
|
||
<meta name="twitter:site" content="@home_assistant">
|
||
|
||
<meta name="twitter:title" content="Templating">
|
||
<meta name="twitter:description" content="Instructions how to use the templating feature of Home Assistant.">
|
||
<meta name="twitter:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.png">
|
||
|
||
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
|
||
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
|
||
<link rel='shortcut icon' href='/images/favicon.ico' />
|
||
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
|
||
</head>
|
||
|
||
<body >
|
||
|
||
<header>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
|
||
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
|
||
<a href="/" class="site-title">
|
||
<img width='40' src='/images/favicon-192x192.png'>
|
||
<span>Home Assistant</span>
|
||
</a>
|
||
</div>
|
||
|
||
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
|
||
<nav>
|
||
<input type="checkbox" id="toggle">
|
||
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
|
||
<ul class="menu pull-right">
|
||
<li>
|
||
<a href="/getting-started/">Getting started</a>
|
||
<ul>
|
||
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
|
||
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
|
||
<li><a href='/getting-started/devices/'>Adding devices</a></li>
|
||
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
|
||
<li><a href='/getting-started/automation/'>Automation</a></li>
|
||
<li><a href='/getting-started/templating/'>Templating</a></li>
|
||
<li><a href='/cookbook'>Configuration cookbook</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href='/components/'>Components</a></li>
|
||
<li>
|
||
<a href="/developers/">Developers</a>
|
||
<ul>
|
||
<li><a href="/developers/architecture/">Architecture</a></li>
|
||
<li><a href="/developers/frontend/">Frontend development</a></li>
|
||
<li><a href="/developers/creating_components/">
|
||
Creating components
|
||
</a></li>
|
||
<li><a href="/developers/add_new_platform/">
|
||
Adding platform support
|
||
</a></li>
|
||
<li><a href="/developers/api/">API</a></li>
|
||
<li><a href="/developers/credits/">Credits</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="/blog/">Blog</a></li>
|
||
<li><a href="/help/">Need help?</a></li>
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</header>
|
||
|
||
|
||
|
||
<div class="grid-wrapper">
|
||
<div class="grid grid-center">
|
||
|
||
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
|
||
|
||
|
||
<article class="page">
|
||
|
||
|
||
<header>
|
||
<h1 class="title indent">
|
||
Templating
|
||
</h1>
|
||
</header>
|
||
<hr class="divider">
|
||
|
||
|
||
<p class="note">
|
||
This is an advanced feature of Home Assistant. You need a basic understanding of the <a href="/developers/architecture/">Home Assistant architecture</a>, especially states.
|
||
</p>
|
||
|
||
<p>Templating is a powerful feature in Home Assistant that allows the user control over information that is going into and out of the system. It is used for:</p>
|
||
|
||
<ul>
|
||
<li>Formatting outgoing messages in, for example, the <a href="/components/notify/">notify</a> and <a href="/components/alexa/">alexa</a> components.</li>
|
||
<li>Process incoming data from sources that provide raw data, like <a href="/components/mqtt/">MQTT</a>, <a href="/components/sensor.rest/">Rest sensor</a> or the <a href="/components/sensor.command_line/">command line sensor</a>.</li>
|
||
</ul>
|
||
|
||
<h2><a class="title-link" name="building-templates" href="#building-templates"></a> Building templates</h2>
|
||
|
||
<p>Templating in Home Assistant is powered by the Jinja2 templating engine. This means that we are using their syntax and make some custom Home Assistant variables available to templates during rendering. We will not go over the basics of the syntax, as Jinja2 does a lot better job at this in their <a href="http://jinja.pocoo.org/docs/dev/templates/">Jinja2 documentation</a>.</p>
|
||
|
||
<p class="note">
|
||
The frontend has a template editor developer tool to help develop and debug templates.
|
||
</p>
|
||
|
||
<p>Templates can get pretty big pretty fast. To keep a clear overview, consider using YAML multiline strings to define your templates:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">script</span>:
|
||
<span class="key">msg_who_is_home</span>:
|
||
<span class="key">sequence</span>:
|
||
- <span class="string"><span class="content">service: notify.notify</span></span>
|
||
<span class="key">data</span>:
|
||
<span class="key">message</span>: <span class="string"><span class="delimiter">></span><span class="content">
|
||
{% if is_state('device_tracker.paulus', 'home') %}
|
||
Ha, Paulus is home!
|
||
{% else %}
|
||
Paulus is at {{ states('device_tracker.paulus')) }}.
|
||
{% endif %}</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="home-assistant-template-extensions" href="#home-assistant-template-extensions"></a> Home Assistant template extensions</h3>
|
||
|
||
<p>Home Assistant adds extensions to allow templates to access all of the current states:</p>
|
||
|
||
<ul>
|
||
<li>Iterating <code>states</code> will yield each state sorted alphabetically by entity id</li>
|
||
<li>Iterating <code>states.domain</code> will yield each state of that domain sorted alphabetically by entity id</li>
|
||
<li><code>states.sensor.temperature</code> returns state object for <code>sensor.temperature</code></li>
|
||
<li><code>states('device_tracker.paulus')</code> will return the state string (not the object) of given entity or <code>unknown</code> if it doesn’t exist.</li>
|
||
<li><code>is_state('device_tracker.paulus', 'home')</code> will test if given entity is specified state.</li>
|
||
<li><code>is_state_attr('device_tracker.paulus', 'battery', 40)</code> will test if given entity is specified state.</li>
|
||
<li>Filter <code>multiply(x)</code> will convert input to number and multiply it with <code>x</code></li>
|
||
<li>Filter <code>round(x)</code> will convert input to number and round it to <code>x</code> decimals.</li>
|
||
</ul>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>
|
||
# Next two statements result in same value if state exists
|
||
# Second one will result in an error if state does not exist
|
||
{{ states('device_tracker.paulus') }}
|
||
{{ states.device_tracker.paulus.state }}
|
||
|
||
# Print an attribute if state is defined
|
||
{% if states.device_tracker.paulus %}
|
||
{{ states.device_tracker.paulus.attributes.battery }}
|
||
{% else %}
|
||
??
|
||
{% endif %}
|
||
|
||
# Print out a list of all the sensor states
|
||
{% for state in states.sensor %}
|
||
{{ state.entity_id }}={{ state.state }},
|
||
{% endfor %}
|
||
|
||
{% if is_state('device_tracker.paulus', 'home') %}
|
||
Ha, Paulus is home!
|
||
{% else %}
|
||
Paulus is at {{ states('device_tracker.paulus')) }}.
|
||
{% endif %}
|
||
|
||
{{ states.sensor.temperature | multiply(10) | round(2) }}
|
||
|
||
{% if states('sensor.temperature') | float > 20 %}
|
||
It is warm!
|
||
{%endif %}
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="processing-incoming-data" href="#processing-incoming-data"></a> Processing incoming data</h2>
|
||
|
||
<p>The other part of templating is processing incoming data. It will allow you to modify incoming data and extract only the data that you care about. This will work only for platforms and components that mentioned support for this in their documentation.</p>
|
||
|
||
<p>It depends per component or platform but it is common to be able to define a template using the <code>value_template</code> configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions:</p>
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Variable</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>value</code></td>
|
||
<td>The incoming value.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>value_json</code></td>
|
||
<td>The incoming value parsed as JSON.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre># Incoming value:
|
||
{"primes": [2, 3, 5, 7, 11, 13]}
|
||
|
||
# Extract third prime number
|
||
{{ value_json.primes[2] }}
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</article>
|
||
|
||
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<footer>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
<div class="grid__item">
|
||
<div class="copyright">
|
||
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
|
||
<a rel="me" href='https://github.com/balloob/home-assistant'><i class="icon-github"></i></a>
|
||
|
||
<div class="credit">
|
||
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
|
||
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
|
||
<!--[if lt IE 7]>
|
||
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
|
||
<![endif]-->
|
||
|
||
<script>
|
||
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
|
||
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
|
||
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
|
||
s.parentNode.insertBefore(g,s)}(document,'script'));
|
||
</script>
|
||
|
||
</body>
|
||
</html> |