Dynamic Options 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 hardcoding 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”, “0”, “-1”, then instead of needing to rely on your team members who are building the forms to get the values correct, you can instead feed them from your API.


Creating a Dynamic Option

Dynamic options are accessed through the “Predefined Elements” item in the side menu, and then the “Dynamic Options” tab.





On this page you will see a list of current Dynamic Options, as well as the ability to create your own by selecting the plus button.


Firstly, you’ll need to name your dynamic 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


Dynamic Options List example:


[
   {
      "value":"1",
      "label":"Pass",
      "colour":"#00DD00"
   },
   {
      "value":"0",
      "label":"Fail",
      "colour":"#DD0000"
   },
   {
      "value":"-1",
      "label":"N/A",
      "colour":"#CCCCCC"
   }
]



Filtering Options


Dynamic option lists 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 dynamic list 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:


Github: Dynamic Form Elements



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.



Using Dynamic Options 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. 





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 dynamic option results.


When the app is first opened, all dynamic options 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 dynamic options will be displayed.