Homey Apps SDK
📖 Apps SDK Reference🌍 Web API🛠 Developer Tools
  • Welcome to the Apps SDK documentation 👋
  • The Basics
    • Getting Started
      • Homey CLI
    • App
      • Manifest
      • Internationalization
      • Permissions
      • Persistent Storage
    • Drivers & Devices
      • Pairing
        • System Views
          • Devices List
          • Add Devices
          • OAuth2 Login
          • Credentials Login
          • Pincode
          • Loading
          • Done
        • Custom Views
      • Capabilities
      • Energy
      • Settings
      • Best practices
        • Lights
        • Window coverings
        • Battery status
    • Flow
      • Arguments
      • Tokens
    • Widgets
      • Settings
      • Styling
      • Debugging
  • Wireless
    • Wi-Fi
      • Discovery
    • Bluetooth LE
    • Z-Wave
    • Zigbee
    • 433 MHz
    • Infrared
    • Matter
  • Cloud
    • OAuth2
    • Webhooks
  • App Store
    • Publishing
    • Guidelines
    • Verified Developer
    • Updating
  • Advanced
    • Custom Views
      • App Settings
      • Custom Pairing Views
      • HTML & CSS Styling
    • Web API
    • Images
    • LED Ring
    • Homey Compose
  • Guides
    • Homey Cloud
    • Breaking Changes
    • Tools
      • Bluetooth LE
      • Zigbee
      • TypeScript
    • Using ESM in Homey Apps
  • Upgrade Guides
    • Homey v6.0.0
    • Upgrading to SDK v3
      • Zigbee Apps
    • Device Capabilities
Powered by GitBook
On this page
  • Creating an App Settings page
  • Example
  • Settings View API
  • Homey.ready()
  • Homey.get( [String name,] Function callback )
  • Homey.set( String name, Mixed value, Function callback )
  • Homey.unset( String name, Function callback )
  • Homey.on( String event, Function callback )
  • Homey.api( String method, String path, Mixed body, Function callback )
  • Homey.alert( String message, Function callback )
  • Homey.confirm( String message, Function callback )
  • Homey.popup( String url[, Object opts] )
  • Homey.openURL( String url )
  • Homey.__( String key [, Object tokens] )

Was this helpful?

  1. Advanced
  2. Custom Views

App Settings

App Settings allow you to add custom HTML pages, that users can view to modify your app's settings. App Settings can be used for global configuration parameters for your app.

PreviousCustom ViewsNextCustom Pairing Views

Last updated 8 months ago

Was this helpful?

A Homey App can save settings that are persistent across reboots. These settings can be accessed from anywhere in your app through . You can also create a page where users can update the App Settings.

Custom app setting views are not allowed on Homey Cloud. Any information your app might need to function should be asked for when pairing a device. Read the documentation for more information.

/app.js
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const username = this.homey.settings.get('username');
    // ...
  }
}

module.exports = App;

Creating an App Settings page

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.

Example

/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>
    <header class="homey-header">
      <h1 class="homey-title" data-i18n="settings.title">
        <!-- This will be filled with the translated string with key 'settings.title'. -->
      </h1>
      <p class="homey-subtitle" data-i18n="settings.subtitle">
        <!-- This field will also be translated -->
      </p>
    </header>

    <fieldset class="homey-form-fieldset">
      <legend class="homey-form-legend">My Settings</legend>

      <div class="homey-form-group">
        <label class="homey-form-label" for="username">Username</label>
        <input class="homey-form-input" id="username" type="text" value="" />
      </div>
      <div class="homey-form-group">
        <label class="homey-form-label" for="password">Password</label>
        <input class="homey-form-input" id="password" type="password" value="" />
      </div>
    </fieldset>

    <button id="save" class="homey-button-primary-full">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"
  }
}

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 path is relative to your app's API endpoint. The third argument body is optional, and null can be provided to ignore it. For example:

/settings/index.html
<script type="text/javascript">
  // 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);
  });
</script>

Homey.alert( String message, Function callback )

Show an alert dialog.

Homey.confirm( String message, Function callback )

Show a confirm dialog. 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] )

Below is a simple example to save a username & password. Learn more about

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 in the .

ManagerSettings
Custom Pairing Views
HTML usage and CSS styling.
internationalization guide