# Survey Builder - Complete Guide

## Overview

The Survey Builder allows you to create fully customizable post-study surveys with multiple question types. Participants will see your survey after completing their study session (card sort, tree test, or prototype test).

## Features

### 6 Question Types

1. **Short Text** - One-line text input
   - Great for: Names, short answers, simple feedback
   
2. **Long Text (Textarea)** - Multi-line text input
   - Great for: Detailed feedback, open-ended questions, explanations
   
3. **Multiple Choice** - Select one option from a list
   - Great for: Single selection questions, demographics, preferences
   - Example: "What is your primary role?" with options like Designer, Developer, Manager
   
4. **Checkboxes** - Select all that apply
   - Great for: Multi-selection questions, feature requests, interests
   - Example: "Which features would you use?" with multiple options
   
5. **5-Star Rating** - Visual star rating (1-5)
   - Great for: Satisfaction ratings, ease of use, quick feedback
   - Interactive: Hover and click stars to rate
   
6. **Numeric Scale** - Custom range with labels
   - Great for: NPS scores, likelihood questions, intensity ratings
   - Example: 1-10 scale with "Not Likely" to "Very Likely" labels

### Key Capabilities

- **Unlimited Questions** - Add as many questions as you need
- **Required/Optional** - Mark questions as required or optional
- **Custom Options** - Define your own answer choices for multiple choice/checkbox questions
- **Flexible Scales** - Set custom min/max values and labels for numeric scales
- **Reorderable** - Questions display in the order you create them
- **Real-time Preview** - See exactly how participants will see your survey

## Getting Started

### 1. Access Survey Builder

From the **Studies** page, click the **📋 Survey** button next to any study.

### 2. Add Questions

1. Click **+ Add Question** button
2. Enter your question text
3. Select question type from dropdown
4. Configure type-specific options:
   - **Multiple Choice/Checkbox**: Add answer options (click + Add Option)
   - **Scale**: Set min/max values and optional labels
5. Check/uncheck "Required question" as needed
6. Click **Add Question** or **Save Changes**

### 3. Activate Survey

1. Check the box: "Show this survey to participants after they complete the study"
2. Click **Save Settings**

### 4. Test Your Survey

- Click **👁️ Preview Survey** to see how participants will experience it
- Complete a test study session to see the survey in action

## Managing Questions

### Edit a Question
- Click **Edit** button on any question card
- Modify text, type, or options
- Click **Save Changes**

### Delete a Question
- Click **Delete** button on any question card
- Confirm deletion (this also deletes all participant responses to that question)

### Reorder Questions
Questions display in the order created. To reorder:
1. Delete questions you want to move
2. Re-add them in the desired position

## Question Type Details

### Multiple Choice Example
```
Question: "What would you call this site?"
Type: Multiple Choice
Options:
  - Secure Site
  - Client Site  
  - Company Portal
  - Business Hub
```

### Checkbox Example
```
Question: "Select all features you'd use in a mobile app:"
Type: Checkbox (Select All That Apply)
Options:
  - Push notifications
  - Offline mode
  - Dark theme
  - Biometric login
  - Data export
```

### Scale Example
```
Question: "How likely are you to recommend this product?"
Type: Scale
Range: 0 to 10
Min Label: "Not at all likely"
Max Label: "Extremely likely"
```

### Rating Example
```
Question: "How would you rate your overall experience?"
Type: 5-Star Rating
(Displays as interactive stars: ★★★★★)
```

## Best Practices

### General Tips
- **Keep it concise** - 3-7 questions work best
- **Mix question types** - Use variety to keep participants engaged
- **Start broad, end specific** - Begin with general impressions, then dive into details
- **Make strategic questions required** - Don't make everything required

### Recommended Questions

For **Card Sorting**:
1. "Were any card labels unclear or confusing?" (Long Text)
2. "Which category was most difficult to organize?" (Multiple Choice - list your categories)
3. "What would you rename [category name]?" (Short Text)
4. "Rate your confidence in your final groupings" (5-Star Rating)

For **Tree Testing**:
1. "Which task was most difficult to complete?" (Multiple Choice - list your tasks)
2. "Were any menu labels unclear?" (Long Text)
3. "How intuitive was the navigation structure?" (Scale: 1-10)
4. "Rate your overall experience" (5-Star Rating)

For **Prototype Testing**:
1. "What was your overall impression?" (Long Text)
2. "Which features would you use regularly?" (Checkbox)
3. "How easy was it to complete the main task?" (Scale: 1-7)
4. "Rate the visual design" (5-Star Rating)

### NPS (Net Promoter Score) Template
```
Question: "How likely are you to recommend this product to a friend or colleague?"
Type: Scale
Range: 0 to 10
Min Label: "Not at all likely"
Max Label: "Extremely likely"

Question: "What is the primary reason for your score?"
Type: Long Text
Optional
```

