# Board (cf.cplace.cboard.main)

## Overview

The Board app provides a highly configurable Kanban-style board widget for visualizing and managing pages as cards across columns and swimlanes. It enables different agile working methods through drag-and-drop interactions that update attribute values in real-time.

**Key Capabilities:**
- Display any page type as cards on a board
- Organize cards into columns (based on enumeration or date attributes)
- Optionally group cards into swimlanes (second dimension)
- Drag-and-drop to move cards between columns/swimlanes (updates the underlying attribute)
- Rich card display with titles, descriptions, assignees, dates, tags, and icons
- Real-time synchronization across multiple users

## Dependencies

| App | Qualified Name | Auto-Installed |
|-----|----------------|----------------|
| cplace Basis | `cf.cplace.platform` | Yes (platform base) |

**Note:** The Board app has no additional dependencies beyond the platform base.

## Types Provided

**None.** The Board app does not introduce any new types. It is a pure widget app that works with existing types in your workspace.

## Widgets Provided

| Widget | Widget Kind | Description |
|--------|-------------|-------------|
| Board | `cf.cplace.cboard.main.board` | Configurable Kanban board for visualizing pages as cards |

### Board Widget Details

The Board widget is the sole feature of this app. It transforms structured cplace data into an interactive visual board.

#### Widget Attributes

| Attribute | Type | Required | Description |
|-----------|------|----------|-------------|
| `cf.cplace.cboard.title` | Localized String | No | Board title displayed in the widget header |
| `cf.cplace.cboard.searchConfigurations` | JSON (multiple) | Yes | Card source configurations (search queries defining which pages appear) |
| `cf.cplace.cboard.columnMapping` | JSON | Yes | Column definitions and attribute mappings |
| `cf.cplace.cboard.swimlaneMapping` | JSON | No | Swimlane definitions and attribute mappings |
| `cf.cplace.cboard.visualComponents` | JSON | No | Visual settings (card appearance, colors, icons) |
| `cf.cplace.cboard.height` | Number | No | Widget height in pixels |

#### Configuration Tools

The MCP server provides specialized tools for configuring board widgets:

| Tool | Purpose |
|------|---------|
| `cplace_board_get_configuration` | Get current configuration in a friendly format |
| `cplace_board_configure_cards` | Configure card sources (search queries) |
| `cplace_board_configure_columns` | Configure columns (static or dynamic) |
| `cplace_board_configure_swimlanes` | Configure swimlanes (or disable) |
| `cplace_board_configure_visual` | Configure UI settings |

#### Minimal Initial Configuration

When adding a board widget via `cplace_execute_layout_script` / `layout.define()`, use this minimal configuration:

```json
{
  "cf.cplace.cboard.searchConfigurations": ["{}"],
  "cf.cplace.cboard.columnMapping": "{}"
}
```

Then use the specialized configuration tools to set up the board properly.

## Use Cases

### Kanban Workflow Management
Map work items through workflow stages (Backlog, In Progress, Review, Done). Status attribute maps to columns. Drag cards to update status instantly.

### Sprint Planning
Organize stories across sprints with sprint as swimlanes and status as columns. Visualize work distribution per sprint.

### Project Portfolio View
Track projects through phases with phase as columns and department as swimlanes. Executive-level overview of project states.

### Order/Request Tracking
Monitor orders through fulfillment stages. Order status as columns, priority or customer as swimlanes.

### Time-Based Planning
Use dynamic date-based columns (weeks, months, quarters) for event planning or release scheduling.

## Design Patterns

### Column Types

1. **Static Columns**: Predefined columns with explicit labels and order
   - Best for: Fixed workflow stages, known status values

2. **Dynamic Columns**: Auto-generated from attribute values
   - Best for: Data-driven boards where values may change

3. **Date-Based Dynamic**: Columns representing time periods
   - Best for: Timeline views, release planning, event scheduling

### Board Structures

- **Flat Board** (columns only): Simple workflows, single categorization
- **Two-Dimensional** (columns + swimlanes): Cross-categorization (e.g., status x priority)

### Common Combinations

- **Board + Table**: Visual workflow alongside detailed data analysis
- **Board + Charts**: Individual items + aggregated metrics (e.g., burndown)
- **Master-Detail**: Click card to show details in connected widget

## When to Use Board vs. Alternatives

| Scenario | Best Widget |
|----------|-------------|
| Visualize workflow stages | **Board** |
| Enable drag-and-drop status updates | **Board** |
| Detailed data analysis with sorting/filtering | Table |
| Hierarchical parent-child structures | Tree |
| Quantitative metrics and trends | Charts |
| Complex search and bulk operations | Search/Table |

## Usage Notes

1. **No Types Required**: The Board app works with any existing types - it displays pages matching your search queries as cards.

2. **Attribute Requirements**: For columns/swimlanes to work, the underlying pages need:
   - An enumeration attribute (for static/dynamic columns)
   - Or a date attribute (for date-based columns)
   - Drag-and-drop updates the mapped attribute value

3. **Performance**: Configure card limits to prevent performance issues with large datasets.

4. **Real-Time Sync**: Multiple users see updates automatically through polling.

5. **Unmapped Cards**: Cards that don't match any column/swimlane appear in an optional sidebar.

## Investigation Metadata

| Property | Value |
|----------|-------|
| Investigation Date | 2026-02-02 |
| Investigation Workspace | `gzatw4vf7lvh37bo581gimk9y` |
| Apps After Install | 2 (platform + Board) |
| New Types | 0 |
| New Widgets | 1 |