You are currently viewing the Homey Apps SDK v2 documentation. New apps should use Homey Apps SDK v3 ››

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

Name Type Description Example
placeholder object Text to show without input { "en": "What to say", "nl": "Wat te zeggen" }

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

Name Type Description Example
placeholder object Text to show without input { "en": "What to say", "nl": "Wat te zeggen" }

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

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

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

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

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

Name Type Description Example
placeholder object Text to show without input { "en": "When to ..", "nl": "Wanneer te .." }

Example

/app.json

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

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

Example

/app.json

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

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

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

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

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

  });