The standard contributing and community guidelines for the openHAB project, including signing off your commits, also apply for the development of the UI.
The repository for web user interfaces, including this project, is located at https://github.com/openhab/openhab-webui and the code of this project, including this file, is found in the bundles/org.openhab.ui folder.
This project is built using Vue.js, webpack and Framework7.
You need Node v20.12.2 or later and npm 10.5.0 or later installed.
If you use a Node version manager like nvm, change to the web directory and run nvm use.
Change to the web directory, gather the necessary dependencies with npm install then the scripts below will be available.
npm start- run the development server (see below)npm run build-prod- build web app for production (note: no need to prepare a production version when submitting a PR, the build server will do it)npm run dev- run the development server (same as above)npm run dev:blockly- run the development server with Blockly source-maps (allows Blockly debugging)npm run test:unit- start the Jest test runner and run the unit testsnpm run test:unit:watch- start the Jest test runner, run the unit tests, keep running and watch for changesnpm run test:e2e- start Cypress and run the e2e testsnpm run test:e2e:gui- open the Cypress GUI
Before starting the development server with npm start, you should have an instance of openHAB (either a complete distribution or the demo app) running on localhost:8080.
The development server will run on the next available port (for instance, 8081) and proxy requests to well-known openHAB URLs like the REST API or icon servlet, forwarding them to their equivalent on port 8080.
If you wish to change the target of these forwards and use a remote instance, set the OH_APIBASE environment variable to the desired URL (e.g. OH_APIBASE=http://openhab-dev:8080) before running npm start.
You can also run the unit tests (test/jest) and e2e (test/cypress) tests using the abovementioned commands.
Cypress is configured to assume the development server is running on port 8081 - you can change that in cypress.json but remember not to commit.
You can also use Majestic GUI to run the unit tests and temporarily collect code coverage and view coverage reports (it is disabled by default for performance reasons): install it globally with npm install -g majestic, and run majestic in the root web folder to open Majestic in a browser window.
Since openHAB's MainUI is using Vue, it is really helpful to install the Vue DevTools in your browser. Please note that you can only use the Vue DevTools with the development server.
Some of its very helpful features are:
- Access to all Vue components of the current page in a tree model (like the
Elementstab of the browsers DevTools) - Read (and write)
props,dataandcomputedof Vue components. - Select a component by clicking on it (very helpful when you want to change something in MainUI, but don't know which component you have to edit).
- Access to the Vuex storage.
This FAQ tries to provide some guidance on how to start off with some common changes to MainUI.
In general, it is a good start to open the web/src/pages directory.
In this directory, open the sub-folders according to the path of the MainUI page.
E.g.: You want to edit /settings/transformations. Open web/src/pages/settings/transformations. You'll find transformations-list.vue and transformation-edit.vue, it should be self-explaining which page does what.
When you open a .vue file, check out the template tags for the structure of the page. You will note, that several UI structures are packed into Vue components, which you can directly open from the template tags inside your IDE.
E.g. for IntelliJ-based IDEs: To open a component from the template tags, press CTRL and then click on the component name. To follow the example with the transformations, open transformation-edit.vue, and search for transformation-general-settings inside the template tags. CTRL + click on it, and the Vue component will open up.
Instead of following the way described above, you can also use the Vue DevTools to find out which component you need to modify.
UI widgets are Vue components, not pages, therefore you'll find them in the web/src/components/widgets/standard directory.
When opening one of those widgets you can use in the UI, e.g. oh-clock-card.vue, you'll notice that it basically wraps the oh-clock.vue component from web/src/components/widgets/system.
If you now want to modify the functionality or appearance of the clock widget, your changes usually need to be done inside the wrapped component, in this case oh-clock.vue, not oh-clock-card.vue.
In case you want to edit widget parameters, make sure to adjust the widget's parameter definition in web/src/assets/definitions/widgets/system. After editing those definitions, it is required to regenerate the component docs, see Documentation & Resources.
- Blocks are defined within blockly-editor.vue.
- Blocks are implemented inside the web/src/assets/definitions/blockly directory.
- Each block requires a Blockly.Blocks section that defines the visual representation and a javascriptGenerator.forBlock section that implements the code generation of the block.
- Please refer to the visualisation and code generation documentation on how to define blocks.
- Also follow the Blockly Best Practices and Blockly Style guide.
The "How do I..." and "Quick Start" sections are created from JSON definitions located at the web/src/assets/definitions/help directory.
Edit the web/src/assets/automation-languages.js file.
Edit the web/src/assets/transformations.js file.
This is a PWA. Don't forget to check what is inside your service-worker.js. It is also recommended that you disable the service worker (or enable "Update on reload") in your browser's dev tools during development.
The openHAB docs provide a Component Reference as well as docs for each component.
You can find the components docs in the doc/components folder.
To generate the auto-generated parts of these component docs, run node generate.js inside the doc/components/src folder.