What are settings?

Settings are bits of data that you can set via the widgets admin interface and usually represent the configuration of the app. These might include API keys for authentication, etc.

You can design settings under the “Settings” tab of a widget.

Types of setting

Settings are split into three categories; targets, backend and non-backend settings. A description for each is as follows:

• Targets – Where the widget will appear in Deskpro, e.g. “Ticket” makes the app appear in the ticket sidebar

• Non-backend – settings that are generally not secret and can be accessed via the frontend of the widget, via an event context

• Backend – these settings are generally sensitive in nature, like secret keys for an API. Backend settings are not available in the frontend of a widget and are merged with requests sent via the apps proxy. We’ll talk about backend settings in the proxy part of this guide

Managing Settings

To design settings for a widget, create a new widget or open an existing one in Deskpro admin. Navigate to the “Settings” tab and you’ll see two sections. The first is the “targets” section and below this is where we’ll add our settings.

Firstly, select a target or targets where you’d like the app to appear. Next, start adding some settings by clicking the “Add Setting” button. You’ll now see a settings form for creating or updating individual settings. Here’s a brief explanation of the fields:

• Name – The name of the setting that is both used by the app itself and the app proxy when talking to APIs. The name must not contain spaces or special characters, e.g. “api_key” (required)

• Title – A friendly name for the setting, following the example above this would be “API Key” (required)

• Description – Text that might explain how to use the setting, it’s shown below the setting to prompt users accordingly (optional)

• Type – The type of setting this is, commonly this will be “String”, representing a line of text, API key, etc. (required)

• Required? - Is this setting required in order for the widget to work?

• Backend Only? - When communicating securely with APIs, it is necessary to hide these secret values from the app. “Backend Only” settings are only injected into API requests when using the apps proxy

Once you’ve added a setting you can then provide a value. The value is something we can reference using the setting name in our widget code.

Using Settings

Non-backend settings are passed along with an widget context when listening to app events. In the following example we’ll reference some settings in the app context when listening to the SHOW event.

Create a ticket targeted widget with a non-backend setting named "title", with the type of "String", and give it a value of "Test Value".

In the "body" of your widget code, enter the following:

<script>
  Deskpro.client.onShow(function (context) {
    console.log(context.settings.title);
  });
</script>
 copy

Then, open your browser's dev console and click on your widget in the ticket sidebar of the Deskpro agent interface. You should see the following:

Settings are passed with all context objects after each app event.