`update_list_element`

Admin-only MCP tool.

Update an existing List Element in a Formulize form.

Overview: List elements let the user select from a set of options. There are several types of list elements: radio buttons, checkboxes, dropdown lists, etc.

Important notes:

When altering options in a list, consider whether any data that users have entered into the form already, should be altered as well to match the new options. See the updateExistingEntriesToMatchTheseOptions property below. This is only relevant when options are being changed. If options are being re-organized, or new ones added, or old ones deleted, you do not need to update existing entries to match.

Properties common to all List elements:

options (array, list of options for the element)
selectedByDefault (optional, an array containing a value or values from the options array that should be selected by default when the element appears on screen to users. If this is not specified, no options will be selected by default. The values in this array should match what’s in the options array, even if the databaseValues property is being used.)
databaseValues (optional, an array of values to store in the database, if different from the values shown to users. This is not normally used, but if the application would require a coded value to be stored in the database, for compatibility with other code or other systems, this is useful. Must be the same length as the options array, and each value in this array corresponds by position to the value in the options array. If not provided, the values in the options array will be used as the values stored in the database.)
updateExistingEntriesToMatchTheseOptions (optional, a 1/0 indicating if existing entries should be updated to match the new options. Default is 0. Set this to 1 when an element has existing options that are being changed, and then every record in the database where the old first option was selected, will change to having the new first option selected, and every record where the old second option was selected will change to the new second option, etc. This works when changing storage formats from numbers to text, and when just changing wording of options. Any kind of change is supported. This is useful when correcting typos and changing wording, such as switching an option from ‘Backwards’ to ‘Back’, or when making refinements, such as an element with options ‘S’, ‘M’, ‘L’ that is changing to ‘Small’, ‘Medium’, ‘Large’. Sometimes changes to options are just reordering the existing options, or adding new options, or removing removing options, and in those cases this setting should be left unspecified or set to 0.)

Basic examples:

A list of toppings for pizza: { options: [ ‘pepperoni’, ‘mushrooms’, ‘onions’, ‘extra cheese’, ‘green peppers’, ‘bacon’ ] }
A list of toppings for pizza, with ‘pepperoni’ and ‘mushrooms’ selected by default: { options: [ ‘pepperoni’, ‘mushrooms’, ‘onions’, ‘extra cheese’, ‘green peppers’, ‘bacon’ ], selectedByDefault: [ ‘pepperoni’, ‘mushrooms’ ] }
A list of movies: { options: [ ‘2001: A Space Odyssey’, ‘WarGames’, ‘WALL-E’, ‘The Matrix’, ‘Inception’, ‘Children of Men’ ] }
A list of movies, with ‘Children of Men’ selected by default: { options: [ ‘2001: A Space Odyssey’, ‘WarGames’, ‘WALL-E’, ‘The Matrix’, ‘Inception’, ‘Children of Men’ ], selectedByDefault: [ ‘Children of Men’ ] }
A list of states where the value stored in the database is the shortform code, but the user sees the full state name: { options: [ ‘California’, ‘Delaware’, ‘Hawaii’, ‘Maine’, ‘New York’, ‘Vermont’ ], databaseValues: [ ‘CA’, ‘DE’, ‘HI’, ‘ME’, ‘NY’, ‘VT’ ] }
A list of chocolate flavours, with both milk chocolate and dark chocolate selected by default: { options: [ ‘milk chocolate’, ‘dark chocolate’, ‘white chocolate’, ‘orange chocolate’ ], selectedByDefault: [ ‘milk chocolate’, ‘dark chocolate’ ] }
A list of chocolate flavours, with both milk chocolate and dark chocolate selected by default, and numeric values stored in the database instead of text: { options: [ ‘milk chocolate’, ‘dark chocolate’, ‘white chocolate’, ‘orange chocolate’ ], databaseValues: [ 11, 22, 33, 44 ], selectedByDefault: [ ‘milk chocolate’, ‘dark chocolate’ ] }
A list which previously had the options ‘No’, ‘Maybe’, ‘Yes’, and is now being updated with new options, that should replace the old options in every entry people have made in the form already: { options: [ ‘Never’, ‘Sometimes’, ‘Always’ ], updateExistingEntriesToMatchTheseOptions: 1 }

Element: Autocomplete List (autocomplete)

Description: A single-line text box that provides autocomplete suggestions from a predefined list of options as the user types. The user can select one of the suggested options, or if the allowNewValues property is enabled then the user can enter a new value that is not found in the list. Autocomplete Lists can be set to allow multiple selections, with the allowMultipleSelections property. Autocomplete Lists are good for a large number of options that would be too many for a Dropdown List, Radio Buttons, or Checkboxes. For a small number of predefined options, use Radio Buttons or Dropdown Lists, or use Checkboxes if selecting multiple options must be possible.

Properties:

