# Survey Question Types Guide

This guide explains all available question types in the PX360 survey system and how they appear to patients.

## Available Question Types

The survey system supports 7 different question types:

### 1. Rating (rating)
**Description**: 1-5 star rating for measuring satisfaction levels

**How it appears to patients**:
- Shows 5 radio buttons with labels
- Options: Poor (1), Fair (2), Good (3), Very Good (4), Excellent (5)
- Only one option can be selected
- Required by default

**Best for**:
- Overall satisfaction questions
- Quality ratings (nursing care, facilities, etc.)
- Experience metrics

**Example**:
```
How would you rate the quality of nursing care?
○ Poor  ○ Fair  ○ Good  ○ Very Good  ○ Excellent
```

---

### 2. NPS (Net Promoter Score)
**Description**: 0-10 scale for measuring customer loyalty

**How it appears to patients**:
- Shows a horizontal scale from 0 to 10
- Click on the number to select
- Only one number can be selected
- Optional (can be set as required)

**Best for**:
- Net Promoter Score questions
- Likelihood to recommend
- Loyalty measurement

**Example**:
```
How likely are you to recommend our hospital to a friend?
0 1 2 3 4 5 6 7 8 9 10
```

---

### 3. Yes/No (yes_no)
**Description**: Binary yes/no question

**How it appears to patients**:
- Shows 2 radio buttons
- Options: Yes, No
- Only one can be selected

**Best for**:
- Simple binary questions
- Confirmation questions
- Experience qualifiers

**Example**:
```
Were you satisfied with the waiting time?
○ Yes  ○ No
```

---

### 4. Multiple Choice (multiple_choice)
**Description**: Select one or more options from a predefined list

**How it appears to patients**:
- Shows checkboxes for each option
- Multiple options can be selected
- Supports up to 10+ options
- Each option has bilingual labels (English/Arabic)

**Best for**:
- Selecting departments/services
- Multiple feedback categories
- Check all that apply questions

**Example**:
```
What aspects of your experience were satisfactory? (Select all that apply)
☐ Staff friendliness
☐ Cleanliness
☐ Communication
☐ Wait times
☐ Facilities
```

---

### 5. Text (text)
**Description**: Short text answer (single line input)

**How it appears to patients**:
- Shows a single-line text input field
- Character limit typically 200 characters
- Optional (usually not required)

**Best for**:
- Names
- Brief comments
- Contact information
- Short identifiers

**Example**:
```
Please provide your name:
[_________________]
```

---

### 6. Text Area (textarea)
**Description**: Long text answer (multi-line input)

**How it appears to patients**:
- Shows a multi-line textarea
- Character limit typically 1000-2000 characters
- Optional (usually not required)
- Larger input area for longer responses

**Best for**:
- Detailed comments
- Feedback explanations
- Narrative responses
- Suggestions for improvement

**Example**:
```
Please share any additional comments about your stay:
[___________________________________________]
[___________________________________________]
[___________________________________________]
```

---

### 7. Likert Scale (likert)
**Description**: 5-point agreement scale

**How it appears to patients**:
- Shows 5 radio buttons
- Options: Strongly Disagree, Disagree, Neutral, Agree, Strongly Agree
- Only one can be selected
- Required by default

**Best for**:
- Agreement measurement
- Opinion statements
- Perception questions

**Example**:
```
The staff was professional and courteous.
○ Strongly Disagree  ○ Disagree  ○ Neutral  ○ Agree  ○ Strongly Agree
```

---

## Bilingual Support

All question types support bilingual (English/Arabic) display:

- **Question Text**: Both English and Arabic versions stored
- **Answer Options**: For multiple choice, each option has both English and Arabic labels
- **Automatic Switching**: Patients see questions in their preferred language

**Example Multiple Choice with Bilingual Support**:
```
English View:
Which department did you visit?
○ Emergency
○ Outpatient
○ Inpatient
○ Surgery
○ Radiology

Arabic View:
ما هو القسم الذي زرته؟
○ الطوارئ
○ العيادات الخارجية
○ الإقامة الداخلية
○ الجراحة
○ الأشعة
```

---

## Configuration Options

Each question type can be configured with:

### Required/Optional
- **is_required**: Boolean field
- If `true`: Patient must answer to submit survey
- If `false`: Patient can skip the question

