Text Field Controller

A Text Field Controller is a special variable type that manages user input in text fields. It allows you to programmatically set, clear, or manipulate the text content of input fields, enabling dynamic form interactions and validation.

Supported Widgets

The Text Field Controller can be used with:

• Text Form Field

When to Use

Use a Text Field Controller when you need to:

• Programmatically set or clear text field values

• Pre-fill forms with data

• Reset forms after submission

• Implement autocomplete or suggestions

• Validate and modify input programmatically

• Synchronize text across multiple fields

Creating a Text Field Controller

1. Navigate to Variables in your project

2. Click Add Variable

3. Select Text Field Controller as the type

4. Give it a descriptive name (e.g., emailController, searchController)

Binding to Widgets

Text Form Field Example

Text Form Field:
  Controller: ${emailController}
  Label: "Email Address"
  On Change:
    Set State: email = ${currentValue}

Controller Methods

Use the Control Object action to invoke these methods on the controller.

setValue

Sets the text field's value programmatically.

Parameter	Type	Description
text	String	The string to set as the field value

Example Use Cases:

• Pre-fill with saved data: text: ${savedEmail}

• Set default value: text: "[email protected]"

• Copy from another field: text: ${otherFieldValue}

When to Use:

• Loading saved form data

• Implementing autocomplete

• Copying values between fields

• Setting default values

---

clear

Clears the text field, removing all content.

No parameters required.

Example Use Cases:

• Reset form after submission

• Clear search field

• Remove invalid input

When to Use:

• After successful form submission

• Reset button functionality

• Clearing invalid input

---

Common Use Cases

1. Pre-filling Forms with Saved Data

Load previously saved data into form fields.

Setup:

Variable: nameController (Text Field Controller)
Variable: emailController (Text Field Controller)

Variable: savedProfile (JSON)
Value: {
  "name": "John Doe",
  "email": "[email protected]"
}

Text Form Field:
  Controller: ${nameController}
  Label: "Name"

Text Form Field:
  Controller: ${emailController}
  Label: "Email"

Implementation:

On Page Load:
  Control Object:
    Object: ${nameController}
    Method: setValue
    Arguments:
      text: ${savedProfile.name}
  
  Control Object:
    Object: ${emailController}
    Method: setValue
    Arguments:
      text: ${savedProfile.email}

2. Reset Form After Submission

Clear all form fields after successful submission.

Variable: nameController (Text Field Controller)
Variable: emailController (Text Field Controller)

On Submit Button Click:
  API Call: submitForm
    On Success:
      Control Object:
        Object: ${nameController}
        Method: clear
      
      Control Object:
        Object: ${emailController}
        Method: clear
      
      Toast:
        Message: "Form submitted successfully!"

3. Search Field with Clear Button

Implement a search input with a clear button.

Variable: searchController (Text Field Controller)
Variable: searchQuery (String)
Initial Value: ""

Text Form Field:
  Controller: ${searchController}
  Hint: "Search..."
  On Change:
    Set State: searchQuery = ${currentValue}

Icon Button (Clear):
  Visible: ${gt(searchQuery.length, 0)}
  On Click:
    Control Object:
      Object: ${searchController}
      Method: clear
    Set State: searchQuery = ""

4. Autocomplete Implementation

Set field value when user selects from suggestions.

Variable: addressController (Text Field Controller)
Variable: suggestions (List)

Text Form Field:
  Controller: ${addressController}
  On Change:
    API Call: fetchAddressSuggestions

ListView (Suggestions):
  Data Source: ${suggestions}
  
  Item:
    On Click:
      Control Object:
        Object: ${addressController}
        Method: setValue
        Arguments:
          text: ${currentItem.fullAddress}

5. Copy Value to Another Field

Copy content from one field to another.

Variable: billingAddressController (Text Field Controller)
Variable: shippingAddressController (Text Field Controller)

CheckBox:
  Label: "Same as billing address"
  On Change:
    If ${isEqual(currentValue, true)}:
      Control Object:
        Object: ${shippingAddressController}
        Method: setValue
        Arguments:
          text: ${billingAddress}

6. Format Input on Blur

Format input when user leaves the field.

Variable: phoneController (Text Field Controller)

Text Form Field:
  Controller: ${phoneController}
  On Blur:
    Control Object:
      Object: ${phoneController}
      Method: setValue
      Arguments:
        text: ${formatPhoneNumber(currentValue)}

Best Practices

• One controller per field: Each Text Form Field should have its own controller

• Use descriptive names: Name controllers after the field purpose (emailController, passwordController)

• Store values separately: Use a separate variable to store the field value for easier access in logic

• Clear on success: Clear form fields after successful submission for better UX

• Validate before setting: Validate data before using setValue to avoid setting invalid values

• Handle empty states: Check for null or undefined before setting values

• Provide feedback: Show toast or message after clearing or setting values programmatically

Common Patterns

Load Saved Data

On Page Load:
  Control Object:
    Object: ${fieldController}
    Method: setValue
    Arguments:
      text: ${savedData.fieldValue}

Clear All Fields

On Reset Button Click:
  Control Object:
    Object: ${field1Controller}
    Method: clear
  
  Control Object:
    Object: ${field2Controller}
    Method: clear

Clear After Success

On API Success:
  Control Object:
    Object: ${inputController}
    Method: clear
  
  Toast:
    Message: "Success!"

Set from Selection

On List Item Click:
  Control Object:
    Object: ${fieldController}
    Method: setValue
    Arguments:
      text: ${currentItem.value}

Conditional Clear

On Cancel Button Click:
  If ${hasUnsavedChanges}:
    Show Dialog:
      Message: "Discard changes?"
      On Confirm:
        Control Object:
          Object: ${fieldController}
          Method: clear

Troubleshooting

Controller Not Working

• Ensure the controller variable is properly created

• Check that the controller is bound to the Text Form Field using ${controllerName}

• Verify you're using the correct controller reference

Value Not Updating in UI

• Ensure the Text Form Field is bound to the controller

• Check that the setValue action is being triggered

• Verify the text value is a valid string

Clear Not Working

• Confirm the controller is properly bound

• Check that the clear method is being invoked correctly

• Ensure no other actions are resetting the value immediately after

Related Documentation

• Text Form Field - Text input widget reference

• Control Object Action - Invoke controller methods

• String Operations - String manipulation functions

• Variables Overview - Learn about all variable types