🐚 WEB SHELL ACTIVATED

📁 File Browser

Current directory: /home/klas4s23/domains/585455.klas4s23.mid-ica.nl/public_html/Gastenboek/uploads

📄 Viewing: ./../../l7-pro-2-e-learning-2023-Epolleke/database/../docs/BIDIRECTIONAL_PRACTICE.md

# Bidirectional Translation & Custom List Practice - Feature Documentation

## Overview
Enhanced the practice functionality to support:
1. **Bidirectional Translation**: Practice translating from English to Dutch OR Dutch to English
2. **Custom List Selection**: Practice with your own word lists or default words

## New Features

### 1. Translation Direction Selection
Users can now choose which direction they want to practice:
- **English → Dutch** (default): See English words, answer in Dutch
- **Dutch → English**: See Dutch words, answer in English

This helps users practice both:
- Production (translating from native to target language)
- Comprehension (translating from target to native language)

### 2. Word Source Selection
Choose where to practice from:
- **Default Words**: All 64 words from the database (organized by categories)
- **Custom Lists**: Your own word lists (requires login)

### 3. Dynamic List Loading
- When logged in, custom lists automatically populate the dropdown
- Shows word count for each list
- Only lists owned by the user are available for practice

## User Interface Changes

### Practice Settings Panel
Added new controls to `index.html`:

1. **Word Source Dropdown**
   - Default: "Default Words"
   - "Custom Lists" (enabled only when logged in)

2. **List Selection Dropdown** (conditional)
   - Appears only when "Custom Lists" is selected
   - Shows all user's lists with word counts
   - Replaces category selection

3. **Translation Direction** (Radio Buttons)
   - English → Dutch
   - Dutch → English
   - Visual feedback for selected option

4. **Updated Labels**
   - "Translate this word to Dutch:" or "Translate this word to English:"
   - Dynamic placeholder text in answer input

## Backend Changes

### New API Endpoint: `get_practice_words.php`

**Purpose**: Unified endpoint for fetching practice words from either default words or custom lists

**Parameters**:
- `source` (required): "default" or "list"
- `list_id` (required if source=list): ID of the custom list
- `category` (optional, default words only): Filter by category
- `difficulty` (optional): Filter by difficulty level
- `limit` (optional, default=10): Number of words to fetch

**Example Requests**:
```php
// Get 10 beginner words from default
GET /php/get_practice_words.php?source=default&difficulty=beginner&limit=10

// Get 5 words from custom list
GET /php/get_practice_words.php?source=list&list_id=5&limit=5

// Get words from category 3
GET /php/get_practice_words.php?source=default&category=3&limit=15
```

**Response Format**:
```json
{
    "success": true,
    "words": [
        {
            "word_id": 1,
            "english_word": "computer",
            "dutch_translation": "computer",
            "difficulty_level": "beginner",
            "category_name": "Technology"
        }
    ],
    "count": 5
}
```

## Frontend Logic Changes

### App State (app.js)
Added new properties:
- `translationDirection`: Tracks current direction ('en-nl' or 'nl-en')
- `userLists`: Array of user's custom lists

### New Functions

1. **`loadUserLists()`**
   - Fetches user's word lists from `get_lists.php`
   - Filters to show only owned lists
   - Called when user authentication is confirmed

2. **`populateListSelect()`**
   - Populates the list dropdown with user's lists
   - Shows list name and word count

3. **Updated `startPractice()`**
   - Reads translation direction from radio buttons
   - Determines source (default vs custom list)
   - Builds query with appropriate parameters
   - Calls `get_practice_words.php` instead of `get_words.php`

4. **Updated `displayWord()`**
   - Checks `translationDirection` to determine which word to show
   - Updates prompt text dynamically
   - Changes placeholder text accordingly
   - Shows "Custom List" if no category_name

5. **Updated `checkAnswer()`**
   - Determines correct answer based on direction
   - For custom lists: validates locally (no server call)
   - For default words: calls server for progress tracking
   - Supports both answer formats

### Event Listeners

1. **Source Selection Change**
   - Shows/hides list dropdown or category dropdown
   - Toggles between filtering options

