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 pair-folder in your driver's folder. The names of these files are linked to the pair view id described in /app.json (see the example at Pairing).

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

View API

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

Homey.emit( String event, Mixed data, Function callback )

Emit an event to your app. The function called will be socket.on( String event ) in driver.js.

Example

/drivers/my_driver/pair/start.html

Homey.emit( 'start', { 'foo': 'bar' }, function( err, result ){
    console.log(result); // result is Started!
});

/drivers/my_driver/driver.js

class MyDriver extends Homey.Driver {

    onPair( socket ) {
        socket.on('start', function( data, callback ) {
            // data = { 'foo': 'bar' }
            callback( null, 'Started!' );
        });
    }

}

Homey.on( String event, Function callback )

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

Example

/drivers/my_driver/pair/start.html

Homey.on('hello', function( message, callback ){
    Homey.alert( message ); // Hello to you!
    callback( null, 'Hi!' ) // send something back, (err, result) style
});

/drivers/my_driver/driver.js

class MyDriver extends Homey.Driver {

    onPair( socket ) {
        socket.emit('hello', 'Hello to you!', function( err, result ){
            console.log( result ) // Hi!
        });
    }

}

Homey.setTitle( String title )

Set the window's title.

Example

/drivers/my_driver/pair/start.html

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

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');

Homey.prevView()

Show the previous view.

Homey.nextView()

Show the next view.

Homey.addDevice( Object device, Function callback )

Add a device to Homey. The device object must at least contain the property data and may contain class, capabilities, capabilitiesOptions, mobile, settings and name.

Example

/drivers/my_driver/pair/start.html

Homey.addDevice({
    // the data object should contain only unique properties for the device. So a MAC address is good, an IP address is bad (can change over time)
    data: {
        id: 'ab:cd:ef'
    },

    // the name for this device,
    name: 'My Device',

    // initial settings (optional)
    settings: { 'foo': 'bar' },

    // initial store
    store: { 'x': 'y' }
}, function( err, result ){
    if( err ) return Homey.alert(err);
    Homey.done();
});

Homey.getZone( Function callback )

Get the Zone ID of the active Zone. The function callback returns ( err, zoneId ).

Homey.getOptions( [String viewId], Function callback )

Get the options of a view, or the current view when viewId is omitted. The function callback returns ( err, viewOptions ).

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

Homey.setNavigationClose()

Remove all navigation buttons and show a single Close button.

Homey.done()

Close the pairing window.

Homey.alert( String message[, String icon], Function callback )

Show an alert dialog. The second parameter icon can be null, error, warning or info.

Homey.confirm( String message[, String icon], Function callback )

Show a confirm dialog. The second parameter icon can be null, error, warning or info. The callback's 2nd argument will be true when the user pressed OK.

Homey.popup( String url[, Object opts] )

Show a popup (new window). The object opts can optionally have a width and height property of type number. The default width and height is 400.

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.