270 lines
No EOL
13 KiB
HTML
270 lines
No EOL
13 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>Frontend development - Home Assistant</title>
|
||
<meta name="author" content="Paulus Schoutsen">
|
||
<meta name="description" content="Tips and hints if you are starting on Home Assistant frontend development">
|
||
|
||
<meta name="viewport" content="width=device-width">
|
||
<link rel="canonical" href="https://home-assistant.io/developers/frontend/">
|
||
|
||
<meta property="fb:app_id" content="338291289691179">
|
||
<meta property="og:title" content="Frontend development">
|
||
<meta property="og:site_name" content="Home Assistant">
|
||
<meta property="og:url" content="https://home-assistant.io/developers/frontend/">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:description" content="Tips and hints if you are starting on Home Assistant frontend development">
|
||
<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="Frontend development">
|
||
<meta name="twitter:description" content="Tips and hints if you are starting on Home Assistant frontend development">
|
||
<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='/demo/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>Getting started <i class="icon icon-caret-down"></i></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>
|
||
</ul>
|
||
</li>
|
||
<li><a href='/components/'>Components</a></li>
|
||
<li><a href='/cookbook'>Examples</a></li>
|
||
<li>
|
||
<a>Developers <i class="icon icon-caret-down"></i></a>
|
||
<ul>
|
||
<li><a href="/developers/">Setup Development</a></li>
|
||
<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">
|
||
|
||
|
||
<div class='edit-github'><a href='https://github.com/balloob/home-assistant.io/tree/master/source/developers/frontend.markdown'>Edit this page on GitHub</a></div>
|
||
|
||
|
||
|
||
<header>
|
||
<h1 class="title indent">
|
||
Frontend Development
|
||
</h1>
|
||
</header>
|
||
<hr class="divider">
|
||
|
||
|
||
<p>Home Assistant uses <a href="https://www.polymer-project.org/">Polymer</a> for the UI and <a href="http://optimizely.github.io/nuclear-js/">NuclearJS</a> for maintaing the app state.</p>
|
||
|
||
<ul>
|
||
<li>Polymer allows building encapsulated custom HTML elements.<br />
|
||
<a href="https://github.com/balloob/home-assistant-polymer">Home-Assistant-Polymer source code on GitHub.</a></li>
|
||
<li>NuclearJS is a reactive flux built with ImmutableJS data structures.<br />
|
||
<a href="https://github.com/balloob/home-assistant-js">Home-Assistant-JS source code on GitHub.</a></li>
|
||
</ul>
|
||
|
||
<p class="note warning">
|
||
Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes.
|
||
</p>
|
||
|
||
<h2><a class="title-link" name="setting-up-the-environment" href="#setting-up-the-environment"></a> Setting up the environment</h2>
|
||
|
||
<p>Home Assistant will by default serve the compiled version of the frontend. To enable development mode for Home Assistant, update your <code>configuration.yaml</code> to have these lines:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">http</span>:
|
||
<span class="key">development</span>: <span class="string"><span class="content">1</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>Next step is to get the frontend code. When you clone the Home Assistant repository, the frontend repository is not cloned by default. You can setup the frontend development environment by running:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ script/setup
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="development" href="#development"></a> Development</h2>
|
||
|
||
<p>While you are developing, you need to have webpack running to have your JavaScript changes be made available.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>$ cd homeassistant/components/frontend/www_static/home-assistant-polymer
|
||
$ npm run js_dev
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>The source code for the frontend can be found in two different directories:</p>
|
||
|
||
<ul>
|
||
<li>UI: <code>homeassistant/components/frontend/www_static/home-assistant-polymer/src/</code></li>
|
||
<li>Core: <code>homeassistant/components/frontend/www_static/home-assistant-polymer/node_modules/home-assistant-js/src/</code></li>
|
||
</ul>
|
||
|
||
<p>After your changes have been accepted into the home-assistant-js repository, you’ll have to update Home Assistant Polymer to use the latest version of it. This can be done by updating <code>package.json</code>. Look for the line that contains home-assistant-js and update the SHA to the SHA of the last commit.</p>
|
||
|
||
<h1><a class="title-link" name="building-the-polymer-frontend" href="#building-the-polymer-frontend"></a> Building the Polymer frontend</h1>
|
||
|
||
<p>Building a new version of the frontend is as simple as running <code>script/build_frontend</code>. This fires off the following commands:</p>
|
||
|
||
<ul>
|
||
<li><strong>home-assistant-polymer</strong>: Install NPM dependencies.</li>
|
||
<li><strong>home-assistant-polymer</strong>: start frontend build.
|
||
<ul>
|
||
<li>Compile all used JavaScript to <code>_app_compiled.js</code>.</li>
|
||
<li>Install Bower dependencies.</li>
|
||
<li>Vulcanize all Webcomponents to <code>frontend.vulcan.html</code>.</li>
|
||
<li>Minify <code>frontend.vulcan.html</code> and save it as <code>frontend.html</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Copy the webcomponents polyfill <code>webcomponents-lite.min.js</code> from <strong>home-assistant-polymer</strong> to <code>components/frontend/www_static/webcomponents-lite.min.js</code>.</li>
|
||
<li>Copy the final frontend build <code>frontend.html</code> from <strong>home-assistant-polymer</strong> to <code>components/frontend/www_static/frontend/</code>.</li>
|
||
<li>Generate MD5 hash of <code>frontend.html</code> to signal caches to redownload the UI.</li>
|
||
</ul>
|
||
|
||
<p class="img">
|
||
<img src="/images/frontend/polymer-build-architecture.png" alt="Polymer build architecture diagram" />
|
||
Polymer build architecture diagram
|
||
</p>
|
||
|
||
<h1><a class="title-link" name="adding-state-cards" href="#adding-state-cards"></a> Adding state cards</h1>
|
||
|
||
<p>The main interface of Home Assistant is a list of the current entities and their states. For each entity in the system, a state card will be rendered. State cards will show a state badge, the name of the entity, when the state has last changed and the current state or a control to interact with it.</p>
|
||
|
||
<p><img src="/images/frontend/frontend-cards.png" alt="Cards in the frontend" /></p>
|
||
|
||
<p>The different card types can be found <a href="https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary">here</a>.</p>
|
||
|
||
<p>Adding a custom card type can be done with a few simple steps. For this example we will add a new state card for the domain <code>camera</code>: <em>(All files in this example link to their source-code)</em></p>
|
||
|
||
<ol>
|
||
<li>Add <code>'camera'</code> to the array <code>DOMAINS_WITH_CARD</code> in the file <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-card-type.js#L3-L4"><code>/util/state-card-type.js</code></a>.</li>
|
||
<li>Create the files <code>state-card-camera.html</code> and <code>state-card-camera.js</code> in the folder <a href="https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary"><code>/state-summary/</code></a>.</li>
|
||
<li>Add <code>require('./state-card-camera')</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/state-summary/state-card-content.js"><code>state-card-content.js</code></a>.</li>
|
||
<li>Add <code><link rel="import" href="state-card-camera.html"></code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html"><code>state-card-content.html</code></a>.</li>
|
||
</ol>
|
||
|
||
<h1><a class="title-link" name="more-info-screens-for-custom-types" href="#more-info-screens-for-custom-types"></a> More info screens for custom types</h1>
|
||
|
||
<p>Whenever the user taps or clicks on one of the cards, a more info dialog will show. The header of this dialog will be the state card, followed by the history of this entity for the last 24 hours. Below this the more info component is rendered for that entity. The more info component can show more information or allow more ways of control.</p>
|
||
|
||
<p class="img" style="max-width: 400px; margin-left: auto; margin-right: auto;">
|
||
<img src="/images/frontend/frontend-more-info-light.png" />
|
||
The more info dialog for a light allows the user to control the color and the brightness.
|
||
</p>
|
||
|
||
<p>The instructions to add a more info dialog are very similar to adding a new card type. This example will add a new more info component for the domain <code>camera</code>:<br />
|
||
<em>(All files in this example link to their source-code)</em></p>
|
||
|
||
<ol>
|
||
<li>Add <code>'camera'</code> to the array <code>DOMAINS_WITH_MORE_INFO</code> in the file <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-more-info-type.js#L1"><code>util/state-more-info-type.js</code></a>.</li>
|
||
<li>Create the files <code>more-info-camera.html</code> and <code>more-info-camera.js</code> in the folder <a href="https://github.com/balloob/home-assistant-polymer/tree/master/src/more-infos"><code>/more-infos</code></a>.</li>
|
||
<li>Add <code>require('./more-info-camera')</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/more-infos/more-info-content.js"><code>more-info-content.js</code></a></li>
|
||
<li>Add <code><link rel="import" href="more-info-camera.html"></code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html"><code>more-info-content.html</code></a></li>
|
||
</ol>
|
||
|
||
|
||
</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> |