Skip to content

Latest commit

 

History

History
102 lines (66 loc) · 7.55 KB

CONTRIBUTING.md

File metadata and controls

102 lines (66 loc) · 7.55 KB
Raw

Contributing to the openHAB UI

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.

Prerequisites

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 Scripts

  • 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 tests
  • npm run test:unit:watch - start the Jest test runner, run the unit tests, keep running and watch for changes
  • npm run test:e2e - start Cypress and run the e2e tests
  • npm run test:e2e:gui - open the Cypress GUI

Development server

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.

Vue DevTools

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 Elements tab of the browsers DevTools)
  • Read (and write) props, data and computed of 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.

How Do I?

This FAQ tries to provide some guidance on how to start off with some common changes to MainUI.

Edit an existing page?

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.

Edit or add a widget?

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.

Edit or add Blockly blocks?

Update the FAQ or Quick Start of the developer sidebar's help?

The "How do I..." and "Quick Start" sections are created from JSON definitions located at the web/src/assets/definitions/help directory.

PWA

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.

Documentation & Resources

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.

Framework7