Update frontend docs

This commit is contained in:
Paulus Schoutsen 2018-05-28 21:34:02 -04:00
parent 8b6633373e
commit 001705fba3
8 changed files with 172 additions and 91 deletions

View File

@ -0,0 +1,62 @@
---
title: "Home Assistant Frontend Architecture"
sidebar_label: "Architecture"
---
The Home Assistant frontend is built using web components. This is a modern web technology allowing us to encapsulate templates, styling and logic into a single file and expose it as an HTML tag in the browser. These componens are composable, allowing a very dynamic and powerful foundation of our application.
## Structure
The Home Assistant frontend can be broken up in 4 parts:
### Bootstrap
File: `src/entrypoints/core.js`
This is a very tiny script which is the first thing that is loaded on the page. It is responsible for checking for authentication credentials and setting up the websocket connection with the backend.
The script allows us to start downloading the data while also downloading the rest of the UI in parallel.
### App shell
File: `src/entrypoints/app.js`
This is everything that is required to render the sidebar and handle the routing.
### Panels
Folder: `src/panels/`
Each page in Home Assistant is a panel. Components can register extra panels to be shown to the user. Examples of panels are "states", "map", "logbook" and "history".
### More info dialog
Folder: `src/dialogs/more-info`
This is a dialog that allows users to see more information about an entity and control it's state.
The more info dialog can be triggered from any component in the app by firing a DOM event `hass-more-info` with as detail `{ entityId: 'light.kitchen' }`.
## Data Flow
The frontend leverages the [Websocket API](external_api_websocket.md) and the [Rest API](external_api_rest.md) to interact with Home Assistant.
The data is made available as the `hass` property which is passed down to every component. The `hass` property contains the whole application state and has methods to call APIs.
We use a unidirectional data flow (like Flux, Redux). When you make a change in the backend (like turning on a light), the `hass` object will be updated at the root of the application and will be made available to every component that needs it.
## Routing
The frontend uses decentralized routing. Each component only knows enough about the routing to know how to handle the part it's repsonsible for. Further routing is passed down the component tree.
For example, the `<home-assistant>` main component will look at the first part of the url to decide which panel should be loaded. Each panel can have its own mapping between the url and what content to show.
For the routing, we use the [`<app-route>`](https://www.polymer-project.org/3.0/toolbox/routing) web component.
## Bundling
We use Webpack to bundle up the application. We have various gulp scripts to help with generating the icon set and the index.html.
We're aggresively code splitting our application by leveraging the dynamic import syntax (`import('path/to/some/file.js')`). When encountering an `import()`, Webpack will split the code into different chunks and makes sure that they are loaded when needed.

View File

@ -0,0 +1,86 @@
---
title: "Frontend development"
sidebar_label: "Development"
---
The Home Assistant frontend is built using web components and powered by the [Polymer](https://www.polymer-project.org/) framework.
> 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.
## Setting up the environment
> All commands below need to be run from inside the home-assistant-polymer repository.
### Getting the code
First step is to git clone the [home-assistant-polymer repository][hass-polymer]. You can place the repository anywhere on your system.
```bash
$ git clone https://github.com/home-assistant/home-assistant-polymer.git
$ cd home-assistant-polymer
```
### Configuring Home Assistant
Next step is to configure Home Assistant to use the development mode for the frontend. Do this by updating the frontend config in your `configuration.yaml` and set the path to the home-assistant-polymer repository that you cloned in the last step:
```yaml
frontend:
# Example absolute path: /home/paulus/dev/hass/home-assistant-polymer
development_repo: <absolute path to home-assistant-polymer repo>
```
### Installing Node.js
Node.js is required to build the frontend. The preferred method of installing node.js is with [nvm](https://github.com/creationix/nvm). Install nvm using the instructions in the [README](https://github.com/creationix/nvm#install-script), and install the correct node.js by running the following command:
```bash
$ nvm install
```
[Yarn](https://yarnpkg.com/en/) is used as the package manager for node modules. [Install yarn using the instructions here.](https://yarnpkg.com/en/docs/install)
Next, development dependencies need to be installed to bootstrap the frontend development environment. First activate the right Node version and then download all the dependencies:
```bash
$ nvm use
$ script/bootstrap
```
## Development
During development, you will need to run the development script to maintain a development build of the frontend that auto updates when you change any of the source files. To run this server, run:
```bash
$ nvm use
$ script/develop
```
## Creating pull requests
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.
```bash
$ git remote add fork <github URL to your fork>
```
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
``` bash
$ git add -A
$ git commit -m "Added new feature X"
$ git push -u fork HEAD
```
## Building the Polymer frontend
If you're making changes to the way the frontend is packaged, it might be necessary to try out a new packaged build of the frontend in the main repository (instead of pointing it at the frontend repo). To do so, first build a production version of the frontend by running `script/build_frontend`.
To test it out inside Home assistant, run the following command from the main Home Assistant repository:
```bash
$ pip3 install --upgrade /path/to/home-assistant-polymer/dist/home-assistant-frontend-xxxxxxxx.x.tar.gz
$ hass --skip-pip
```
[hass-polymer]: https://github.com/home-assistant/home-assistant-polymer

View File

@ -1,92 +1,10 @@
---
title: "Frontend development"
title: "Home Assistant Frontend"
sidebar_label: "Introduction"
---
Home Assistant is built on top of the [Polymer](https://www.polymer-project.org/) webcomponents framework. Polymer allows building encapsulated custom HTML elements. [Home-Assistant-Polymer source code on GitHub.][hass-polymer]
The Home Assistant frontend allows users to browse and control the state of their house, manage their automations and configure integrations.
> 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.
The frontend is designed as a mobile-first experience. It is a progressive web application and offers an app-like experience to our users.
## Setting up the environment
> All commands below need to be run from inside the home-assistant-polymer repository.
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.
First step is to configure Home Assistant to use the development mode for the frontend. Do this by updating the frontend config in your `configuration.yaml` and set the path to the polymer repo:
```yaml
frontend:
development_repo: <absolute path to home-assistant-polymer>
```
Next step is to git clone the [home-assistant-polymer repository][hass-polymer]. 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.
```bash
$ git clone https://github.com/home-assistant/home-assistant-polymer.git
$ cd home-assistant-polymer
```
After cloning, your folder structure should look like this:
```text
/home-assistant
/home-assistant-polymer
```
Node.js is required to build the frontend. The preferred method of installing node.js is with [nvm](https://github.com/creationix/nvm). Install nvm using the instructions in the [README](https://github.com/creationix/nvm#install-script), and install the correct node.js by running the following command:
```bash
$ nvm install
```
[Yarn](https://yarnpkg.com/en/) is used as the package manager for node modules. [Install yarn using the instructions here.](https://yarnpkg.com/en/docs/install)
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:
```bash
$ nvm use
$ script/bootstrap
```
This script will use yarn and bower to install all the necessary dependencies necessary for development and do an initial build.
### Creating pull requests
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.
```bash
$ git remote add <remote name> <github URL to your fork>
```
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
``` bash
$ git add -A
$ git commit -m "Added new feature X"
$ git push -u <remote name> HEAD
```
## Development
If you are changing `html` files under `/src` or `/panels` - just reload the page in your browser to see changes.
If you are changing javascript files under `/js` you need to have gulp running to watch the source files for changes and build when necessary.
```bash
$ script/develop
```
The source code for the frontend can be found in different directories:
- UI: `/home-assistant-polymer/src/`
- Panels: `/home-assistant-polymer/panels/`
- Javascript code: `/home-assistant-polymer/js/`
# Building the Polymer frontend
Building a new version of the frontend is as simple as running `script/build_frontend`.
To use a built version package it: `python setup.py sdist`
Install it: `pip3 install dist/home-assistant-frontend-xxxxxxxx.0.tar.gz --upgrade`
Run Home Assistant without trying to reinstall production package: `hass --skip-pip`
[hass-polymer]: https://github.com/home-assistant/home-assistant-polymer
![Screenshot of the Home Assistant Frontend](/img/en/frontend/frontend-hero.png)

View File

@ -61,6 +61,7 @@ We need a couple more steps to do frontend development. First, make sure you hav
Update the Hass.io component configuration in your `configuration.yaml` to point at the frontend repository:
```yaml
# configuration.yaml
hassio:
development_repo: /home/paulus/dev/hass/home-assistant-polymer
```

View File

@ -33,6 +33,9 @@ class Footer extends React.Component {
/>
)}
</a>
<div>
<a href="https://twitter.com/hass_devs">Follow Home Assistant devs on Twitter</a>
</div>
{/* <div>
<h5>Docs</h5>
<a href={this.docUrl('doc1.html', this.props.language)}>

View File

@ -66,9 +66,13 @@
"external_api_websocket": "WebSocket API",
"frontend_add_card": "Adding state card",
"frontend_add_more_info": "Adding more info dialogs",
"frontend_architecture": "Home Assistant Frontend Architecture",
"Architecture": "Architecture",
"frontend_creating_custom_panels": "Creating custom panels",
"frontend_creating_custom_ui": "Creating custom UI",
"frontend_index": "Frontend development",
"frontend_development": "Frontend development",
"Development": "Development",
"frontend_index": "Home Assistant Frontend",
"hassio_addon_communication": "Add-On Communication",
"hassio_addon_config": "Add-On Configuration",
"hassio_addon_index": "Developing an add-on",
@ -91,7 +95,6 @@
"maintenance": "Maintenance",
"misc": "Miscellaneous",
"releasing": "Releasing",
"Architecture": "Architecture",
"Frontend": "Frontend",
"Backend": "Backend",
"Misc": "Misc",
@ -102,6 +105,8 @@
"Config Entries": "Config Entries",
"Data Entry Flow": "Data Entry Flow",
"Entity Registry": "Entity Registry",
"Extending the frontend": "Extending the frontend",
"Customizing the frontend": "Customizing the frontend",
"Developing a feature": "Developing a feature",
"Development 101": "Development 101",
"Creating Platforms": "Creating Platforms",

View File

@ -35,10 +35,16 @@
"Extending Frontend": {
"Frontend": [
"frontend_index",
"frontend_architecture",
"frontend_development"
],
"Extending the frontend": [
"frontend_add_card",
"frontend_add_more_info",
"frontend_creating_custom_panels",
"frontend_creating_custom_ui"
"frontend_add_more_info"
],
"Custom UI": [
"frontend_creating_custom_ui",
"frontend_creating_custom_panels"
]
},
"Extending HASS": {

Binary file not shown.

After

Width:  |  Height:  |  Size: 226 KiB