### Customer Satisfaction Template
```
Question: "How satisfied are you with your experience?"
Type: 5-Star Rating
Required

Question: "What did you like most?"
Type: Long Text  
Optional

Question: "What could be improved?"
Type: Long Text
Optional
```

## Viewing Results

1. Go to **Reports** from the main menu
2. Select your study
3. Click **Survey Results** tab
4. View responses by:
   - Question (aggregate view)
   - Participant (individual responses)
   - Export to CSV for analysis

### Response Types in Results

- **Text/Textarea**: Full text responses listed
- **Multiple Choice**: Count and percentage per option
- **Checkbox**: Count and percentage per option (participants can select multiple)
- **Rating**: Average rating + distribution chart
- **Scale**: Average score + distribution chart

## Database Schema

### Tables Created

**survey_questions**
- Stores individual questions with type and options
- Links to study_id
- Ordered by sequence

**survey_question_responses**
- Stores individual answers to each question
- Links to survey_responses (main response record)
- Supports text, JSON (checkbox), and numeric values

## Migration & Setup

### Run Migration (One Time)

1. Navigate to: `/scripts/run_survey_builder_migration.php`
2. Log in as admin
3. Migration creates the new tables automatically
4. Backwards compatible with old survey system

### Backwards Compatibility

- Old fixed-question surveys still work
- Participants see old survey format if no new questions exist
- `survey_responses` table supports both old and new formats
- Migrate old surveys by recreating questions in builder

## Troubleshooting

### Survey Not Showing to Participants
- ✅ Check that survey is marked "Active" in settings
- ✅ Verify at least one question exists
- ✅ Complete a study session to reach the thank you page

### Questions Not Saving
- ✅ Ensure question text is not empty
- ✅ For multiple choice/checkbox, add at least one option
- ✅ For scale, ensure max value > min value
- ✅ Check browser console for API errors

### Responses Not Appearing in Results
- ✅ Verify responses are being submitted (check survey_responses table)
- ✅ Check survey_question_responses table for individual answers
- ✅ Ensure results page is querying the correct study_id

## API Endpoints

### Get Survey Questions
```
GET /public/api/survey_questions.php?study_id=X
Returns: { ok: true, questions: [...] }
```

### Create Question
```
POST /public/api/survey_questions.php
Body: {
  study_id: X,
  question_text: "...",
  question_type: "text|textarea|multiple_choice|checkbox|rating|scale",
  options: ["opt1", "opt2"], // for multiple_choice/checkbox
  scale_min: 1,              // for scale
  scale_max: 10,             // for scale
  is_required: true,
  sequence: 0
}
```

### Update Question
```
PUT /public/api/survey_questions.php
Body: { id: X, ...fields to update }
```

### Delete Question
```
DELETE /public/api/survey_questions.php
Body: { id: X }
```

### Submit Survey Response
```
POST /public/api/survey_submit.php
Body: {
  survey_id: X,
  study_id: Y,
  responses: [
    {
      question_id: 1,
      response_text: "..." // for text/textarea/multiple_choice
    },
    {
      question_id: 2,
      response_json: ["opt1", "opt2"] // for checkbox
    },
    {
      question_id: 3,
      response_value: 5 // for rating/scale
    }
  ]
}
```

## Example Surveys

### Quick Feedback (3 Questions)
1. "How easy was this task?" - 5-Star Rating - Required
2. "What worked well?" - Long Text - Optional  
3. "What was confusing?" - Long Text - Optional

### Comprehensive UX Survey (7 Questions)
1. "Rate your overall experience" - 5-Star Rating - Required
2. "How easy was it to complete your main goal?" - Scale (1-7) - Required
3. "Were any terms or labels unclear?" - Long Text - Optional
4. "What's your primary role?" - Multiple Choice - Required
5. "Which features would you use?" - Checkbox - Optional
6. "How likely are you to recommend this?" - Scale (0-10) - Required
7. "Any additional feedback?" - Long Text - Optional

### Simple NPS
1. "How likely are you to recommend this to a colleague?" - Scale (0-10) - Required
2. "What's the main reason for your score?" - Long Text - Required

---

## Need Help?

- The survey builder uses the same pattern as the Tree Test builder
- Questions are completely flexible - no hard limits
- All responses are stored and exportable
- Surveys work with all study types (card sort, tree test, prototype test)

**New in this version:**
- ✅ Unlimited custom questions (vs. fixed 5 questions)
- ✅ 6 question types (vs. text-only)
- ✅ Required/optional toggle per question
- ✅ Structured data storage for better analysis
- ✅ Visual rating widgets
- ✅ Select-all-that-apply checkboxes