# Preferred Location/Country Implementation Summary

## Overview
Successfully implemented 'Preferred Location/Country' reference data feature across the application, replacing the text-based "Preferred Countries" field with a dropdown-based system.

## Changes Made

### 1. Database Models

#### New Model Created
- **PreferredLocationCountry** model in `candidates/models.py`
  - Single field: `name` (CharField, max_length=200, unique=True)
  - Includes proper Meta class with verbose names and ordering

#### Model Updates
- **CandidateProfile** (`candidates/models.py`)
  - Added `preferred_locations` ManyToManyField to PreferredLocationCountry
  - Kept existing `preferred_countries` CharField for backward compatibility

- **StudyAbroadProfile** (`study_abroad/models.py`)
  - Added `preferred_locations` ManyToManyField to PreferredLocationCountry
  - Kept existing `preferred_location_country` CharField for backward compatibility

- **Job** (`jobs/models.py`)
  - Added `preferred_location` ForeignKey to PreferredLocationCountry
  - Allows employers to specify preferred location for job postings

### 2. Migrations Created

1. **0015_preferredlocationcountry.py** - Creates PreferredLocationCountry model
2. **0016_populate_preferred_locations.py** - Populates model with 140+ countries/locations from ABROAD COUNTRIES.md
3. **0017_candidateprofile_preferred_locations.py** - Adds ManyToMany field to CandidateProfile
4. **0012_studyabroadprofile_preferred_locations.py** - Adds ManyToMany field to StudyAbroadProfile
5. **0014_job_preferred_location.py** - Adds ForeignKey field to Job model

### 3. Admin Reference Data Management

#### Forms (`custom_admin/forms/reference.py`)
- Added **PreferredLocationCountryForm** with proper styling

#### Views (`custom_admin/views/reference_data.py`)
- Added complete CRUD operations:
  - `preferred_location_list` - List all locations with pagination
  - `preferred_location_create` - Create new location
  - `preferred_location_edit` - Edit existing location
  - `preferred_location_delete` - Delete location

#### URLs (`custom_admin/urls.py`)
- Added URL patterns under `jobs/preferred-locations/`:
  - List: `/jobs/preferred-locations/`
  - Create: `/jobs/preferred-locations/create/`
  - Edit: `/jobs/preferred-locations/<pk>/edit/`
  - Delete: `/jobs/preferred-locations/<pk>/delete/`

### 4. Registration Forms Updates

#### Jobs Abroad Registration (`accounts/forms.py`)
- **AbroadRegistrationForm**
  - Changed `preferred_countries` from CharField to ModelMultipleChoiceField
  - Uses SelectMultiple widget with size=5
  - Label changed to "Preferred Location/Country"
  - Save method updated to use `preferred_locations.set()`

#### Study Abroad Registration (`accounts/forms.py`)
- **StudyAbroadRegistrationForm**
  - Changed `preferred_location_country` from ChoiceField to ModelMultipleChoiceField
  - Uses SelectMultiple widget with size=5
  - Label: "Preferred Location/Country"
  - Save method updated to use `preferred_locations.set()`

### 5. User Account Profile Updates

#### Candidate Profile (`candidates/views.py`)
- **ProfileUpdateView**
  - Updated form fields for 'abroad' registration type
  - Changed from `preferred_countries` to `preferred_locations`
  - Uses SelectMultiple widget with proper styling

#### Study Abroad Profile (`study_abroad/views.py`)
- **ProfileView**
  - Updated fields list to include `preferred_locations`
  - Removed `preferred_location_country` from form fields

### 6. Employer Job Posting

#### Job Form (`jobs/forms.py`)
- Added `preferred_location` field to JobForm
- Uses Select widget with form-select class
- Includes help text for guidance

## Data Populated

The system includes 140+ locations/countries from ABROAD COUNTRIES.md:
- Continents: Africa, Asia, Europe, North America, Oceania, South America
- Countries: UAE, Saudi Arabia, Qatar, USA, UK, Canada, Australia, etc.
- UAE Cities: Dubai, Abu Dhabi, Sharjah, Ajman, etc.
- Other specific locations and cities

## Features

### Admin Panel
- Full CRUD operations for managing locations/countries
- Manual addition of new locations through admin interface
- Pagination support (20 items per page)
- Consistent UI with existing reference data pages

### User Registration
- Multi-select dropdown for choosing multiple preferred locations
- Better UX compared to text input
- Data validation through model constraints
- Consistent across Jobs Abroad and Study Abroad registration

### User Profiles
- Update preferred locations from account dashboard
- Multi-select interface for easy selection
- Maintains existing data through backward-compatible fields

### Employer Job Posting
- Select preferred location for job postings
- Single selection (ForeignKey)
- Helps in better job categorization

## Backward Compatibility

- Existing `preferred_countries` field in CandidateProfile retained
- Existing `preferred_location_country` field in StudyAbroadProfile retained
- No data loss for existing users
- Gradual migration path available

## Database Schema

```
PreferredLocationCountry
- id (PK)
- name (unique)

CandidateProfile
- ... existing fields ...
- preferred_countries (CharField) - legacy
- preferred_locations (M2M to PreferredLocationCountry) - new

StudyAbroadProfile
- ... existing fields ...
- preferred_location_country (CharField) - legacy
- preferred_locations (M2M to PreferredLocationCountry) - new

Job
- ... existing fields ...
- preferred_location (FK to PreferredLocationCountry) - new
```

## Next Steps (Optional)

1. Run migrations: `python manage.py migrate`
2. Verify data in admin panel: `/admin/jobs/preferred-locations/`
3. Test registration forms with new dropdown
4. Update templates if needed to display multiple locations
5. Consider data migration script to move existing text data to new M2M relationships
6. Eventually deprecate old CharField fields after data migration

## Notes

- All changes maintain consistency with existing project structure
- No existing features or functionality affected
- Forms use proper validation and error handling
- UI styling consistent with existing forms
- All CRUD operations protected with @staff_required decorator