Settings

You can define settings you want users to set for the app. While settings are completely optional, they're simple to set up and use. The framework even auto-generates a settings page for you.

Settings are defined in the manifest.json file with the "parameters" property. The value of the "parameters" property consists of a list of JSON objects representing the settings you want your users to set.

Example:

"parameters": [
  {
    "name": "subdomain",
    "type": "text",
    "required": true,
    "secure": false,
    "default": "yoursubdomain"
  },

  {
    "name": "token",
    "type": "text",
    "required": true,
    "secure": true
  },

  {
    "name": "useSSL",
    "type": "checkbox"
  }
]

See also the Settings sample app on Github.

Setting properties

name

The name of the setting itself.

  "name": "subdomain",

Because you use this value in your app code, make sure you name it appropriately.

required

A boolean value that determines if the user must define the setting or not to install the app. Optional.

  "required": true,
default

Specifies a default value to enter for the setting if the user doesn't specify one. Optional.

  "default": "yoursubdomain",

The default value is used to populate the parameter form field when the admin installs or updates the app. However, it will not take effect for existing parameters where a value has already been set. Don't use the default value as a fallback value. If your app needs a fallback value, implement it in the app.

secure

Use the optional "secure" property when you don't want users to see sensitive information in the parameters when making HTTP requests. Since a lot of apps make HTTP requests to get or set infomation, any agent can view this data in their browser if the setting is not secure.

  "secure": true,

For details, see Secure Settings below.

type

Specifies the control to use on the auto-generated settings page for the user.

  "type": "text",

The framework generates an HTML settings page for users installing the app. The following controls are available:

Type Control
text A single-line input field
password A masked single-line input field
checkbox A single checkbox
url A single-line input field, validated for correct URL syntax
number A single-line input field, validated to include only numbers
multiline A multi-line textarea. User input is limited to 64Kb
hidden A parameter never shown to the user on the settings page

Creating a settings page for users

Users need some kind of user interface to enter the settings when installing the app or to edit the settings after installing the app. The framework generates an HTML settings page based on the settings defined in the manifest file. Setting type controls on the page are rendered in the same order as the settings in the manifest file. Example:

Asterisks indicate required fields.

The maximum length of any setting is 64kB. Exceeding this limit will result in an error.

You can define the setting labels displayed on the generated settings page. The labels and help text in the example above are extracted from the translation file. To translate parameters and add help text, add a parameters property to the app object in your translations files as follows:

{
  "app": {
    "parameters": {
      "subdomain" : { "label": "Subdomain" },
      "token"     : { "label": "Token" },
      "useSSL"    : { "label": "Use SSL?", "helpText": "Use SSL for a secure connection." }
    }
  }
}

Retrieving setting values

You can retrieve and insert setting values in your JavaScript code or your Handlebars templates.

In your app.js code, use the setting('name') framework method to retrieve the value of a setting. Example:

alert( this.setting('subdomain') );

The snippet displays a JavaScript alert box with the value of the subdomain setting.

In your templates, use the {{setting 'name'}} template helper. Example:

<a href="{{setting 'email'}}" />

Updating settings

Sometimes you want to change and save a setting from within the app. This can be achieved by using our REST API.

Note that only admins can update settings, not agents.

requests: {
  saveSettings: function(settings) {
    return {
      url: helpers.fmt('/api/v2/apps/installations/%@.json', this.installationId()),
      type: 'put',
      dataType: 'json',
      contentType: 'application/json',
      data: JSON.stringify({ settings: settings })
    };
  }
},
...
onButtonClick: function() {
  if (this.currentUser().role() !== 'admin') return;

  this.ajax('saveSettings', {
    name: "My installation name",
    some_setting: "new value"
  });
}

Secure settings

When an app makes an AJAX request, the settings for the request can be viewed in the browser console. Some settings may contain sensitive information such as an API key or token. Secure settings are a way to make settings inaccessible to agents when making AJAX requests. In a nutshell, they're a way to insert the values of some settings server-side at the proxy layer.

Secure settings only work in secure requests. They don't work anywhere else in the app.

Secure setting values can't be changed programmatically on the client side. For example, you can't create username and password secure settings, then try (or have the framework try) to base64-encode the values in app.js to do basic authentication. See Securing credentials for basic authentication.

Secure settings are configured in your manifest file. To secure a setting, add a "secure": true property to the parameter that defines your setting. Example:

  "parameters": [
    {
      "name": "token",
      "type": "text",
      "secure": true
    },
    ...

You also need to define a domainWhitelist property for secure requests in the manifest file. Only requests to the white-listed domains will work for secure requests. The whitelist prevents attackers from hijacking the secure setting to reroute it to another domain and using it. Non-secure requests aren't affected by the whitelist.

{
  ...
  "domainWhitelist": ["{{setting.subdomain}}.herokuapp.com"],
  "parameters": [
    {
      "name": "token",
      "type": "text",
      "secure": true
    },
    ...
  ]
}

In your app.js file, add {{setting.name}} placeholders and secure: true to your request definition.

requests: {
  fetchInfo: {
    url: 'http://{{setting.subdomain}}.herokuapp.com/200/ok?token={{setting.token}}',
    type: 'GET',
    dataType: 'json',
    secure: true
  }
},

In the example, both the subdomain and token are hidden from agents. All they can see in the console are the placeholders, not the values. The values are inserted server-side at the proxy layer.

Don't confuse the {{setting.name}} placeholder with the {{setting 'name'}} template helper and the setting('name') framework method used for retrieving setting values. See Retrieving setting values.

For more information on making requests, see Requests.