App Settings - Homey Apps SDK v2 Documentation

App Settings

A Homey App can save settings that are persistent across reboots. Additionally, the folder /userdata/ is writable for your app.

Refer to ManagerSettings to learn more about changing settings programmatically. This article is about creating a front-end for your app's settings.

Usage

To create a settings view, create a folder named /settings/ in your app's root, and create a new file named index.html in it.

Include the following script in your <head>:

/settings/index.html

<head>
  <!-- ... -->
  <script type="text/javascript" src="/homey.js" data-origin="settings"></script>
</head>

Next, add a function called onHomeyReady:

/settings/index.html

<script type="text/javascript">
function onHomeyReady( Homey ){
	// ...

	Homey.ready();
}
</script>

The first argument of onHomeyReady will be a Homey instance, which can be used to communicate with Homey.

Finally, call Homey.ready() to show the settings view.

API

`Homey.ready()`

The settings view will be hidden until this method has been called. Use the extra time to make required API calls to prevent flickering on screen.

`Homey.get( [String name,] Function callback )`

Gets a single setting's value when name is provided, or an object with all settings when name is omitted.

`Homey.set( String name, Mixed value, Function callback )`

Sets a single setting's value. The value must be JSON-serializable.

`Homey.unset( String name, Function callback )`

Unsets a single setting's value.

`Homey.on( String event, Function callback )`

Register an event listener for your app's realtime events. System events when modifying settings are: settings.set, settings.unset.

`Homey.api( String method, String path, Mixed body, Function callback )`

Make a call to your App's Web API. The first argument method can be either GET, POST, PUT or DELETE. The second argument body is relative to your app's API endpoint. The third argument body is optional, and null can be provided to ignore it. For example:

// make a PUT call to /api/app/com.your.app/hello
Homey.api('PUT', '/hello', { 'foo': 'bar' }, function( err, result ) {
	if( err ) return Homey.alert(err);
});

`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.openURL( String url )`

Show a new window.

`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.

Example

Below is a simple example to save a username & password.

/settings/index.html

<!doctype html>
<html>
    <head>

    	<!-- The '/homey.js' script must be included in your settings view to work -->
	    <script type="text/javascript" src="/homey.js" data-origin="settings"></script>

    </head>
    <body>

        <h1 data-i18n="settings.title">
        	<!--
        	This field will automatically be filled by a translated string with key 'settings.title'.
        	Read more about translations at Internationalization.
        	-->
        </h1>
        <p data-i18n="settings.subtitle">
        	<!--
        	This field will also be translated
			-->
        </p>

        <fieldset>
            <legend>My Settings</legend>

            <div class="field row">
                <label for="username">Username</label>
                <input id="username" type="text" value="" />
            </div>
            <div class="field row">
                <label for="password">Password</label>
                <input id="password" type="password" value="" />
            </div>

        </fieldset>

        <button id="save" class="right">Save changes</button>

        <script type="text/javascript">

        // a method named 'onHomeyReady' must be present in your code
        function onHomeyReady( Homey ){

	        // Tell Homey we're ready to be displayed
            Homey.ready();

            var usernameElement = document.getElementById('username');
            var passwordElement = document.getElementById('password');
            var saveElement = document.getElementById('save');

            Homey.get('username', function( err, username ) {
	           if( err ) return Homey.alert( err );
			   usernameElement.value = username;
	        });

            Homey.get('password', function( err, password ) {
	           if( err ) return Homey.alert( err );
			   passwordElement.value = password;
	        });

	        saveElement.addEventListener('click', function(e) {

	            Homey.set('username', usernameElement.value, function( err ){
		            if( err ) return Homey.alert( err );
	            });
	            Homey.set('password', passwordElement.value, function( err ){
		            if( err ) return Homey.alert( err );
	            });

	        });
        }
        </script>

    </body>
</html>

/locales/en.json

{
  "settings": {
    "title": "My Settings Page",
    "subtitle": "Please log in"
  }
}