# Calendar Grid Implementation {#calendar-grid-implementation}


The Calendar Grid is an advanced question type that allows tracking data over time in a matrix format, optimized for calendar-based tracking (monthly or weekly periods).


## Features {#features}


- **Dual Modes**: Monthly or weekly tracking
- **Flexible Columns**: select_one, select_multiple, integer, and text field types
- **Configurable Periods**: 1-120 months or 1-520 weeks
- **Future Periods**: Optional allowance for future months/weeks
- **Offline Support**: Works in offline mode
- **XLSForm Compatible**: Import/export with existing XLSForm tools


## Question Schema {#question-schema}



### JSON Structure {#json-structure}


```json
{
  "type": "calendar_grid",
  "name": "reproductive_calendar",
  "label": "Reproductive History Calendar",
  "calendar_config": {
    "mode": "monthly",
    "months_back": 60,
    "start_from": "today",
    "allow_future": false
  },
  "columns": [
    {
      "key": "marital_status",
      "type": "select_one",
      "label": "Marital Status",
      "choices": [
        { "name": "1", "label": "Married" },
        { "name": "2", "label": "Unmarried" }
      ]
    },
    {
      "key": "fertility",
      "type": "integer",
      "label": "Number of Children"
    }
  ]
}
```


### Calendar Config Fields {#calendar-config-fields}


| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `mode` | string | Yes | "monthly" or "weekly" |
| `months_back` | integer | Yes | Number of past periods (1-120 monthly, 1-520 weekly) |
| `start_from` | string | No | "today" or "survey_start" |
| `allow_future` | boolean | No | Whether to show future periods |


### Column Fields {#column-fields}


| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `key` | string | Yes | Variable name for the column |
| `type` | string | Yes | "select_one", "select_multiple", "integer", or "text" |
| `label` | string | Yes | Display label |
| `choices` | array | For select types | List of choices |
| `relevant` | string | No | XPath condition for column visibility |


## Backend Implementation {#backend-implementation}



### Files Modified {#files-modified}


1. **survey-service/api/common/dtos/survey.py** - Added `CALENDAR_GRID` enum, `CalendarColumnSchema`, `CalendarConfigSchema` DTOs
2. **survey-service/api/domain/validators/schema_validator.py** - Calendar grid field validation
3. **survey-service/api/usecase/xlsform_parser.py** - Type mapping for calendar_grid
4. **survey-service/api/usecase/xlsform_writer.py** - Export conversion to begin_repeat with field-list


## Frontend Implementation {#frontend-implementation}



### Survey Designer Components {#survey-designer-components}


- **survey-designer-types.ts** - `QuestionType` includes `calendar_grid`, `CalendarColumn`, `CalendarConfig` interfaces
- **survey-designer.tsx** - "Calendar Grid" option in Add Question menu, editor panel with mode selector, periods back input, columns builder
- **survey-designer-utils.ts** - Schema transformations for calendar_grid


### Form Filler {#form-filler}


- **calendar-grid-renderer.tsx** - NEW: renders calendar as table matrix, handles monthly/weekly modes, ISO week date algorithm
- **form-filler.tsx** - Added calendar_grid to page processing


## Validation Rules {#validation-rules}


1. **Required Fields**: `calendar_config` must be present, at least one column required
2. **Column Validation**: Each column must have a unique `key`. Types must be: select_one, select_multiple, integer, or text. Select types must have choices
3. **Range Validation**: months_back: 1-120 (monthly) or 1-520 (weekly)


## XLSForm Import/Export {#xlsform-importexport}



### Export (MQUAD -> XLSForm) {#export-mquad---xlsform}


Calendar grid converts to a repeat group with field-list appearance:

```
type                name                    label                   appearance    repeat_count
begin_repeat        reproductive_calendar    Reproductive Calendar   field-list   60
select_one          marital_status          Marital Status
select_one          fertility              # of Children
end_repeat
```


### Import (XLSForm -> MQUAD) {#import-xlsform---mquad}


The importer detects calendar patterns: repeat with field-list appearance, contains 2+ select questions, repeat_count uses months calculation or label contains "calendar".


## Related Features {#related-features}



### Calendar Rules Engine {#calendar-rules-engine}


The Calendar Rules Engine enables automatic prefilling of calendar grid columns based on answers to previous questions. See the Calendar Rules guide for details.