MiSearchField

The MiSearchField component is a Flutter widget that provides a customizable search input field with integrated list filtering, configurable via JSON.

Overview

MiSearchField extends MiStatelessWidget and integrates with MiListView to enable real-time filtering of list data based on user input. It renders a MiTextFormField and automatically triggers a search action on text changes to update which items are visible in an associated MiListView, providing a powerful and flexible search interface.

Component Name: searchField

This component is identified in your JSON configurations using the component key set to searchField.

Parameters

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
label	String	String	The label text displayed for the search field.	null	Yes	No
labelBehavior	String	String	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	No
fontSize	num (Number)	double	Font size of the text in the input field and the label (if inline).	15.0	Yes	No
fillColor	String	Color	Background color of the search field. Accepts Flutter color names or hex codes.	Theme's default fill color	Yes	No
borderRadius	num (Number)	double	Corner radius of the search field's border.	8.0	Yes	No
borderColor	String	Color	Color of the search 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	No
focusBorderColor	String	Color	Color of the search 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	No
listKey	String	String	The key (${key}) that points to the list of data to be searched. This key should match the listKey parameter of the MiListView that displays the search results.	null	Yes	No
props	List	List<String>	A list of string values to search within each item of the list identified by listKey. Refer to listKey for the list to be searched. Each value inside props should represent a field of the list's item.	null	Yes	No
nestedListKey	String	String	The key (${key}) that points to a nested list within each item of the main list (identified by listKey). Used for searching within nested data structures.	null	Yes	No
nestedProps	List	List<String>	A list of string values to search within each item of the nested list (identified by nestedListKey). These should be fields of the nested list's items. Refer to nestedListKey for the list to be searched.	null	Yes	No
color	String	Color	The background color of the search field's container (not the input field itself).	null	Yes	No
width	num (Number)	double	Defines a fixed width for the search field component.	null	Yes	No
height	num (Number)	double	Defines a fixed height for the search field component.	null	Yes	No
padding	List<num>	EdgeInsets	Sets padding within the search field container.	null	Yes	No
margin	List<num>	EdgeInsets	Defines the margin surrounding the search field widget.	null	Yes	No
alignment	String	AlignmentGeometry	Specifies how the search field should be aligned within its parent.	"topLeft"	Yes	No

Note:

• Inherited Parameters: color, alignment, width, height, padding, and margin are inherited parameters from MiStatelessWidget and allow for styling and positioning of the MiSearchField component.
• Integration with MiListView: MiSearchField is designed to work in conjunction with MiListView. The listKey, props, nestedListKey, and nestedProps parameters must be configured correctly to target the data displayed in the associated MiListView. Ensure that the listKey in both components refers to the same data source.
• State Management and searchInList: When the text in the MiSearchField changes, the searchInList method within the MiCubit is called. This method filters the list data based on the searchTerm, props, nestedListKey, and nestedProps. The searchInList updates the "match" property within each item of the list, which the MiListView uses to determine which items to display.
• Data Binding and Keys: The listKey, props, nestedListKey, and nestedProps support state variable keys using the ${} notation. Ensure to include ${} in the JSON configuration.
• Helper Classes: DoubleHelper.get is used internally to assist in converting JSON values to the correct Flutter types for fontSize and borderRadius respectively.

Example JSON Configurations

Example 1: Basic Search Field with Single-Level Data

{
    "component": "column",
    "children":[
        {
            "component": "searchField",
            "label": "Search Items",
            "listKey": "${items}",
            "props": ["name"]
        },
        {
            "component": "listView",
            "listKey": "${items}",
            "childComponent": {
                "component": "text",
                "text": "${name}"
            }
        }
    ]
}

Explanation of Example 1:

• component: "column" - This indicates that the configuration is for a MiColumn component, which arranges its children vertically.
• children - This key contains a list of configurations for the child components of the MiColumn.
  • The first child component is a MiSearchField.
    • component: "searchField" - Identifies the component as a MiSearchField.
    • label: "Search Items" - Sets the label for the search field.
    • listKey: "${items}" - Specifies that the MiSearchField will filter the list data referenced by the state key "items". This data is assumed to be a list of items. items key MUST be enclosed in $\{}.
    • props: ["name"] - Indicates that the MiSearchField will search within the "name" field of each item in the "items" list.
  • The second child component is a MiListView.
    • component: "listView" - Identifies the component as a MiListView.
    • listKey: "${items}" - Specifies that the MiListView will display the list data referenced by the state key "items". The same listKey as the MiSearchField, ensuring both components operate on the same data. items key MUST be enclosed in $\{}.
    • childComponent - Configuration for the component that will be rendered for each item in the list.
      • component: "text" - Indicates that each item in the list will be rendered using a MiText component.
      • text: "${name}" - Sets the text of the MiText component to the value of the "name" key within each item in the "items" list.

Example 2: Search Field with Nested Data

{
    "component": "column",
    "children": [
        {
            "component": "searchField",
            "label": "Search Products",
            "listKey": "${categories}",
            "props": ["categoryName"],
            "nestedListKey": "${products}",
            "nestedProps": ["productName"]
        },
        {
            "component": "listView",
            "listKey": "${categories}",
            "childComponent": {
                "component": "column",
                "children": [
                    {
                        "component": "text",
                        "text": "Category: ${categoryName}"
                    },
                    {
                        "component": "listView",
                        "listKey": "${products}",
                        "childComponent": {
                            "component": "text",
                            "text": "Product: ${productName}"
                        }
                    }
                ]
            }
        }
    ]
}

Explanation of Example 2:

• component: "column" - This indicates that the configuration is for a MiColumn component, which arranges its children vertically.
• children - This key contains a list of configurations for the child components of the MiColumn.
  • The first child component is a MiSearchField.
    • component: "searchField" - Identifies the component as a MiSearchField.
    • label: "Search Products" - Sets the label for the search field.
    • listKey: "${categories}" - Specifies that the MiSearchField will filter a list of categories. categories key MUST be enclosed in $\{}.
    • props: ["categoryName"] - Indicates that the MiSearchField will search within the "categoryName" field of each item in the "categories" list.
    • nestedListKey: "${products}" - Specifies that each category has a nested list of products, accessed via the "products" key. products key MUST be enclosed in $\{}.
    • nestedProps: ["productName"] - Indicates that the MiSearchField will also search within the "productName" field of each item in the nested "products" list.
  • The second child component is a MiListView.
    • component: "listView" - Identifies the component as a MiListView.
    • listKey: "${categories}" - Specifies that the MiListView will display a list of categories. categories key MUST be enclosed in $\{}.
    • childComponent - Configuration for the component that will be rendered for each item in the list.
      • component: "column" - Arranges category and product information vertically.
      • children - A list of configurations for the child components of the MiColumn.
        • A MiText component to display the category name.
          • component: "text" - Renders the category name.
          • text: "Category: ${categoryName}" - Sets the text to "Category: " followed by the value of the "categoryName" key within each item in the "categories" list.
        • A nested MiListView to display the products within each category.
          • component: "listView" - Renders a list of products for each category.
          • listKey: "${products}" - Specifies that this list will display the list of products associated with the category, products key MUST be enclosed in $\{}.
          • childComponent - Configuration for the component that will be rendered for each item in the nested list (each product).
            • component: "text" - Renders the product name.
            • text: "Product: ${productName}" - Sets the text to "Product: " followed by the value of the "productName" key within each item in the "products" list.