diff --git a/atom.xml b/atom.xml index a01e6b2843..44e5f6ee94 100644 --- a/atom.xml +++ b/atom.xml @@ -4,7 +4,7 @@ <![CDATA[Home Assistant]]> - 2015-07-14T18:52:12-07:00 + 2015-07-14T20:33:59-07:00 https://home-assistant.io/ diff --git a/blog/categories/architecture/atom.xml b/blog/categories/architecture/atom.xml index 7044f0d91f..217dfd8359 100644 --- a/blog/categories/architecture/atom.xml +++ b/blog/categories/architecture/atom.xml @@ -4,7 +4,7 @@ <![CDATA[Category: architecture | Home Assistant]]> - 2015-07-14T18:52:12-07:00 + 2015-07-14T20:33:59-07:00 https://home-assistant.io/ diff --git a/blog/categories/branding/atom.xml b/blog/categories/branding/atom.xml index 4d209b2015..78ef97c218 100644 --- a/blog/categories/branding/atom.xml +++ b/blog/categories/branding/atom.xml @@ -4,7 +4,7 @@ <![CDATA[Category: branding | Home Assistant]]> - 2015-07-14T18:52:12-07:00 + 2015-07-14T20:33:59-07:00 https://home-assistant.io/ diff --git a/blog/categories/component/atom.xml b/blog/categories/component/atom.xml index c469a6ebcd..843d14f9c1 100644 --- a/blog/categories/component/atom.xml +++ b/blog/categories/component/atom.xml @@ -4,7 +4,7 @@ <![CDATA[Category: component | Home Assistant]]> - 2015-07-14T18:52:12-07:00 + 2015-07-14T20:33:59-07:00 https://home-assistant.io/ diff --git a/blog/categories/core/atom.xml b/blog/categories/core/atom.xml index 3e0865ac8b..ea70a10fae 100644 --- a/blog/categories/core/atom.xml +++ b/blog/categories/core/atom.xml @@ -4,7 +4,7 @@ <![CDATA[Category: core | Home Assistant]]> - 2015-07-14T18:52:12-07:00 + 2015-07-14T20:33:59-07:00 https://home-assistant.io/ diff --git a/blog/categories/frontend/atom.xml b/blog/categories/frontend/atom.xml index 56e06117bb..ef398ac3da 100644 --- a/blog/categories/frontend/atom.xml +++ b/blog/categories/frontend/atom.xml @@ -4,7 +4,7 @@ <![CDATA[Category: frontend | Home Assistant]]> - 2015-07-14T18:52:12-07:00 + 2015-07-14T20:33:59-07:00 https://home-assistant.io/ diff --git a/blog/categories/release-notes/atom.xml b/blog/categories/release-notes/atom.xml index f36f07ad94..a31c87ec3f 100644 --- a/blog/categories/release-notes/atom.xml +++ b/blog/categories/release-notes/atom.xml @@ -4,7 +4,7 @@ <![CDATA[Category: release-notes | Home Assistant]]> - 2015-07-14T18:52:12-07:00 + 2015-07-14T20:33:59-07:00 https://home-assistant.io/ diff --git a/blog/categories/website/atom.xml b/blog/categories/website/atom.xml index 9e390637f6..c7a357a7f8 100644 --- a/blog/categories/website/atom.xml +++ b/blog/categories/website/atom.xml @@ -4,7 +4,7 @@ <![CDATA[Category: website | Home Assistant]]> - 2015-07-14T18:52:12-07:00 + 2015-07-14T20:33:59-07:00 https://home-assistant.io/ diff --git a/developers/frontend.html b/developers/frontend.html index 8459202742..a37fe13daf 100644 --- a/developers/frontend.html +++ b/developers/frontend.html @@ -105,11 +105,24 @@
-

Home Assistant uses Polymer for the frontend. Polymer allows building encapsulated and interoperable custom elements that extend HTML itself.

+

Home Assistant uses Polymer for the UI and NuclearJS for all data management.

+ + + + +

+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. +

+

Turning on development mode

-

Home Assistant will by default serve the compiled version of the frontend. To change it so that the components are served separately, update your configuration.yaml to have these lines:

+

Home Assistant will by default serve the compiled version of the frontend. To change it so that each component and JavaScript are served separately, update your configuration.yaml to have these lines:

1
 2
@@ -117,61 +130,90 @@
   development: 1
-

After turning on development mode, you will have to install the web components that the frontend depends on. You can do this by running the build_frontend script.

+

After turning on development mode, you will have to install the web components that the frontend depends on. Firing off a build of the frontend by running scripts/build_frontend will ensure all dependencies are installed.

-

-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. -

+

Once this is done, you can start editting the webcomponents in the folder homeassistant/components/frontend/www_static/home-assistant-polymer/src. To see the changes you’ve made, simply refresh your browser.

+

Enabling JavaScript backend development

