328 lines
19 KiB
HTML
328 lines
19 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, print" 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 class='site-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="/docs/">Docs</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>
|
||
<li><a href='#' class='show-search'><i class="icon-search"></i></a></li>
|
||
</ul>
|
||
</nav>
|
||
<div class='search-container' style='display: none'>
|
||
<div class='search'>
|
||
<i class="icon-search"></i>
|
||
<input id='search' placeholder='Search the docs…'>
|
||
<a href='#' class='close'><i class="icon-remove-sign"></i></a>
|
||
</div>
|
||
</div>
|
||
</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 is built on top of the <a href="https://www.polymer-project.org/">Polymer</a> webcomponents framework. 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></p>
|
||
<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 class="note">
|
||
All commands below need to be run from inside the home-assistant-polymer repository.
|
||
</p>
|
||
<p>Home Assistant will by default serve the compiled version of the frontend from the hass_frontend Python package. For development you want to work with the unbundled source files which are in the home-assistant-polymer repository.</p>
|
||
<p>First step is to configure Home Assistant to use the development mode for the frontend. Do this by updating the frontend config in your <code class="highlighter-rouge">configuration.yaml</code> and set the path to the polymer repo:</p>
|
||
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">frontend</span><span class="pi">:</span>
|
||
<span class="s">development_repo</span><span class="pi">:</span> <span class="s"><absolute path to home-assistant-polymer></span>
|
||
</code></pre>
|
||
</div>
|
||
<p>Next step is to git clone the <a href="https://github.com/home-assistant/home-assistant-polymer">home-assistant-polymer repository</a>. You can place the repository anywhere on your system but to keep these instructions simple we’re cloning the home-assistant-polymer repository as a sibling to the Home Assistant repo.</p>
|
||
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git clone https://github.com/home-assistant/home-assistant-polymer.git
|
||
<span class="gp">$ </span><span class="nb">cd </span>home-assistant-polymer
|
||
</code></pre>
|
||
</div>
|
||
<p>After cloning, your folder structure should look like this:</p>
|
||
<div class="language-text highlighter-rouge"><pre class="highlight"><code>/home-assistant
|
||
/home-assistant-polymer
|
||
</code></pre>
|
||
</div>
|
||
<p>Node.js is required to build the frontend. The preferred method of installing node.js is with <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 the correct node.js by running the following command:</p>
|
||
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>nvm install
|
||
</code></pre>
|
||
</div>
|
||
<p><a href="https://yarnpkg.com/en/">Yarn</a> is used as the package manager for node modules. <a href="https://yarnpkg.com/en/docs/install">Install yarn using the instructions here.</a></p>
|
||
<p>Next, development dependencies need to be installed to bootstrap the frontend development environment. First activate the right Node version and then download all the needed modules and do a first build:</p>
|
||
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>nvm use
|
||
<span class="gp">$ </span>script/bootstrap
|
||
</code></pre>
|
||
</div>
|
||
<p>This script will use yarn and bower to install all the necessary dependencies necessary for development and do an initial build.</p>
|
||
<h3><a class="title-link" name="creating-pull-requests" href="#creating-pull-requests"></a> Creating pull requests</h3>
|
||
<p>If you’re planning on issuing a PR back to the Home Assistant codebase you need to fork the polymer project and add your fork as a remote to the Home Assistant Polymer repo.</p>
|
||
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git remote add <remote name> <github URL to your fork>
|
||
</code></pre>
|
||
</div>
|
||
<p>When you’ve made your changes and are ready to push them change to the working directory for the polymer project and then push your changes</p>
|
||
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git add -A
|
||
<span class="gp">$ </span>git commit -m <span class="s2">"Added new feature X"</span>
|
||
<span class="gp">$ </span>git push -u <remote name> HEAD
|
||
</code></pre>
|
||
</div>
|
||
<h2><a class="title-link" name="development" href="#development"></a> Development</h2>
|
||
<p>If you are changing <code class="highlighter-rouge">html</code> files under <code class="highlighter-rouge">/src</code> or <code class="highlighter-rouge">/panels</code> - just reload the page in your browser to see changes.
|
||
If you are changing javascript files under <code class="highlighter-rouge">/js</code> you need to have gulp running to watch the source files for changes and build when necessary.</p>
|
||
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>yarn run dev-watch
|
||
</code></pre>
|
||
</div>
|
||
<p>The source code for the frontend can be found in different directories:</p>
|
||
<ul>
|
||
<li>UI: <code class="highlighter-rouge">/home-assistant-polymer/src/</code></li>
|
||
<li>Panels: <code class="highlighter-rouge">/home-assistant-polymer/panels/</code></li>
|
||
<li>Javascript code: <code class="highlighter-rouge">/home-assistant-polymer/js/</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>.
|
||
To use a built version package it: <code class="highlighter-rouge">python setup.py sdist</code>
|
||
Install it: <code class="highlighter-rouge">pip3 install dist/home-assistant-frontend-xxxxxxxx.0.tar.gz --upgrade</code>
|
||
Run Home Assistant without trying to reinstall production package: <code class="highlighter-rouge">hass --skip-pip</code></p>
|
||
</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_guidelines/'>Style guidelines </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/development_101/'>Development 101 </a>
|
||
<ul>
|
||
<li><a href='/developers/development_hass_object/'>Hass object </a></li>
|
||
<li><a href='/developers/development_events/'>Events </a></li>
|
||
<li><a href='/developers/development_states/'>States </a></li>
|
||
<li><a href='/developers/development_services/'>Services </a></li>
|
||
<li><a href='/developers/development_config/'>Config </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/developers/add_new_platform/'>Creating a new platform (to support a new device) </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_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/intent/'>Intents (handling voice responses) </a>
|
||
<ul>
|
||
<li><a href='/developers/intent/firing/'>Firing intents </a></li>
|
||
<li><a href='/developers/intent/handling/'>Handling intents </a></li>
|
||
<li><a href='/developers/intent/conversation/'>Registering sentences </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/developers/asyncio/'>Asynchronous Programming </a>
|
||
<ul>
|
||
<li><a href='/developers/asyncio_101/'>Introduction to asyncio </a></li>
|
||
<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>
|
||
<li><a href='/developers/frontend_creating_custom_ui/'>Add Custom UI </a></li>
|
||
<li><a href='/developers/frontend_translation/'>Translation </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/developers/hassio/architecture/'>Hass.io architecture </a>
|
||
<ul>
|
||
<li><a href='/developers/hassio/debugging/'>Debugging Hass.io </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/developers/hassio/addon_development/'>Hass.io Add-on Development </a>
|
||
<ul>
|
||
<li><a href='/developers/hassio/addon_tutorial/'>Tutorial: Making your first add-on </a></li>
|
||
<li><a href='/developers/hassio/addon_config/'>Configuration </a></li>
|
||
<li><a href='/developers/hassio/addon_communication/'>Communication </a></li>
|
||
<li><a href='/developers/hassio/addon_testing/'>Local Testing </a></li>
|
||
<li><a href='/developers/hassio/addon_publishing/'>Publishing </a></li>
|
||
<li><a href='/developers/hassio/addon_repository/'>Repositories </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/developers/api/'>API </a>
|
||
<ul>
|
||
<li><a href='https://dev-docs.home-assistant.io/en/dev/'>Python API </a></li>
|
||
<li><a href='/developers/websocket_api/'>Websocket API </a></li>
|
||
<li><a href='/developers/rest_api/'>REST API </a></li>
|
||
<li><a href='/developers/python_api/'>Python REST API </a></li>
|
||
<li><a href='/developers/server_sent_events/'>Server-sent events </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/developers/documentation/'>Website/Documentation </a>
|
||
<ul>
|
||
<li><a href='/developers/documentation/standards/'>Standards </a></li>
|
||
<li><a href='/developers/documentation/create_page/'>Create a new page </a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href='/developers/helpers/'>Online helpers </a></li>
|
||
<li><a href='/developers/releasing/'>Releasing </a></li>
|
||
<li><a href='/developers/maintenance/'>Maintenance </a></li>
|
||
<li>
|
||
Governance
|
||
<ul>
|
||
<li><a href='/developers/cla/'>Contributor License Agreement </a></li>
|
||
<li><a href='/privacy/'>Privacy Policy </a></li>
|
||
<li><a href='/tos/'>Terms of Service </a></li>
|
||
<li><a href='/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> (no support!).<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>
|
||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css" />
|
||
<script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js"></script>
|
||
<script type="text/javascript">
|
||
docsearch({
|
||
apiKey: 'ae96d94b201c5444c8a443093edf3efb',
|
||
indexName: 'home-assistant',
|
||
inputSelector: '#search',
|
||
debug: false // Set debug to true if you want to inspect the dropdown
|
||
});
|
||
document.querySelector('.search .close').addEventListener('click', function(ev) {
|
||
ev.preventDefault();
|
||
document.querySelector('.search-container').style.display = 'none';
|
||
});
|
||
document.querySelector('.show-search').addEventListener('click', function(ev) {
|
||
ev.preventDefault();
|
||
document.querySelector('.search-container').style.display = 'block';
|
||
document.getElementById('toggle').checked = false;
|
||
document.querySelector('.search-container input').focus();
|
||
});
|
||
</script>
|
||
</body>
|
||
</html>
|