Grid Widget Documentation

Overview​

The Grid Widget is a flexible layout component that allows you to create responsive column-based layouts for organizing other widgets. It supports responsive design, form functionality, loops, and various styling options.

Basic Configuration​

Global Settings​

Name​

• Description: Display name for the grid widget
• Type: Text input
• Usage: Used for identification and can be displayed in collapse mode

Variable/Model​

• Description: The data model that the grid widget binds to
• Type: Text input
• Required: Yes (except for certain widget types)
• Validation: Must be a valid variable name
• Usage: Defines the data binding for the grid component

Gutter​

• Description: Spacing between columns in pixels
• Type: Number input
• Default: 0
• Usage: Controls the horizontal spacing between grid columns

Loop Configuration​

Loop​

• Description: Enable repeating the grid for each item in an array
• Type: Toggle switch
• Default: false
• Availability: Not available if widget is already inside a parent loop
• Usage: When enabled, the grid will repeat for each item in the bound array

Default Length​

• Description: Initial number of loop iterations
• Type: Number input
• Minimum: 0
• Availability: Only when Loop is enabled
• Usage: Sets how many grid instances are created by default

Show Button​

• Description: Always display the add button in loop mode
• Type: Toggle switch
• Default: false
• Availability: Only when Loop is enabled
• Usage: Controls visibility of the add new item button

Add Text​

• Description: Text displayed on the add button
• Type: Text input
• Availability: Only when Loop is enabled
• Usage: Customizes the label for the add new item button

Form Configuration​

Form​

• Description: Create a separate form context
• Type: Toggle switch
• Default: false
• Availability: Not available if widget is inside a parent form or loop
• Usage: Creates an isolated form scope for validation and submission

Column Configuration​

Adding Columns​

1. Navigate to the "Columns" section in the widget configuration
2. Click "Add Column" to create a new column
3. Configure the column span and responsive breakpoints

Column Properties​

Span​

• Description: Default column width (out of 24 total grid units)
• Type: Number input
• Range: 1-24
• Usage: Defines the column width on medium and larger screens

Responsive Breakpoints​

Each column supports responsive design with the following breakpoints:

• xs (Extra Small): Mobile phones (< 768px)
• sm (Small): Tablets (≥ 768px)
• md (Medium): Small laptops (≥ 992px)
• lg (Large): Laptops (≥ 1200px)
• xl (Extra Large): Large screens (≥ 1920px)

Configuration:

1. Click the expand button (arrow) next to a column
2. Enter values for each breakpoint
3. If left empty, the system will use the default span value

Column Management​

• Reorder: Drag columns using the grip handle (≡ icon)
• Remove: Click the minus (-) button to delete a column
• Expand: Click the arrow button to show responsive breakpoint inputs

Layout and Styling​

Justify Content​

• Options: Start, End, Center, Space Around, Space Between
• Usage: Controls horizontal alignment of columns within the grid
• Default: Start

Align Items​

• Options: Top, Middle, Bottom
• Usage: Controls vertical alignment of content within columns
• Default: Top

Visual Effects​

Shadowed​

• Type: Toggle switch
• Usage: Adds a shadow effect to the grid container
• Note: Not applied when Loop or Collapse is enabled

Fixed​

• Type: Toggle switch
• Usage: Makes the grid position fixed on the page
• Note: Not applied when Loop is enabled

Collapse​

• Type: Toggle switch
• Availability: Not available when Loop is enabled
• Usage: Makes the grid collapsible with the widget name as header

Form Styling (Form Mode Only)​

Label Position​

• Options: Left, Right, Top
• Availability: Only when Form is enabled
• Usage: Controls the position of form field labels

Advanced Configuration​

Custom Classes​

Static Classes​

• Field: Class
• Type: Text input
• Usage: Add CSS class names separated by commas
• Example: custom-grid, highlighted

Dynamic Classes​

• Access: Click the paint brush icon next to the Class field
• Usage: Write JavaScript expressions that return class names
• Context: Access model data using models. prefix
• Example: models.status === 'active' ? 'active-grid' : 'inactive-grid'

Validation Rules​

The grid widget supports validation across different screen contexts:

Screen-Based Validation​

For each screen/context, you can configure:

• Available: Whether the widget exists in this context
• Visible: Whether the widget is visible (supports conditions)
• Required: Whether the widget is required (for applicable contexts)
• Disable: Whether the widget is disabled

Advanced Conditions​

1. Simple Mode: Use toggle switches for boolean values
2. Advanced Mode: Write JavaScript expressions for dynamic behavior

Expression Format:

• Use {{variable}} to reference model data
• Example: {{user.role}} === 'admin'
• Example: {{status}} !== 'draft' && {{approved}} === true

Widget Rules​

Add validation rules that apply to the grid context:

1. Click "Add rule" in the Rules section
2. Select a rule type from the dropdown
3. Configure the rule value and error message
4. Rules are evaluated in the order they appear

Data Binding and Context​

Model Binding​

The grid widget creates a data context that child widgets can access:

• Form Context: When Form is enabled, creates isolated form scope
• Loop Context: When Loop is enabled, provides iteration data
• Standard Context: Normal data binding to the specified model

Child Widget Access​

Child widgets placed within grid columns can access:

• Parent grid data through the model binding
• Loop iteration data (when in loop mode)
• Form validation context (when in form mode)

Best Practices​

Column Design​

1. Plan for Mobile: Always configure xs breakpoints for mobile compatibility
2. Use 24-Unit System: Total column spans should add up to 24 for full width
3. Progressive Enhancement: Start with mobile (xs) and enhance for larger screens

Performance Considerations​

1. Limit Loop Items: Be mindful of performance with large loop datasets
2. Optimize Nested Widgets: Avoid deeply nested grid structures
3. Efficient Validation: Use simple boolean conditions when possible

Accessibility​

1. Meaningful Names: Use descriptive names for screen readers
2. Logical Tab Order: Ensure proper keyboard navigation
3. Color Contrast: Ensure sufficient contrast for shadowed elements

Common Use Cases​

Responsive Form Layout​

Configuration:
- Columns: 2
- Column 1: xs=24, sm=12, md=8
- Column 2: xs=24, sm=12, md=16
- Form: Enabled
- Label Position: Top

Product Listing (Loop)​

Configuration:
- Loop: Enabled
- Default Length: 6
- Show Button: Enabled
- Add Text: "Add Product"
- Columns: 3 (xs=24, sm=12, md=8 each)

Dashboard Layout​

Configuration:
- Columns: 4
- Justify: Space Between
- Align: Top
- Shadowed: Enabled
- Responsive: xs=24, sm=12, md=6

Collapsible Section​

Configuration:
- Collapse: Enabled
- Name: "Advanced Options"
- Shadowed: Enabled
- Single column with xs=24

Troubleshooting​

Common Issues​

1. Columns Not Responsive: Check that responsive breakpoints are configured
2. Content Overflow: Ensure column spans don't exceed 24 total
3. Loop Not Working: Verify that the model contains array data
4. Form Validation Issues: Check that Form mode is enabled and model is properly bound

Debug Tips​

1. Use browser developer tools to inspect column classes
2. Check console for JavaScript errors in custom conditions
3. Verify model data structure matches expected format
4. Test responsive behavior at different screen sizes

Integration Notes​

• The grid widget automatically integrates with the parent interface validation system
• Form grids participate in parent form submission unless isolated
• Loop grids automatically handle add/remove operations
• Validation rules cascade to child widgets appropriately