A

Widget Patterns

Common UI patterns using Appivo widgets

Widget Patterns Example

Learn common UI patterns built with Appivo's widget system.

What You'll Build

Reusable UI patterns including:

  • Master-detail layouts
  • Dashboard with metrics
  • Search with filters
  • Modal workflows

Prerequisites

  • Completed the Hello World example
  • Understanding of widgets and data binding

Pattern 1: Master-Detail Layout

Display a list with detail panel.

Layout Structure

FlexContainer: Master-Detail
├── Panel: Master List (width: 40%)
│   └── DataGrid: Items
│       - Click row to select
│       - Highlight selected row
│
└── Panel: Detail View (width: 60%)
    └── Shows selected item details
    └── Empty state when nothing selected

Implementation

FlexContainer: Master-Detail
Direction: row
Gap: 20px

Left Panel:
├── DataGrid: Customers
│   Columns: name, email, status
│   onRowClick: Set selected_customer
│   Row highlighting: When id = selected_customer.id

Right Panel (visible when customer selected):
├── Panel: Customer Details
│   ├── Label: customer.name (large)
│   ├── Label: customer.email
│   ├── Label: customer.phone
│   └── Panel: Recent Orders
│       └── DataGrid: Orders filtered by customer_id

Empty State

Panel: No Selection (visible when no customer selected)
├── Icon: user
└── Label: "Select a customer to view details"

Pattern 2: Dashboard Layout

Display metrics and quick actions.

Layout Structure

GridContainer: Dashboard (3 columns)
├── Panel: Today's Sales
│   ├── Large number: $12,345
│   └── Change indicator: +15%
│
├── Panel: New Orders
│   ├── Large number: 47
│   └── Link: View all
│
├── Panel: Pending Approval
│   ├── Large number: 5
│   └── Button: Review
│
├── Panel: Sales Chart (spans 2 columns)
│   └── Chart: Line chart of sales
│
└── Panel: Recent Activity
    └── List: Latest 10 activities

Metric Card Pattern

Panel: Metric Card
├── Label: "Total Revenue" (small, gray)
├── Label: "$45,678" (large, bold)
├── FlexContainer: Change
│   ├── Icon: arrow-up (green) or arrow-down (red)
│   └── Label: "12% vs last month"
└── Link: "View details →"

Calculate Metrics

Use data binding with aggregations:

Label: Total Revenue
Value: SUM(orders.total) where created_at = today
Format: Currency

Label: Order Count
Value: COUNT(orders) where status != "Cancelled"

Pattern 3: Search with Filters

Advanced search interface.

Layout Structure

Panel: Search Interface
├── FlexContainer: Search Bar
│   ├── TextField: Search (with icon)
│   └── Button: Advanced Filters
│
├── Panel: Filter Panel (collapsible)
│   ├── Select: Status
│   ├── DateField: Date From
│   ├── DateField: Date To
│   ├── Select: Category
│   └── Button: Apply Filters
│
├── Label: "Showing 25 of 142 results"
│
└── DataGrid: Results
    └── Paginated, sortable

Search Bar Component

FlexContainer: Search Bar
├── TextField: Search Query
│   Placeholder: "Search products..."
│   Icon: magnifying glass
│   onKeyPress (Enter): Execute search
│   onChange (debounced 300ms): Filter results
│
├── Button: Clear
│   Visible when: search has value
│   onClick: Clear search
│
└── Button: Filters
    Icon: funnel
    Badge: Active filter count
    onClick: Toggle filter panel

Active Filters Display

FlexContainer: Active Filters
  Visible when: Any filter active

├── Chip: Status = Active
│   └── X button to remove
├── Chip: Category = Electronics
│   └── X button to remove
├── Chip: Date: Jan 1 - Jan 31
│   └── X button to remove
└── Button: Clear all

Pattern 4: Modal Form

Form in a modal dialog.

Button: Add New Customer
onClick: Show Add Customer Modal

Modal: Add Customer
├── Header: "Add New Customer"
├── Content:
│   ├── TextField: Name (required)
│   ├── EmailField: Email (required)
│   ├── PhoneField: Phone
│   └── Select: Type (Personal/Business)
└── Footer:
    ├── Button: Cancel (closes modal)
    └── Button: Save (primary)
        Disabled until: Form is valid
        onClick:
          1. Create customer
          2. Close modal
          3. Refresh list
          4. Show success toast

