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 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.

Adding a List Field to a Table

Follow these steps to add a list field to 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.
  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.

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.

list_wizard

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

list_results

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:

Criteria Behavior
Equal Only 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 Equal The exact opposite of Equal. Only records that are not the exact match of the provided values are returned.
Contains If “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 Contain If “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 Blank Records with List field having no values are returned.
Is Not Blank Records 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.
list_wizard_filter

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 Bridge 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.

Additional Notes about List Fields

  • As of the Caspio Bridge 9.9 release, Lists can now be used in 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.
  • At this time, List fields cannot be used in Charts, Pivot Tables, Grouping, Aggregations, Formula Field, and Calculated Field. Lists will be supported in more areas in future releases.

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