296 lines
No EOL
14 KiB
HTML
296 lines
No EOL
14 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="Home Assistant">
|
|
<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/default-social.png">
|
|
|
|
<meta name="twitter:card" content="summary_large_image">
|
|
<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/default-social.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 href="/getting-started/">Getting started</a></li>
|
|
<li><a href="/components/">Components</a></li>
|
|
<li><a href="/ecosystem/">Ecosystem</a></li>
|
|
<li><a href="/cookbook/">Examples</a></li>
|
|
<li><a href="/developers/">Developers</a></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">
|
|
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 maintaining the app state.</p>
|
|
|
|
<ul>
|
|
<li>Polymer allows building encapsulated custom HTML elements.
|
|
<a href="https://github.com/home-assistant/home-assistant-polymer">Home-Assistant-Polymer source code on GitHub.</a></li>
|
|
<li>NuclearJS is a reactive flux built with ImmutableJS data structures.
|
|
<a href="https://github.com/home-assistant/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. As everything is compiled into the file <code class="highlighter-rouge">frontend.html</code> you do not want to work with the compiled version but with the separate files during development. To enable development mode for Home Assistant, update your <code class="highlighter-rouge">configuration.yaml</code> to have these lines:</p>
|
|
|
|
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">http</span><span class="pi">:</span>
|
|
<span class="s">development</span><span class="pi">:</span> <span class="s">1</span>
|
|
</code></pre>
|
|
</div>
|
|
|
|
<p>Node.js is required to setup the frontend development environment. The preferred method of installing node.js is <a href="https://github.com/creationix/nvm">nvm</a>. Install nvm using the instructions in the <a href="https://github.com/creationix/nvm#install-script">README</a>, and install node.js by running the following command:</p>
|
|
|
|
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>nvm install node
|
|
</code></pre>
|
|
</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="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>script/setup
|
|
</code></pre>
|
|
</div>
|
|
|
|
<h2><a class="title-link" name="development" href="#development"></a> Development</h2>
|
|
|
|
<p>While you are developing, you need to have Rollup running to have your JavaScript changes be made available.</p>
|
|
|
|
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span><span class="nb">cd </span>homeassistant/components/frontend/www_static/home-assistant-polymer
|
|
<span class="gp">$ </span>npm run js_dev
|
|
</code></pre>
|
|
</div>
|
|
|
|
<p>The source code for the frontend can be found in three different directories:</p>
|
|
|
|
<ul>
|
|
<li>UI: <code class="highlighter-rouge">homeassistant/components/frontend/www_static/home-assistant-polymer/src/</code></li>
|
|
<li>Core: <code class="highlighter-rouge">homeassistant/components/frontend/www_static/home-assistant-polymer/home-assistant-js/src/</code></li>
|
|
<li>Panels: <code class="highlighter-rouge">homeassistant/components/frontend/www_static/home-assistant-polymer/panels/</code></li>
|
|
</ul>
|
|
|
|
<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 class="highlighter-rouge">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.</li>
|
|
<li>Install Bower dependencies.</li>
|
|
<li>Vulcanize and minify the core and panel sources to build dir.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Copy the webcomponents polyfill <code class="highlighter-rouge">webcomponents-lite.min.js</code> from <strong>home-assistant-polymer</strong> to <code class="highlighter-rouge">components/frontend/www_static/webcomponents-lite.min.js</code>.</li>
|
|
<li>Copy the final frontend build <code class="highlighter-rouge">frontend.html</code> and panel sources from <strong>home-assistant-polymer</strong> to <code class="highlighter-rouge">components/frontend/www_static/frontend/</code>.</li>
|
|
<li>Generate MD5 hashes of core and panel sources.</li>
|
|
<li>Create gzip versions of all the sources.</li>
|
|
</ul>
|
|
|
|
|
|
</article>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
|
|
<div class="grid">
|
|
|
|
|
|
<section class="aside-module grid__item one-whole lap-one-half">
|
|
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/frontend.markdown'>Edit this page on GitHub</a></div>
|
|
<div class='section'>
|
|
<h1 class="title delta">Development Guide</h1>
|
|
<ul class='divided sidebar-menu'>
|
|
<li>
|
|
<a href='/developers/'>Introduction </a>
|
|
<ul>
|
|
<li><a href='/developers/architecture/'>Architecture </a></li>
|
|
<li><a href='/developers/architecture_components/'>Components </a></li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<a href='/developers/development/'>Starting with Development </a>
|
|
<ul>
|
|
<li><a href='/developers/development_environment/'>Setting up Environment </a></li>
|
|
<li><a href='/developers/development_submitting/'>Submit your Work </a></li>
|
|
<li><a href='/developers/development_checklist/'>Checklist </a></li>
|
|
<li><a href='/developers/development_testing/'>Testing </a></li>
|
|
<li><a href='/developers/development_catching_up/'>Catching up with Reality </a></li>
|
|
<li><a href='/developers/development_validation/'>Validation </a></li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<a href='/developers/add_new_platform/'>Support a new device (as a platform) </a>
|
|
<ul>
|
|
<li><a href='/developers/code_review_platform/'>Checklist creating a platform </a></li>
|
|
<li><a href='/developers/platform_example_sensor/'>Example sensor platform </a></li>
|
|
<li><a href='/developers/platform_example_light/'>Example light platform </a></li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<a href='/developers/creating_components/'>Adding a new component </a>
|
|
<ul>
|
|
<li><a href='/developers/code_review_component/'>Checklist creating a component </a></li>
|
|
<li><a href='/developers/component_loading/'>Loading components </a></li>
|
|
<li><a href='/developers/component_deps_and_reqs/'>Requirements & Dependencies </a></li>
|
|
<li><a href='/developers/component_initialization/'>Initialization </a></li>
|
|
<li><a href='/developers/component_events/'>Handling events </a></li>
|
|
<li><a href='/developers/component_states/'>States </a></li>
|
|
<li><a href='/developers/component_visibility/'>Visibility </a></li>
|
|
<li><a href='/developers/component_generic_discovery/'>Loading Platforms </a></li>
|
|
<li><a href='/developers/component_discovery/'>Component Discovery </a></li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<a href='/developers/asyncio/'>Asynchronous Programming </a>
|
|
<ul>
|
|
<li><a href='/developers/asyncio_categorizing_functions/'>Categorizing Functions </a></li>
|
|
<li><a href='/developers/asyncio_working_with_async/'>Working with Async </a></li>
|
|
<li><a href='/developers/asyncio_misc/'>Miscellaneous </a></li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<a class='active' href='/developers/frontend/'>Frontend Development </a>
|
|
<ul>
|
|
<li><a href='/developers/frontend_add_card/'>Add State Card </a></li>
|
|
<li><a href='/developers/frontend_add_more_info/'>Add More Info Dialog </a></li>
|
|
<li><a href='/developers/frontend_creating_custom_panels/'>Add Custom Panels </a></li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
API
|
|
<ul>
|
|
<li><a href='https://dev-docs.home-assistant.io/en/dev/'>Home Assistant API </a></li>
|
|
<li><a href='/developers/websocket_api/'>Websocket API </a></li>
|
|
<li><a href='/developers/rest_api/'>RESTful API </a></li>
|
|
<li><a href='/developers/python_api/'>Python API </a></li>
|
|
<li><a href='/developers/server_sent_events/'>Server-sent events </a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href='/developers/helpers/'>Online helpers </a></li>
|
|
<li><a href='/developers/multiple_instances/'>Multiple Instances </a></li>
|
|
<li><a href='/developers/website/'>Home-Assistant.io </a></li>
|
|
<li><a href='/developers/releasing/'>Releasing </a></li>
|
|
<li>
|
|
Governance
|
|
<ul>
|
|
<li><a href='/developers/cla/'>Contributor License Agreement </a></li>
|
|
<li><a href='/developers/code_of_conduct/'>Code of Conduct </a></li>
|
|
<li><a href='/developers/credits/'>Credits </a></li>
|
|
<li><a href='/developers/license/'>License </a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
</div>
|
|
</aside>
|
|
|
|
</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://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
|
|
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
|
|
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
|
|
|
|
<div class="credit">
|
|
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
|
|
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>
|
|
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">home-assistant.io</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</footer>
|
|
|
|
<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> |