all the common properties for List elements, plus:
allowNewValues (optional, a 1/0 indicating if users should be allowed to enter values that are not in the predefined list of options. Default is 0, meaning users can only select from the predefined options. Set to 1 to allow users to enter new values.)
allowMultipleSelections (optional, a 1/0 indicating if multiple selections should be allowed. For Autocomplete Lists, the default is 0. Set to 1 to allow multiple selections.)

Examples:

A list of cutlery and flatware, allowing multiple selections: { options: [ ‘fork’, ‘knife’, ‘spoon’, ‘plate’, ‘bowl’, ‘cup’ ], allowMultipleSelections: 1 }
A list of authors, allowing new values to be entered so that users don’t have to select from the predefined options: { options: [ ‘Isaac Asimov’, ‘Arthur C. Clarke’, ‘Philip K. Dick’, ‘Frank Herbert’ ], allowNewValues: 1 }

Element: Checkboxes (checkbox)

Description: A series of boxes that the user can check to select one or more options. Checkboxes are best used when there are a small number of options (generally less than 7) and you want the user to see all the options at once, without having to open a dropdown list or type in an autocomplete box. For a single choice, use Radio Buttons instead, and for a large number of options use an Autocomplete List with multiple selections allowed.

Properties:

all the common properties for List elements, plus:
delimiter (optional, a string indicating how to separate the items in the list. Valid values are ‘linebreak’, ‘space’, or a custom string, which can include any valid HTML. Default is ‘linebreak’, however this can be altered in the Formulize preferences. It is not normally necessary to specify this property, unless you want to override the default for the system, or use a custom string.)

Examples:

A checkbox element with the options ‘A’, ‘B’ and ‘C’, with a delimiter of a space: { options: [‘A’, ‘B’, ‘C’], delimiter: ‘space’ }
A checkbox element with the options ‘A’, ‘B’ and ‘C’, with a delimiter of a slash: { options: [‘A’, ‘B’, ‘C’], delimiter: ‘ / ‘ }

Element: Listbox (listbox)

Description: A box that shows a list of options, allowing users to select one or more options from the list. The user experience with Listboxes is generally poor. Use Radio Buttons, Checkboxes, Dropdown Lists, or Autocomplete Lists instead, unless there’s a specific reason to use a Listbox or the user has speciically requested one.

Properties:

all the common properties for List elements, plus:
allowMultipleSelections (optional, a 1/0 indicating if multiple selections should be allowed in the listbox. For Listboxes, the default is 1. Set to 0 to allow only a single selection.)

Example:

A list of favorite colors, and only one choice is allowed: { options: [ ‘red’, ‘blue’, ‘green’, ‘yellow’, ‘purple’, ‘orange’ ], allowMultipleSelections: 0 }

Element: Radio Buttons (radio)

Description: A list of options where the user can select only one choice. Radio buttons are best used when there are a small number of options (generally less than 7) and you want the user to see all the options at once, without having to open a dropdown list or type in an autocomplete box.

Properties:

all the common properties for List elements, plus:
delimiter (optional, a string indicating how to separate the items in the list. Valid values are ‘linebreak’, ‘space’, or a custom string, which can include any valid HTML. Default is ‘linebreak’, however this can be altered in the Formulize preferences. It is not normally necessary to specify this property, unless you want to override the default for the system, or use a custom string.)

Examples:

A Radio Button element with options ‘Red’, ‘Green’ and ‘Blue’, with ‘Green’ selected by default, and with a delimiter of a space: { options: [‘Red’, ‘Green’, ‘Blue’], selectedByDefault: [‘Green’], delimiter: ‘space’ }
A Radio Button element with options ‘Red’, ‘Green’ and ‘Blue’, with ‘Green’ selected by default, and with a delimiter of a tilde with an HTML span around it so it can be styled with CSS: { options: [‘Red’, ‘Green’, ‘Blue’], selectedByDefault: [‘Green’], delimiter: “~” }

Element: Dropdown List (select)

Description: A dropdown list of options where the user can select one choice. Dropdown lists are best used when there are a moderate number of options (generally between 5 and 20) and you want to save space on the form. For a small number of options, use Radio Buttons instead, and for a large number of options use an Autocomplete List.

Properties:

all the common properties for List elements

Element: Yes/No Radio Buttons (yn).

Description: A pair of radio buttons, one for Yes and one for No.

Properties:

defaultvalue (int, a 1 for ‘Yes’ and a 0 for ‘No’, if omitted or empty, no default is set)

Examples:

A Yes/No radio button that has no default value: { }
A Yes/No radio button that defaults to No: { defaultvalue: 0 }
A Yes/No radio button that defaults to Yes: { defaultvalue: 1 }

Properties

