# User-Created Categories Tracking

## Overview
The system now tracks and displays user-created categories in card sorting studies, making it clear which categories were created by participants versus predefined categories.

## What Was Implemented

### 1. Database Table
A new table `user_created_categories` was created to track:
- Which study the category was created in
- Which session created it
- The category name
- When it was created
- Team session ID (if created during team sorting)

**SQL Migration File:** `scripts/user_created_categories_setup.sql`

### 2. API Endpoint
**New File:** `public/api/log_custom_category.php`

This endpoint logs whenever a participant creates a custom category during card sorting. It prevents duplicate logging and validates the session.

### 3. Participant Interface Updates
**Updated File:** `public/participant.php`

Two places where users can create categories now log to the database:
- **Standard Card Sort:** When clicking "Add" button for new categories
- **Visual Navigation Builder:** When clicking "+ Add Navigation Category"

Both interfaces now call the logging API when a custom category is created.

### 4. Enhanced Reports
**Updated File:** `public/reports/cardsort.php`

The card sort analysis report now shows:

#### New Metric Card
- Displays count of user-created categories
- Shows with a ✨ sparkle icon

#### Card Agreement Section
- Each card now shows if its top category was user-created
- Displays "✨ Created by X participant(s)" badge
- Helps identify consensus on custom vs. predefined categories

#### Category Usage Section
- Shows which categories are user-created vs. predefined
- User-created: "✨ Created by X participant(s)"
- Predefined: "📋 Predefined"

#### Distribution Pills
- Alternative category placements are highlighted if user-created
- Gold border and background with sparkle icon

## Visual Indicators

### Color Coding
- **User-Created Categories:** Gold/amber (#ffc107) with sparkle icon ✨
- **Predefined Categories:** Muted gray with clipboard icon 📋

### What You'll See
Instead of just seeing "Non-Nav Option: 1", you now see:
- **Category name:** Non-Nav Option
- **Badge:** "✨ Created by 1 participant"

This makes it immediately clear that:
1. It's a custom category (not predefined)
2. How many participants independently created this same category name
3. Whether there's emerging consensus around this label

## How It Works

### During Card Sorting
1. Participant types a new category name
2. Clicks "Add" button
3. Category appears on screen
4. System logs the creation to the database

### In Reports
1. System fetches all predefined categories from `categories` table
2. System fetches user-created categories with creator counts
3. Each category in the report is checked against both lists
4. Appropriate badge/indicator is displayed

## Benefits

### For Researchers
- **Identify Emerging Patterns:** See which custom categories multiple participants independently created
- **Validate IA:** Check if user-created categories align with or differ from predefined ones
- **Measure Discoverability:** High agreement on user-created categories may indicate missing predefined options
- **Data-Driven Decisions:** Use creation frequency to inform information architecture

### For Analysis
- Distinguish between consensus on predefined categories vs. user innovation
- Track how many participants felt existing categories were insufficient
- Identify common language patterns in user-generated labels

## Database Setup

Run this SQL in phpMyAdmin:

```sql
-- Copy from scripts/user_created_categories_setup.sql
CREATE TABLE IF NOT EXISTS `user_created_categories` (
  `id` INT(11) NOT NULL AUTO_INCREMENT,
  `study_id` INT(11) NOT NULL,
  `session_id` INT(11) NOT NULL,
  `team_session_id` INT(11) NULL,
  `category_name` VARCHAR(255) NOT NULL,
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_study_id` (`study_id`),
  KEY `idx_session_id` (`session_id`),
  KEY `idx_team_session_id` (`team_session_id`),
  KEY `idx_category_name` (`category_name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

## Example Report Display

### Before
```
Category Usage
- Non-Nav Option: 15 cards
```

### After
```
Category Usage
- Non-Nav Option: 15 cards
  ✨ Created by 3 participants
```

This immediately tells you that 3 different participants independently came up with "Non-Nav Option" as a category label, suggesting it might be meaningful terminology for your users.

## Technical Details

### Files Modified
1. `includes/schema.php` - Added `user_created_categories` to allowed tables
2. `public/participant.php` - Added logging calls for category creation
3. `public/reports/cardsort.php` - Enhanced display with user-created indicators

### Files Created
1. `scripts/user_created_categories_setup.sql` - Database migration
2. `public/api/log_custom_category.php` - Logging API endpoint
3. `documentation/USER_CREATED_CATEGORIES_GUIDE.md` - This file

### Backward Compatibility
- If the table doesn't exist yet, reports gracefully handle the missing data
- Existing studies work without any issues
- No data loss if you don't run the migration immediately

## Next Steps

1. **Run the SQL migration** in phpMyAdmin
2. **Start a new card sort session** and create a custom category
3. **View the report** to see the new indicators
4. **Analyze patterns** in user-created categories

## Notes

- Team sessions currently use predefined categories only
- Preview mode doesn't log category creation
- Duplicate categories from the same session are not logged twice
- The sparkle icon (✨) is the universal indicator for user-created content