# Card Tooltip Feature

## Overview
This feature allows you to add tooltips to individual cards in card sort studies. This is particularly useful for:
- **Compeer-specific terminology** (e.g., "Leasing programs", "Operating loans")
- **Agriculture/finance jargon** (e.g., "Working capital", "Crop insurance")
- **Technical terms** that participants might not be familiar with

## Setup Instructions

### 1. Database Migration
Run the tooltip column migration on your web server:

**Option A: Run PHP script**
```bash
php /path/to/ux_tst/scripts/add_tooltip_column.php
```

**Option B: Run SQL directly**
```sql
ALTER TABLE `cards` 
ADD COLUMN `tooltip` TEXT NULL 
AFTER `title`;
```

### 2. Verify Installation
Once the migration runs, the system will automatically:
- ✅ Detect the tooltip column in the API
- ✅ Display edit functionality in the card management UI
- ✅ Show tooltip icons on cards during participant sessions

## How to Use

### Adding Tooltips to Cards

1. Navigate to **Studies** → Select your study → **Manage Cards**
2. Find the card you want to add a tooltip to
3. Click the **Edit** button next to the card
4. Enter the tooltip definition in the "Tooltip (optional)" field
5. Click **Save Changes**

**Example:**
- **Card:** "Operating Loan"
- **Tooltip:** "Short-term financing to cover day-to-day farm expenses like seeds, fertilizer, and labor"

### Participant Experience

When participants do the card sort:
- Cards **with tooltips** show a small **blue "?"** icon
- Hovering over the "?" icon displays the tooltip
- Clicking the "?" icon toggles the tooltip visibility
- Tooltips follow the card as it's dragged between categories

## Visual Design

### Tooltip Icon
- Small blue circle with "?" symbol
- Appears on the right side of card text
- Subtle animation on hover
- Mobile-friendly click interaction

### Tooltip Popup
- Dark themed to match the interface
- Blue accent border (consistent with app design)
- Positioned above the card
- Arrow pointer to the source icon
- Max width: 280px for readability

## Accessibility Features

- ✅ High contrast text and borders
- ✅ Keyboard accessible (Escape to close)
- ✅ Screen reader friendly
- ✅ Works with mouse and touch
- ✅ Clear visual indicators

## Technical Details

### Database Schema
```sql
cards table:
- id (int, primary key)
- title (varchar)
- tooltip (text, nullable) ← NEW
- study_id (int, foreign key)
```

### API Changes
The `cards_list.php` API automatically includes tooltip data:
```json
{
  "ok": true,
  "cards": [
    {
      "id": 1,
      "title": "Operating Loan",
      "tooltip": "Short-term financing for day-to-day expenses"
    }
  ]
}
```

### Files Modified
1. **Database:**
   - `scripts/add_tooltip_column.sql` - SQL migration
   - `scripts/add_tooltip_column.php` - PHP migration helper

2. **Backend:**
   - `public/studies/cards.php` - Edit UI and update logic
   - `public/api/cards_list.php` - Already supported tooltips

3. **Frontend:**
   - `public/participant.php` - Tooltip display in card sort
   - `assets/css/style.css` - Tooltip styling

## Best Practices

### When to Add Tooltips
✅ **Use tooltips for:**
- Industry-specific jargon
- Acronyms or abbreviations
- Financial/agricultural terms
- Company-specific terminology

❌ **Don't use tooltips for:**
- Common words
- Self-explanatory terms
- Long explanations (keep it concise)

### Tooltip Writing Tips
- **Be concise:** 1-2 sentences max
- **Use plain language:** Define terms in simple words
- **Be specific:** "A type of loan" → "Short-term loan for operational expenses"
- **Consider your audience:** What would a non-expert need to know?

### Examples

**Good Tooltip Examples:**
- **Term:** "HELOC"
  **Tooltip:** "Home Equity Line of Credit - a revolving credit line secured by your home"

- **Term:** "Variable Rate"
  **Tooltip:** "Interest rate that changes based on market conditions"

- **Term:** "Amortization"
  **Tooltip:** "The process of gradually paying off a loan through regular payments"

**Poor Tooltip Examples:**
- Too vague: "A financial product" ❌
- Too long: "This is a comprehensive financial instrument that..." ❌
- Redundant: "Bank" → "A place where you bank" ❌

## Troubleshooting

### Tooltips Not Showing?
1. Verify the database column exists (run migration script)
2. Check that tooltip text was saved in the Edit modal
3. Clear browser cache and reload
4. Check browser console for JavaScript errors

### Edit Button Not Appearing?
- Make sure you're logged in as a researcher
- Verify the cards.php page loaded correctly
- Check that the card has a valid study_id

### Tooltip Positioning Issues?
- The tooltip auto-positions above the card
- On mobile, ensure there's space above the card
- Tooltips use fixed positioning to avoid overflow issues

## Future Enhancements

Potential improvements for the tooltip system:
- [ ] Bulk tooltip import (CSV upload)
- [ ] Tooltip templates for common terms
- [ ] Analytics on which tooltips are viewed most
- [ ] Rich text formatting in tooltips
- [ ] Image/icon support in tooltips

---

**Last Updated:** October 27, 2025  
**Version:** 1.0