-
Notifications
You must be signed in to change notification settings - Fork 299
Developer Guide: UI apps and components
Note
This wiki page has been migrated to the following documentation page:
https://docs.openremote.io/docs/developer-guide/working-on-ui-and-apps
Please update your bookmarks.
Front end applications are webcomponent based using the lit library and Material Design for styling. We use a combination of Polymer LIT, Material Design and our own OpenRemote elements. The UI components are published on NPM. The applications themselves are composed of our re-usable modular UI components which can be found in the code base in the ui/component folder, these are also published to NPM.
To work on an app for example the Manager UI
then cd
into the app directory e.g. ui/app/manager
and run the following npm
script:
-
npm run serve
- Compiles the typescript model from java code and then starts webpack dev server and serves the web app which can then be accessed athttp://localhost:9000/manager/
(NOTE: trailing/
is required)
The following environment variables can be set when running npm run serve
using the syntax npm run serve -- --env ENV_NAME=ENV_VALUE
:
- config - To apply a custom
manager_config.json
you can set theconfig
environment variable on thenpm run serve
command using a path relative to theapp/manager
directory e.g.- Windows:
npm run serve -- --env config=..\..\..\..\deployment\manager\app
- Mac:
npm run serve -- --env config=../../../../deployment/manager/app
- Windows:
- managerUrl - By default webpack dev server expects the manager to be available at
http://localhost:8080
but this can be configured for example when running the manager docker image (e.g.npm run serve -- --env managerUrl=https://localhost
) - keycloakUrl - By default keycloak expects to be available at
managerUrl/auth
but this can be configured for example when running the manager docker image (e.g.npm run serve -- --env keycloakUrl=https://keycloak/auth
)
Components are published as ES6 modules (for use in bundlers like webpack) and are also pre-bundled for direct consumption.
Doing development on the UI means working on any of:
- Front end applications
- Front end components and their demos, shared between applications
- Keycloak theme(s) used in authentication screens
You will need the standard tool chain (see Preparing the environment) to be able to build and run the components and apps. Working on the web applications and/or components will also generally require backend services to interact with, you can either:
- Run a Manager instance in an IDE (refer to Setting up an IDE)
- Deploy the Manager using a Docker container (refer to UI Development profile)
If you want to create a new component
or app
then simply copy an existing one as a template (when creating a component
then you may need to create a corresponding demo
which acts as a development harness that can be served by webpack dev server - one demo may act as harness for multiple components).
All UI components and apps are located in the ui
directory; here you can find the standard OpenRemote web UI components and apps using a monorepo architecture. The code is divided into categories by directory:
-
component
- Base OpenRemote JS modules and web components (built using Polymer) these are written as ES6 modules -
app
- Built-in OpenRemote web applications (applications can be built with whatever frameworks/libraries are desired) -
demo
- Demos of each web component (provides a development harness for developers working on the components)
Typescript is used to provide static typing with the OpenRemote model available in the @openremote/model
component package; the components are published to npm
under the @openremote
scope; see the README in each component for information about each specific component.
Yarn workspaces are used to symlink the OpenRemote packages into a root node_modules
directory (refer to the Yarn documentation for more details). Yarn acts as an alternative to npm
so please use it.
NPM scripts are used for build and development purposes (the main build tool for the entire code base is gradle
so there are gradle
tasks that launch NPM scripts - these gradle
tasks have the prefix npm
followed by the NPM script name e.g. npmBuild
).
The following standard NPM scripts are used throughout the components and apps for consistency:
-
clean
- Cleans up any build artefacts (typically uses theshx
package) -
build
- Build the component/app ready for publishing/deployment -
test
- Run any automated tests -
modelWatch
- Starts agradle
task to watch thejava
model code and to run thetypescript
generator when changes are detected, the generatedmodel
andrestclient
typescript code is then transpiled tojavascript
-
modelBuild
- Similar tomodelWatch
but just does a onetime build rather than watching for changes -
serve
- Startswebpack dev server
typically onhttp://localhost:9000/[app|demo]/
The above script names should be used in package.json
files and then appropriate build.gradle
files should be added, see existing components, apps, demos for examples. Typically only the apps
need to be built by gradle
tasks as typescript should follow project references and compile any dependent components.
Components can be developed and tested in isolation (with dependencies on other components and/or public npm modules as required). Some components have no visuals and provide standard OpenRemote functionality e.g. @openremote/core
, whilst others provide visuals that allow interaction with the Manager backend.
If you are working on a map component then please refer to the working on maps.
Apps bring together components and/or public NPM modules and can be written using any framework/library etc that is compatible with web components (see here).
These are apps for development purposes Generally a 1-1 mapping between components and demos; they provide a simple harness for the components that can be used during development and optionally can be deployed to offer component demos.
Publishing is done using lockstep versioning; we use yarn version plugin to manage workspace package version incrementing as follows:
- The public packages are marked for version bump:
yarn workspaces foreach --no-private --topological version --deferred <patch | minor | major>
- The new versions are applied:
yarn version apply --all
- The components are prepared:
yarn workspaces foreach --no-private --topological npm prepublishOnly
- The public packages are packed and published:
yarn workspaces foreach --no-private --topological npm publish
Source · Documentation · Forum · Issues · Docker Images · OpenRemote Inc.
- Overview
- Bluetooth Mesh
- HTTP
- KNX
- LoRa
- MQTT
- Simulator
- SNMP
- Serial
- TCP
- UDP
- Velbus
- Websocket
- Z-Wave
- Partner Integrations
- OpenRemote as Edge Gateway
- Auto provisioning devices and users
- Connect ESP32 or ESP8266 using MQTT
- Firmware updating with Hawkbit
- Partner Integrations
- Weather data using HTTP Agent
- Connect Your MQTT Client
- ChirpStack LoRaWAN Integration
- Celcius to Fahrenheit with Flow
- Configure mobile app behaviour
- Simulating data in attribute
- Preparing the environment
- Installing and using Docker
- Setting up an IDE
- Building and testing
- Working on UI and apps
- Working on maps
- Docker compose profiles
- Creating a custom project
- Maintaining an installation
- Adding Widgets on Insights
- Working on the mobile consoles
- Connecting Protocol adaptors with Agents
- Edge device firmware updating
- Licensing guidelines for contributors
- Useful commands and queries
- Data migration
- Gateway tunnelling setup