> For the complete documentation index, see [llms.txt](https://docs.amltd.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amltd.com/dc-works/applets/data-binding.md).
# Data Binding
Learn how to connect fields to Applet records so that information can be displayed, collected, and prepared for database operations.
Data binding creates a connection between a field on an Applet page and a value in an Applet record.
This connection works in both directions:
* When a record is populated, its values appear in the bound fields.
* When a user changes a bound input field, the corresponding value in the working record changes.
The Applet record serves as the connection between the page and the database table.
### Understand the data flow
Fields do not connect directly to database tables. They connect to Applet records.
A typical data flow is:
1. An action loads information from a database table into an Applet record.
2. Bound fields display the values from that record.
3. The user enters or changes information in the bound fields.
4. Data binding places the new values in the working record.
5. An action writes the working record to the database table.
| Data movement | How it occurs | Database changed? |
| ------------------------------- | -------------------------------------------------------------- | ----------------- |
| Database table to Applet record | **Lookup Record**, a table-row action, or another data action | No |
| Applet record to bound field | Data binding | No |
| Input field to Applet record | Data binding | No |
| Applet record to database table | **Add Record**, **Update Record**, or **Update or Add Record** | Yes |
{% hint style="info" %}
The Applet record is the working copy of the data. Data binding displays or changes that working copy. A database action is required to permanently save the information.
{% endhint %}
```mermaid
flowchart LR
D["Database table"] -->|"Lookup or load action"| R["Single Applet record"]
R -->|"Binding displays values"| F["Bound input fields"]
F -->|"User input updates record"| R
R -->|"Add or update action"| D
```
### Single records and list records
DC Works supports records that hold either one entry or multiple entries.
#### Single record
A single record holds one set of values.
For example, an **Equipment record** can hold the values for one equipment item:
* Equipment ID
* Equipment Name
* Category
* Serial Number
* Status
* Location
* Assigned To
* Checkout Date
* Expected Return Date
* Notes
Single records are commonly used to:
* Populate fields with existing information.
* Collect information from input fields.
* Display the details of a selected item.
* Prepare a new record for insertion into a table.
* Hold an existing record while it is being updated.
* Store the result of a lookup.
#### List record
A list record holds multiple entries from the same source.
For example, an **Equipment list** can contain multiple equipment records.
List records are commonly used with:
* Table View fields.
* Chart View fields.
* Table searches.
* Operations that return multiple matching records.
{% hint style="info" %}
Use a single record when working with one item. Use a list record when displaying or processing multiple items.
{% endhint %}
### Bind an input field
Input fields are generally bound to a specific field within a single record.
To bind an Input field:
1. Select the Input field in the Main Workspace.
2. Open **Info** in the Properties Panel.
3. Open **Bound Record**.
4. Select the single record.
5. Select the specific record field that should supply or receive the value.
6. Save the Applet.
For example:
* Bound Record: **Equipment record**
* Record field: **Assigned To**
The same process can be used with other input field types, including:
* Multiline Input.
* Date/Time Input.
* Password Input.
* Checkbox.
* Radio Buttons.
* Slider Input.
* Popup List.
### Configure input capture properties
When **Capture Data** is enabled for an Input field, the field can receive values entered with the keyboard or captured with a barcode scanner.
To configure capture properties:
1. Select the Input field.
2. Open **Capture Properties** in the Properties Panel.
3. Enable **Capture Data**.
4. Select the permitted **Capture Type**.
5. Configure any validation, formatting, default-value, or locking settings.
6. Save the Applet.
Enable Capture Data and configure how the Input field accepts and processes captured values.
#### Capture Type
Use **Capture Type** to determine which input methods the field accepts:
* **Keyboard / Scanner** accepts both keyboard entry and scanner input.
* **Keyboard only** accepts keyboard entry.
* **Scanner only** accepts scanner input.
* **None** prevents the field from capturing keyboard or scanner input.
#### Validate captured values
The following properties control which values the field accepts:
* **Min Length** sets the minimum permitted number of characters.
* **Max Length** sets the maximum permitted number of characters.
* **Allowed Chars** restricts the types of characters that can be entered. Available options include **Any**, **Alpha only**, **Numeric only**, **Alphanumeric only**, and **Numeric Decimal only**.
* **Char Case** preserves the entered capitalization or converts the value to **Upper** or **Lower** case.
Use these settings to help prevent invalid values from being placed in the bound record.
#### Set a default value
Enter a value under **Default Value** when the field should contain an initial value before the user enters or captures other information.
The default value is placed in the field when it is initialized and becomes part of the field’s bound record value.
#### Lock captured values
Enable **Lockable** when users should be able to lock and unlock the Input field.
Enable **Lock On Input** when the field should lock automatically after a value is entered or captured. Use **Lock Background Color** and **Lock Highlight Color** to control how the locked field is displayed.
Locking can help prevent a successfully captured value from being changed or replaced accidentally.
### Populate an input field from a record
A bound input field displays the current value held in its associated record field.
For example, suppose an Input field is bound to:
* Record: **Equipment record**
* Record field: **Status**
If an action loads an equipment item whose Status is **Available** into the Equipment record, the bound Input field displays **Available**.
The record can be populated in several ways, including:
* Looking up a database record with **Lookup Record**.
* Selecting an entry from a Table View and setting the single record.
* Using **Set Record** to assign a value directly to the record.
* Receiving a record from another configured operation.
Once the working record is populated, the associated fields display its values through their bindings.
#### Example: populate equipment details
An Equipment Lookup workflow might operate as follows:
1. The user enters or scans an Equipment ID.
2. A **Lookup Record** action searches the Equipment database table.
3. The matching database entry is placed in **Equipment record**.
4. Bound fields display the equipment’s name, serial number, status, location, and other information.
At this point, the database has not been changed. The Applet is displaying a working copy of the retrieved record.
### Update a record through input fields
When a user changes a bound input field, the new value is placed in the corresponding field of the working record.
For example:
1. **Equipment record.Status** contains **Available**.
2. The bound Status input displays **Available**.
3. The user changes the input to **Checked Out**.
4. **Equipment record.Status** now contains **Checked Out**.
The database table still contains the original value until an appropriate update action runs.
To save the change:
1. Load the existing database record into the single Applet record.
2. Allow the user to change the bound input fields.
3. Run **Update Record**.
4. Confirm that the database table contains the updated information.
{% hint style="warning" %}
Changing a bound field changes the working record, but it does not automatically update the database table. The Applet must run **Update Record** or another appropriate database action.
{% endhint %}
### Add a new record through input fields
Bound input fields can also be used to collect the values for a new database record.
For example, an Applet can use an **Equipment Status record** containing:
* Status
* Description
The page can include two input fields:
* A Status input bound to **Equipment Status record.Status**.
* A Description input bound to **Equipment Status record.Description**.
As the user enters information, data binding places both values in the single working record.
To add the record to the database:
1. Confirm that the working record is empty or ready for a new entry.
2. Enter values in the bound input fields.
3. Select the button configured with **Add Record**.
4. The action inserts the working record into the associated database table.
5. Confirm the new entry from the table’s Records page.
After adding the record, use **Reset Record** and **Clear Fields** when the page should be prepared for another entry.
### Choose the appropriate database action
The required action depends on whether the record is new or already exists.
#### Add Record
Use **Add Record** to insert a new entry into the database table associated with the record.
#### Update Record
Use **Update Record** to save changes to an existing database record.
The existing record must first be loaded into the working record so DC Works can identify which database entry to update.
#### Update or Add Record
Use **Update or Add Record** when the Applet should:
* Update the record if its primary field already exists.
* Add a new record if no matching primary-field value is found.
Detailed instructions for configuring these actions are provided on the next page.
### Bind multiple fields to one record
Multiple page fields can be bound to different fields within the same single record.
For an Equipment Checkout form, the bindings might include:
| Page field | Bound record field |
| -------------------- | ------------------------------------- |
| Equipment ID | Equipment record.Equipment ID |
| Equipment Name | Equipment record.Equipment Name |
| Status | Equipment record.Status |
| Assigned To | Equipment record.Assigned To |
| Checkout Date | Equipment record.Checkout Date |
| Expected Return Date | Equipment record.Expected Return Date |
| Notes | Equipment record.Notes |
When the Equipment record is populated, these page fields display the corresponding values.
When the user changes an enabled input field, the corresponding value in the Equipment record changes. A single database action can then add or update the completed working record.
### Populate a bound field with Set Field
The **Set Field** action can place a value directly into a page field.
If the selected field is bound to a record, the value also becomes part of the working record. The field’s configured Input Actions are also executed.
A Set Field value can come from sources such as:
* Static text.
* Another Applet record.
* An environment record.
* Another supported value source.
This is useful for automatically populating values such as:
* The current user.
* A device identifier.
* A default status.
* The current date or time.
* A value calculated or retrieved earlier in the workflow.
### Required bound fields
For supported input fields, enable **Required Field** when a value must be provided before the associated record can be added or updated.
If a required bound field is empty when the database action runs:
* The operation does not complete.
* The input field is highlighted.
* The user must supply the missing value before trying again.
Required fields help prevent incomplete records from being written to the database table.
### Bind a Table View
A Table View displays multiple entries and must therefore be bound to a list record.
For example:
* Table View Bound Record: **Equipment list**
* Display columns: **Equipment ID**, **Equipment Name**, and **Serial Number**
Binding identifies which list record the Table View displays. A data action such as **Load Table** is still required to populate that list with database records.
A Table View can also be updated after **Add Record** by selecting it as the optional **Field** within the action.
Table Views are only one use of data binding. Most data-entry and detail pages rely primarily on individual fields bound to a single working record.
### Clear bound data
Clearing a page field and resetting a record are related but different operations.
#### Clear Fields
**Clear Fields** empties the selected fields displayed on the page.
#### Reset Record
**Reset Record** clears the values held in the selected working record.
When preparing a form for another entry, both actions may be required:
1. Run **Reset Record** to clear the working data.
2. Run **Clear Fields** to clear the associated page fields.
### Plan bindings before adding actions
Before configuring actions, confirm that:
* The necessary records have been added to the Applet.
* Single records and list records are used appropriately.
* Each input field is bound to the correct record field.
* Fields intended to display existing data use the correct record.
* Required fields are identified.
* The working record contains every value required by the database table.
* The correct add or update operation will be used.
Clear and consistent bindings make actions and conditions easier to configure and troubleshoot.
### Test data binding
After configuring the bindings:
1. Save the Applet.
2. Run it on a device or as a Web App.
3. Load an existing record.
4. Confirm that its values populate the bound fields.
5. Change one or more input values.
6. Run the configured database action.
7. Confirm the result from the database table’s Records page.
8. Test adding a new record separately from updating an existing record.
If a value appears correctly on the page but is not present in the database table, review the configured database action rather than the binding alone.
### Next
Data binding determines how values move between fields and Applet records. Actions determine when records are loaded, changed, cleared, or saved, while conditions determine whether particular actions should run.
Continue to **Actions, Events, and Conditions** to learn how to trigger operations, control their execution order, and create conditional Applet behavior.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.amltd.com/dc-works/applets/data-binding.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.