Repository navigation
BLL Lists JSON
Examples · Custom functions · Workflows
BLL variables do not have a separate array type. Store a list as JSON in a text variable, then evaluate or parse it when you need its contents. The array walkthrough and rainfall discussion demonstrate this approach.
The expressions below are bare BLL JavaScript. Fixed arrays make them directly testable; select actual Homey tags when adapting them. A variable name typed into JavaScript does not automatically retrieve a BLL variable.
- Create a text variable called
RainHistoryin settings. - Set its text to
[]once to initialize an empty list. - Use a variable-setting BLL expression to append a reading.
- Save the returned JSON text back into
RainHistory.
Use the appendItem function for appending.
For example, appendItem([1, 0], 2) returns [1,0,2] as JSON text.
The original post calls its function pushAsString; the behavior is the
same. This screenshot shows the community's setup:
Community example: a custom function appends a value and returns JSON text for storage in a BLL text variable.
If a controlled variable contains [1,0,2], inserting its tag unquoted
in an expression makes that content a JavaScript array literal. The forum
uses this technique. Alternatively, JSON.parse("[1,0,2]") explicitly
converts JSON text into an array. Do not wrap arbitrary JSON-containing
tags in quotes: embedded quotes or backslashes can break the expression.
Use JSON-capable cards for data that cannot safely be inserted as code.
These adaptations extend the forum's rainfall use case:
| Bare expression | Result | Purpose |
|---|---|---|
[1, 0, 2, 4][0] |
1 |
First reading; indexes start at zero. |
_.last([1, 0, 2, 4]) |
4 |
Most recent reading when appending at the end. |
[1, 0, 2, 4].length |
4 |
Number of stored readings. |
_.sum([1, 0, 2, 4]) |
7 |
Total stored rainfall. |
_.sum(_.takeRight([1, 0, 2, 4], 3)) |
6 |
Total of the latest three readings. |
JSON.stringify([1, 0, 2, 4].slice(-2)) |
[2,4] |
Keep the latest two as JSON text. |
JSON.stringify([1, 0, 2, 4].map((value, index) => index === 2 ? 7 : value)) |
[1,0,7,4] |
Replace the third reading. |
Store numeric readings, not localized strings such as "1,5". A rolling
list represents days only if your Flow adds exactly one daily reading.
Missed runs, repeated runs and cumulative sensor readings need explicit
handling; do not treat a partial history as a complete rainfall record.
The rainfall thread asks for a FIFO list with ten places. The following
adaptation implements a bounded history instead of allowing an array
to grow indefinitely. Save it as rollingReadings:
(function (items, value, limit) {
if (!Array.isArray(items) || !items.every(Number.isFinite) ||
!Number.isFinite(value) || !Number.isInteger(limit) || limit < 1) {
throw new Error("Expected numeric readings and a positive integer limit");
}
return JSON.stringify(items.concat(value).slice(-limit));
})Example:
rollingReadings([1, 0, 2], 4, 3)This returns [0,2,4] as text. For a ten-day history, call the function with
limit 10, the current history and that day's reading, then store the result.
Perform the append-and-save steps sequentially: simultaneous updates can
both read an old list and overwrite each other.
For watering decisions, check history completeness and sensor freshness before comparing a recent total with your chosen threshold. See stale-sensor checks.
Use JSON.stringify instead of manually concatenating JSON strings:
JSON.stringify({ room: "Kitchen", temperature: 21.5, online: true })This adaptation produces valid JSON text and preserves number/boolean
types. A later JSON reader can select room, temperature or online.
Use BLL's JSON result tag when the receiving card supports it; otherwise
pass text in the shape that card expects.
Do not confuse JSON data with JavaScript source. JSON.parse requires
valid JSON, including double-quoted property names. Invalid JSON should
raise an error rather than silently becoming an empty list.
The pipe-splitting example shows why the function's returned property names and the JSON reader's paths must agree. For MQTT sensor objects and looping over timer names, see the multi-app workflows.
For table output rather than individual values, use BLL's JSON-to-CSV and Excel actions.
Support development - If Better Logic Library is useful to you, you can support its
continued development through GitHub Sponsors,
Patreon,
PayPal, or
bunq.
Thank you!
