Survey Designer

The MQUAD survey designer is a visual, drag-and-drop interface for building surveys. It supports the full XLSForm standard with MQUAD enhancements for constraint expressions, skip logic, and data validation. This page documents the designer in full: the interface, every question type (its configuration in the designer and how it behaves when someone fills in the form), choices, appearance, languages, and logic.

Before you get here: a form must be created inside a project inside a workspace. See Surveys for the creation flow. After creating a form the designer opens automatically; otherwise open it from the Surveys list via Design Form.

Interface Overview

The designer header shows Form Designer with the form's title, a last-saved indicator, and an auto-saving indicator. The body is organised as a row of tabs across the top, and the Design tab is a three-panel workspace.

Tabs

Design tab — three panels

• Left Panel (Add Question / Question Bank) — switch between Types and Bank:
  • Types lists every question type grouped into categories with a count badge. Each entry shows an icon, the type label, and a one-line description. Click a type to append it to the canvas.
  • Bank opens the Question Bank browser; you can save questions from the canvas to the Question Bank to reuse them across forms, and clicking a saved question inserts it into the current form.
• Center Panel (Canvas) — the form being built:
• The canvas header shows the question/group count (e.g. "12 questions (2 groups)") and a Form Title input.
• An empty form shows a Start Building Your Form prompt with an Add First Question shortcut.
• Questions can be dragged to reorder, moved up/down, duplicated, deleted, grouped, and collapsed (groups/repeats).
• Duplicate a question: Click the duplicate icon on the question card (or use the card context menu) to create a copy of the selected question with its configuration.
• Multi-select is available for bulk actions: hold Ctrl/⌘ and click, or use the multi-select mode toggle. A press-and-hold handle on each card is the drag target.
• Right Panel (Properties) — configure the currently selected question. Until a question is selected it shows "Select a question to edit its properties".

Question cards

Each question on the canvas shows:

• A type badge — the question type, or 📅 Calendar Grid, 🔁 Repeat, or 📁 Group for containers.
• The variable name (monospace) used in expressions.
• A Required badge when the question is mandatory.
• A Count badge on repeats that have a fixed count.
• A months badge on calendar grids showing the configured window.
• An Error badge when the form validator flags the question (e.g. a broken reference). The card border also turns red.

Question Types Reference

The palette groups types into families: Text, Number, Date/Time, Choice, Location, Media, Display/Calculated, Metadata, External Data, and Grouping containers, plus MQUAD's Calendar Grid.

The Runtime input column below describes how the field appears and behaves when someone fills in the form (identical on the web form and the mobile field app — the same expression engine and rendering rules run on both).

Text

Number

Date & Time

Choice

Location

Media

Display / Calculated

Metadata

These are auto-populated by the system and generally hidden from the respondent: start, end, today, deviceid, username, email, phonenumber, simserial, subscriberid, and audit. They are useful for auditing and for expressions (e.g. referencing today()), and record device/time context automatically.

External Data

Grouping Containers

Containers and repeats: group and repeat boundaries (begin_group/end_group, begin_repeat/end_repeat) are managed by the canvas. When you add a container you can add child questions directly into it via Add to group, and ungroup to lift its children back out.

Question Properties Panel

Selecting a question in the canvas fills the right-hand Properties panel. The sections are:

Basic information

Options

Choices (choice-based questions)

Select-one, select-multiple, and rank questions show a choices editor where you add options. Each choice has a name (value), a label, optional per-language labels, optional media, an optional per-choice constraint (visibility rule), and lookup/extra columns. Shared lists are managed from the Choices tab.

Advanced

Extended properties

Beyond the core fields, the properties panel exposes MQUAD extensions:

• Choice relation — bind a question to a shared choice list / relationship.
• Limit — restrict how many options can be selected (select_multiple) or the count of a repeat.
• Paradata — enable paradata capture (e.g. audio/timing) for a question.
• Media file — attach or reference a media asset from the media library.
• Data privacy — mark a field as sensitive.
• Additional values — extra columns/attributes carried on the question.

Calendar Grid configuration

The Calendar Grid type has a dedicated configuration:

Appearance Tokens

The Appearance field accepts a space-separated list of tokens (XLSForm-style), for example minimal columns-3 or no-columns. The designer stores appearance as free text; the runtime interprets recognised tokens:

Unknown tokens are ignored. Keep appearance tokens lowercase and space-separated.

Choices Tab

The Choices tab uses a worksheet editor to manage every choice list in the form in one place: add/remove choices, edit names and labels, set per-choice constraints, and manage extra columns. Changes here stay in sync with the per-question choices editor in the Properties panel.

Preview Tab

The Preview tab renders the form as a respondent sees it, with live skip logic, validation, and calculated values. Preview submissions do not affect project data. Use it to:

1. Verify skip logic reveals and hides questions correctly.
2. Test validation rules with valid and invalid inputs.
3. Confirm calculated and auto-populated values update as expected.
4. Check translations by switching the active language.

Settings Tab

The Settings tab manages form-level configuration.

Languages

• Default language — the language used when no translation is chosen.
• Available languages — the list of languages the form is translated into. Languages can be reordered (drag to reorder).
• Add language — opens a dialog to choose a language (code + name, with a flag). After adding, you can provide per-language labels for each question.
• Languages can also be seeded from a predefined set and deleted.

General settings

• Version & history — shows the current form version and opens the version history dialog. See Surveys for version management.
• Instance name template — the pattern used to name submitted instances.
• Auto-save — toggles automatic saving and its interval. When enabled, edits are saved periodically and the header shows an auto-saving indicator.

Lookup Setup and Lookup Data Tabs

• Lookup Setup configures relationships between questions — for example, cascading selects where one field's options depend on another, or fields that reference external datasets.
• Lookup Data manages the records behind those lookups (the reference data the form resolves against at fill time).