### Order
- **order**: Integer field
- Controls display sequence
- Lower numbers appear first
- Can be reordered in survey builder

### Choices (for multiple_choice)
- **choices_json**: JSON array of choice objects
- Format: `[{"value": "1", "label": "Option 1", "label_ar": "خيار 1"}]`
- Supports unlimited choices (recommended max: 10)

---

## Demo Survey Template

A demo survey template has been created with example questions:

### Template: "Patient Experience Demo Survey"
**Template ID**: 700b7897-bd02-4588-8d79-1494f1efea67

**Questions**:
1. **Text**: "Please share any additional comments about your stay"
   - Optional, allows free-form feedback

2. **Rating**: "How would you rate quality of nursing care?"
   - Required, 1-5 star rating

3. **Multiple Choice**: "Which department did you visit?"
   - Required, select one option
   - Options: Emergency, Outpatient, Inpatient, Surgery, Radiology

4. **Multiple Choice**: "What aspects were satisfactory?"
   - Optional, select multiple
   - Options: Staff, Cleanliness, Communication, Wait times, Facilities

5. **Rating**: "How would you rate hospital facilities?"
   - Required, 1-5 star rating

---

## How to View Demo Questions

1. Navigate to: http://localhost:8000/surveys/templates/
2. Find and click on: "Patient Experience Demo Survey"
3. You'll see the survey builder with all questions
4. The right panel shows a live preview of how questions appear

---

## Best Practices

### Choosing Question Types

| Use Case | Recommended Type | Why |
|----------|------------------|-----|
| Satisfaction rating | Rating | Standard 1-5 scale, easy to score |
| Recommendation likelihood | NPS | Industry standard 0-10 scale |
| Simple binary | Yes/No | Clear, quick to answer |
| Multiple selections | Multiple Choice | Flexible, supports many options |
| Brief comment | Text | Short, focused answers |
| Detailed feedback | Text Area | Allows narrative responses |
| Agreement measurement | Likert | Standard scale for opinions |

### Design Guidelines

1. **Keep it simple**: Use the simplest question type that meets your needs
2. **Be consistent**: Use the same rating scale throughout a survey
3. **Limit choices**: Multiple choice questions should have 5-7 options maximum
4. **Make required questions clear**: Patients should know which questions are mandatory
5. **Use optional text questions**: Allow patients to provide additional context

### Scoring Considerations

- **Rating, Likert**: Automatically scored (1-5 scale)
- **NPS**: Special NPS calculation (promoters - detractors)
- **Text, Text Area**: No numerical score (used for qualitative feedback)
- **Yes/No**: Can be converted to numeric (Yes=1, No=0) if needed
- **Multiple Choice**: Not scored by default (can add custom scoring logic)

---

## Technical Implementation

### Question Type Constants

```python
class QuestionType(BaseChoices):
    RATING = 'rating', 'Rating (1-5 stars)'
    NPS = 'nps', 'NPS (0-10)'
    YES_NO = 'yes_no', 'Yes/No'
    MULTIPLE_CHOICE = 'multiple_choice', 'Multiple Choice'
    TEXT = 'text', 'Text (Short Answer)'
    TEXTAREA = 'textarea', 'Text Area (Long Answer)'
    LIKERT = 'likert', 'Likert Scale (1-5)'
```

### Data Storage

Each question response is stored in a `SurveyResponse` object:

```python
class SurveyResponse(UUIDModel, TimeStampedModel):
    survey_instance = models.ForeignKey(SurveyInstance, ...)
    question = models.ForeignKey(SurveyQuestion, ...)
    
    numeric_value = models.DecimalField(...)  # For rating, NPS, Likert
    text_value = models.TextField(...)         # For text, textarea
    choice_value = models.CharField(...)      # For multiple choice, yes_no
```

---

## Related Documentation

- [Survey Builder Implementation](SURVEY_BUILDER_IMPLEMENTATION.md)
- [Survey Analytics Frontend](SURVEY_ANALYTICS_FRONTEND.md)
- [Survey Tracking Implementation](SURVEY_TRACKING_IMPLEMENTATION.md)

---

## Questions?

For questions about survey question types or implementation:
- Review the demo survey template at `/surveys/templates/`
- Check the model definitions in `apps/surveys/models.py`
- See the template files in `templates/surveys/public_form.html`
