Inputs

Inputs, also known as input arguments, are the parameters that a function uses to execute its action. By default, inputs are configured using YAML, a straightforward and human-readable format, though this can be switched to HTML if needed.

Data Formats & Types

An input can accept any data type supported by the JSON format: Null, Boolean, Number, String, Array, and Object. This allows for any complex or nested data structure your application might require.

YAML, a data-serialization language designed to be human-readable and straightforward, is the default format for providing static or structured data to function inputs. The following cheat sheet provides a quick overview of the most common YAML syntax you'll need.

YAML Input: A Quick Cheat Sheet

This guide will help you provide data in the correct format. It's a human-friendly way to specify data that is perfect for configuration.

Basic Values (Scalars)

These are the simplest data types. You can usually type them directly without quotes.

Strings: For text. Quotes are only needed if your text looks like another data type (e.g., 'true', '123') or contains special characters.
```
# Unquoted string
Hello world
```
```
# Quoted string (useful for special cases)
'1.2.3'
```
Numbers: For integers or decimals.
```
101
```
```
3.14159
```
Booleans: For true/false values.
```
true
```
```
false
```
Null: To represent an empty or non-existent value.
```
null
```

Lists (Arrays)

A list is a collection of items.

Block Style: Start each item on a new line with a hyphen and a space (- ).
```
- Apple
- Orange
- Banana
```
Compact Style: Enclose a comma-separated list of items in square brackets.
```
[Apple, Orange, Banana]
```

Objects (Key-Value Maps)

Objects let you group data under specific keys. The format is key: value.

Block Style: Each key-value pair gets its own line. Use indentation for nested objects.

user:
  name: Alex
  email: [email protected]
  permissions:
    can_read: true
    can_write: false

Compact Style: Enclose comma-separated key-value pairs in curly braces.
```
{ name: Alex, email: [email protected] }
```

Multiline Strings

This is essential for providing large blocks of text, code, or pre-formatted templates.

Literal Style (|): Use the pipe symbol to preserve every single line break exactly as you typed it. This is perfect for code or templates.

|
  ^XA^FO30,80^BQN,2,3^FDLA,{{assetId}}#{{date}}^FS
  ^FO120,140^A0N,22,22^FD{{assetId}}#{{date}}^FS
  ^RFW,A^FD {{assetId}}^FS
  ^XZ

Folded Style (>): Use the greater-than symbol to convert single newlines into spaces. This is great for writing long paragraphs that you want to be read as a single line of text. Blank lines will be kept as newlines.
```
description: >
  This is a very long description that is written
  on multiple lines in the editor, but it will be
  processed as a single, continuous sentence.

  A new paragraph starts after a blank line.
```

Sources of Input Data

A function's input can receive data from three primary sources:

Static Data: You can type a fixed value directly into the input box. This value is set at build-time and does not change.
Dynamic Data from Logic: An input can be dynamically populated by linking it to the output of another function.
Data Binding from the UI: An input can be linked to an input widget property via data binding. This allows the function to receive live data entered by the user in the user interface.

Handling Special Characters as Strings

Sometimes, a value containing special characters (like :, {, or >) can be misinterpreted by the YAML parser. To ensure your input is always treated as a plain string, you can use one of two methods:

Use a Folded Block Scalar (>-): Place >- on the first line, then start your text on the next line, indented with two spaces.
Use Single Quotes: Simply enclose your entire input in single quotes (e.g., 'special: {value}').

Configuring Inputs

You can interact with an input box in several ways:

Right-click on an input box to open a context menu where you can:
- Switch between YAML and HTML input formats.
- Set the input as a Secret, which hides the value (useful for passwords).
- Clear the content or Delete the input box.
Add another argument to functions that support it by clicking the + icon next to an existing input.
View documentation for an input by hovering over the arrow icon on the right side of the box.

Special Input Types: Callbacks

Certain functions, often named with an "on" prefix (e.g., onMessage), use a special Callback input. In traditional programming, a callback is a function passed as an argument to another, to be "called back" when an event occurs.

In Heisenware, this is represented by a special dashed input box that contains its own output. This allows a function to listen for external events (like an incoming MQTT message) and provide the data from that event through the callback's output, ready to be used in the rest of your flow.

Last updated 5 days ago