MiListView

The MiListView component is a Flutter widget for displaying a scrollable list of items.

Overview

MiListView extends MiStatelessWidget, and is used to render a dynamic list of UI components, making it ideal for displaying data-driven content. It supports both vertical lists and dynamic height grids using DynamicHeightGridView (if crossAxisCount is greater than 1).

Component Name: listView

JSON key: "component": "listView"

Parameters

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
`listKey`	`String`	`List`	The key (`${key}`) that points to the list of data to be displayed. Each item in this list will be used to generate a child component within the list.	`[]`	Yes	No
`searchable`	`bool`	`bool`	If `true`, filters the list based on a `"match"` key within each list item. Items where `"match"` is `false` will be hidden. This requires a search mechanism that updates the 'match' key in your list data. This functionality is enabled by `MiSearchField`.	`false`	Yes	No
`spacing`	`num` (Number)	`double`	The spacing between items in the list. For single-column lists (`crossAxisCount == 1`), this is the vertical spacing. For grids (`crossAxisCount > 1`), this is the spacing between both rows and columns. Converted from JSON `num` to Flutter `double` using `DoubleHelper.get`.	`20.0`	Yes	No
`childComponent`	`Map`	`Widget`	A JSON configuration defining the component to be rendered for each item in the list. This allows you to dynamically generate UI elements based on the data in your list. The `childComponent` can access the data for the current list item using the `widgetArgs` scope and keys like `${[index]}` (e.g. `${name}` instead of `${items[0].name}`).	`{}`	Yes	Yes
`emptyDisplayText`	`String`	`String`	The text to display when the list is empty (i.e., when `listKey` resolves to an empty list).	`"No items"`	Yes	No
`layoutConfig`	`String`	`String`	A string that specifies how the grid layout should adapt to different screen sizes. It's a series of numbers separated by hyphens (e.g., `"3-2-1"`), representing the number of columns for extra large, large/expanded and medium/compact screens respectively. `"max"` sets it to 1 column regardless of the screen size. See `ResponsiveBuilder.dart` for further details	`"3-1"`	Yes	No
`color`	`String`	`Color`	The background color of the list.	Theme default color	Yes	No
`width`	`num` (Number)	`double`	The width of the list component.	None (Intrinsic width)	Yes	No
`height`	`num` (Number)	`double`	The height of the list component.	None (Intrinsic height)	Yes	No
`padding`	`List<num>`	`EdgeInsets`	Padding to be applied around the list. Expects a list of numbers representing padding values (e.g., `[left, top, right, bottom]` or `[horizontal, vertical]` or `[all]`).	None	Yes	No
`margin`	`List<num>`	`EdgeInsets`	Margin to be applied around the list. Expects a list of numbers representing margin values (e.g., `[left, top, right, bottom]` or `[horizontal, vertical]` or `[all]`).	None	Yes	No
`alignment`	`String`	`AlignmentGeometry`	How the list should be aligned within its allocated space. Accepts alignment keywords like 'topLeft', 'center', 'bottomRight', etc. Refer to Flutter's `Alignment` documentation.	Defaults to `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 MiListView component.
Layout Parameters: width, height, padding, and margin control the size and spacing of the MiListView.
Responsive Layout: The layoutConfig parameter, in conjunction with the ResponsiveBuilder widget, allows the number of columns in the grid to adapt to different screen sizes. The ResponsiveBuilder uses breakpoints defined in ResponsiveBuilder.dart to determine the current LayoutType (compact, medium, expanded, large, extraLarge), and the layoutConfig string defines the number of columns for each layout type.
Data Binding and Widget Arguments: The childComponent has access to the data for the current list item through the widgetArgs. The DataUtil.updateWidgetArgs function is used to create a new widgetArgs map that includes the current item's index, enabling usage of "${name}" instead of "${items[index].name}". Note that "items" must also be declared as listKey value in the MiListView configuration.
Helper Classes: DoubleHelper.get and EdgeInsetsHelper.get are used internally to assist in converting JSON values to the correct Flutter types for spacing, padding and margin respectively.
Empty List Handling: If the listKey resolves to an empty list, the MiListView displays the text specified in the emptyDisplayText parameter.
Searchable List: When searchable is set to true, each item in the resolvedList must have a "match" key (boolean). If the "match" key is set to false, the list item will not be displayed. This functionality is enabled by MiSearchField.

