Settings

A widget you share across many tiles shouldn’t have a device name or a favourite colour written into it. Settings let each tile choose these things, and the widget reads the choice.

A tile’s settings dialog is built from the settings your widget declares, so you never draw a form yourself. A setting for a device becomes a device picker that lists only the devices that fit, a setting for a number becomes a slider, and so on.

Declaring settings

Open the Settings tab in the editor and press Add a setting. Pick a kind, give it a name and a label, and fill in what it needs. Beside the form, a preview shows what the tile’s settings dialog will look like.

The form and its JSON view are two ways of editing the same list, which the editor stores with your widget. Use the JSON view if you prefer typing or pasting. This list declares four settings:

[  { "type": "text", "name": "title", "label": "Title", "default": "Garden", "maxLength": 30 },  {    "type": "color",    "name": "accent",    "label": "Accent colour",    "default": "lit",    "group": "look"  },  {    "type": "size",    "name": "titleSize",    "label": "Title size",    "default": "medium",    "group": "look"  },  {    "type": "device",    "name": "pump",    "label": "Pump",    "help": "The socket the garden pump is plugged into",    "requires": { "all": ["onoff"] },    "classes": ["socket"]  }]

Every setting has these fields:

• type is the kind of setting.
• name is the key the template reads: settings.title. It starts with a lower-case letter and continues with letters and digits, up to 32 characters.
• label is what the tile’s dialog calls it, up to 60 characters.
• help is an optional line under it, up to 200 characters.
• required says whether a tile must choose something. It is true unless you say otherwise.
• group says which tab of the tile’s settings it sits on: content (the default), layout, look, chart, map or tap.

Settings that are simple values always have a default, so the widget works before anyone has chosen anything. A widget can declare up to 32 settings. The settings reference lists every kind with all its options.

The kinds

Some settings choose something from the tile’s Homey:

• A device picks a device. You say which devices fit: readings they must all have, readings of which one is enough, and optionally a device class. A socket that is set to be an EV charger in Homey counts as an EV charger.
• A capability picks one reading, of the tile’s own device or of a device setting.
• A flow, a mood and a dashboard pick one of those on the Homey.
• Turn on Several for any of these four, and the tile picks a list of them. “All my smoke detectors” is then one setting, not eight.

Others are simple values with a default: a number (a slider, a stepper or a field), a percentage, yes/no, text, a choice, a colour, an icon, a size and a spot (one of the nine places on a tile).

A third group is made for bigger jobs: lists of readings for a chart, values like the custom tile has, buttons, places for a map, and a tap, which lets the tile’s owner choose what a part of the widget does when it is tapped. You will read more about taps in Taps and handlers.

Reading a setting in the template

Every setting is under settings, by its name:

<h2 class="title">{{ settings.title }}</h2>{% if settings.pump %}  <p>    {{ settings.pump.name }}:    {{ settings.pump.cap.measure_power.text }} {{ settings.pump.cap.measure_power.unit }}  </p>{% else %}  <p>Choose a pump in the tile’s settings.</p>{% endif %}

What you get depends on the kind:

• A device reads like the tile’s own device, with its own cap: settings.pump.name, settings.pump.cap.onoff.value.
• A capability reads like cap.<id>, with its id as well: settings.reading.text.
• A flow and a mood are objects with an id and a name, and a dashboard has an id and a name.
• Numbers, text, choices, colours, icons, sizes and spots are the value itself. A yes/no is true or false.

A setting that isn’t chosen, is gone from the Homey, or no longer fits is null. That is why {% if settings.pump %} works, and why a device setting must always be tested before you use it. An optional text left empty, and an icon or a colour without a default, are null as well.

Going through a list

A setting with Several on is a list. Go through it with for:

{% for alarm in settings.alarms %}  <p class="{% if alarm.cap.alarm_smoke.value %}alarm{% endif %}">    {{ alarm.zone }}: {{ alarm.cap.alarm_smoke.text }}  </p>{% else %}  <p>Choose smoke detectors in the tile’s settings.</p>{% endfor %}

Each device in the list reads like a device setting. A list is never null, only empty, so test it with {% if settings.alarms.size > 0 %}.

Each tile picks its devices in an order, or takes every device that fits. With every device that fits, a smoke detector added to Homey later shows up by itself.

An action inside the loop names its device: toggle('onoff', '{{ alarm.id }}'). While it is on its way, alarm.pending.onoff shows it, as settings.pump.pending does for a single device.

The editor checks your widget with settings left empty, so a template that assumes a device is there is reported while you write it. Reading settings.pump without declaring it is an error.

Reading a setting in the style

Settings that are simple values reach the style as CSS variables. The name is --setting- followed by the setting’s name in lower-case words joined with dashes: titleSize becomes --setting-title-size.

.title {  color: var(--setting-accent);  font-size: calc(18px * var(--setting-title-size-scale));}

What each kind becomes:

Devices, capabilities, flows, moods and the bigger kinds aren’t values a style can use, so they get no variable.

A style can also look at a choice through an attribute that you set from Liquid:

<div class="panel" data-layout="{{ settings.layout }}">…</div>

.panel[data-layout='compact'] {  gap: 4px;}

Devices by their id

Sometimes you want a widget for one particular device, and you copy its id into the template as devices['…']. That works, but only on your Homey, and the editor warns you about it. A device setting does the same job on every Homey, so the editor offers Make this a setting instead.

Naming settings well

• Name the setting after what it is, not where it sits: charger, not device2.
• Write the label for the person using the tile: Charger, not charger_device.
• Put a few lines of help on the settings that need explaining.
• Keep the first tab short. Move settings about looks to look, so a tile’s Content tab only holds what matters most.