Custom configuration view

In the Configuration section we have already introduced a very easy way to add configuration to a plug-in. It is as simple as adding a couple of field definitions to the plug-in manifest. The advantages of this approach are obvious: It is easy to setup, it uses the Haiilo Home native UI/UX to render the form fields and it is perfectly embedded in the Haiilo Home environment. But above all else it pushes the complexity of configuration management away from the plug-in. Thus, you can even build simple plug-ins without the need of a plug-in backend or any persistence layer whatsoever.

While this approach is very flexible it also has its limits. If you are aiming for a complex configuration view or rich features like auto-complete search, a generically rendered configuration will not suffice. That's why you can also implement your very own configuration view.

Providing a custom configuration view

You can define a custom configuration view by providing a configUrl in the entry point section of your manifest file. The URL should point to a standalone configuration screen that will then be rendered in the settings modal of your plug-in. Haiilo Home takes care of the details and will only show the screen to users with the given permissions. However, if you want to store configuration data on your side you need to re-evaluate the permissions of the user.

📘

config and configUrl are mutually exclusive

Please note that you can choose between a dynamically rendered configuration screen (via config field definitions) or a custom configuration view (via configUrl) - but not both.

The configuration view follows the exact same principles as the plug-in itself. It first needs to be initialized to setup a working communication channel to Haiilo Home. Simply call the init method of our plug-in adapter and provide true as first argument. This tells the adapter to initialize a configuration view (and not a plug-in view). You should also observe the dimensions of your configuration view by calling the adapter's observeHeight method. Again, call the method and provide true as first argument to tell the adapter to observe the height of a configuration view.

Saving configuration data

The plug-in adapter provides you with yet another useful method called onSave. It lets you register a callback that is executed every time Haiilo Home initiates a save request, i.e. every time a user clicks the save button in the settings modal. It provides you with another callback, which is to be called when you have finished validating the configuration view on your side. The inner callback can be called with three possible values:

• JSON: You can provide a JSON object or array to the callback. The data will then be transmitted back to Haiilo Home and stored as local configuration for your plug-in. Haiilo Home takes care about the lifecycle of the data and will automatically remove it if the plug-in instance is deleted. The data will be provided to your plug-in view via the initialization message.
• true: Simply provide true to let Haiilo Home know that the settings modal can be closed successfully. Choose this option if you do not want to store any configuration data on Haiilo Home side, but on your plug-in back end. The callback lets Haiilo Home know that your asynchronous saving action has been completed and Haiilo Home can close the modal window.
• false: Provide false to indicate an error. This can be a communication error to your plug-in backend or a validation error in your configuration view. Haiilo Home will abort the save request, the user has initiated and keep the modal window open. Note that Haiilo Home does not display any errors, because your plug-in knows the error better than Haiilo Home does. A useful error message is expected within your configuration view.

Sounds complicated? It really is not. Let's take a look at a simple example that saves a config value on Haiilo Home side:

pluginAdapter.onSave(done => {
  const config = // retrieve values from config form
  const valid = // determine config validity
  if (valid) {
    done(config); // successful save
  } else {
    done(false); // abort save
  }
});