Example JSON Configurations

Example 1: Basic Vertical List with Text Items

{
    "component": "listView",
    "listKey": "${names}",
    "childComponent": {
        "component": "text",
        "text": "${name}"
    }
}

Explanation of Example 1:

component: "listView" - Identifies this configuration as being for a MiListView component.
listKey: "${names}" - Specifies that the data for the list will be retrieved from the state using the key "names". It is assumed that the state contains a list of names. Refer to Key.
childComponent: Defines the component that will be rendered for each item in the list.
- component: "text" - Specifies that a MiText component will be used to display each item.
- text: "${name}" - Sets the text of the MiText component to the value of the "name" key within each item in the names list. This assumes that each item in the names list is an object that has a "name" property.

Example 2: Grid with Dynamic Height Cards

{
    "component": "listView",
    "listKey": "${products}",
    "layoutConfig": "2-1",
    "spacing": 16,
    "childComponent": {
        "component": "card",
        "width": 200,
        "child": {
            "component": "column",
            "children": [
                {
                    "component": "text",
                    "text": "${productName}"
                },
                {
                    "component": "image",
                    "url": "${imageUrl}",
                    "height": 100
                }
            ]
        }
    }
}

Explanation of Example 2:

component: "listView" - Identifies this configuration as being for a MiListView component.
listKey: "${products}" - Specifies that the data for the list will be retrieved from the state using the key "products". It is assumed that the state contains a list of product objects. Refer to Key.
layoutConfig: "2-1" - Configures the grid layout to have 2 columns on larger screens and 1 column on smaller screens. The mEye Framework uses this to manage column counts.
spacing: 16 - Sets the spacing between the grid items to 16 logical pixels. This numeric JSON value is converted to a Flutter double using DoubleHelper.get.
childComponent: Defines the component that will be rendered for each item in the list.
- component: "card" - Specifies that a MiCard component will be used to display each item, providing a visual container.
- width: 200 - Sets the width of each card to 200 logical pixels.
- child: Defines the content of the card using a nested column component.
  - component: "column" - Specifies that a MiColumn component will be used to arrange the card's content vertically.
  - children: Defines the child components of the column.
    - component: "text" - Specifies that a MiText component will be used to display the product name.
    - text: "${productName}" - Sets the text of the MiText component to the value of the "productName" key within each product object.
    - component: "image" - Specifies that an MiImage component will be used to display the product image.
    - url: "${imageUrl}" - Sets the URL of the MiImage component to the value of the "imageUrl" key within each product object.
    - height: 100 - Sets the height of the MiImage component to 100 logical pixels.

Example 3: Searchable List with Filter

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

Explanation of Example 3:

component: "column" - Defines the MiColumn that holds the MiSearchField and MiListView components.
component: "searchField" - Configures the MiSearchField component.
- label: "Search Items" - Sets the label for the search field.
- listKey: "${items}" - Specifies that the search should be performed on the list referenced by the key "items". Refer to Key.
- props: ["name"] - Indicates that the search should be performed on the "name" property of each item in the "items" list. Refer to Key.
component: "listView" - Configures the MiListView component.
- listKey: "${items}" - Specifies that the list should display data from the "items" key.
- searchable: true - Enables search filtering on the list. It will hide the list items if resolvedList[index]?['match'] is false. The list item will be hidden if resolvedList[index]?['match'] is false, which MiSearchField is updating.
- childComponent - Defines the component to render for each list item.
  - component: "text" - Displays the "name" property of each item as text.

Overview​

Parameters​

Example JSON Configurations​

Overview

Parameters

Example JSON Configurations