MiDatePicker

The MiDatePicker component is a stateless Flutter widget for selecting dates using a dialog, configurable via JSON.

Overview

The MiDatePicker component is designed to provide a user-friendly interface for date selection within forms and other UI elements. It leverages Flutter's showDatePicker to present a date selection dialog to the user.

Component Name: datePicker

JSON key: "component": "datePicker".

Parameters

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
format	String	String	Date Format: Specifies the date format used for display. Accepted values include: "dd/MM/yyyy", "M/d/yyyy", and "yyyy/MM/dd". This format also influences the locale of the date picker dialog.	"dd/MM/yyyy"	Yes	No
label	String	String	Input Label: The text label associated with the date picker input field. This label provides context and description for the input.	null	Yes	No
labelBehavior	String	String	Label Behavior: Determines how the label is displayed. "inline" positions the label as a placeholder or floating label within the input field. "top" places the label above the input field.	"inline"	Yes	No
fontSize	num	double	Font Size: The font size for the label and the input text within the date picker. Converted from JSON num to Flutter double using DoubleHelper.get.	15.0	Yes	No
value	String	String	Value Key: Key used for data binding. This key links the selected date to a specific state variable. When a date is selected, the state variable associated with this key is updated with the selected date in ISO 8601 format (YYYY-MM-DD). Refer to value Key.	null	Yes	No
valueType	String	String	Value Type: This parameter is not directly used in MiDatePicker's buildWidget method in the provided code. It might be intended for future use or for validation logic not currently implemented in this component version.	null	Yes	No
keyboardType	String	TextInputType	Keyboard Type: Defines the type of keyboard to display when the input field is focused. While MiDatePicker primarily uses a dialog, this parameter might be relevant for accessibility or alternative input methods. Values are converted to TextInputType using TextInputTypeHelper.get.	null	Yes	No
fillColor	String	Color	Fill Color: Background color of the date picker input field. Resolved using the theme system.	null	Yes	No
roundBorders	bool	bool	Round Borders: If true, the input field will have fully rounded ends (pill-shaped).	false	Yes	No
borderRadius	num	double	Border Radius: Border radius for the corners of the input field, applied when roundBorders is false. Converted from JSON num to Flutter double using DoubleHelper.get.	8.0	Yes	No
borderColor	String	Color	Border Color: Color of the input field's border in the normal (unfocused) state. Resolved using the theme system.	Theme's outline color or Colors.black	Yes	No
focusBorderColor	String	Color	Focus Border Color: Border color when the input field is focused. Resolved using the theme system.	Theme's accent color or Colors.black	Yes	No
isRequired	bool	bool	Required Field: If true, indicates that date selection is mandatory. An asterisk (*) may be displayed to indicate this requirement, and validation will enforce date selection.	false	Yes	No
validationRegex	String	String	Validation Regex: Regular expression string used to validate the input value. If provided, the input value will be tested against this regex.	null	Yes	No
validationMessage	String	String	Validation Error Message: Custom error message to display if the input value fails validation against validationRegex.	null	Yes	No
enabled	bool	bool	Enabled State: If true (default), the date picker is enabled and interactive. If false, it is disabled and non-interactive.	true	Yes	No
onChangedAction	Map	Map	On Changed Action: JSON configuration for an action to be executed when a date is selected. This allows triggering application logic upon date selection.	null	Yes	No
padding	List<num>	EdgeInsets	Padding: Padding around the MiDatePicker component. Inherited from MiStatelessWidget.	null	Yes	No
margin	List<num>	EdgeInsets	Margin: Margin around the MiDatePicker component. Inherited from MiStatelessWidget.	null	Yes	No
alignment	String	AlignmentGeometry	Alignment: Alignment of the MiDatePicker component within its parent. Inherited from MiStatelessWidget.	"topLeft"	Yes	No
color	String	Color	Color: Background color of the container for the MiDatePicker component. Inherited from MiStatelessWidget.	null	Yes	No
width	num	double	Width: Fixed width of the MiDatePicker component. Inherited from MiStatelessWidget.	null	Yes	No
height	num	double	Height: Fixed height of the MiDatePicker component. Inherited from MiStatelessWidget.	null	Yes	No

Note:

