DefaultPageLayout

The DefaultPageLayout component is a stateless Flutter widget that provides a standard page structure for applications. It extends PageLayout and offers a common layout with header, body, and footer sections, responsiveness, and optional refresh functionality.

Overview

DefaultPageLayout simplifies the creation of consistent application pages by providing a pre-defined layout structure. It includes:

Header, Body, and Footer Sections: Clearly defined areas for page header content, the main page body, and a footer.
Responsive Design: Adapts to different screen sizes.
Optional Pull-to-Refresh: Provides pull-to-refresh functionality on mobile devices (non-web) to trigger a "refresh" action.
Floating Action Button (FAB) Support: Allows for adding a floating action button with configurable icon and action.
Background Color Customization: Sets the background color of the entire page.
Layout Configuration for Body: The body section content can be further structured using layout configurations (e.g., using MiColumn with layoutConfig).
Button Area in Body: Includes a dedicated area within the body for placing buttons.
Navigation Control: Supports defining a popRoute to handle back navigation behavior.
Actions Definition: Supports defining actions that can be triggered on page load (init) or by other components within the page.
JSON configuration for defining page structure and properties.

Component Name: defaultPageLayout

JSON key: "component": "defaultPageLayout".

Parameters

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
`bgColor`	`String`	`Color`	Background Color: Background color of the entire page. Can be a theme color key. Inherited from `PageLayout`.	Theme's `bgColor`	Yes	No
`header`	`Map`	`Widget`	Header: JSON configuration for a widget to be used as the page header. Typically, you would use a `MiHeader` component here for a standard header structure with leading elements, title, and actions. Refer to the documentation for [`MiHeader`].	`SizedBox.shrink()`	Yes	Yes
`body`	`List<Map>`	`List<Widget>`	Body: List of JSON configurations for widgets to be displayed in the main page body. These widgets will be arranged within a `MiColumn`.	`null`	Yes	Yes
`bodySpacing`	`num`	`double`	Body Spacing: Vertical spacing (in logical pixels) between elements within the `body` column and below the body section.	`20.0`	Yes	No
`footer`	`Map`	`Widget`	Footer: JSON configuration for a widget to be displayed as the page footer.	`SizedBox.shrink()`	Yes	Yes
`canRefresh`	`bool`	`bool`	Can Refresh: If `true` and on non-web platforms, enables pull-to-refresh functionality for the page, triggering the "refresh" action on the `MiCubit`.	`false`	Yes	No
`layoutConfig`	`String`	`String`	Layout Config: Configuration string passed down to the `MiColumn` component used to structure the `body` content. This string determines the number of columns the `MiColumn` will use for different screen sizes. See "Layout Configuration for Body (`layoutConfig`)" note below for details.	`'3-1'`	Yes	No
`buttons`	`List<Map>`	`List<Widget>`	Buttons: List of JSON configurations for buttons to be displayed below the main `body` content. These buttons will be arranged in a vertical column.	`null`	Yes	Yes
`floatingActionButton`	`Map`	`Map`	Floating Action Button (FAB): JSON configuration for a floating action button. This should be a JSON map defining FAB properties like `icon`, `color`, and `actionName`. If `null`, no FAB is displayed.	`null`	Yes	No
`popRoute`	`String`	`String`	Pop Route: GoRouter route string to navigate to when the user attempts to pop/go back from the page (e.g., using the device's back button on Android). This is only relevant when `canRefresh` is enabled on non-web platforms.	`null`	Yes	No
`actions`	`Map<String, List<Map>>`	`Map<String, List<dynamic>>`	Actions: Defines a map of actions that can be invoked within this page. The key is the action name (e.g., `"init"`, `"addMember"`), and the value is a list of action configurations to be executed sequentially when the action is triggered. The `"init"` action is a reserved keyword and is automatically executed when the page is initialized.	`null`	Yes	Yes
`padding`	`List<num>`	`EdgeInsets`	Page Padding: Padding applied to the main content area (body, header, footer). Inherited from `MiStatelessWidget`.	`null`	Yes	Yes
`margin`	`List<num>`	`EdgeInsets`	Page Margin: Margin applied to the entire page layout widget. Inherited from `MiStatelessWidget`.	`null`	Yes	Yes
`alignment`	`String`	`AlignmentGeometry`	Page Alignment: Alignment of the page content within its available space. Inherited from `MiStatelessWidget`.	`"topLeft"`	Yes	No
`color`	`String`	`Color`	Container Color: Color of the outermost container of the page layout. Inherited from `MiStatelessWidget`.	`null`	Yes	No
`width`	`num`	`double`	Page Width: Sets a fixed width for the page's content area, useful for controlling responsiveness on larger screens. Inherited from `MiStatelessWidget`.	`null`	Yes	No
`height`	`num`	`double`	Page Height: Sets a fixed height for the page layout. Inherited from `MiStatelessWidget`.	`null`	Yes	No

Note:

Page Structure: DefaultPageLayout is designed to provide a standard page layout with distinct header, body, and footer sections, enhancing UI consistency across the application.
Responsiveness and Maximum Width: The page layout incorporates responsiveness by using LayoutBuilder and SizedBox to constrain the page body width on larger screens, ensuring readability and optimal layout on various devices, especially on the web.
Pull-to-Refresh (Mobile Only): The pull-to-refresh functionality is only enabled on non-web platforms when canRefresh is set to true. On web, the page uses a simple SingleChildScrollView.
Floating Action Button Configuration: To add a FAB, provide a JSON map to the floatingActionButton parameter. This map should include:
- "icon": Icon data key (String) for the FAB icon (e.g., "add").
- "color": Color key (String) for the FAB background color (e.g., "primary", "accent").
- "actionName": Action name (String) to be invoked when the FAB is pressed.
Navigation Control with popRoute: The popRoute parameter, in conjunction with canRefresh (on mobile), allows you to control where the user is navigated when they try to go back from the page. This is useful for scenarios like preventing accidental back navigation during data loading or specific workflows.
Actions Definition (actions parameter): The actions parameter allows you to define a set of actions that can be triggered within the page. This parameter accepts a JSON map where:
- Keys: are action names (Strings), like "init" or custom action names like "addMember".
- Values: are lists of action configuration JSONs. Each action configuration in the list defines a specific action to be performed (e.g., navigation, data update, etc.).
- init Action: The "init" action is a special reserved action name. If defined, the list of actions under "init" will be executed automatically when the DefaultPageLayout is first built and initialized. This is useful for performing initial data loading or setup tasks for the page.
- Custom Actions: You can define your own action names (like "addMember" in Example 4). These custom actions can then be invoked by other components within the page, such as buttons or toggle switches, using the actionName parameter of those components. This provides a mechanism for wiring up UI interactions to specific application logic defined within the page layout.
Layout Configuration for Body (layoutConfig): The layoutConfig parameter controls the responsive layout of the body content. It is passed to the underlying MiColumn component which structures the body's children. layoutConfig is a string that defines the number of columns for different screen sizes (LayoutTypes).
- Layout Types: Screen sizes are categorized into LayoutTypes: compact, medium, expanded, large, and extraLarge. These correspond to increasing screen widths.
- layoutConfig String Formats:
  - "max": Forces a single-column layout (crossAxisCount = 1) for all screen sizes.
  - "X-Y-Z-A-B" (5 values): Explicitly defines the number of columns for each LayoutType in the order: extraLarge-large-expanded-medium-compact. For example, "4-3-2-2-1" would set 4 columns for extra-large screens, 3 for large, 2 for expanded and medium, and 1 for compact screens.
  - "X-Y-Z" (3 values): Defines columns for extraLarge/large, expanded, and medium/compact. Example: "3-2-1" means 3 columns for extra-large and large, 2 for expanded, and 1 for medium and compact.
  - "X-Y" (2 values): Defines columns for extraLarge/large/expanded and medium/compact. Example: "2-1" means 2 columns for extra-large, large, and expanded, and 1 for medium and compact.
  - "X" (1 value): Sets the same number of columns for all LayoutTypes. Example: "2" means 2 columns for all screen sizes.
- Responsiveness: The MiColumn uses the ResponsiveBuilder to determine the current LayoutType based on the screen width and then uses the layoutConfig string to select the appropriate crossAxisCount for rendering its children in a grid or column layout.

Example JSON Configuration

Example 1: Basic Page Layout with Header and Body

{
  "component": "defaultPageLayout",
  "header": {
    "component": "container",
    "color": "primary",
    "padding": [16, 0],
    "child": {
      "component": "text",
      "text": "My Page Title",
      "color": "white",
      "fontSize": 20,
      "fontWeight": "bold",
      "alignment": "center"
    }
  },
  "body": [
    {
      "component": "text",
      "text": "Welcome to my page!",
      "fontSize": 16
    },
    {
      "component": "text",
      "text": "This is the main content area.",
      "fontSize": 14
    }
  ]
}

Explanation of Example 1:

This JSON defines a basic DefaultPageLayout.
"component": "defaultPageLayout" specifies the component.
"header" defines a header section using a MiContainer to style the header background and padding, and a MiText widget for the title.
"body" contains a list of MiText widgets, which will be rendered vertically in the page body using a default MiColumn.

Example 2: Page Layout with Footer, Buttons, and Pull-to-Refresh

{
  "component": "defaultPageLayout",
  "bgColor": "greyLight",
  "header": {
    "component": "container",
    "color": "accent",
    "padding": [12, 0],
    "child": {
      "component": "text",
      "text": "Settings Page",
      "color": "white",
      "fontSize": 18,
      "fontWeight": "semiBold",
      "alignment": "center"
    }
  },
  "body": [
    {
      "component": "text",
      "text": "General Settings:",
      "fontWeight": "bold",
      "padding": [0, 0, 0, 8]
    },
    {
      "component": "toggleButton",
      "label": "Dark Mode",
      "value": "${darkModeEnabled}",
      "tile": true
    },
    {
      "component": "toggleButton",
      "label": "Notifications",
      "value": "${notificationsEnabled}",
      "tile": true
    }
  ],
  "bodySpacing": 30,
  "buttons": [
    {
      "component": "button",
      "label": "Save Changes",
      "actionName": "saveSettings",
      "color": "primary"
    }
  ],
  "footer": {
    "component": "container",
    "padding": [8],
    "child": {
      "component": "text",
      "text": "© 2023 My App",
      "fontSize": 12,
      "alignment": "center",
      "color": "greyDark"
    }
  },
  "canRefresh": true,
  "popRoute": "/home"
}

Explanation of Example 2:

This example shows a more complex DefaultPageLayout with:
- "bgColor": "greyLight": Sets the page background color to a light grey theme color.
- A styled "header" similar to Example 1 but with "Settings Page" title and different styling.
- A "body" containing a title text "General Settings" and two MiToggleSwitch components for "Dark Mode" and "Notifications" settings, demonstrating nested components within the body and data binding.
- "bodySpacing": 30: Increases spacing within and below the body section.
- "buttons": Defines a "Save Changes" button below the body, triggering the "saveSettings" action.
- "footer": Adds a simple footer with copyright text.
- "canRefresh": true: Enables pull-to-refresh on mobile.
- "popRoute": "/home": Sets the navigation route to "/home" when the user tries to go back from this page.

Example 3: Page Layout with Floating Action Button

{
  "component": "defaultPageLayout",
  "floatingActionButton": {
    "icon": "add",
    "color": "accent",
    "actionName": "addNewItem"
  },
  "body": [
    {
      "component": "text",
      "text": "Page Content with FAB"
    }
  ]
}

Explanation of Example 3:

This example demonstrates adding a Floating Action Button.
"floatingActionButton": Configures the FAB with:
- "icon": "add": Sets the FAB icon to the "add" icon.
- "color": "accent": Sets the FAB background color to the theme's "accent" color.
- "actionName": "addNewItem": Specifies the "addNewItem" action to be invoked when the FAB is pressed.
The "body" simply contains a text widget for demonstration.

Example 4: Page Layout with Actions, Header with Back Button, and Body Content with Action Button

{
  "component": "defaultPageLayout",
  "actions": {
    "init": [],
    "addMember": [
      {
        "actionType": "navigate",
        "navigationType": "push",
        "pageUrl": "/edit-team",
        "pageArgs": {
          "TEAM_MEMBER": null
        }
      }
    ]
  },
  "header": {
    "component": "header",
    "leading": {
      "component": "backButton"
    }
  },
  "layoutConfig": "2",
  "body": [
    {
      "component": "text",
      "text": "This page demonstrates actions and header configuration.",
      "fontSize": 16
    },
    {
      "component": "text",
      "text": "Click the button below to trigger the 'addMember' action, which navigates to the edit team page.",
      "fontSize": 14
    },
    {
      "component": "button",
      "label": "Add Member",
      "actionName": "addMember"
    }
  ]
}

Explanation of Example 4:

This example demonstrates defining actions within the DefaultPageLayout, configuring a header with a back button, and adding body content including a button that triggers a defined action.
"component": "defaultPageLayout" specifies the component.
"actions": Defines actions, including the init action (empty here) and a custom "addMember" action for navigation (as described in previous Example 4 explanation).
"header": Configures the page header using MiHeader with a backButton in the leading position.
"layoutConfig": "2": Sets the layout configuration for the body to "2". This means the MiColumn in the body will use a 2-column grid layout for all screen sizes.
"body": Contains MiText components to display explanatory text and a MiButton.
- The MiButton is configured with "actionName": "addMember". When this button is pressed, it will invoke the "addMember" action defined in the "actions" section of the DefaultPageLayout, triggering the navigation to the "/edit-team" page.

Overview​

Parameters​

Example JSON Configuration​

Overview

Parameters

Example JSON Configuration