MiGroupCard

The MiGroupCard component is a Flutter widget for displaying a titled card containing a list of items, configurable via JSON.

Overview

The MiGroupCard component extends MiStatelessWidget and is used to group a list of items within a card, providing a title and optional buttons. It leverages the MiListView component to display the list and provides parameters for customization, all configurable via JSON.

Component Name: groupCard

JSON key: "component": "groupCard".

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 within the card. This list is retrieved from the application's state managed by the `MiCubit`. Each item in this list will be used to generate a child component within the list. If null, the card renders as empty. Refer to `Key`.	`null`	Yes	No
`spacing`	`num` (Number)	`double`	The spacing between items in the list within the card. Converted from JSON `num` to Flutter `double` using `DoubleHelper.get` .	`20.0`	Yes	No
`searchable`	`bool`	`bool`	If `true`, enables search filtering on the list within the card. Items where `resolvedList[index]?['match']` is `false` will be hidden. Requires an external search mechanism (e.g., `MiSearchField`) to update the `"match"` key in your list data.	`false`	Yes	No
`title`	`String`	`String`	The title text to display at the top of the card.	`null`	Yes	No
`titleColor`	`String`	`Color`	The color of the title text. Accepts Flutter color names or hex codes.	`"t1"` (theme's primary text color)	Yes	No
`titleSize`	`num` (Number)	`double`	The font size of the title text. Converted from JSON `num` to Flutter `double` using `DoubleHelper.get`.	`24.0`	Yes	No
`buttons`	`List`	`List<Widget>`	A list of JSON configurations for buttons to display in the upper-right corner of the card, next to the title. These buttons are typically `MiButton` components and allow for user interactions related to the grouped content.	`null`	Yes	Yes
`childComponent`	`Map`	`Widget`	A JSON configuration defining the component to be rendered for each item in the list within the card. 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. `${items[0].name}`).	`{}`	Yes	Yes
`emptyDisplayText`	`String`	`String`	The text to display when the list within the card 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 card. (Inherited from `MiStatelessWidget`)	Theme default color	Yes	No
`width`	`num` (Number)	`double`	The width of the card component. (Inherited from `MiStatelessWidget`)	None (Intrinsic width)	Yes	No
`height`	`num` (Number)	`double`	The height of the card component. (Inherited from `MiStatelessWidget`)	None (Intrinsic height)	Yes	No
`padding`	`List<num>`	`EdgeInsets`	Padding to be applied around the list within the card. Expects a list of numbers representing padding values (e.g., `[left, top, right, bottom]` or `[horizontal, vertical]` or `[all]`). (Inherited from `MiStatelessWidget`)	None	Yes	No
`margin`	`List<num>`	`EdgeInsets`	Margin to be applied around the card. Expects a list of numbers representing margin values (e.g., `[left, top, right, bottom]` or `[horizontal, vertical]` or `[all]`). (Inherited from `MiStatelessWidget`)	None	Yes	No
`alignment`	`String`	`AlignmentGeometry`	How the card should be aligned within its allocated space. Accepts alignment keywords like 'topLeft', 'center', 'bottomRight', etc. Refer to Flutter's `Alignment` documentation. (Inherited from `MiStatelessWidget`)	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 MiGroupCard.
Data Binding: Parameters listKey, title, titleColor, and emptyDisplayText are bound to the application's state, allowing dynamic updates to the card's content and appearance.
Keys and Data Binding: listKey relies on data binding to access list data from the application's state. This data binding is facilitated by the "$" syntax in the listKey value, linking it to the application's state.
Helper Classes: DoubleHelper.get and EdgeInsetsHelper.get are used internally to assist in converting JSON values to the correct Flutter types for spacing, titleSize, padding and margin.
Integration with MiListView: The MiGroupCard uses a MiListView internally to display the list of items. The MiListView's parameters, such as searchable, spacing, childComponent, and layoutConfig, are used to configure the list's appearance and behavior within the card. Refer to the MiListView.
Searchable Card: The searchable parameter allows filtering of the list within the card, integrating it with a MiSearchField. This requires an external mechanism to update the "match" key in your list data. Refer to the MiSearchField documentation for more details on how to implement the search functionality.

Example JSON Configurations

Example 1: Basic Group Card with Title and List of Names

{
    "component": "groupCard",
    "title": "Names",
    "listKey": "${names}",
    "childComponent": {
        "component": "text",
        "text": "${name}"
    }
}

Explanation of Example 1:

component: "groupCard" - Identifies this configuration as being for a MiGroupCard component.
title: "Names" - Sets the title of the card to "Names".
listKey: "${names}" - Specifies that the data for the list within the card will be retrieved from the state using the key "names". It is assumed that the state contains a list of name objects with the name key. 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: Group Card with Title, Buttons, and Dynamic Height Grid of Products

{
    "component": "groupCard",
    "title": "Products",
    "buttons": [
        {
            "component": "button",
            "label": "Add Product",
            "action": {
                "actionType": "openDialog",
                "dialogName": "addProductDialog"
            }
        }
    ],
    "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: "groupCard" - Identifies this configuration as being for a MiGroupCard component.
title: "Products" - Sets the title of the card to "Products".
buttons - Defines a list of buttons to display in the upper-right corner of the card.
- component: "button" - Specifies that a MiButton component will be used as a button.
- label: "Add Product" - Sets the label of the button to "Add Product".
- action - Defines the action to be performed when the button is pressed.
  - actionType: "openDialog" - Specifies that the action is to open a dialog.
  - dialogName: "addProductDialog" - Specifies the name of the dialog to open.
listKey: "${products}" - Specifies that the data for the list within the card 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.
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.

Overview​

Parameters​

Example JSON Configurations​

Overview

Parameters

Example JSON Configurations