HABot Walkthrough (6/n): Configuring Card Components & Dynamic Expressions

This is a wiki topic, regular members as well as staff may edit it freely and are encouraged to do so! The content will eventually be migrated somewhere in the main documentation when it’s stabilized and enough feedback has been received. When replying to posts on this series, please try to stay on-topic - there will be several of them, each covering a particular feature or area, so please look for the appropriate topic and reply there, or create a new topic. Thanks! :slight_smile:


As presented in the previous article, HABot’s card are trees of components and slots. Most components are nearly straightforward hosts for their counterparts from the Quasar Framework - HbBtn is a wrapping around Quasar’s QBtn, HbKnob is a wrapping around QKnob, and so on. They will often have configuration properties mimicking the original Quasar component’s.

Here we’ll cover some of the most useful things to know when configuring components.

Colors

Component properties defining colors use Quasar’s Color Palette.
The palette is available at:
https://quasar-framework.org/quasar-play/android/index.html#/showcase/style-and-identity/color-palette

You can use unsuffixed colors like “red”, “indigo”, “teal” or variations like “red-7” or “blue-5”, as well as the predefined colors like “positive” (green), “negative” (red), “info” (cyan) or “dark”.
The only difference is the “primary” and “secondary” colors which have been changed to standard openHAB orange and blue.

The following screenshot shows a card where the HbCard’s component color property has been set to “dark” and the HbSlider’s color property has been set to “secondary”:

Icons

HABot embeds two icon sets provided by the Quasar Framework: Material Icons (official iconset from Google) and MDI (community-based icon collection inspired by Material Design). To keep the app lean and avoid external dependencies, no other icons are available.

Configuration properties in components specifying icons expect a string according to:
https://quasar-framework.org/components/icons.html#Cheatsheet

  • for Material Icons, go to https://material.io/icons, choose your icon and copy its name without change in the configuration property, for example “trending_up”

(note: new icons are frequently added to the MDI iconset, so there might be a delay between those icons appearing on https://materialdesignicons.com and them being available in HABot!)

The HbContainer Component

The HbContainer is a very versatile component which allows you to use CSS classes from the Quasar Framework to design more complex cards. Use its “classes” configuration property to add Quasar classes for spacing (e.g. “q-mt-sm”, “q-pa-md”), typography (“q-caption”, “uppercase”), coloring (“text-gray-5”, “bg-warning”), sizing (“fit”, “full-width”) or the flex positioning (“row”, “col”, “flex”, “flex-center”) etc.
Check the Quasar docs to see what’s available and experiment!

Here’s the main slot JSON of the main slot of the card in the screenshots above - create a new card and edit the “main” slot’s JSON as described in the previous article, replacing it by the contents of the file to see how this layout was achieved:
multiroomaudio-main-slot.json (8.1 KB)

Dynamic Expressions

A number of component properties, like the card’s title, subtitle, or HbListItem’s properties don’t accept only literal values but can be made dynamic with the use of expressions.

To specify an expression for these properties, prefix it with an equal sign = like for instance in Excel spreadsheets. Not all properties accept expressions; the property’s description below the field will usually indicate whether or not you can use expressions. Note that some properties only accept expressions, not literal values: in this case, the field will already have an = prefix, and there is no need to add it yourself!

The expression language powered by the JEXL library will be parsed and the expression will be evaluated instead of a literal value.
Expressions can not only be a way to display dynamic text, but also change colors or icons dynamically.

2018-11-05_15-42-18

You can access your openHAB items in expressions by using the items variable. It contains an object whose keys are the items’ names. Each key will contain the representation of the item as returned by the rest/items REST API endpoint, except the states are updated in real-time.

The ternary operator will often be your best friend when building dynamic cards with expressions!

Here are the expressions used in the screenshot above:

  • HbCard subtitle:
    ="Average temperature: " + items.Temperature.state + " °C"
  • HbKnob color:
    =items.Temperature_Setpoint.state < items.Temperature.state ? "blue" : "red"
  • HbKnob state (state is a special variable defined only for expressions in HbSlider’s and HbKnob’s “state” property):
    =state + " °C"
  • HbKnob iconLeft:
    =items.Temperature_Setpoint.state < items.Temperature.state ? "mdi-snowflake" : "mdi-radiator"

Card Suggestions

The “suggestcriteria” property on the root HbCard component is a powerful way to present contextual cards only when they are useful or relevant. For example, you might want to quickly see a card controlling your audio-video equipment only when it’s powered on, cards displaying webcams are most useful when nobody’s home or when an intrusion alarm triggered, heating controls might be useful only when the temperature is outside a certain range…
Use an expression in this field, which must be a boolean value and can of course include the items variable to use item states; the card will then appear in the “Suggestions” screen only when the expression evaluates to true.

If there are card suggestions, a shortcut button will appear in the beginning of chat sessions to get to them as quickly as possible.


Expression used in this example for “suggestcriteria”:
items.Temperature_Setpoint.state < 18 || items.Temperature_Setpoint.state > 24

Next Steps

The next article will show how to make HABot send messages by itself! - with push notifications from your rules. You can even make it show a card you’ve designed.

5 Likes