# Building Pages: Components & Widgets
# UI Components: introduction and structure
UI components are the basic building blocks for many UIs in openHAB. The Main UI Pages and Personal Widgets are notable UI components, but Sitemaps that were created in the UI and HABPanel dashboards are as well.
These structures make up hierarchies that notably define the pages in their entirety, and are relatively simple. Each component has:
- A type
- Most of the time, a set of configuration properties
- Optionally, a set of named slots which hold collections of more components. By putting components into slots, we therefore define a hierarchy.
Slots are optional, and have a name; usually when there’re slots involved there’s a
defaultslot but not always.
The semantics of both the config properties and the slots depend on the component type, as well as the allowed sub-component types in the slots. The Component Reference provide details on what you can put in a certain component's config & slots.
Sometimes, the slots can be seen as different placeholders within a component where new components may be added. For instance, cell widgets have a
header slot which represents the part of the cell when not expanded.
default slot is the space in the cell which becomes visible when the cell is expanded.
In various parts of the UI page designers can "focus" on a particular component usually by selecting the Edit YAML item in a black context menu.
Below is a typical component as represented in YAML:
- component: ...
- component: ...
- component: ...
# Root Components & Props
At the top of the component tree we can find a root component. Pages are examples of root components. They have additional attributes:
- name: group1
label: Property group
- name: prop1
label: Prop 1
description: What prop1 does
- name: prop2
label: Prop 2
description: Choose an item for this prop
- name: prop3
tags: ["tag1", "tag2"]
- a uid (its Unique IDentifier)
- a props structure describing its own properties; props define parameters and parameter groups following a subset of the configuration description schema found in bindings, services and throughout openHAB: see Configuration Descriptions
- a set of tags
# Widgets: Definition & Usage
Widgets are nothing more than discrete components that can be added to a Page.
No matter which type of page you’re editing, the designer will feature black buttons beside most widgets, that open a contextual menu for the widget in question.
These menus will in most cases allow you to:
- Configure the documented parameters with a config sheet (“Configure Widget” or similar)
- Open the part of the page’s YAML representation pertaining to the widget (“Edit YAML”), that is, a subgraph of the page’s component tree with that widget as its root component
- Perform cut/copy/paste operations, if supported (you can only do that in the same page currently, to copy or move widgets between pages, you may use the YAML view)
- Reorder the widget within its parent slot (these options are usually named “Move Up” and “Move Down” although you may occasionally encounter other labels, like “Move Left”/“Move Right”)
- Remove the widget
Configuring the widget with the config sheet is of course more user-friendly than editing the YAML, as the options are usually organized logically in groups and feature a description:
However, it's important to know that there are limitations and sometimes editing the YAML directly will be best, because:
Not all options are described, since widgets are often wrappers for a similar concept in the library it is based on, either Framework7, ECharts, Leaflet, or other specialized libraries. This means that in these cases, these underlying concepts will usually be passed the key/values of the (openHAB) widget component's config so that more parameters can be accepted than those which are documented in the widget's definition. Sometimes it will be indicated somewhere when configuring the widget, or in the openHAB documentation itself, on the other hand some options won't be available for use (for instance, because they expect a callback function and you cannot define those in the widget's config) or need some transformation.
Sometimes you'll want to use an expression to configure the property, but the UI will get in your way - for instance, it will display an item picker while your intention is to set the prop value to be
=props.item1. Learn more about widget expressions.
To quickly and efficiently duplicate similar widgets with only a few differences, it is always way easier to copy/paste the relevant YAML in the editor.
The YAML is the best way of sharing complete or partial component structures like pages or widgets with others in the forum.
Besides, there are several options that virtually all widgets in layout pages, map pages and plan pages accept, all of which are not currently available in the config sheet:
visible: You can specify a
falseboolean to this option to hide the widget. This powerful feature, combined with widget expressions, allows you to dynamically show widgets or even entire sections (if you use it on layout widgets containing other widgets), depending on the state of your items Example:
visible: =items.TV_Powered.state === 'ON' && items.TV_Input.state === 'HDMI1'
visibleTo: This accepts an array of strings like
user:<userid>, allowing the widget to be only visible to specific users or those with a certain role. Example:
visibleTo: ["user:scott", "role:administrator"]
styleare standard Vue.js attributes (opens new window) and can be used to either alter the CSS classes or add inline styling to the component. Please refer to Styling pages & widgets using CSS.
# Types of Widgets
To help you define usable pages, there are a number of built-in widgets that you can use - most of which will be in layout pages. Those built-in widgets revolve around several libraries:
- The System library includes "crude" controls that you cannot add with the designers - for instance
oh-colorpicker. Instead, you're more likely to use them within some container (card, list item...) provided by a widget of the Standard library; but when designing a personal widget with a complex layout you may want to use one or several of them directly. You may also use them in a slot of another widget, for those which define some, in order to add additional controls to that widget.
- The Standard library, which has several classes of widgets:
- layout widgets, examples:
oh-grid-colthat you usually add with the designer to a layout page
- standalone widgets, examples:
oh-player-card- usually not much more than widgets from the System library wrapped in a card
- list item widgets, examples:
oh-toggle-item- widgets that are thinner than the standalone ones, which you can only add as a part of a list (
- cell widgets, examples:
oh-colorpicker-cell: These widgets are fixed-size cells that you can only add to an
oh-cellscontainer widget immediately below an
oh-blockin a layout page - they will either perform an action - switching a light on & off - or expanding to reveal additional controls
- page-specific widgets, for instance map pages have
oh-map-circle-marker, charts have different types of widgets than the rest to represent axes, series etc.
- layout widgets, examples:
See the Component Reference for details about the different libraries of components.
# Dynamically Configuring Components with Expressions
To dynamically configure components based on data changed on runtime, expressions can be used.
Please refer to widget expressions for more information.
# Modifying Styling with CSS
In case you want to customize the styling of a page or all its widgets, you can set CSS classes and properties globally for the page:
label: My Page
Please read CSS for Pages & Widgets to learn more about using CSS.
When configuring a widget, you will encounter options related to actions (usually, when something is clicked or touched, but there might be several actions configured for a single widget, for instance, clicking on different parts or a long tap with a touch device); regardless, they will all have the same options:
These action options allow you to configure the interactivity within your pages, as well as the relation between them, in an extensive way. You can navigate to another page, display additional controls, popups and other modals, send commands to items every time a widget allows you to choose an action. For instance, a floor plan marker might either open another page in a popup, or toggle an item. Configuring the action type reveal more options in the action sheet:
# Types of Actions
|What it does
|Navigate to page
|Opens a different Page with an optional transition.
|Issues a command to an Item.
|Alternate an item between two states by sending commands (regular command if the item's state is different, or an alternative command if the state is equal to the regular command). Typically used with ON/OFF.
|Issues a command to the configured Item based on a comma-separated locally-defined list of options, or on the Item's State Description.
|Trigger a rule directly.
|Open a Page or personal widget in a popup which will be displayed fullscreen on phones and in a 630x630-pixel modal dialog on larger screens.
|Open a Page or personal widget in a small "callout" comic-like bubble
|Open a Page or personal widget in a drawer appearing from the bottom of the screen.
|Open photo browser
|Displays a full screen interface to view one of several images
|Used with Group items to open a popup with an automatically-generated list of the members of the group, represented by their default list item widget. For Groups with a base type like Switch, a standard card widget will also be shown for the Group itself.
|Opens the Analyzer window for the specified item(s) and period
|Open an external web page
|Set a variable that you can use in other parts of the page or widget.
In your own personal widgets (see below code snippet), you can define a parameter group with an
action context to automatically define implicit props that you can pass "en masse" to built-in components that accept actions with the
- name: myaction
label: My Action
How the implicit props are named
The property names will be in the following format:
The list of
actionPropNames can be found in the Component Reference (they’re always the same), for instance in the oh-button reference.
groupName prefix is the name of the parameter group, but occurrences of the word "action" will be removed from it.
If you name the parameter group
action there won't be a prefix anymore so the underscore will be removed too.
|Prop Name Examples
action, actionItem, actionCommand, actionCommandAlt
tap_action, tap_actionItem, tap_actionCommand, tap_actionCommandAlt
sceneOne_action, sceneOne_actionItem, sceneOne_actionCommand, sceneOne_actionCommandAlt
You can dump the
props objects in JSON to verify the names like in the following example (or just use
=JSON.stringify(props) wherever you can display text in your widget):
- name: sceneOne
label: Scene One
- name: sceneTwo
label: Scene Two
- name: tapAction
label: Tap Action
- name: action
label: Tap Action
- name: prop1
label: Prop 1
description: A text prop
- component: Label
text: =JSON.stringify(props, null, 4)