Pascal Nohl

Widget Forge

User Guide & Examples

What is Widget Forge

Widget Forge lets you create flexible dashboard widgets for Homey that are not tied to a specific app, brand or device. Widgets are built and updated entirely through Flows.

This means you can display static text or numbers, but also dynamic values coming from Homey Tags, including numeric, boolean and text data.

Depending on the widget type, you can customise titles, labels, text styles, icons, icon position, separators, spacing, colours, frames and conditional formatting.

Example of an energy dashboard built with Widget Forge.

Top left column: Message widget
Middle left column: Big Data Block widget
Bottom left column: Styled List widget

The other widgets in the image are additional Styled List widgets with different styling.

Depending on the widget type, you can customise titles, labels, text styles, icons, icon placement, separators, spacing, colours, frames and conditional colour formatting.

All widget content and styling are updated dynamically through Flows.

Example of a Flow used with Widget Forge.

This Flow shows how different Widget Forge action cards can be used to style a widget and dynamically update its values.

The Flow logic is explained in more detail later in this guide. For now, this example is only meant to give you a first visual impression.

Requirements & Installation

To use Widget Forge, you need the Homey Dashboard and the Widget Forge app installed on your Homey.

After installation, add a Widget Forge widget to your dashboard. Each widget is linked to a widget ID and is configured and updated through Flows using the Widget Forge action cards. The widget ID logic is important and is explained in the next section.

Here is a direct link to the store page: Homey App Store

Important Widget Logic

You can create up to 26 widgets for each Widget Forge widget type.
When creating a widget, you must assign a widget ID in the widget settings, for example BA from the range BA to BZ. The available ID range depends on the widget type, because each widget type uses its own range.

This widget ID is very important, because it is the reference used by Widget Forge to identify that widget instance. To configure, style or update the widget, you must always use the exact same widget ID in the Widget Forge Flow cards.

Widget instances remain stored in memory, even if you remove them from the dashboard. To avoid confusing behaviour, it is important to understand the following:

If you create a widget with the same ID on another dashboard, both widgets will show the same data and will be controlled by the same Flows.
If you delete a widget and later create it again with the same ID, the previously stored data will appear again. If the Flow that styled the widget no longer exists, the widget will continue to show its last known state.
If you create line 3 in a widget and later remove the Flow card for line 3, that line will still remain visible and continue to show the last stored data. To remove it completely, run the card Clear widget ID xx once. This clears the widget data from memory, and your Flow can then build the widget again from scratch.
If you define lines 1, 2, 3 and 6, lines 4 and 5 will simply not be rendered. If you want to insert an empty space, use a Set spacer line card. This allows you to create a pixel-precise empty space for line 4 or 5.

Please follow the step-by-step guide below.

Create Your First Widget

To create a Widget Forge widget, start by adding the desired widget type to your Homey dashboard.

Then open the widget settings and select a widget ID from the dropdown list. This ID is important, because it links the dashboard widget to the Widget Forge Flow cards that will later configure, style and update it.

Depending on the widget type, some options can already be set directly in the widget settings, while most content and styling are controlled dynamically through Flows.

Once the widget has been added and the correct widget ID has been selected, you are ready to build it step by step.

Select one of the available Widget Forge widgets

Widget Settings

Each Widget Forge widget has its own settings. These settings are used for the basic configuration of the widget, such as selecting the widget ID and, depending on the widget type, defining certain layout or default style options.

Additional content and styling are then applied dynamically through Flows.

Because Widget Forge includes different widget types, the available settings may vary from one widget to another.

Show Title: Shows or hides the title above the widget. This is a Homey setting.
Title: Defines the title shown above the widget. This is a Homey setting.
Widget ID: Defines the ID of this widget instance. See the logic notes above.
Show widget title: Shows or hides the title bar inside the widget.
Title text: Defines the text shown in the title bar.
Title icon: Defines the icon shown in the title bar. Can be set to none.
Title alignment: Defines the title alignment: left, center or right.
Title text color: Defines the text color used for the title.
Title icon color: Defines the color of the icon in the title bar.
Show title separator: Shows or hides the separator line below the title.
Title separator color: Defines the color of the separator line.
Show widget frame: Shows or hides the frame around the widget.
Frame thickness: Defines the frame thickness: x-small, small, medium or large. Default: small.
Frame color: Defines the color of the frame.
Frame opacity: Defines the opacity of the frame.
Boolean values: Defines how boolean values are displayed: switches, true/false or Homey-style x/√.
Decimals: Defines the number of digits shown after the decimal point.

Building and Styling Widgets with Flow Cards

Message widget