• Inherited Parameters: padding, margin, alignment, color, width, and height are inherited from MiStatelessWidget, providing standard layout and styling options. These parameters control the outer appearance and positioning of the MiDatePicker.
• Date Selection Flow: Tapping the MiDatePicker input field triggers the display of a native Flutter date picker dialog. Upon date selection and confirmation, the chosen date is displayed in the input field, formatted according to the format parameter. Simultaneously, if the value parameter is provided, the selected date in ISO 8601 format (YYYY-MM-DD) is used to update the state variable associated with the value key.
• Data Binding (value Key): The value parameter is crucial for integrating the MiDatePicker with the application's state management. By providing a key (e.g., ${DATA_KEY.DATE}), the selected date is automatically bound to and updates the corresponding state variable. Ensure that the key is correctly defined in your application's state for proper data binding. Refer to Key for state variable access.
• Validation: The MiDatePicker supports client-side validation through the isRequired, validationRegex, and validationMessage parameters, ensuring data integrity before submission or further processing. The isRequired parameter enforces mandatory date selection, while validationRegex allows for custom validation rules using regular expressions.
• Helper Classes: DoubleHelper.get, EdgeInsetsHelper.get, TextInputTypeHelper.get, and AlignmentHelper.get are used internally to convert JSON values to their respective Flutter types (double, EdgeInsets, TextInputType, Alignment). These helper classes ensure type safety and proper conversion of configuration values.
• Action Handling (onChangedAction): The onChangedAction parameter enables triggering actions when a date is selected. This facilitates dynamic behavior and integration with application logic.

Example JSON Configurations

Example 1: Basic Date Picker with Label and Value Binding

{
  "component": "datePicker",
  "label": "Select Date",
  "value": "${formData.eventDate}"
}

Explanation of Example 1:

• component: "datePicker" - Specifies that this JSON configuration is for a MiDatePicker component.
• label: "Select Date" - Sets the label of the date picker input field to "Select Date". This label will be displayed inline within the input field as the default labelBehavior is "inline". See the "labelBehavior" parameter description in the table for label placement options.
• value: "${formData.eventDate}" - Binds the selected date to the state variable accessed by the key formData.eventDate. When a date is chosen, the state associated with formData.eventDate will be updated with the selected date in ISO 8601 format (YYYY-MM-DD). Refer to the "value" parameter description in the table and Key note for details on data binding and state variable keys.

Example 2: Styled and Validated Date Picker with Top Label and Action

{
  "component": "datePicker",
  "label": "Appointment Date",
  "labelBehavior": "top",
  "value": "${appointmentData.date}",
  "format": "M/d/yyyy",
  "isRequired": true,
  "roundBorders": true,
  "borderColor": "grey",
  "focusBorderColor": "blueAccent",
  "margin": [0, 10],
  "onChangedAction": {
    "actionType": "customAction"
  }
}

Explanation of Example 2:

• component: "datePicker" - Identifies this as a MiDatePicker component configuration.
• label: "Appointment Date" - Sets the label text to "Appointment Date". See the "label" parameter description in the table for details on label customization.
• labelBehavior: "top" - Positions the label above the input field, enhancing readability when the input field is filled. See the "labelBehavior" parameter description in the table for label placement options.
• value: "${appointmentData.date}" - Binds the selected date to the state variable accessed by the key appointmentData.date. The selected date will update the state associated with this key. Refer to the "value" parameter description in the table and Key note for details on data binding and state variable keys.
• format: "M/d/yyyy" - Sets the date display format to Month/Day/Year (e.g., 12/25/2024). This also affects the locale of the date picker dialog. See the "format" parameter description in the table for supported formats.
• isRequired: true - Makes the date selection mandatory. The component will visually indicate this requirement and enforce validation. See the "isRequired" parameter description in the table for details on required field validation.
• roundBorders: true - Applies fully rounded borders to the input field for a distinct visual style. See the "roundBorders" parameter description in the table for border styling options.
• borderColor: "grey" - Sets the border color to grey in the normal state, customizing the appearance. See the "borderColor" parameter description in the table for border color customization.
• focusBorderColor: "blueAccent" - Changes the border color to "blueAccent" when the input field is focused, providing visual feedback. See the "focusBorderColor" parameter description in the table for focus border customization.
• margin: [0, 10] - Adds a top and bottom margin of 10 logical pixels for vertical spacing. See the "margin" parameter description in the table and MiStatelessWidget.dart.
• onChangedAction: Specifies the action to be executed.