List is a collection data type. It allows multiple values to be stored within the same field. In Table Design, you must configure the List data type with all the values that the field stores. These values will be available for the field in table Datasheet view and in DataPages.

For example, in a Patients table, Allergies may be a List – String data type that is configured with all known allergies. Within an application, a user filling out a New Patients form can select all the allergies that pertain to them from the provided options.

There are three List data types:

  • List - String for a maximum of 30 text values of up to 255 characters.
  • List - Number for numeric values of up to 15 digits.
  • List - Date for date or date/time values.

Follow these steps to add a list field in a table:

  1. Open a Table in Design mode.
  2. Click on the last row of the table to add a new field.
  3. Enter a name for the field in the column Name.
  4. In the DataType column, select the List data type for the field from the dropdown. The List options are:
    • List - String
    • List - Number
    • List - Date

    Any previously created Text(255) or Text(64000) fields can be easily converted to a corresponding List data type, and vice-versa, without any changes to existing data in these fields. Also, List data types can be converted from one List type to another. For example, a List – Date can be converted to a List – String without any data loss. However, converting from List – String to List – Number will result in loss of incompatible data if you already have entered values for the field.

  5. On the right pane, under the Options section, you must provide the Values available for the data type. Up to 1000 values are supported. You can enter the values one by one, paste a list into this area, or import from one of your existing tables by clicking the import icon  import_icon.
    A sample table with the list of data types visible.
  6. Use the toolbar at the bottom of the Values list to add, delete, rearrange, or sort the items in the list. The order of Values applies to current and future fields.
  7. Click Save to save your table design.

In table Datasheet view, the List data types are presented as a dropdown of checkboxes. The Values of the List data type are the options in the multi-select checkboxes.

The datasheet view of a table presenting the list data type.

List Fields in Form DataPages

List fields allow you to provide a multi-select list of options in all interfaces designed for entering data, including search forms, submission forms, editable details pages, inline add and edit as well as bulk and grid edit forms.

In DataPage wizards, List fields can be configured as one of the two special form elements:

  • Multi-select listbox
  • Multi-select dropdown

You can enable Show “Select All” for List fields in forms. It adds an option with text that can be localized, to the bottom of the multi-select listbox or multi-select dropdown. This option allows the form user to quickly select or deselect all options.

A sample DataPage with the control to add an option to select all the elements in a list data type selected.

Displaying List Fields in DataPages

All DataPages can display the existing values of List fields. The collection of values can be presented in any of the following formats:

  • Simple list
  • Bulleted list
  • Numbered list
  • Delimited values

A sample DataPage wizard view with visible options for selecting the display of the List data type.

The user view of a DataPage that presents the display of the List data type.

List Fields in Search and Filtering Criteria

The following comparison types are available for List fields in DataPage search forms and predefined criteria, as well as in Datasheet filtering option and in configuring Views:

CriteriaBehavior
EqualOnly records that contain exactly each of the provided values are returned. If a record contains additional values, it does not meet the criteria. For example, if A and B are selected, only records that contain A and B are returned. If a record contains A, B and C - it is not returned.
Not EqualThe exact opposite of Equal. Only records that are not the exact match of the provided values are returned.
ContainsIf “Match all” is selected, records must contain all the selected values. If “Match any” is selected, records must contain at least one of the selected values. In both cases, other values may or may not be present.
Does Not ContainIf “Match all” is selected, records must not contain all the selected values. If “Match any” is selected, records must not contain at least one of the selected values. In both cases, other values may or may not be present.
Is BlankRecords with List field having no values are returned.
Is Not BlankRecords with List field containing at least one value are returned.

 

In search forms, under the Advanced tab, you can choose the behavior for blank list fields. One option is to ignore the criteria, and the other is to return records with blank values in the list field.

Sample logic for a blank list field.

List Fields as Parameters

  • Parameters can now be received or passed to a List Data Type field in DataPages.
  • List Fields can also be passed as parameters on exit of a DataPage or via query string parameters.
  • The Check all values by default option will not be applied if the Receive values or parameters option is enabled.
  • Comma is used as a separator between each list item value.
  • If a list item contains a comma, then the comma value will be encoded.

Sample configuration of a List field that defines the parameters to receive on load and pass on exit.

Additional Notes about List Fields

  • List fields can receive or pass Parameters.
  • Up to 1,000 Values can be defined in each List data type and up to 1000 values can be stored in each List field.
  • All duplicate and blank values are automatically removed when table design is saved.
  • At this time, Lists cannot use lookup tables.
  • Changing the Values of a List does not affect the values in existing records.
  • Each List field can be repeated in up to 15 search or filter criteria in DataPage or View wizards.
  • You can use up to 100 items from a List field in search or filter criteria in DataPage or View wizards. 
  • At this time, List fields cannot be used in Charts, Pivot Tables, Grouping, Aggregations, Formula Fields, Calculated Fields, or as Authentication parameters. Lists will be supported in more areas in future releases.
  • With release 10.0, REST APIs support List fields in Table design and Row manipulation calls (GET, PUT, POST). As a result, you can manage the values of List fields programatically.

Watch the video below to see how to create multi-select dropdowns in Caspio: