Your first widget
In this page you build a tile for a lamp: its name, whether it is on, its brightness, a tap to switch it and a bulb that glows. It takes about ten minutes, and every step shows something new on the preview.
Start from the Light widget
- Choose Your widgets in the sidebar, then New widget.
- Choose Start from a widget, pick Light, and call yours Lamp.
- The editor opens with a copy of the Light widget’s template and style. Select everything on the Template tab and delete it.
Starting from Light means your widget fits the same devices as Light does: lights that can switch on and off. The preview on the right draws it with a demo lamp, and can show the lamp in each of its states, such as on, off and unavailable, so you can see how the widget behaves in each.
Show the name
Type this on the Template tab:
<p class="name">{{ device.name }}</p>The double curly braces are Liquid’s way of writing a value into the page.
device is the tile’s own device, and name is its name in Homey.
The preview now shows the name of the demo lamp.
Show whether it is on
A lamp’s state is the reading onoff.
Readings live in cap, and each has a value, so the state is cap.onoff.value.
It is true while the lamp is on and false while it is off.
{% assign on = cap.onoff.value %}<p class="name">{{ device.name }}</p><p class="big">{% if on %}On{% else %}Off{% endif %}</p>{% assign %} gives the value a short name, on, so you can use it more than once.
{% if %} shows one thing or the other.
Switch the preview between the lamp’s states to see the text change.
Show the brightness
Lamps that dim also have a reading called dim, a number from 0 to 1.
The percent filter turns it into text such as 62 %.
{% assign on = cap.onoff.value %}<p class="name">{{ device.name }}</p><p class="big">{% if on %}{{ cap.dim.value | percent }}{% else %}Off{% endif %}</p>A filter is written after a vertical bar and changes the value in front of it. Liquid lists the filters you can use.
Make it a button
Wrap the content in a button, and tell the button what to do when it is tapped:
{% assign on = cap.onoff.value %}<button class="lamp" data-hd-on-click="toggle('onoff')" aria-pressed="{{ on }}"> <span class="name">{{ device.name }}</span> <span class="big">{% if on %}{{ cap.dim.value | percent }}{% else %}Off{% endif %}</span></button>data-hd-on-click holds a handler: a short line that runs when the button is clicked.
toggle('onoff') switches the reading onoff to the other value.
Tiledash checks the action before it reaches your Homey, and the tile shows the new state at once.
aria-pressed tells screen readers whether the button is on.
It also gives your style something to react to in the next step.
You can read more about handlers in Taps and handlers.
Add the bulb
hd-bulb is one of Tiledash’s own components.
It lights up and fades as the lamp is switched, and its glow follows the brightness.
{% assign on = cap.onoff.value %}<button class="lamp" data-hd-on-click="toggle('onoff')" aria-pressed="{{ on }}"> <hd-bulb on="{{ on }}" level="{{ cap.dim.value }}" size="22px"></hd-bulb> <span class="name">{{ device.name }}</span> <span class="big">{% if on %}{{ cap.dim.value | percent }}{% else %}Off{% endif %}</span></button>Its attributes take the values you already have: on says whether it is lit and level is the brightness from 0 to 1.
Style it
The Style tab is plain CSS. Replace what is there with this:
.lamp { all: unset; display: grid; align-content: space-between; height: 100%; cursor: pointer;}.name { font: 500 13px var(--hd-font-ui); color: var(--hd-text-muted);}.big { font: var(--hd-number-weight) 48px / 1 var(--hd-font-display);}[aria-pressed='true'] .big { color: var(--hd-lit);}all: unset takes away the button’s default look, and the grid puts the bulb at the top and the number at the bottom.
The colours and fonts are theme variables, so the tile follows whichever theme the dashboard uses, including the black and white e-ink ones.
--hd-lit is the warm colour a theme uses for something that is on, and the last rule paints the number with it while the button is pressed.
The whole widget
Here it is, running. The tile is drawn by the same engine the app uses, with a demo lamp. Switch the demo lamp between On, Off and Away, or pick another theme under the tile. Press Edit and change something.
{% assign on = cap.onoff.value %}<button class="lamp" data-hd-on-click="toggle('onoff')" aria-pressed="{{ on }}"> <hd-bulb on="{{ on }}" level="{{ cap.dim.value }}" size="22px"></hd-bulb> <span class="name">{{ device.name }}</span> <span class="big">{% if on %}{{ cap.dim.value | percent }}{% else %}Off{% endif %}</span></button>Save it and use it
Press Save. The footer says where your widget is used, and the last 10 saves are kept in History.
Your widget now appears in the widget picker under Your widgets. To use it, add a tile, pick Lamp, and choose a light.
If you would rather replace the built-in Light everywhere, open the Details panel in the editor and turn on Use mine instead of the built-in Light. Every Light tile on every dashboard then draws yours. Turn it off to go back.
One more step: a lamp that is gone
Devices go offline.
A tile should say so instead of showing the last value as if nothing happened.
Every device has an available flag, so change the text of the big number:
<span class="big"> {%- if device.available == false -%} Offline {%- elsif on -%} {{ cap.dim.value | percent }} {%- else -%} Off {%- endif -%}</span>The dashes inside the tags trim the spaces around them, so the text sits snugly in the element.
elsif adds a third case between if and else.
Show the preview’s unavailable lamp to check it.