Arguments

An argument is an input field in a Flow card that the user can fill in. An argument can have an optional placeholder property which is displayed when no value is present, and an optional title property which is shown above the argument input.

List of arguments

Text

"type": "text"

Regular text input. Tokens can be dropped in this field as well.

Attributes

Name Type Description Example
placeholder object Text to show without input { "en": "What to say", "nl": "Wat te zeggen" }
title object Text shown above argument { "en": "My title", nl": "Mijn titel" }

Example

/app.json

"args": [
  {
    "type": "text",
    "name": "my_text",
    "placeholder": {
      "en": "Type something..."
    },
    "title": {
      "en": "My title"
    }
  }
]

Autocomplete

"type": "autocomplete"

This is the same as a text input, but with an additional autocomplete popup. The returned value when the card is run, is one of the objects provided in the autocomplete array.

Attributes

Name Type Description Example
placeholder object Text to show without input { "en": "What to say", "nl": "Wat te zeggen" }
title object Text shown above argument { "en": "My title", nl": "Mijn titel" }

Example

/app.json

"args": [
  {
    "type": "autocomplete",
    "name": "my_autocomplete",
    "placeholder": {
      "en": "Search for things..."
    },
    "title": {
      "en": "My title"
    }
  }
]

/app.js

const myActionCard = this.homey.flow.getActionCard('my_action');

myActionCard.registerArgumentAutocompleteListener('my_arg', async (query, args) => {
  const results = [
    {
      name: 'Value name',
      description: 'Optional description',
      icon: 'https://path.to/icon.svg',
      // For images that are not svg use:
      // image: 'https://path.to/icon.png',

      // You can freely add additional properties to access in registerRunListener
      id: '...',
    },
  ];

  // filter based on the query
  return results.filter((result) => {
    return result.name.toLowerCase().includes(query.toLowerCase());
  });
});

If you don't filter based on the query it will cause the autocomplete results to appear unresponsive. The simplest strategy is to filter based on name, and casting both query and name to lowercase as shown above.

Number

"type": "number"

Regular text input. Tokens can be dropped in this field as well.

Attributes

Name Type Description Example
min number Minimum input value 0
max number Maximum input value 25
step number Step size 0.1
placeholder object Text to show without input { "en": "In degree celcius", "nl": "In graden celcius" }
title object Text shown above argument { "en": "My title", nl": "Mijn titel" }

Example

/app.json

"args": [
  {
    "type": "number",
    "name": "my_number",
    "min": 0,
    "max": 100,
    "step": 10,
    "placeholder": {
      "en": "Set a value"
    },
    "title": {
      "en": "My title"
    }
  }
]

Range

"type": "range"

A slider with a minimum and maximum value.

Attributes

Name Type Description Example
min number Minimum input value 0
max number Maximum input value 25
step number Step size 0.25
label string The units after the number %
labelMultiplier number Number is shown after multiplying by this factor 100
labelDecimals number Number of decimals to round 2
title object Text shown above argument { "en": "My title", nl": "Mijn titel" }

Example

/app.json

"args": [
  {
    "type": "range",
    "name": "my_range",
    "min": 0,
    "max": 1,
    "step": 0.01,
    "label": "%",
    "labelMultiplier": 100,
    "labelDecimals": 0,
    "title": {
      "en": "My title"
    }
  }
]

Date

"type": "date"

Date input (presented in dd-mm-yyyy)

Attributes

Name Type Description Example
placeholder object Text to show without input { "en": "When to ..", "nl": "Wanneer te .." }
title object Text shown above argument { "en": "My title", nl": "Mijn titel" }

Example

/app.json

"args": [
  {
    "type": "date",
    "name": "my_date",
    "placeholder": {
      "en": "31-12-2016"
    },
    "title": {
      "en": "My title"
    }
  }
]

Time

"type": "time"

Time input (presented in HH:mm)

Attributes

Name Type Description Example
placeholder object Text to show without input { "en": "When to ..", "nl": "Wanneer te .." }
title object Text shown above argument { "en": "My title", nl": "Mijn titel" }

Example

/app.json

"args": [
  {
    "type": "time",
    "name": "my_time",
    "placeholder": {
      "en": "13:37"
    },
    "title": {
      "en": "My title"
    }
  }
]

Dropdown

"type": "dropdown"

A dropdown list with pre-defined values

Attributes

Name Type Description Example
values array An array of possible values [ { "id": "value1", "label": { "en": "Value 1" } } ]
title object Text shown above argument { "en": "My title", nl": "Mijn titel" }

Example

/app.json

"args": [
  {
    "type": "dropdown",
    "name": "my_dropdown",
    "title": {
      "en": "My title"
    },
    "values": [
      {
        "id": "monday",
        "label": {
          "en": "Monday"
        }
      },
      {
        "id": "tuesday",
        "label": {
          "en": "Tuesday"
        }
      },
      {
        // ...
      }
    ]
  }
]

Device

"type": "device"

When you add a device argument to your flow card, and provide a driver_id filter, e.g. "filter": "driver_id=yourdriverid", the flow card will only be displayed for devices that belong to that specific driver (Flow-Devices|read more).

If the device was already there because the device's class is a supported device class (e.g. light), your cards will be appended to the existing stack of cards. An example would be a Light driver that has a 'disco' mode, next to on/off, dim and color.

If the card has more than one device fields, the other fields will behave like an autocomplete-like argument, which show devices paired in your app.

Attributes

Name Type Description Example
placeholder object Text to show without input { "en": "Which coffee machine", "nl": "Welk koffiezetapparaat" }
filter string Querystring-like filter driver_id=coffeemachine

Example

/app.json

"args": [
  {
    "type": "device",
    "name": "my_device",
    "filter": "driver_id=my_driver"
  }
]

Color

"type": "color"

A color picker that returns a HEX color, e.g. #FF0000.

Attributes

This argument has no attributes

Example

/app.json

"args": [
  {
    "type": "color",
    "name": "my_color"
  }
]

Droptoken

This is a special argument because it is placed before the card's title. You must add it to your card's /app.json by specifying "droptoken": "string" (string, number or boolean) next to the args array.

Multiple token types are allowed by specifying an array, e.g. "droptoken": [ "string", "number" ].

Read more about Tokens.

Example

/app.json

"actions": [
  {
    "id": "my_action",
    "droptoken": "number"
  }
]

Special arguments

If your card is an instance of ActionCard a special property duration can be provided which allows users to add a duration to the Flow card. If a user provides this argument to the Flow card it will be passed to the card handler as an argument named duration in milliseconds.

Note: duration: true has precedence over an argument with name: duration as they are both provided as arguments to the same handler. It is advised to not mix these.

Example

/app.json

"actions": [
  {
    "id": "run_animation",
    "duration": true
  }
]

/app.js

const myAction = this.homey.flow.getActionCard('run_animation');
myAction.registerRunListener(async (args, state) => {
  if (args.duration != null) {
    // do something with the duration (e.g. run an animation for duration milliseconds)
  }

  return true;
});

Optional arguments

By default all Flow card arguments are required however if you want to allow an argument to be optional you can set the required property to false. If an argument is not required and is not provided by the user it may be undefined in your Flow card run handler.

Example

/app.json

"args": [
  {
    "type": "text",
    "name": "optional_text",
    "required": false
    "placeholder": {
      "en": "When I am not specified the Flow can still be saved..."
    },
    "title": {
      "en": "My optional argument"
    }
  }
]

Subscribing for argument changes

It might be useful to know when a trigger has changed. For example a Twitter app that triggers on a specific hashtag might run a search on that hashtag.

/app.js

const myAction = this.homey.flow.getActionCard('my_action');

myAction.on('update', () => {
  this.log('update');

  myAction.getArgumentValues()
    .then(args => {
      // args is [{
      //   "my_arg": "user_value"
      // }]
    });
});