Custom Views

Most drivers will suffice using the provided templates. Some advanced drivers however can benefit from creating their own views.

The front-end consists of .html files in the /drivers/<driver_id>/pair-folder. The name of the file is the view ID, as id described in /app.json.

The front-end has a few Homey-specific JavaScript functions available. They are documented here.

Back-end API

The session property passed in onPair can control the front-end programmatically.

/drivers/my_driver/driver.js

class MyDriver extends Homey.Driver {
  async onPair(session) {
    // Show a specific view by ID
    await session.showView('my_view');

    // Show the next view
    await session.nextView();

    // Show the previous view
    await session.prevView();

    // Close the pair session
    await session.done();

    // Received when a view has changed
    session.setHandler('showView', async function (viewId) {
      console.log('View: ' + viewId);
    });
  }
}

Front-end API

The following methods are available at the front-end to communicate with the back-end. The Homey object is globally available.

Emit an event

Homey.emit( String event, Mixed data ): Promise<any>

Emit an event to your app. The function called will be the one registered by session.setHandler( String event, Function callback ) in driver.js.

Example

/app.json

{
  "id": "com.athom.example",
  // ...
  "drivers": [
    {
      "id": "my_driver",
      // ...
      "pair": [
        {
          "id": "my_view"
        }
      ]
    }
  ]
}

/drivers/my_driver/pair/my_view.html

Homey.emit('my_event', { foo: 'bar' }).then(function (result) {
  console.log(result); // result is: Hello!
});

/drivers/my_driver/driver.js

class MyDriver extends Homey.Driver {
  async onPair(session) {
    session.setHandler('my_event', async function (data) {
      // data is { 'foo': 'bar' }
      return 'Hello!';
    });
  }
}

Receive an event

Homey.on( String event, Function callback )

Listen to a message from your app. You can trigger this function from your app by calling session.emit().

Example

/drivers/my_driver/pair/start.html

Homey.on('hello', function (message) {
  Homey.alert(message); // Hello to you!
  return 'Hi!'; // send a reply back to the pairing session

  // you can return a promise if you need to do some async
  // work before replying to the message.
});

/drivers/my_driver/driver.js

class MyDriver extends Homey.Driver {
  async onPair(session) {
    session.setHandler('showView', async (viewId) => {
      if (viewId === 'start') {
        const data = await session.emit('hello', 'Hello to you!');
        console.log(data); // Hi!
      }
    });
  }
}

Set a Title

Homey.setTitle( String title )

Set the window's title.

Example

/drivers/my_driver/pair/start.html

Homey.setTitle(Homey.__('pair.title_searching'));

Show a View

Homey.showView( String viewId )

Navigate to another view. The parameter viewId should be an ID as specified in your app's /app.json.

/drivers/my_driver/pair/start.html

Homey.showView('list_devices');

Previous View

Homey.prevView()

Show the previous view.

Next View

Homey.nextView()

Show the next view.

Get the current view

Homey.getCurrentView()

Returns the current view ID.

Create a device

Homey.createDevice( Object device ): Promise<Object>

Create a device with the properties in device.

The device object must at least contain the property data and may contain name, icon, class, capabilities, capabilitiesOptions, store and settings.

Example:

/drivers/my_driver/pair/start.html

Homey.createDevice({
  // The name of the device that will be shown to the user
  name: 'My Device',

  // The data object is required and should contain only unique properties for the device.
  // So a MAC address is good, but an IP address is bad (can change over time)
  data: {
    id: 'abcd',
  },

  // Optional: The store is dynamic and persistent storage for your device
  store: {
    // For example store the IP address of your device
    address: '127.0.0.1',
  },

  // Optional: Initial device settings that can be changed by the user afterwards
  settings: {
    pincode: '1234',
  },
})
  .then(function (result) {
    Homey.done();
  })
  .catch(function (error) {
    Homey.alert(err);
  });

Get current zone

Homey.getZone(): Promise<string>

Get the Zone ID of the active Zone. The promise resolves to the zone id.

Get view options

Homey.getOptions( [String viewId] ): Promise<Object>

Get the options of a view, or the current view when viewId is omitted. The promise resolves to the viewOptions of the specified view.

View options may be added to a view by specifying an options object in the /app.json.

Set navigation close

Homey.setNavigationClose()

Remove all navigation buttons and show a single Close button.

Close the pair session

Homey.done()

Close the pairing window.

Alert dialog

Homey.alert( String message[, String icon] ): Promise<void> Show an alert dialog. The second parameter icon can be null, error, warning or info.

Confirm dialog

Homey.confirm( String message[, String icon] ): Promise<boolean> Show a confirm dialog. The second parameter icon can be null, error, warning or info.

The promise will resolve to true when the user pressed OK.

Popup

Homey.popup( String url ) Show a popup with a remote website.

Internationalisation

Homey.__( String key [, Object tokens] )

Translate a string programmatically. The first argument key is the name in your /locales/__language__.json. Use dots to get a sub-property, e.g. settings.title. The optional second argument tokens is an object with replacers. Read more about translations at Internationalization.

Show the loading overlay

Homey.showLoadingOverlay()

Shows the loading overlay.

Hide the loading overlay

Homey.hideLoadingOverlay()

Hides the loading overlay.

Get a view's store value

Homey.getViewStoreValue( String viewId, String key ): Promise<any>

Get's a view's store value. Promise will resolve to the requested value.

Set a view's store value

Homey.setViewStoreValue( String viewId, String key, Mixes value): Promise<void>

Set a view's store value.

Example

/drivers/my_driver/pair/start.html

var devicesArray = [
  {
    name: 'My Device',
    data: {
      id: 'abcd',
    },
  },
];
Homey.setViewStoreValue('add_devices', 'devices', devicesArray);