MiSelectFromListButton

The MiSelectFromListButton component is a stateless Flutter widget that provides a button which, when tapped, navigates the user to a dedicated page (MiSelectFromListPage) to select items from a list. It's designed for scenarios where you need to select one or more items from a potentially large dataset, offering search and list display functionalities on a separate page.

Overview

MiSelectFromListButton simplifies the process of selecting items from a list by:

• Navigation to Selection Page: Opens a new page (MiSelectFromListPage) when tapped, dedicated to item selection.
• Data Fetching for Items: Fetches the list of selectable items from an API endpoint specified in the configuration.
• Search Functionality: Provides a search field on the selection page to filter items based on specified properties.
• Item Display with Cards: Displays items in a ListView using smallCard components for each item, showing relevant information (lines 1 and 2) and optionally a quantity selector or checkbox.
• Selection Persistence: Manages the selection state and updates the data based on user selections when the selection page is closed.
• Customizable Button: Allows using a custom button widget for triggering the navigation to the selection page. If no custom button is provided, a default button is rendered.
• Optional Save API: Supports an optional API call to save the selected items upon confirmation on the selection page.
• Data Binding: Uses data binding to manage the list of selected items and update the application state upon selection changes.

Component Name: selectFromList

JSON key: "component": "selectFromList".

Parameters

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
selectedItems	String	List<dynamic>	Selected Items Key: Key to access the list in the data model that will hold the currently selected items. This list is updated when items are selected or deselected on the selection page. Data binding is used to reflect changes in the UI.	null	Yes	No
pageTitle	String	String	Page Title: Title to be displayed on the MiSelectFromListPage (selection page) in the header.	null	Yes	No
pageItemName	String	String	Page Item Name: Singular name of the items being selected (e.g., "Item", "Product", "Customer"). This name is used in labels on the selection page (e.g., in the "selected items" text).	null	No	No
pageItemsApi	Map	Map	Page Items API Configuration: JSON configuration for an API call to fetch the list of items to be displayed on the selection page. This should be a standard API action configuration as used with invokeAction. The API response is expected to contain a list of items under the key DATA.ITEMS.	null	No	No
pageItemsId	String	String	Page Item ID Key: Key within each item object (in the API response) that uniquely identifies the item. This ID is used to match and update selected items.	null	No	No
pageItemsQuantity	String	String	Page Item Quantity Key (Optional): Key within each item object to store the selected quantity. If provided, the smallCard on the selection page will render a quantityButton for each item, allowing quantity selection. If null, a checkbox is used for simple selection.	null	Yes	No
pageItemSearchProps	List<String>	List<String>	Page Item Search Properties: List of item property keys (from the API response) that should be used for searching within the item list on the selection page. The search field will filter items based on these properties.	null	Yes	No
pageSearchLabel	String	String	Page Search Label: Label to be displayed in the search field on the selection page.	null	Yes	No
pageItemCardLine1	String	String	Page Item Card Line 1: Key to the item property (from the API response) to be displayed as the first line in each smallCard on the selection page.	null	Yes	No
pageItemCardLine2	String	String	Page Item Card Line 2: Key to the item property (from the API response) to be displayed as the second line in each smallCard on the selection page.	null	Yes	No
pageSaveApi	Map	Map	Page Save API Configuration (Optional): JSON configuration for an API call to be made when the user confirms the selection on the MiSelectFromListPage by tapping the "Save" button. If provided, this API is invoked with the selected items. If null, no API call is made on save.	null	Yes	No
pagePopAction	Map	Map	Page Pop Action (Optional): JSON configuration for an action to be invoked when the MiSelectFromListPage is popped (closed) without saving via pageSaveApi, but after selections are made. This allows performing actions based on the selections made even if not explicitly "saved" to a backend via pageSaveApi.	null	Yes	No
button	Map	Widget	Custom Button (Optional): JSON configuration for a custom button widget to be used as the trigger for opening the MiSelectFromListPage. If provided, this widget replaces the default button. This should be a standard component configuration that MiFactory can resolve.	null	Yes	Yes
isRequired	bool	bool	Is Required (Optional): If true, an asterisk (*) is displayed next to the pageItemName label to indicate that item selection is mandatory.	false	Yes	No
padding	List<num>	EdgeInsets	Padding: Padding around the MiSelectFromListButton widget. Inherited from MiStatelessWidget.	null	Yes	No
margin	List<num>	EdgeInsets	Margin: Margin around the MiSelectFromListButton widget. Inherited from MiStatelessWidget.	null	Yes	No
alignment	String	AlignmentGeometry	Alignment: Alignment of the MiSelectFromListButton widget within its parent. Inherited from MiStatelessWidget.	"topLeft"	Yes	No
color	String	Color	Color: Background color of the container for the MiSelectFromListButton widget. Inherited from MiStatelessWidget.	null	Yes	No
width	num	double	Width: Fixed width of the MiSelectFromListButton widget. Inherited from MiStatelessWidget.	null	Yes	No
height	num	double	Height: Fixed height of the MiSelectFromListButton widget. Inherited from MiStatelessWidget.	null	Yes	No