-

Building the frontend

- -

To build the frontend you need to install node and the npm packages bower and vulcanize.

+

Polymer is only providing a UI toolkit for Home Assistant. All data management and interaction with the server is done by home-assistant-js leveraging NuclearJS. To enable JavaScript development:

1
-
npm install -g bower vulcanize
+2
+3
+
cd homeassistant/components/frontend/www_static/home-assistant-polymer/
+npm run setup_js_dev
+npm run js_dev
-

After that you can run ./build_frontend from the project directory. This will take all the used web components and ‘vulcanize’ it into a single file to be served by Home Assistant. The script also updates homeassistant/components/http/frontend.py with an MD5 hash of the frontend.

+

npm run js_dev will start the process that will ensure that your latest changes to the JavaScript files will be loaded when you refresh the page. This command has to be always running while working on home-assistant-js.

-

Adding state cards

+

Building the Polymer frontend

-

The main interface of Home Assistant is a list of current states in the State Machine. It will filter out the group states and offers options to filter by groups on the top.

- -

Currently there are two supported card types:

+

Building a new version of the frontend is as simple as running scripts/build_frontend. This fires off the following commands:

    -
  • Display: shows the state on the card
    • -
  • Toggle: allows the user to toggle a device on/off from the card
    • +
  • home-assistant-polymer: Install NPM dependencies.
    • +
  • home-assistant-polymer: start frontend build. + +
      +
    • Compile all used JavaScript to _app_compiled.js.
      • +
    • Install Bower dependencies.
      • +
    • Vulcanize all Webcomponents to frontend.vulcan.html.
      • +
    • Minify frontend.vulcan.html and save it as frontend.html.
      • +
    +
    • +
  • Copy the webcomponents polyfill webcomponents-lite.min.js from home-assistant-polymer to components/frontend/www_static/webcomponents-lite.min.js.
    • +
  • Copy the final frontend build frontend.html from home-assistant-polymer to components/frontend/www_static/frontend.html.
    • +
  • Generate MD5 hash of frontend.html to signal caches to redownload the UI.
-

To add your own card type, follow the following steps:

+

+Polymer build architecture diagram +

+ + +

Adding state cards

+ +

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.

+ +

+ +

Some domains will be filtered out of the main view and are available through separate menu options. Examples are group, script, scene.

+ +

The different card types can be found here.

+ +

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 camera:
+(All files in this example link to their source-code)

    -
  1. Adjust the cardType property of the State class in home-assistant-api.html to return your new card type when appropriate.
    2. -
  2. Create a new component following the naming convention state-card-CARDTYPE.html in /cards/.
    3. -
  3. Import your new component in /cards/state-card-content.html.
    4. +
  4. Add 'camera' to the array DOMAINS_WITH_CARD in the file /util/state-card-type.js.
    5. +
  5. Create the files state-card-camera.html and state-card-camera.js in the folder /cards/.
    6. +
  6. Add require('./state-card-camera') to state-card-content.js.
    7. +
  7. Add <link rel="import" href="state-card-camera.html"> to state-card-content.html.

More info screens for custom types

-

When you click on a card, the more info dialog will open for that card. This will allow you to see more information and more options to control that entity.

+

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.

-

- - The more info dialog for a light allows us to control the color and the brightness. +

+ + The more info dialog for a light allows the user to control the color and the brightness.

-

To add your own more info dialog, follow the following steps:

+

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 camera:
+(All files in this example link to their source-code)

    -
  1. Adjust the moreInfoType property of the State class in home-assistant-api.html to return your new more info type when appropriate.
    2. -
  2. Create a new component following the naming convention more-info-CARDTYPE.html in /more-infos/.
    3. -
  3. Import your new component in /more-infos/more-info-content.html.
    4. +
  4. Add 'camera' to the array DOMAINS_WITH_MORE_INFO in the file util/state-more-info-type.js.
    5. +
  5. Create the files more-info-camera.html and more-info-camera.js in the folder /more-infos.
    6. +
  6. Add require('./more-info-camera') to more-info-content.js
    7. +
  7. Add <link rel="import" href="more-info-camera.html"> to more-info-content.html
diff --git a/images/frontend/frontend-cards.png b/images/frontend/frontend-cards.png new file mode 100644 index 0000000000..cca6cdd707 Binary files /dev/null and b/images/frontend/frontend-cards.png differ diff --git a/images/frontend/frontend-more-info-light.png b/images/frontend/frontend-more-info-light.png new file mode 100644 index 0000000000..9036a92f7c Binary files /dev/null and b/images/frontend/frontend-more-info-light.png differ diff --git a/images/frontend/polymer-build-architecture.png b/images/frontend/polymer-build-architecture.png new file mode 100644 index 0000000000..000e8b5d46 Binary files /dev/null and b/images/frontend/polymer-build-architecture.png differ