Option Sets are a way for you to populate form selections automatically, from a list of items returned from your APIs.
For example, you may have a list of supervisors that a user can select from a form. Instead of hard-coding those users into the form, you could feed this select box from an API that is designed to return the latest list of users.
Additionally, this feature also allows you to have more control over the values being passed to your backend system when a form is submitted.
For example, you may have a radio button set that allows a user to select “Pass”, “Fail”, or “N/A”, but your backend expects the values of these options to be “1”, “-1”, “0”, then instead of needing to rely on your form builders to get the values correct, you can instead feed them from your API.
Creating an Option Set
Option sets can be found by clicking on the “Options Sets” on the left side menu.
On this page you will see a list of currently configured Option sets, as well as the ability to create your own by selecting the plus button.
Firstly, you’ll need to name your option set. Keep in mind this is the name the user building the form will see when they add this to the form (more on this below), so we’d recommend keeping this short but descriptive.
For the source you can either select a OneBlink Hosted API, or choose to enter your own custom URL.
Expected Payload
Your API should return a payload in JSON format. It should be an array, with each item allowing four keys:
value: the value that will be passed in the submission data — Required
label: the label that will be displayed to the user in the form — Required
colour: set the colour of your button when using radio buttons displayed as buttons — Optional
attributes: are used to filter dynamic lists, they contain their own label and value — Optional
For more on attributes see Filtering Options below
Option Set example:
[
{
"value":"1",
"label":"Pass",
"colour":"#00DD00"
},
{
"value":"0",
"label":"Fail",
"colour":"#DD0000"
},
{
"value":"-1",
"label":"N/A",
"colour":"#CCCCCC"
}
]Filtering Options
Option sets can also contain attributes. These are used to filter the list based on the inputs of other elements.
For example, I have a list of users and each of those users have a supervisor. I am able to limit the list by selecting a specific supervisor.
Expected Attribute Payload
label: the displayed name for the attributes in the forms builder — Required
value: the value that will be filtered by a separate configured option set — Required
The option set will look like this:
{
value: 'ASmith',
label: 'Alex Smith',
attributes: [
{
'label': supervisor,
'value': 'Lisa Daniels'
},
{
'label': position,
'value': 'Marketing'
}
]
},
{
value: 'JCauthen',
label: 'Mary Johnson',
attributes: [
{
'label': supervisor,
'value': 'Lisa Daniels'
},
{
'label': position,
'value': 'Operations'
}
]
},
{
value: 'AWilliams',
label: 'Alice Williams',
attributes: [
{
'label': supervisor,
'value': 'Liam Jackson'
},
{
'label': position,
'value': 'Sales'
}
]
},
{
value: 'JDavis',
label: 'Jacob Davis',
attributes: [
{
'label': supervisor,
'value': 'Liam Jackson'
},
{
'label': position,
'value': 'Marketing'
}
]
}Now when a supervisor is selected the list will be filtered so that it only include the users with that supervisor. See below:
When no supervisor is selected the entire list is shown. When Supervisor Lisa Daniels is selected the list is filtered to only display users assigned to Lisa.
Multiple attributes
Attributes are an array meaning you can have multiple attributes for the same option.
When adding multiple attributes the options will display if ANY of the attributes are met.
So if we search on the position attribute to each of our users as well as the supervisor we will get the users who have ANY of those attributes.
As you can see, only Alex and Mary have Lisa as their supervisor, but Alex and Jacob are in the Marketing team so all 3 are being displayed.
Download Code Examples
You can download code examples from our GitHub repo. This code is standard NodeJS, and can be used in a OneBlink Hosted API, or in your own code to get you started:
Using Option Sets in a Form
When a team member builds a form, they will now be able to use the predefined options you just created to populate their form.
These will be available for:
Select boxes
Radio buttons
Checkboxes
Autocomplete
When adding one of these field types to the form, in the Options section they will be able to either “Enter My Own”, where they simply add their own options directly into the form builder, or they can choose “Use Predefined.”
When selecting “Use Predefined”, they will be presented with a list of the predefined elements you’ve added. They will see the names of each of the items, which they can simply select.
Attributes
When implementing attributes you will assign the element which will be used as the filter.
Referring back to our Supervisor example you would conditionally base the users on the supervisor element as shown below.
Testing
Once you’ve set up your endpoint in the OneBlink Console, you can click on the Test button. This will test your endpoint to ensure it is returning data in the expected format.
If any errors are found, they’ll be displayed to you for further debugging.
If the test is successful it will return the number of records found, and allow you to view the response details.
Offline Usage
Your app users can often be in either intermittent coverage, or no coverage at all. In these cases your app will continue to operate as usual, using a cached version of your option set results.
When the app is first opened, all option sets in all of your forms will be automatically cached.
The app will work in a “connected first” assumption, where if your user has an internet connection then your options will be populated directly from your API. If, however, they have no internet connection, the cached version of your option sets will be displayed.