Modal: Small (400px)
  - Simple confirmations
  - Quick inputs

Modal: Medium (600px)
  - Standard forms
  - Most common

Modal: Large (800px)
  - Complex forms
  - Multi-section content

Modal: Full (90% width)
  - Detailed views
  - Wizards

Pattern 5: Tabs with Content

Organize content into tabs.

Tab Structure

TabContainer: Customer Details
├── Tab: Overview
│   ├── Customer info
│   └── Quick stats
│
├── Tab: Orders
│   └── DataGrid: Customer orders
│
├── Tab: Documents
│   └── List: Uploaded files
│
└── Tab: Notes
    ├── List: Previous notes
    └── Form: Add note

Tab with Badge

Tab: Orders
Badge: 12 (active order count)

Tab Loading

Tab: Documents
Loading: Show spinner until data loads
Empty: "No documents uploaded"

Pattern 6: Wizard / Stepper

Multi-step process.

Wizard Structure

Panel: Order Wizard
├── Stepper: Progress
│   ├── Step 1: Cart (completed)
│   ├── Step 2: Shipping (active)
│   ├── Step 3: Payment
│   └── Step 4: Confirm
│
├── Panel: Step Content
│   └── Current step form/content
│
└── FlexContainer: Navigation
    ├── Button: Back
    │   Disabled on: First step
    ├── Spacer
    ├── Button: Next (steps 1-3)
    │   onClick: Validate, then advance
    └── Button: Complete (step 4)
        onClick: Submit order

Step Validation

Step 2: Shipping
Required fields: address, city, country
Validation: All required fields filled
Next button: Disabled until valid

Pattern 7: Card Grid

Display items as cards.

Card Grid Layout

GridContainer: Products
Columns: 4 (responsive: 3 on tablet, 2 on mobile)
Gap: 20px

Card Template:
├── Image: Product photo
├── Label: Product name
├── Label: Price (bold)
├── Label: Category (small, gray)
└── Button: Add to Cart

Card with Actions

Panel: Product Card
├── Image: product.image
│   AspectRatio: 4:3
│
├── FlexContainer: Content
│   ├── Label: product.name
│   ├── Label: product.price (formatted)
│   └── StarRating: product.rating (read-only)
│
└── FlexContainer: Actions
    ├── Button: Quick View (icon only)
    ├── Button: Add to Wishlist (icon only)
    └── Button: Add to Cart

Pattern 8: Table Actions

DataGrid with row actions.

Row Action Menu

DataGrid: Orders
Columns:
  - order_number
  - customer
  - date
  - total
  - status
  - actions (custom column)

Actions Column:
├── Button: View (icon: eye)
├── Button: Edit (icon: pencil)
└── Menu: More
    ├── Item: Duplicate
    ├── Item: Print
    ├── Separator
    └── Item: Delete (danger)

Bulk Actions

DataGrid: Orders
Selection: Checkbox column
Bulk Actions Toolbar (visible when items selected):
├── Label: "3 items selected"
├── Button: Export
├── Button: Update Status
└── Button: Delete

Pattern 9: Empty States

Handle no-data scenarios.

Empty State Component

Panel: Empty State
Centered: true
├── Icon: inbox (large, gray)
├── Label: "No orders yet" (heading)
├── Label: "Orders will appear here..." (description)
└── Button: Create First Order (primary)

Context-Specific Empty States

Search Results Empty:
  Icon: search
  Title: "No results found"
  Description: "Try different search terms"
  Action: Clear search

Filtered Empty:
  Icon: filter
  Title: "No matching items"
  Description: "Adjust your filters"
  Action: Clear filters

New User Empty:
  Icon: rocket
  Title: "Welcome!"
  Description: "Get started by..."
  Action: Create first item

Best Practices

Consistency

  1. Use same patterns across views
  2. Maintain consistent spacing
  3. Use consistent button placement
  4. Follow established conventions

Responsiveness

  1. Test on multiple screen sizes
  2. Stack elements on mobile
  3. Adjust column counts
  4. Consider touch targets

Accessibility

  1. Use proper labels
  2. Ensure keyboard navigation
  3. Provide screen reader text
  4. Maintain color contrast

Performance

  1. Lazy load tab content
  2. Paginate large lists
  3. Optimize images
  4. Cache where appropriate

Next Steps