# Patient Name Language-Aware Implementation

## Summary

This document describes the implementation of language-aware patient name display and LTR phone number formatting across the entire AgdarCentre project.

## Changes Made

### 1. Created Custom Template Tags (`core/templatetags/patient_tags.py`)

Created a new Django template tag library with the following components:

#### Template Tags:
- **`patient_name`**: Returns patient's full name based on current language
  - Returns `full_name_ar` when language is Arabic ('ar')
  - Returns `full_name_en` for all other languages
  
- **`patient_first_name`**: Returns patient's first name based on current language
  - Returns `first_name_ar` when language is Arabic ('ar')
  - Returns `first_name_en` for all other languages

- **`patient_last_name`**: Returns patient's last name based on current language
  - Returns `last_name_ar` when language is Arabic ('ar')
  - Returns `last_name_en` for all other languages

#### Template Filter:
- **`ltr`**: Wraps content in `<span dir="ltr">` to force left-to-right display
  - Used for phone numbers to ensure they always display LTR even in Arabic mode

### 2. Updated Template Files

**Total Files Updated: 85 templates**

The update script automatically:
1. Added `{% load patient_tags %}` to templates that reference patient data
2. Replaced all instances of `patient.full_name_en` with `{% patient_name patient %}`
3. Replaced all instances of `*.patient.full_name_en` with `{% patient_name *.patient %}`
4. Replaced combinations like `{{ patient.first_name_en }} {{ patient.last_name_en }}` with `{% patient_name patient %}`
5. Added `|ltr` filter to all phone number displays

#### Key Template Categories Updated:
- **Core templates**: patient_detail.html, patient_card.html, patient_list_partial.html
- **Appointments**: All appointment-related templates
- **Medical**: Consultation and follow-up templates
- **Nursing**: Encounter templates
- **SLP**: Assessment, intervention, and progress templates
- **OT**: Session and consultation templates
- **ABA**: Consultation and behavior tracking templates
- **Finance**: Invoice and payment templates
- **Referrals**: Referral templates

### 3. Usage Examples

#### In Templates:

```django
{% load i18n patient_tags %}

<!-- Display patient name (language-aware) -->
<h1>{% patient_name patient %}</h1>

<!-- Display phone number (always LTR) -->
<p>Phone: {{ patient.phone|ltr }}</p>

<!-- For nested patient objects -->
<p>Patient: {% patient_name appointment.patient %}</p>
<p>Phone: {{ appointment.patient.phone_number|ltr }}</p>
```

#### How It Works:

1. **English Language Selected**:
   - `{% patient_name patient %}` → Returns "John Smith" (from `full_name_en`)
   - `{{ patient.phone|ltr }}` → Returns `<span dir="ltr">+966501234567</span>`

2. **Arabic Language Selected**:
   - `{% patient_name patient %}` → Returns "جون سميث" (from `full_name_ar`)
   - `{{ patient.phone|ltr }}` → Returns `<span dir="ltr">+966501234567</span>` (still LTR)

### 4. Benefits

1. **Automatic Language Switching**: Patient names automatically display in the correct language based on user's language preference
2. **Consistent Phone Display**: Phone numbers always display left-to-right, maintaining readability
3. **Centralized Logic**: All language logic is in one place (template tags), making it easy to maintain
4. **Backward Compatible**: Falls back to English names if Arabic names are not available
5. **No Code Duplication**: Single implementation used across all 85+ templates

### 5. Testing

To test the implementation:

1. **Switch to English**:
   - Navigate to any patient page
   - Verify patient names show in English
   - Verify phone numbers display left-to-right

2. **Switch to Arabic**:
   - Change language to Arabic in the UI
   - Navigate to the same patient page
   - Verify patient names show in Arabic (if available)
   - Verify phone numbers still display left-to-right

3. **Test Locations**:
   - Patient detail page
   - Patient list
   - Appointment lists
   - Clinical records (medical, nursing, OT, SLP, ABA)
   - Financial records (invoices, payments)
   - Referrals

### 6. Files Modified

#### New Files Created:
- `core/templatetags/__init__.py`
- `core/templatetags/patient_tags.py`
- `update_patient_templates.py` (utility script)
- `test_patient_tags.py` (test script)

#### Templates Updated (85 files):
See the output from `update_patient_templates.py` for the complete list.

### 7. Maintenance Notes

- When creating new templates that display patient names, remember to:
  1. Load the template tags: `{% load patient_tags %}`
  2. Use `{% patient_name patient %}` instead of `{{ patient.full_name_en }}`
  3. Use `{{ patient.phone|ltr }}` for phone numbers

- The template tags handle `None` values gracefully, returning empty strings

### 8. Future Enhancements

Potential improvements:
1. Add similar tags for other bilingual fields (clinic names, etc.)
2. Create a template tag for caregiver names
3. Add unit tests for the template tags
4. Consider adding a context processor to make language-aware display automatic

## Conclusion

The implementation successfully makes patient names language-aware across the entire project while ensuring phone numbers always display in the correct direction. This improves the user experience for Arabic-speaking users while maintaining compatibility with English users.