Note:

• Selection Flow: When the MiSelectFromListButton is tapped, it navigates to MiSelectFromListPage. On this page, users can search, view, and select/deselect items. Tapping "Save" on MiSelectFromListPage will update the selectedItems data-bound list and optionally invoke pageSaveApi. Navigating back from MiSelectFromListPage (without "Save") also updates selectedItems and optionally invokes pagePopAction.
• Data Binding for selectedItems: The selectedItems parameter is crucial for data binding. Changes made on the MiSelectFromListPage are directly reflected in the data list referenced by this key, making it easy to manage selected items within your application's state.
• API Driven Item List: The list of items is dynamically fetched from an API endpoint using pageItemsApi. This ensures that the selection list is always up-to-date.
• Customizable Item Display: The pageItemCardLine1, pageItemCardLine2, and pageItemsQuantity parameters allow you to customize how each item is displayed in the list on the selection page, adapting to different data structures and display requirements.
• Quantity Selection vs. Checkbox: If pageItemsQuantity is provided, each item on the selection page will have a quantity selector (quantityButton). If pageItemsQuantity is not provided, a simple checkbox is used for selection/deselection.
• Optional APIs for Save and Pop: The pageSaveApi and pagePopAction parameters provide flexibility for handling selected items. pageSaveApi is for persisting selections to a backend, while pagePopAction is for triggering other actions within the application based on the selections, even if they are not formally "saved."
• Custom Button for Trigger: The button parameter allows for complete customization of the button that triggers the selection process. This is useful for styling the trigger button differently or integrating it more seamlessly within your UI. If not provided, a default styled button is used.
• Required Indication: The isRequired parameter visually indicates to the user if item selection is mandatory, improving user guidance in forms or workflows.

Example JSON Configuration

{
  "component": "selectFromList",
  "selectedItems": "${ITEM.COMBO_ITEMS}",
  "pageTitle": "Select Combo Items",
  "pageItemName": "Combo Item",
  "pageItemsApi": {
    "actionType": "apiCall",
    "path": "/getComboItems",
    "data": {
      "MERCH_ID": "1"
    }
  },
  "pageItemsId": "COMBO_ITEM_ID",
  "pageItemsQuantity": "QTY",
  "pageItemSearchProps": [
    "COMBO_ITEM_NAME",
    "COMBO_ITEM_DESC"
  ],
  "pageSearchLabel": "Search Combo Items",
  "pageItemCardLine1": "${COMBO_ITEM_NAME}",
  "pageItemCardLine2": "${COMBO_ITEM_DESC}",
  "margin": [
    0,
    0,
    0,
    16
  ]
}

Explanation of Example:

• "component": "selectFromList": Specifies the component as MiSelectFromListButton.
• "selectedItems": "${ITEM.COMBO_ITEMS}": Data binds the selected items to the COMBO_ITEMS list within the ITEM data object.
• "pageTitle": "Select Combo Items": Sets the title of the selection page.
• "pageItemName": "Combo Item": Sets the item name used in labels to "Combo Item".
• "pageItemsApi": Configures an API call to /getComboItems to fetch the list of combo items.
• "pageItemsId": "COMBO_ITEM_ID": Specifies that COMBO_ITEM_ID is the unique identifier for each combo item.
• "pageItemsQuantity": "QTY": Indicates that items will have quantity selection, and the quantity is stored in the QTY property.
• "pageItemSearchProps": ["COMBO_ITEM_NAME", "COMBO_ITEM_DESC"]: Enables searching by "COMBO_ITEM_NAME" and "COMBO_ITEM_DESC" on the selection page.
• "pageSearchLabel": "Search Combo Items": Sets the search field label.
• "pageItemCardLine1": "${COMBO_ITEM_NAME}": Displays "COMBO_ITEM_NAME" as the first line in each item card.
• "pageItemCardLine2": "${COMBO_ITEM_DESC}": Displays "COMBO_ITEM_DESC" as the second line in each item card.
• "margin": [0, 0, 0, 16]: Adds a bottom margin to the button.