# Visual Navigation Builder Feature Guide

## Overview
The Visual Navigation Builder is an innovative card sorting display mode that allows participants to build a navigation menu in real-time by dragging cards onto navigation bar categories. This provides a more interactive and visual way to conduct card sorting studies.

## Features

### Two Display Modes for Card Sorting

1. **Standard Card Sort** (Traditional)
   - Cards displayed in a horizontal scrollable container at the top
   - Categories shown in a grid layout below
   - Participants drag cards into category boxes

2. **Visual Navigation Builder** (NEW!)
   - Navigation bar displayed at the top (looks like a real website nav)
   - Cards shown in a grid container below
   - Participants drag cards onto nav categories
   - Dropdown menus appear and build in real-time
   - Hover over categories to see their items
   - More engaging and intuitive for navigation-related studies

## Setup Instructions

### 1. Run the Database Migration

First, add the `display_mode` column to your studies table:

```bash
# Option 1: Using PHP script
php scripts/add_display_mode_column.php

# Option 2: Using SQL directly
mysql -u your_user -p your_database < scripts/add_display_mode_column.sql
```

### 2. Create or Edit a Card Sort Study

1. Go to **Studies** → **Create Study** or edit an existing card sort study
2. Select **Study Type**: "Card Sort Study"
3. Choose **Card Sort Type**: Open, Closed, or Hybrid
4. Select **Display Mode**:
   - **Standard Card Sort**: Traditional layout
   - **Visual Navigation Builder**: Interactive navigation menu builder
5. Add your cards and categories (if using closed/hybrid sort)

### 3. Best Practices

#### When to Use Visual Navigation Builder
- Testing website navigation structures
- Information architecture studies for menus
- Organizing content for dropdown navigation
- Creating intuitive navigation hierarchies
- More engaging for non-technical participants

#### When to Use Standard Card Sort
- General categorization tasks
- Traditional card sorting studies
- When you want a simple, proven interface
- Studies comparing with previous research

## How It Works

### For Participants

1. **Welcome Screen**: Instructions explain the visual navigation concept
2. **Navigation Bar**: Appears at top with category labels (like a real website)
3. **Card Container**: Shows all available cards in a grid below
4. **Drag & Drop**: 
   - Drag cards from bottom onto navigation categories
   - Watch items appear in dropdown menus
   - Hover over categories to see sorted items
   - Drag items back to unsorted area to reorganize
5. **Real-Time Preview**: Navigation menu builds as they sort

### For Researchers

- **Same Data Format**: Records card-to-category assignments just like standard mode
- **Same Reports**: Use existing card sort reports and analysis
- **No Code Changes**: Switch between modes without changing your workflow

## Technical Details

### Files Modified
- `scripts/add_display_mode_column.php` - Migration script
- `scripts/add_display_mode_column.sql` - SQL migration
- `public/studies/create.php` - Added display mode selector
- `public/studies/edit.php` - Added display mode selector
- `public/participant.php` - Added visual nav rendering function
- `assets/css/style.css` - Added visual nav styles

### Database Schema
```sql
ALTER TABLE `studies` ADD COLUMN `display_mode` VARCHAR(20) NOT NULL DEFAULT 'standard' AFTER `sort_type`;
```

Values:
- `'standard'` - Traditional card sort layout
- `'visual_nav'` - Visual navigation builder

### CSS Classes
- `.visual-nav-builder` - Main container
- `.visual-nav-bar` - Navigation bar wrapper
- `.visual-nav-categories` - Category list
- `.visual-nav-category` - Individual category
- `.visual-nav-dropdown` - Dropdown menu
- `.visual-cards-container` - Cards container
- `.visual-card` - Individual card element

## Benefits

### User Experience
- **More Intuitive**: Participants immediately understand they're building navigation
- **Visual Feedback**: See the menu structure as it's created
- **Engaging**: More interactive than traditional card sorting
- **Real-World Context**: Looks like an actual navigation menu

### Research Benefits
- **Better Context**: Participants understand the end goal
- **Higher Engagement**: More fun and interactive experience
- **Same Data**: Compatible with existing analysis methods
- **Flexible**: Switch modes based on study needs

## Troubleshooting

### Display mode option not showing
- Run the migration script to add the `display_mode` column
- Refresh your browser cache

### Cards not dragging properly
- Check browser console for JavaScript errors
- Ensure modern browser with drag-and-drop support
- Try clearing browser cache

### Categories not accepting drops
- Verify categories exist in the database
- Check that sort_type is set correctly (open/closed/hybrid)

## Future Enhancements

Potential additions:
- Multi-level navigation (sub-menus within sub-menus)
- Visual customization options
- Mobile-optimized touch interactions
- Accessibility improvements for screen readers

## Support

For issues or questions:
1. Check browser console for errors
2. Verify migration ran successfully
3. Test with sample study first
4. Compare with standard mode for data consistency

---

**Version**: 1.0  
**Created**: October 2025  
**Compatibility**: Works with all existing card sort features (open, closed, hybrid, tooltips, surveys)