application-form-7/prompts/completed/006-add-page-navigation.md

<objective>
Add a navigation bar with progress indicator to the multi-page job application workflow, allowing users to navigate backward to previous pages to make changes while maintaining sequential forward progression.

This will improve user experience by allowing applicants to review and edit their information without losing progress, reducing form abandonment and improving data quality.
</objective>

<context>
Current state:
- 5-page workflow: email capture → personal info → motivation → upload → confirmation
- Users can only move forward through pages
- No way to go back and edit previous pages after submission
- Pages are: page1_email.html, page2_personal.html, page3_motivation.html, page4_upload.html, page5_confirmation.html
- Uses session-based application tracking with session_id
- All data persisted to YAML files in app/models.py

Target state:
- Progress indicator showing all 5 steps
- Users can click on completed steps (pages they've already visited) to go back
- Cannot skip ahead to pages they haven't reached yet
- Current page highlighted in progress bar
- Navigation preserves all previously entered data

Review the current implementation:
@app/routes.py
@templates/page2_personal.html
@templates/page3_motivation.html
@templates/page4_upload.html
</context>

<requirements>
1. **Create navigation component**:
   - Add progress bar/breadcrumb navigation to base.html or as includable partial
   - Show all 5 steps: Email → Personal → Motivation → Upload → Confirmation
   - Visually distinguish between: completed (clickable), current (highlighted), future (disabled)
   - Must be present on pages 2, 3, 4, 5 (not on page 1)

2. **Navigation behavior**:
   - **Backward navigation**: Users can click on any previously completed page to go back
   - **Forward navigation**: Sequential only - users must click "Next" buttons, cannot skip ahead
   - **Current page tracking**: Use `current_page` field in application data to determine which pages are accessible
   - **Data preservation**: All previously entered data must be preserved when navigating

3. **Visual design** (German labels):
   - Step 1: "E-Mail" (page1_email.html)
   - Step 2: "Daten" (page2_personal.html)
   - Step 3: "Motivation" (page3_motivation.html)
   - Step 4: "Dokumente" (page4_upload.html)
   - Step 5: "Bestätigung" (page5_confirmation.html)

   - Completed steps: Green checkmark + clickable link
   - Current step: Bold + highlighted background
   - Future steps: Gray + no link

4. **Implementation approach**:
   - Add navigation partial to templates/ (e.g., `_navigation.html` or add to `base.html`)
   - Pass `current_page` and `session_id` to all templates
   - Add CSS styling for progress bar (can be inline in base.html or in style.css)
   - Update route handlers to accept navigation from any completed page
   - Ensure CSRF tokens work with navigation

5. **Data handling**:
   - When user navigates backward, load existing data from YAML
   - Pre-populate forms with saved data
   - When user submits, update data and allow forward navigation
   - Don't lose uploaded files when navigating

6. **Edge cases**:
   - If user tries to access a page beyond current_page directly via URL, redirect to current page
   - If session_id is invalid, redirect to page 1
   - On page 5 (confirmation), navigation can be read-only (all steps completed)
</requirements>

<implementation>
**Suggested implementation strategy**:

1. **Create navigation component**:
   - Create `templates/_navigation.html` partial with Jinja2 template for progress bar
   - OR add navigation directly to `base.html` as a conditional block
   - Use Bootstrap-style progress steps or custom CSS

2. **Update base.html**:
   - Add navigation include or block after header
   - Only show navigation if `session_id` exists and `current_page >= 2`

3. **Update all page templates** (page2, page3, page4, page5):
   - Include navigation component at top
   - Pass `current_page`, `session_id`, `job_name` to navigation

4. **Update route handlers** in `app/routes.py`:
   - Add helper function to validate page access: `can_access_page(session_id, page_number)`
   - Add navigation routes or update existing routes to handle backward navigation
   - Ensure all routes check if user can access the requested page

5. **CSS styling**:
   - Add styles to `static/style.css` for progress bar
   - Use semantic colors: green for completed, blue/highlight for current, gray for future
   - Make clickable steps have hover effects

**Example navigation structure** (German):
```
[✓ E-Mail] → [✓ Daten] → [● Motivation] → [ Dokumente] → [ Bestätigung]
 clickable     clickable                current       disabled      disabled
```

**WHY this approach**:
- Progress indicator provides clear visual feedback on completion status
- Backward navigation allows data correction without starting over
- Sequential forward validation ensures data quality and prevents skipping required fields
- Session-based tracking already in place, just need to leverage current_page
- Preserves all existing functionality while adding navigation
</implementation>

<validation_logic>
Add helper function to check page access:

```python
def can_access_page(session_id, requested_page):
    """
    Determine if user can access the requested page.

    Rules:
    - Can always access pages <= current_page (backward navigation)
    - Cannot access pages > current_page (must progress sequentially)
    - Page 1 is always accessible
    """
    if requested_page == 1:
        return True

    app_data = load_application_data(session_id)
    if not app_data:
        return False

    current_page = app_data.get('current_page', 1)
    return requested_page <= current_page
```

Use in route handlers:
```python
@app.route('/apply/<session_id>/personal')
def page2_personal(session_id):
    if not can_access_page(session_id, 2):
        return redirect(url_for('page1_email'))
    # ... rest of handler
```
</validation_logic>

<output>
Modify the following files:

- `./templates/base.html` - Add navigation component or include statement
- `./templates/_navigation.html` (NEW) - Progress bar component (if using partial approach)
- `./templates/page2_personal.html` - Ensure navigation is displayed
- `./templates/page3_motivation.html` - Ensure navigation is displayed
- `./templates/page4_upload.html` - Ensure navigation is displayed
- `./templates/page5_confirmation.html` - Ensure navigation is displayed (read-only mode)
- `./app/routes.py` - Add `can_access_page()` helper and update route guards
- `./static/style.css` - Add navigation styling

Do NOT modify:
- Data models or storage logic
- Form validation logic
- Email functionality
- File upload logic
</output>

<verification>
Before declaring complete, verify:

1. **Visual verification**:
   - Progress bar appears on pages 2, 3, 4, 5
   - Current step is highlighted
   - Completed steps show checkmarks and are clickable
   - Future steps are grayed out and not clickable

2. **Navigation testing**:
   - From page 3, click on "Daten" → should go to page 2 with data pre-populated
   - From page 4, click on "E-Mail" → should go to page 1 with email shown
   - Try to access page 4 by typing URL when on page 2 → should redirect to page 2
   - Complete workflow and verify navigation works at each step

3. **Data preservation**:
   - Fill out page 2, go to page 3, go back to page 2 → all fields still filled
   - Upload files on page 4, go back to page 3, return to page 4 → files still there
   - Make changes on a previous page and save → changes persisted

4. **Edge cases**:
   - Invalid session_id → redirect to page 1
   - Accessing page directly via URL beyond current_page → redirect to current page
   - Page 5 navigation is read-only (all steps completed)

5. **Tests still pass**:
   - Run `pytest tests/ -v` to ensure no regressions
   - Existing tests should pass (they test form submission, not navigation)
   - Consider adding new tests for navigation behavior (optional)
</verification>

<success_criteria>
- Progress bar/breadcrumb navigation visible on pages 2-5
- Users can navigate backward to any completed page
- Users cannot skip ahead to uncompleted pages
- All previously entered data is preserved when navigating
- Current page is visually distinct in navigation
- Navigation uses German labels matching the application
- All existing functionality still works
- No test regressions
- Clean, professional styling that matches existing design
</success_criteria>
Completed: Sa 27 Dez 2025 23:11:04 CET