Dynamic Lists Overview

Dynamic Lists allow you to populate autocomplete, select, radio, or checkbox form elements with re-useable options or dynamic data from your own API (application program interface) or URL. 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.

Dynamic Lists can also be used for calculations, check out the Calculation article for more information. 

Using Dynamic Lists in a Form

You can use the List tab to add Dynamic Lists to an autocomplete, select, radio, or checkbox form element.

Creating a Dynamic List

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)
• Color: set the color of your button when using radio buttons displayed as buttons (Optional)
• Attributes: filter dynamic lists, they contain their own label and value (Optional)

For more on attributes see the Filtering section below.

Dynamic List JSON Example

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

<httpProtocol>
<customHeaders>
<add name="Access-Control-Allow-Origin" value="*" />

<add name="Access-Control-Allow-Methods" value="GET,OPTIONS,HEAD" />

<add name="Access-Control-Allow-Headers"
value="Accept,Authorization,Content-Type,If-None-Match,X-Amz-Date,X-Amz-Security-Token,X-Api-Key,X-OneBlink-User-Token" />

<add name="Access-Control-Expose-Headers" value="Server-Authorization,WWW-Authenticate" />
</customHeaders>
</httpProtocol>

Filtering

Dynamic 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 has a supervisor. I am able to limit the list by selecting a specific supervisor.

Expected Attributes

• Label: the displayed name for the attributes in the forms builder (Required)
• Value: the value that will be filtered by a separate configured dynamic list (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 includes the users with that supervisor. 

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 three are being displayed.

Code Examples

You can download code examples from our GitHub repo. This code is standard NodeJS, and can be used in a CivicPlus Hosted API, or in your own code to get you started:

• GitHub: Dynamic Form Elements

Setting Attributes

When implementing attributes, you will assign the element which will be used as the filter.

Testing

Once you’ve set up your endpoint in the CivicOptimize 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 dynamic lists results.

When the app is first opened, all dynamic lists 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 lists will be populated directly from your API. If, however, they have no internet connection, the cached version of your dynamic lists will be displayed.

Supporting Articles

• Create a Dynamic List
• Create a Form