Property	Type	Required?	Description
element_identifier	string or integer	Required
caption	string	Optional	Optional. The new label for the List Element as it will now appear to users in forms.
properties	object	Optional	Optional. Updated configuration settings for the List Element. The available properties depend on the element type. See the tool description for examples of what properties are needed for different element types. Use the get_form_details tool to see all the element types for the existing elements.
column_heading	string	Optional	Optional. The heading to use at the top of a column in lists of entries. If not specified, the caption will be used. Some captions are long and descriptive, and a shorter heading would be more appropriate for in a list of data.
help_text_for_users	string	Optional	Optional. A longer description or help text for the List Element, shown to users filling out the form. This is NOT an internal notes field, this content appears as part of the element.
required	boolean	Optional	Optional. Whether the List Element is required to have a value when users fill out the form. Default: false
principal_identifier	boolean	Optional	Optional. Whether the List Element is the principal identifying element for entries in this form. Principal identifiers are used in various places in Formulize to represent an entry. The Principal Identifier would typically be a ‘Name’ text box or other element that unique identifies the entry. Each form can only have one Principal Identifier. If a form has a Principal Identifier, and another element is created or updated with this value set to true, the existing Principal Identifier will be replaced with the new one. Default: false.
disabled	boolean	Optional	Optional. Whether the List Element element is disabled (visible but not usable) in the form. Default: false.
display	boolean	Optional	Optional. Whether the List Element is displayed in the form or hidden. Default: true.
display_conditions	array of object	Optional	Optional. A given form entry must meet these conditions in order for this element to be displayed; otherwise it is not shown. Each condition includes an element, an operator, a value, and a ‘type’ flag indicating the logical set the condition belongs to: ‘match-all’ or ‘match-one-or-more’. Multiple match-all conditions are joined with a logical AND operator, and multiple match-one-or-more conditions are joined with a logical OR operator. Only include this property when you intend to change the conditions: omit it entirely to leave any existing conditions unchanged; provide the list of conditions to set or replace them; or provide an empty array ([]) to remove all conditions so the element is always displayed. When setting conditions based on linked elements, do not use foreign keys as values, and instead use the readable value which this tool understands automatically. Use the special value “{BLANK}” (without quotes) to match blank values. Examples: [ { “element”: “status”, “operator”: “=”, “value”: “Approved”, “type”: “match-all” } ] [ { “element”: “award_value”, “operator”: “>”, “value”: “500”, “type”: “match-all” }, { “element”: “award_year”, “operator”: “=”, “value”: “2026”, “type”: “match-all” } ] Match size 40 pants OR green pants: [ { “element”: “pant_size”, “operator”: “=”, “value”: “40”, “type”: “match-one-or-more” }, { “element”: “pant_color”, “operator”: “=”, “value”: “green”, “type”: “match-one-or-more” } ] Match incomplete orders that are due before today, and are going to either Canada or Mexico: [ { “element”: “order_state”, “operator”: “=”, “value”: “incomplete”, “type”: “match-all” }, { “element”: “order_due_date”, “operator”: “<”, “value”: “{TODAY}”, “type”: “match-all” }, { “element”: “order_destination”, “operator”: “=”, “value”: “Canada”, “type”: “match-one-or-more” }, { “element”: “order_destination”, “operator”: “=”, “value”: “Mexico”, “type”: “match-one-or-more” } ] Do not use foreign key values with linked elements; use the readable value instead: Incorrect: [ { “element”: “assigned_judge”, “operator”: “LIKE”, “value”: “509”, “type”: “match-all” } ] Correct: [ { “element”: “assigned_judge”, “operator”: “LIKE”, “value”: “Wapner”, “type”: “match-all” } ]
placement	string	Optional	The canonical position of the element in the form. This order is used on every form screen page that this element has been added to (newly created elements are automatically added to all pages that currently have all existing elements; to add an element to a page that has only some existing elements, use the update_form_screen tool). Use “top” to make this element the first element in the form, use “bottom” to make this element the last (which is the default for new elements), or use an element handle to place this element immediately after that element (based on the live state of the form at the time of this specific request; re-fetch get_form_details first if you need to see the current element order). On updates, omit this to leave the current position unchanged.
data_type	string	Optional	Optional. The MariaDB data type to be used for the field in the database where this data will be stored. The system will default to text in most cases, but will set smart defaults if the type is specifically a number box or a linked element storing foreign keys, etc. Generally this does not need to be specified, but can be used if the user has specifically stated that a certain data type must be used for a given element. Valid types are: text, int(x), decimal(x,y), date, datetime, time, char(x), varchar(x). For int(x), the x is the number of digits to display in MariaDB when showing the number. For decimal(x,y), the x is the total number of digits, and y is the number of digits after the decimal point. For char(x) and varchar(x), the x is the maximum number of characters to store.

← Back to the MCP reference

Getting Started

Professional Services

The Formulize development team provides:
hosting, training, tech support, and consulting

Getting Started

Professional Services

Help and Documentation

`update_list_element`

Properties

Getting Started

Professional Services

Help and Documentation