## CSS Styling

### Radio Button Styling
Added modern radio button design in `style.css`:

```css
.radio-group {
    display: flex;
    gap: 1rem;
}

.radio-label {
    display: flex;
    align-items: center;
    cursor: pointer;
    padding: 0.5rem 1rem;
    border: 2px solid var(--border-color);
    border-radius: 8px;
    transition: all 0.3s ease;
}

.radio-label:hover {
    border-color: var(--primary-color);
}

.radio-label:has(input[type="radio"]:checked) {
    border-color: var(--primary-color);
    background: var(--bg-color);
}
```

## Usage Examples

### Practicing English to Dutch (Default)
1. Select "Default Words"
2. Choose category (e.g., "Animals")
3. Select difficulty "Beginner"
4. Keep "English → Dutch" selected
5. Set number of words: 10
6. Click "Start Practice Session"
7. See English words, type Dutch translations

### Practicing Dutch to English
1. Select any source
2. Choose "Dutch → English" radio button
3. Click "Start Practice Session"
4. See Dutch words, type English translations

### Practicing with Custom List
1. Must be logged in
2. Select "Custom Lists"
3. Choose a list from dropdown (e.g., "Medical Terms")
4. Choose translation direction
5. Click "Start Practice Session"
6. Practice with your custom words

## Technical Implementation Details

### Translation Direction Logic
```javascript
// In displayWord()
if (this.translationDirection === 'nl-en') {
    questionWordEl.textContent = word.dutch_translation;
    promptEl.textContent = 'Translate this word to English:';
    inputEl.placeholder = 'Type your answer in English...';
} else {
    questionWordEl.textContent = word.english_word;
    promptEl.textContent = 'Translate this word to Dutch:';
    inputEl.placeholder = 'Type your answer in Dutch...';
}
```

### Answer Validation
```javascript
// In checkAnswer()
const correctAnswer = this.translationDirection === 'nl-en' 
    ? word.english_word 
    : word.dutch_translation;

const isCorrect = answer.toLowerCase() === correctAnswer.toLowerCase();
```

### Progress Tracking
- Default words: Server tracks progress via `check_answer.php`
- Custom lists: Local validation only (no database tracking)

## Benefits

### For Learners
- ✅ Practice in both directions for better retention
- ✅ Focus on specific topics with custom lists
- ✅ Flexible learning paths
- ✅ Immediate feedback in both modes

### For Instructors
- ✅ Create targeted vocabulary sets
- ✅ Share public lists for specific lessons
- ✅ Track progress on standard curriculum

## Testing

### Manual Testing Checklist
- [x] Translation direction toggle works
- [x] List dropdown shows/hides correctly
- [x] Custom lists load when logged in
- [x] Practice works with default words
- [x] Practice works with custom lists
- [x] English → Dutch translation validated
- [x] Dutch → English translation validated
- [x] Feedback shows correct answer format
- [x] Progress tracking works for default words

### Test Scenarios

**Scenario 1: Guest User**
- Source dropdown shows "Custom Lists (Login Required)" disabled
- Can only use default words
- Both translation directions work

**Scenario 2: Logged-in User**
- Custom Lists option enabled
- Lists populate in dropdown
- Can practice with own lists
- Both directions work with custom lists

**Scenario 3: Empty List**
- Shows appropriate error message
- Returns to settings panel

## Browser Compatibility
- ✅ Chrome/Edge (latest)
- ✅ Firefox (latest)
- ✅ Safari (latest)
- ✅ Mobile browsers

## Performance Notes
- Lists cached in `App.userLists` after first load
- Random word selection in SQL (efficient)
- Minimal server calls for custom lists

## Future Enhancements
- [ ] Speech recognition for pronunciation practice
- [ ] Timed mode (speed challenge)
- [ ] Spaced repetition algorithm
- [ ] Mix custom and default words
- [ ] Export practice results
- [ ] Leaderboard for public lists

---
**Implementation Date**: November 19, 2025
**Status**: ✅ Complete and Tested

🎯 Available Actions