Skip Logic (Relevance)

Skip logic controls when a question is visible. Questions with unmet relevance conditions are hidden automatically.

Visual Builder

1. Select a question and click Conditional Logic in the right panel.
2. The Visual Builder tab lets you add conditions without writing code.
3. Each condition compares another question's answer to a value:
   • If age >= 18 — Show this question only when age is 18 or older.
   • If has_children = Yes — Show only when has_children is "Yes".
4. Combine multiple conditions with AND (all must match) or OR (any must match).
5. Nest condition groups for complex logic like: (A OR B) AND C.

Raw Expression Mode

Switch to the Raw Expression tab to type XPath expressions directly. The client-friendly format uses & for AND and | for OR:

age >= 18 & has_children = Yes

This is automatically converted to the internal XPath format:

${age} >= 18 and ${has_children} = 'Yes'

If you paste an existing XLSForm expression, the system auto-corrects common syntax issues including bare & to and, bare | to or, and missing . prefix.

Validation Rules

Validation rules ensure data quality by constraining what answers are accepted.

Standard Rule Types

MQUAD Regex Shortcuts

For common validation patterns, use the built-in shortcuts instead of writing regex from scratch:

When selected, these shortcuts expand to the full regex expression automatically. They work identically whether set via the visual builder or imported from an XLSForm file.

Calculated Values & Auto-Populate

Calculations let you automatically compute field values based on answers to other questions. There are two modes:

Calculated Value (type = calculate)

Use a Calculated Value question for read-only computed results. These display as formatted text and cannot be edited by respondents.

Examples:

• Total score: ${q1} + ${q2} + ${q3}
• Age from DOB: int(days-between(${dob}, today()) div 365)
• Composite ID: concat(${site_code}, '-', ${participant_num})

Auto-Populate (any other question type)

Use Auto-Populate on any question type (text, integer, select_one, date, etc.) to pre-fill a value that the respondent can override. Unlike Default Values (set once at form start), auto-populate expressions are re-evaluated whenever any dependency changes.

Examples:

• Estimated total on an integer field: ${qty} * ${unit_price}
• Pre-filled location on a text field: concat(${city}, ', ', ${country})

Setting Up in the Designer

1. Select a question in the canvas.
2. In the right panel, scroll to the Advanced section.
3. Click Calculated Value (for calculate type) or Auto-Populate (for all other types).
4. Write your expression using ${question_name} references and built-in functions.
5. The editor validates in real time — unknown variables and unbalanced parentheses are flagged before saving.

The editor provides a Variables panel to insert references and a Functions panel with built-in operators like sum, if, concat, round, and days-between.

For a complete reference of all supported functions and expression syntax, see Expression Reference, Auto-Populate and Calculations, and Date and Time Reference.

Computed Constraints

Constraints can reference other questions in the survey. For example, a "Total household members" question could have:

. >= ${total_members} 

This ensures the current answer is at least as large as the total household members reported earlier.

Choice Constraints

Choice constraints control which options in a select list are visible based on answers to other questions. Each choice in your XLSForm choices sheet can have its own constraint expression. Choices whose constraints evaluate to false are hidden from the respondent.

When to Use

Syntax in the Choices Sheet

Add a constraint column to your XLSForm choices sheet. Write expressions using question names as variable references:

The constraint score >= 26 and score <= 29 means: "Only show this choice when the answer to question score is between 26 and 29."

Supported Expression Patterns

All constraint expressions use the same syntax as survey constraints:

Bare & in expressions (e.g., score>=5&score<=10) is automatically converted to and during import.

How Choice Constraints Differ from choice_filter

Both can be used together: choice_filter runs first to filter the list by extra column values, then each choice's constraint is evaluated individually. A choice is only shown when both pass.

Auto-Correction

When importing from XLSForm, the system automatically:

1. Normalizes operators — & to and, | to or
2. Expands regex shortcuts — regex=email to regex(., 'pattern')
3. Validates references — All ${name} references are checked against existing questions

Runtime Behavior

• Choice constraints are evaluated on every answer change.
• Hidden choices are excluded from the selection list entirely — respondents cannot see or select them.
• If a previously selected choice becomes hidden due to a constraint change, the selection is cleared and the respondent must pick a visible option.
• The same constraint engine runs on both web forms and the mobile field app, ensuring identical behavior.

Expression Reference

Constraint and relevance expressions use a subset of XPath with ODK extensions. Both the web form engine and the mobile field app evaluate expressions identically.

Comparison Operators

Logical Operators

Field References

Reference any question's value using ${question_name}:

${age} >= 18 and ${consent} = 'Yes'

The dot . represents the current question's value:

. >= 5 and . <= 10

Built-in Functions

Common Constraint Patterns

XLSForm Import

When importing an XLSForm file, the system automatically:

1. Expands regex shortcuts — regex=email becomes the full regex expression automatically.
2. Corrects common syntax — Bare & becomes and, bare | becomes or, bare >=10 gains the . prefix.
3. Validates field references — Any ${name} references are checked against existing questions.
4. Detects circular dependencies — Chains like Q1 → Q3 → Q4 → Q1 are flagged and blocked.

Best Practices

• Create the hierarchy first — a form needs a workspace and a project before you can design it.
• Use the Visual Builder for simple skip logic and validation rules.
• Use Raw Expression mode or Custom Expression for complex cross-field constraints.
• Use translation labels rather than duplicating questions for each language.
• Always Preview your survey to verify logic behaves as expected.
• For mobile field data collection, test on an actual device before deploying — media capture, GPS, and barcode behave differently on-device.
• Keep constraint expressions simple — combine multiple simple rules with AND/OR rather than writing one complex expression.