Arguments

An argument is an input field in a Flow card that the user can fill in.

List of arguments

Text

"type": "text"

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

Attributes

Example

/app.json

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

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

Example

/app.json

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

/app.js

let myAction = new Homey.FlowCardAction('my_action');
  myAction
    .register()
    .registerRunListener(( args, state ) => {
      // ...
    })
    .getArgument('my_autocomplete')
    .registerAutocompleteListener(( query, args ) => {
      return Promise.resolve([
        {
          icon: 'https://path.to/icon.svg', // or use "image: 'https://path.to/icon.png'" for non-svg icons.
          name: 'Item name',
          description: 'Optional description',
          some_value_for_myself: 'that i will recognize when fired, such as an ID'
        },
        {
          // ...
        }
      ]);
    })

Number

"type": "number"

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

Attributes

Example

/app.json

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

Range

"type": "range"

A slider with a minimum and maximum value.

Attributes

Example

/app.json

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

Date

"type": "date"

Date input (presented in dd-mm-yyyy)

Attributes

Example

/app.json

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

Time

"type": "time"

Time input (presented in HH:mm)

Attributes

Example

/app.json

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

Dropdown

"type": "dropdown"

A dropdown list with pre-defined values

Attributes

Example

/app.json

"args": [
  {
    "type": "dropdown",
    "name": "my_dropdown",
    "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 device will appear in the sidebar (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

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"
  }
]

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 = new FlowCardAction('my_action');
myAction.register()
  .on('update', () => {
    this.log('update')

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

  });