Create a Message widget on the dashboard. (See Creating a Widget).
Create an Advanced Flow.
Right-click on the canvas and select Add → Then.
In the app list on the left, select Widget Forge, then choose the Set message card.
Select the ID of the widget you want to configure.
Then configure the card by defining the text, text style, text color, icon, icon color and background color.
Run the card using a start button, an event or a recurring time card.

The example card shown here creates the message displayed here.

Big Data List Widget

Create a Big Data Block widget on the dashboard. (See Creating a Widget).
Create an Advanced Flow.
Right-click on the canvas and select Add → Then.
In the app list on the left, select Widget Forge, then choose the Set Data in Big Data Block card.
Select the line and the ID of the widget you want to configure.
Then configure the card by defining the text, text style, text color, icon, icon color and background color.
Run the card using a start button, an event or a recurring time card.

Special features of this card

Invert: Reverses the sign of the value, for example -3200 → 3200.
Factor: Applies a conversion factor such as 0.1, 0.01, 0.001, 10, 100 or 1000. In this example, the PV power value is provided in W, while the card is formatted to display kW. To convert watts to kilowatts, a factor of 0.001 must be applied, so 1000 × 0.001 = 1.

In this example, two lines are rendered according to the definitions in the two cards.

Styled List Widget

The Styled List widget offers all the features of the Big Data Block widget, plus several additional advanced options. It is especially well suited for creating report-style widgets.

In the following section, only the advanced features are described, since the other features are similar to those of the Big Data Block widget.

In the widget settings, you can configure:

an optional title and icon, including title alignment and title color
an optional separator line, its style and color
an optional frame, including its thickness, color and opacity

Titles Inside the List

The Styled List widget supports both regular titles and inline titles.

Both can be customised using the styling options available in the title card.

Separator Lines

The Styled List widget allows you to add separator lines and customise their appearance using different styling options.

Values

To add a value line or modify an existing one, use the Set value card for the Styled List widget and configure the data styling as required.

Conditional Formating

Using Flows to style and update your widgets gives you a lot of flexibility and makes conditional formatting possible.

For example, if you want grid import and grid export to use different labels and colors, the following Flow shows one way to achieve this.

Note: Widget Forge uses data fingerprints to detect changes. If nothing has changed, no update is performed. This helps reduce CPU usage.

Advanced Conditional Formating

Widget Forge includes several advanced cards that allow you to apply value changes and color grades to existing lines. This means you do not need to rebuild the entire line and also gain more advanced color options.

- The Flow below shows one advanced way to use this approach:

First, the Styled List line exists card is used to check whether the line already exists.
If it does not exist, the line is created first and the color grade card is executed afterwards.
If the line already exists, the Apply numeric color grade card is applied directly.

- This card accepts one value and up to seven color grades:

The first color value is the below lowest threshold color. This color is used when the value is below the first defined threshold.
It is followed by up to six threshold/color pairs.
If the value is above one threshold but below the next one, the color of that pair is applied.
The last defined threshold/color pair also defines the color used for all values above the highest defined threshold.

- You do not need to define all thresholds.

- The final setting is the scope. The scope defines whether the color is applied to the value only, the icon only, or both.

These cards are available for both the Big Data Block widget and the Styled List widget.

A similar card, Apply color grade to boolean value, is also available for boolean values. This card accepts a boolean value, one color for true, one color for false, and a scope.

Set Spacer Line

When building a dashboard with different widgets, the widgets in different columns will often not have the same height.

To align them more precisely, you can use a spacer line in the Big Data Block and Styled List widgets.

Besides the widget ID and line number, this card has only one parameter: the spacer height in pixels.

Set Offset Zero Value

This is a generic card and is not tied to any specific widget type.

It can be used to stabilise fluctuating values so that displays or calculations do not react to every small change. A PV system is a good example, because the BMS may switch frequently between small grid imports and exports in order to preserve battery life.

The card accepts a value, a negative offset and a positive offset.
At runtime, it outputs the processed result as a tag.
If the value is between the negative and positive offset, the output is a fixed 0.
If the value is outside that range, the real value is passed through unchanged.

Clear A Widget

As explained earlier, once a line has been created in a widget, it remains stored with its last known value and style, even if you delete the Flow that originally created it.

This can lead to:

If your widget contains 12 lines and you delete the Flow that updates line 3, you can simply create a new Flow for line 3 without any problem.
However, if you want to remove line 3 completely without changing the line numbers used in many other cards, create a small Flow that only runs the Clear widget ID card and execute it once. This clears all stored data for that widget, and your main Flow can then build the widget again from scratch.
Remember that empty lines are not rendered.

Another common case is reusing a widget ID.

If you delete a widget with the ID AD and later use the same ID for a new widget, the widget may immediately display the last stored data.

In that case, create a small Flow that only runs the Clear widget ID card and execute it once.
After that, you can rebuild the widget as needed.

Page updated

Google Sites

Report abuse