upload

DOCS/POLL_INTEGRATION_GUIDE.md

@@ -0,0 +1,226 @@
+# 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.