`create_linked_list_element`

Admin-only MCP tool.

Create a new Linked List Element in a Formulize form.

Newly created elements appear on the pages of form screens where all other elements in the form already appear. To add a newly created element to a form screen page which only has some existing elements, use the update_form_screen tool.

Overview: Linked elements let the user select from a set of options, that are based on values entered into another form. Most of the standard types of list elements can be implemented as a Linked element.

Important notes:

Linked elements are very powerful tools. They generally work best when pointing to a source element that is the principal identifying element of the entries in the source form. For example, if there is a form called Provinces, and another form called Cities, the Cities form might naturally have a Linked element that points to a Text Box called ‘Name’ in the Provinces form. This way, when entering a new City, the user can select the Province it is in from a dropdown list of Province names, and the two entries will be connected together.
When Linked elements allow a single choice by the user (for example, Radio Buttons, Dropdown Lists, etc), they represent one-to-many relationships between forms. The Linked element is on the ‘many’ side of the relationship. The source element is on the ‘one’ side. This is the most common way to use Linked elements.
Some Linked elements can support multiple selections by the user (for example, Checkboxes, Autocomplete Lists with allowMultipleSelections turned on). These Linked elements will represent many-to-many relationships between forms. For example, if there is a form called Participants, and a form called Activities, the Participants form can have a Linked Checkboxes element that points to a Text Box called ‘Name’ in the Activities form. This way, when entering a new Participant, the user can check the boxes for all the Activities that the person is participating in. This is a more complex situation, and not all Linked element types support multiple selections.

Properties common to all Linked elements:

sourceElement (int or string, the element ID or element handle of an element in another form. The options displayed in this Linked element will be based on the values entered into this source element. Element ID numbers and handles are globally unique, so the form can be determined based on the element reference alone.)

Basic examples:

A Linked element with options drawn from the values entered in element 7 (element IDs are globally unique and so imply a certain form): { sourceElement: 7 }
A Linked element with options drawn from the values entered in the element with handle ‘provinces_name’ (element handles are globally unique as well): { sourceElement: ‘provinces_name’ }

Element: Linked Autocomplete List (autocompleteLinked)

Description: A single-line text box that provides autocomplete suggestions from a set of options based on values entered into another form. 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. Linked Autocomplete Lists can be set to allow multiple selections, with the allowMultipleSelections property. If new values are allowed, the new value will be added as a new entry in the source form, which is very convenient, because otherwise the user would have to go to the other form and enter the value there first.

Properties:

all the common properties for Linked elements, plus:
allowNewValues (optional, a 1/0 indicating if users should be allowed to enter values that are not in the source form already. Default is 0, meaning users can only select from the existing options. Set to 1 to allow users to enter new values, which will be saved as entries in the source form.)
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 inventory items, drawing options from the Item Name element in a separate Inventory form, and allowing new inventory items to be added: { sourceElement: ‘inventory_item_name’, allowNewValues: 1 }
A list of countries with options drawn from the Name element in a separate Countries form, and multiple selections are allowed: { sourceElement: ‘country_name’, allowMultipleSelections: 1 }

Element: Linked Checkboxes (checkboxLinked)

Description: A series of boxes that the user can check to select multiple options. Linked Checkboxes have options drawn from values entered into another form. If multiple selections are not required, use Linked Radio Buttons or a Linked Dropdown instead. In general, Checkboxes are best with 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 Linked 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 linked checkbox element with options drawn from the ‘Name’ element in a ‘Games’ form, and using a delimiter of a space: { sourceElement: “games_name”, delimiter: “space” }
A linked checkbox element with options drawn from the ‘Name’ element in a ‘Games’ form, and using a delimiter of an emdash: { sourceElement: “games_name”, delimiter: “ — “ }

Element: Linked Listbox (listboxLinked)

Description: A box that shows a list of options, allowing users to select one or more options from the list. Options are based on values entered into another form. The user experience with Linked Listboxes is generally poor. Use Linked Autocomplete Lists or Linked Checkboxes instead, unless there’s a specific reason to use a Listbox or the user has specifically requested one.

Properties:

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

Example:

A list of ingredients, drawn from the Name element in an Ingredients form, with only one choice allowed: { sourceElement: ‘ingredients_name’, allowMultipleSelections: 0 }

Properties

Property	Type	Required?	Description
form_id	integer	Required	Required. ID of the form that this will be part of.
type	string (one of: autocompleteLinked, checkboxLinked, listboxLinked, selectLinked)	Required	Required. The type of Linked List Element to create.
caption	string	Required	Required. The label for the Linked List Element as it will appear to users in forms and in lists.
properties	object	Required	Required. Additional configuration settings for the Linked 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.
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 Linked 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 Linked List Element is required to have a value when users fill out the form. Default: false
principal_identifier	boolean	Optional	Optional. Whether the Linked 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 Linked List Element element is disabled (visible but not usable) in the form. Default: false.
handle	string	Optional	This is the internal name, used in the database and in API calls. This is optional and does not normally need to be specified, as the system will determine it automatically from the form title and element caption. If the user specifically requests a handle, use this to force the handle to be a certain value. The system may still modify it for uniqueness, so check the tool result to see the actual handle used in by system. Maximum length is 64 characters.
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. Provide a list of conditions to restrict when the element is displayed; if you omit this property (or provide an empty array) it has no conditions and 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

`create_linked_list_element`

Properties

Getting Started

Professional Services

Help and Documentation