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

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

JSON Structure

{
  "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

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

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

Files Modified

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

Frontend Implementation

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

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

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

XLSForm Import/Export

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)

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

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.