# Setting Up Card Sort Tooltips

## Prerequisites
- Your study needs to be set up with cards
- Database access to run the migration

## Setup Steps

### 1️⃣ Add the Database Column

Run this SQL command on your database:

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

**Or execute the migration file:**
- File location: `scripts/add_card_tooltips_column.sql`
- Use your database client (phpMyAdmin, MySQL CLI, etc.) to run it

**Verify it worked:**
```sql
DESCRIBE cards;
-- You should see a "tooltip" column in the output
```

### 2️⃣ Add Tooltips to Your Study Cards

1. Log in as a researcher
2. Go to your study
3. Click "Manage Cards" 
4. In the "Existing Cards" section, you'll see new buttons next to each card:
   - **"+ Add Tooltip"** - Click to add a tooltip
   - **"📝 Edit Tooltip"** - Click to edit an existing tooltip

5. Click the button to open the tooltip editor
6. Write your tooltip text explaining the term:
   ```
   Example: "Compeer Financial provides cooperative financing 
   specifically for agricultural and rural businesses"
   ```
7. Click "Save Tooltip"

### 3️⃣ Publish Your Study

Once you've added tooltips to relevant cards:
1. Save your study configuration
2. Make the study "Active" (visible to participants)
3. Share the study link with participants

### 4️⃣ Participants See the Tooltips

When participants take the study:
- Cards with tooltips show a small **"ℹ"** icon
- Participants click the card or icon to see the tooltip
- The tooltip appears above the card with the explanation
- They can continue sorting as normal

## Best Practices

### When to Use Tooltips
✅ **DO use tooltips for:**
- Industry-specific terms (Compeer, Ag lending, rural development)
- Acronyms (FLPs, FSA, USDA)
- Specialized finance concepts (collateral, equity, cash flow)
- Terms unfamiliar to general audiences
- Domain expertise required to understand

❌ **DON'T use tooltips for:**
- Common everyday words
- Concepts explained in study instructions
- Long explanations (keep it brief!)
- Definitions already in the card title

### Tooltip Writing Tips
- **Keep it short** - 1-2 sentences maximum
- **Be clear** - Write for your target audience
- **Define terms** - Don't assume knowledge
- **Avoid jargon** - Explain complex terms simply
- **Be consistent** - Use similar style across all tooltips

## Example Tooltips

### Agricultural Terms
- "Ag lender" → "A financial institution that specializes in providing loans to agricultural businesses and farmers"
- "Cooperatives" → "Member-owned organizations where farmers pool resources and share profits"
- "Rural development" → "Initiatives and financing aimed at improving economic conditions in rural communities"

### Compeer-Specific
- "Compeer Financial" → "A cooperative organization providing credit and financing specifically for agriculture and rural businesses"
- "Lender" → "At Compeer, a loan professional who works with agricultural businesses"
- "Agricultural credit" → "Specialized financing for farming operations and agricultural equipment"

### Finance Terms
- "Equity" → "The portion of a business that is owned by the owner after all debts are paid"
- "Collateral" → "Assets (like equipment or land) pledged as security to back up a loan"
- "Cash flow" → "The movement of money into and out of a business during a specific time period"

## Testing Your Setup

### For Researchers
1. Go to card management page
2. Verify "Add Tooltip" and "Edit Tooltip" buttons appear
3. Test adding a tooltip to a card
4. Verify button changes to "Edit Tooltip" after saving
5. Test editing and updating the tooltip

### For Participants (Preview Mode)
1. Preview the study as a researcher
2. Look for "ℹ" icons on cards with tooltips
3. Click the icon or card to reveal the tooltip
4. Verify tooltip displays correctly
5. Click elsewhere to close
6. Complete a few card moves to verify no conflicts
7. Finish the sort to confirm everything works

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Add Tooltip" button doesn't appear | Run the SQL migration to add the tooltip column to your database |
| Error when saving tooltip | Check database column exists: `DESCRIBE cards;` |
| Tooltips don't show for participants | Verify tooltip was saved, refresh browser, check browser console |
| Tooltip styling looks wrong | Clear browser cache (Ctrl+Shift+Delete), verify CSS file is loaded |
| Tooltip covers other cards | This is expected on mobile - participants can swipe/scroll as needed |

## Technical Details

- **Database column**: `cards.tooltip` (TEXT, nullable)
- **API endpoint**: `/public/api/cards_list.php` (includes tooltip data)
- **CSS classes**: `.tooltip-icon`, `.tooltip-box`
- **No API changes**: Works with existing card sort API
- **Fully backward compatible**: Studies without tooltips work normally

## Getting Help

For detailed technical information, see:
- `TOOLTIP_IMPLEMENTATION.md` - Complete technical guide
- `TOOLTIP_QUICK_START.md` - Quick reference
- `TOOLTIP_IMPLEMENTATION.md` - Troubleshooting section