mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-23 01:06:30 +00:00
Update frontend docs
This commit is contained in:
Paulus Schoutsen
parent
8b6633373e
commit
001705fba3
62
docs/frontend_architecture.md
Normal file
62
docs/frontend_architecture.md
Normal 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.
|
||||
|
||||
|
||||
86
docs/frontend_development.md
Normal file
86
docs/frontend_development.md
Normal 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
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
@ -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)}>
|
||||
|
||||
@ -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",
|
||||
|
||||
@ -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": {
|
||||
|
||||
BIN
website/static/img/en/frontend/frontend-hero.png
Normal file
BIN
website/static/img/en/frontend/frontend-hero.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 226 KiB |
Loading…
x
Reference in New Issue
Block a user