MiTextFormField

The MiTextFormField component is a stateful Flutter widget that creates a customizable text input field, leveraging Flutter's TextFormField for form handling and validation. It offers various styling and validation options.

Overview

MiTextFormField simplifies the creation of styled and validated text input fields in Flutter applications. It provides parameters for labels, styling (colors, borders, font size), input type, and validation rules, all configurable through JSON. This component is ideal for forms, data input screens, and any UI element requiring user text input with validation.

Component Name: textField

JSON key: "component": "textField".

Parameters

The MiTextFormField component offers customization through these JSON parameters, in addition to the base styling parameters inherited from MiStatelessWidget:

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable
label	String	String	Label: The label text displayed for the text field.	null	Yes
labelBehavior	String	String	Label Behavior: Defines how the label is displayed. Options: "hide", "separate", "inline". "inline": label inside the field, "top": label above the field, "hide": no visible label.	"inline"	Yes
fontSize	num	double	Font Size: Font size of the text in the input field and the label (if inline).	15.0	Yes
value	String	String	Value: Initial value of the text field. Can be used to pre-populate the field or, more importantly, bind it to application state data using state variable placeholders (e.g., "${STATE_KEY}").	null	Yes
valueType	String	String	Value Type: Specifies the expected data type of the input. Options: "double", "int". If set, validation will check if the input is a valid number of the specified type.	null	Yes
keyboardType	String	TextInputType	Keyboard Type: Defines the type of keyboard displayed to the user. Valid options are: "none", "text", "multiline", "visiblePassword", "emailAddress", "number", "phone", "url", "datetime". See Flutter's TextInputType documentation for details on each type. Defaults to "text".	"text"	Yes
fillColor	String	Color	Fill Color: Background color of the text field. Accepts Flutter color names or hex codes.	Theme's default fill color	Yes
roundBorders	bool	bool	Round Borders: If true, the text field will have fully rounded borders (pill-shaped). Overrides borderRadius.	false	Yes
borderRadius	num	double	Border Radius: Corner radius of the text field's border. Ignored if roundBorders is true.	8.0	Yes
borderColor	String	Color	Border Color: Color of the text field's border in the normal (unfocused) state. Accepts Flutter color names or hex codes. Defaults to theme's "outline" color or Colors.black.	Theme's "outline" color or Colors.black	Yes
focusBorderColor	String	Color	Focus Border Color: Color of the text field's border when it is focused. Accepts Flutter color names or hex codes. Defaults to theme's "accent" color or Colors.black.	Theme's "accent" color or Colors.black	Yes
isRequired	bool	bool	Is Required: If true, the text field is marked as required, and validation will fail if it's left empty.	false	Yes
validationRegex	String	String	Validation Regex: A regular expression string used for input validation. If provided, the input will be validated against this regex.	null	Yes
validationMessage	String	String	Validation Message: Custom error message to display if the input fails validation (either required or regex validation).	"Invalid [label or value]!"	Yes
enabled	bool	bool	Enabled: If true, the text field is enabled and editable. If false, it's disabled and non-editable (greyed out).	true	Yes
onChangedAction	dynamic	dynamic	On Changed Action: JSON Action to be executed when the text field's value changes. Typically used to update state or trigger other actions based on user input.	null	Yes
maxLines	int	int	Max Lines: Maximum number of lines for a multiline text field. Defaults to 1 for a single-line field.	1	Yes
padding	List<num>	EdgeInsets	Inner Padding: Sets padding within the text field container. Inherited from MiStatelessWidget.	null	Yes
margin	List<num>	EdgeInsets	Outer Margin: Defines the margin surrounding the text field widget. Inherited from MiStatelessWidget.	null	Yes
alignment	String	AlignmentGeometry	Alignment: Specifies how the text field should be aligned within its parent. Inherited from MiStatelessWidget.	"topLeft"	Yes
color	String	Color	Background Color: Background color of the text field's container (not the input field itself). Inherited from MiStatelessWidget.	null	Yes
width	num	double	Fixed Width: Defines a fixed width for the text field component. Inherited from MiStatelessWidget.	null	Yes
height	num	double	Fixed Height: Defines a fixed height for the text field component. Inherited from MiStatelessWidget.	null	Yes

Note:

• Data Binding with value Parameter: The value parameter is crucial for data binding. By setting the value to a state variable placeholder like "${STATE_KEY}", the text field's initial value and subsequent changes can be directly linked to your application's state management. This enables dynamic updates and data synchronization.
• State Variable Placeholders ($): Parameters like label and value support state variable placeholders using the $ symbol (e.g., "${STATE_KEY}"). These placeholders are resolved at runtime by the DataUtil.getValue method to fetch values from the application's state.
• Label Behavior: The labelBehavior parameter offers visual control over the label's placement relative to the input field. "inline" (default) places the label inside the input field as a hint, "top" positions it above the field, and "hide" removes the visible label (useful when the context is clear).
• Value Type and Validation: Setting valueType to "int" or "double" enables automatic validation to ensure the user enters a valid number of the specified type. Combined with isRequired and validationRegex/validationMessage, you can create robust input validation.
• On Changed Action: The onChangedAction is triggered whenever the text field's value changes. This is often used to update the application state in real-time as the user types, or to perform actions like filtering lists based on input.
• Styling Inheritance: MiTextFormField inherits styling and layout parameters like padding, margin, alignment, color, width, and height from MiStatelessWidget, ensuring consistent styling across your application.

Example JSON Configuration

Example:

{
    "component": "textField",
    "value": "${DELIVERY_MSG}",
    "label": "Delivery Details",
    "validationMessage": "Please enter a valid msg",
    "isRequired": true
}

Explanation of Example:

• component: "textField": Identifies this as a MiTextFormField component.
• value: "${DELIVERY_MSG}": Data Binding: This is the key part. The value parameter is set to "${DELIVERY_MSG}". This binds the text field's value to the state variable DELIVERY_MSG. The text field will initially display the value of DELIVERY_MSG from the application state, and any changes in the text field will update this state variable (due to the onChanged behavior of TextFormField in the underlying implementation).
• label: "Delivery Details": Sets the label for the text field.
• validationMessage: "Please enter a valid msg": Sets a custom validation error message.
• isRequired: true: Makes the "Delivery Details" field mandatory.