MyClub/DOCS/POLL_INTEGRATION_GUIDE.md

# Poll Integration Guide

## Adding Polls to Articles, Events, and Videos

The poll system now supports linking polls to specific content (articles, events, videos), allowing you to create contextual polls that appear embedded within your content.

### Quick Start

#### 1. Create a Poll in Admin Panel

Navigate to `/admin/ankety` and create a new poll:

1. Fill in basic information (title, description, options)
2. **Link to Content**: In the "Basic" tab, scroll to "Propojení s obsahem"
   - **For Article**: Enter the article ID (from `/admin/clanky`)
   - **For Event**: Enter the event ID (from `/admin/aktivity`)
   - **For Video**: Enter the YouTube video URL or ID

Example configurations:

```typescript
// Man of the Match poll for a specific match article
{
  title: "Hráč zápasu",
  related_article_id: 123, // Article ID from database
  options: [...]
}

// Event feedback poll
{
  title: "Jak se vám líbilo?",
  related_event_id: 456, // Event ID
  options: [...]
}

// Video reaction poll
{
  title: "Co si myslíte o videu?",
  related_video_url: "https://youtu.be/abc123", // or just "abc123"
  options: [...]
}
```

#### 2. Polls Automatically Appear in Content

Once linked, polls will automatically display:

- **Articles**: At the end of article content (before newsletter CTA)
- **Events**: At the end of event details
- **Videos**: Can be added to video detail pages

### Implementation Details

#### Article Integration

Polls appear automatically in `ArticleDetailPage.tsx`:

```tsx
{/* Embedded Poll - shows polls related to this article */}
{data?.id && <EmbeddedPoll articleId={data.id} />}
```

#### Event/Activity Integration

Polls appear automatically in `ActivityDetailPage.tsx`:

```tsx
{/* Embedded Poll - shows polls related to this event */}
{data?.id && <EmbeddedPoll eventId={data.id} />}
```

#### Video Integration

To add polls to specific videos, use the `EmbeddedPoll` component:

```tsx
import EmbeddedPoll from '../components/polls/EmbeddedPoll';

// In your video component
<EmbeddedPoll 
  videoUrl="https://youtu.be/abc123"
  title="Co si myslíte?"
  showTitle={true}
/>
```

### EmbeddedPoll Component API

```typescript
interface EmbeddedPollProps {
  articleId?: number;        // Link to article by ID
  eventId?: number;          // Link to event by ID
  videoUrl?: string;         // Link to video by URL/ID
  title?: string;            // Custom title (default: "Hlasování")
  showTitle?: boolean;       // Show/hide title (default: true)
}
```

### Finding Content IDs

#### Article IDs
1. Go to `/admin/clanky`
2. Click on an article to edit
3. The ID is in the URL: `/admin/clanky?edit=123` → ID is `123`

#### Event IDs
1. Go to `/admin/aktivity`
2. Click on an event to edit
3. The ID is in the URL or shown in the interface

#### Video URLs
Use the full YouTube URL or just the video ID:
- Full: `https://youtu.be/abc123`
- Short: `abc123`

### Use Cases

#### 1. Post-Match Article Poll

After publishing a match report article, create a "Man of the Match" poll:

```typescript
{
  title: "Kdo byl hráčem zápasu?",
  related_article_id: 456,  // Match report article ID
  type: "single",
  status: "active",
  end_date: "2025-10-15T23:59:59", // Close after 24 hours
  options: [
    { text: "Jan Novák", player_id: 12 },
    { text: "Petr Svoboda", player_id: 23 }
  ]
}
```

#### 2. Event Feedback Poll

After a club event, get feedback:

```typescript
{
  title: "Jak se vám akce líbila?",
  related_event_id: 789,
  type: "single",
  show_results: "after_end",
  options: [
    { text: "Výborné! 😍" },
    { text: "Dobré 👍" },
    { text: "Průměrné 😐" },
    { text: "Mohlo být lepší 👎" }
  ]
}
```

#### 3. Video Reaction Poll

Get reactions to training videos or highlights:

```typescript
{
  title: "Pomohlo vám toto video?",
  related_video_url: "https://youtu.be/dQw4w9WgXcQ",
  type: "single",
  options: [
    { text: "Ano, velmi! 🎯" },
    { text: "Trochu 📝" },
    { text: "Ne příliš 🤔" }
  ]
}
```

### API Endpoints for Fetching Polls

You can also fetch polls programmatically using the API:

```typescript
import { getPolls } from '../services/polls';

// Get polls for specific article
const articlePolls = await getPolls({ article_id: 123 });

// Get polls for specific event
const eventPolls = await getPolls({ event_id: 456 });

// Get polls for specific video
const videoPolls = await getPolls({ video_url: "abc123" });
```

### Multiple Polls Per Content

You can link multiple polls to the same content. They will all display in the embedded section (max 3 polls shown at once).

Example: For a match article, you could have:
1. Man of the Match poll
2. Match prediction poll (before match)
3. Match rating poll (after match)

### Styling and Customization

The `EmbeddedPoll` component uses your theme colors and automatically adapts to dark/light mode. It's fully responsive and works on all devices.

### Tips

1. **Create polls before publishing content** - This ensures they appear immediately when users view the content
2. **Set appropriate end dates** - Auto-close polls after a reasonable timeframe
3. **Use player linking** - For MOTM polls, link options to player records for rich display
4. **Monitor results** - Check `/admin/ankety` for real-time statistics
5. **Multiple content types** - A single poll can be linked to article AND event if it's relevant to both

### Troubleshooting

**Poll not showing up?**
- Check the poll status is "active"
- Verify the content ID is correct
- Ensure poll dates (if set) include current time
- Check browser console for errors

**Wrong polls appearing?**
- Double-check the IDs in the admin panel
- Clear browser cache
- Verify only one type of relationship is set (don't mix article_id with event_id)

---

**Need Help?**
Refer to `POLL_SYSTEM_IMPLEMENTATION.md` for complete system documentation.