# Card Tooltips - Quick Start Guide

## What's New
You can now add tooltips to cards to explain Compeer-specific or agriculture/finance-specific terms to your study participants.

## Step 1: Database Migration (One-time)
Run this SQL command on your database to add the tooltip column:

```sql
ALTER TABLE `cards` ADD COLUMN `tooltip` TEXT NULL DEFAULT NULL AFTER `title`;
```

**Or use the migration script:**
```
scripts/add_card_tooltips_column.sql
```

## Step 2: Add Tooltips to Your Cards

1. Go to your study's card management page
2. In the "Existing Cards" section, you'll see new buttons:
   - **"+ Add Tooltip"** - for cards without tooltips yet
   - **"📝 Edit Tooltip"** - for cards that already have tooltips

3. Click either button to open the tooltip editor
4. Enter your tooltip text (e.g., "Compeer provides financing specifically for agricultural and rural businesses")
5. Click "Save Tooltip"

## Step 3: Participants See Tooltips

When participants do the card sort:
- Cards with tooltips display a small **"ℹ"** icon
- Participants click the card or icon to see the tooltip
- The tooltip appears above the card
- Clicking elsewhere closes the tooltip

## Example Tooltips

**For Compeer terms:**
- "Compeer Financial - A cooperative organization providing financing to agricultural and rural businesses"
- "Ag lender - Financial institution that specializes in agricultural loans"
- "Rural development - Programs and financing aimed at improving economic conditions in rural areas"

**For Finance terms:**
- "Equity - Ownership stake or net worth in a business"
- "Collateral - Assets pledged as security for a loan"
- "Cash flow - Movement of money in and out of a business"

## Files Changed

- `public/api/cards_list.php` - API now includes tooltip data
- `public/studies/cards.php` - Researcher tooltip management interface
- `public/participant.php` - Tooltip display for participants
- `assets/css/style.css` - Tooltip styling
- `scripts/add_card_tooltips_column.sql` - Database migration

## No Breaking Changes

✅ Tooltips are completely optional
✅ Existing studies work without modification
✅ Database column is nullable
✅ API gracefully handles databases without tooltip column
✅ All existing functionality preserved

## Troubleshooting

**Buttons not showing?**
- Run the SQL migration to add the tooltip column
- Refresh the page

**Tooltips not appearing for participants?**
- Make sure you saved the tooltips
- Check browser console for errors (F12)
- Verify cards are being loaded with API

**Need help?**
- Check `TOOLTIP_IMPLEMENTATION.md` for technical details
- Review CSS classes if styling looks wrong
- Check database to confirm column was added: `DESCRIBE cards;`