User Guide for Polls Addon

The EventON Polls Addon extends the EventON Calendar plugin by allowing you to create interactive polls for your events. This guide walks you through setting up polls, displaying them on the EventCard, configuring settings, and understanding how poll data is stored. Designed for WordPress administrators and event organizers, this addon integrates seamlessly with EventON’s core features.

Note: Ensure you have the EventON core plugin and the Polls Addon installed and activated. Refer to addon installation for installation instructions if needed.

Adding Polls to the EventCard Designer

The EventCard in EventON displays event details on the front-end calendar. With the Polls Addon, you can add a poll field to this layout using the EventCard Designer.

Steps to Add Polls to the EventCard

1. Access the EventCard Designer:
   • Log in to your WordPress admin dashboard.
   • Navigate to EventON > Settings > EventCard > Open Eventcard Designer.
   • This opens the interactive drag-and-drop EventCard Designer introduced in EventON version 4.0 (see “How to Use the EventCard Designer“).
2. Check Available Fields:
   • At the bottom of the designer, look for the Unused EventCard Fields section.
   • After activating the Polls Addon, a new field labeled “Poll” or “Event Poll” should appear here (exact naming may vary based on addon version).
3. Add the Poll Field:
   • Click the + Add a Row button to create a new row in the EventCard layout.
   • Choose a column layout (e.g., single-column or multi-column) depending on where you want the poll to appear.
   • Click the + Set Field button in the new row.
   • From the dropdown or list, select the “Poll” field.
   • The field will now be added to your EventCard layout.
4. Customize Placement:
   • Drag the poll field to adjust its position relative to other fields (e.g., above “Event Details” or below “Location”).
   • Use the layout options to ensure it fits your design preferences.
5. Save Changes:
   • Click Save Changes at the bottom of the EventCard Designer.
   • You will need to add polls in events to see anything on frontend.

Notes

• The poll will only appear on the EventCard if a poll is created and enabled for that event (see “Creating a New Poll” below).
• If the “Poll” field doesn’t appear in the designer, ensure the Polls Addon is activated and compatible with your EventON version.

Poll Settings Box on the Event Edit Page

The Polls Addon adds a new Poll Settings meta box to the event edit page, allowing you to create and manage polls for individual events.

Accessing the Poll Settings Box

1. Go to the Event Edit Page:
   • In your WordPress admin dashboard, navigate to Events > Add New or edit an existing event under Events > All Events.
   • Scroll down below the event description editor to find the Polls box (typically located alongside other meta boxes like “Event Details” or “Tickets Settings”).
2. Overview:
   • The Poll Settings box provides fields and options to create, configure, and manage polls specific to the event.

---

Creating a New Poll

1. Create a Poll:
   • In the Poll Settings box, look for a button or link labeled “Create A New Poll”.
   • Click it to start configuring a new poll.
2. Basic Poll Fields:
   • Poll Question: Enter the question you want users to vote on (e.g., “What’s your favorite part of this event?”).
   • Poll Answers: Add multiple answer options (e.g., “Workshops,” “Networking,” “Keynote Speech”).
     • Use the “+” button to input each option.
     • Optionally, assign colors to answers for visual distinction on the front-end.
   • Poll Description (optional): Provide additional context or instructions (e.g., “Vote to let us know your likes”).
3. Save the Poll:
   • After entering the question and answers, click Create Poll or Update Poll to store the poll data.

---

Details on Poll Settings and What They Do

The Poll Settings box on the event edit page features a lightbox form with the following options:

• Who Can Vote?:
  • Field: Static display (not editable per poll).
  • Options: “Anyone can vote” (if evopo_voter_type is ‘0’) or “Only Registered Users” (if ‘1’).
  • Purpose: Indicates the global voting restriction set in EventON > Settings > Polls. If set to “Only Registered Users,” anonymous users can’t vote, and user_id must be non-zero.
• Recording User IP Address?:
  • Field: Static display.
  • Options: “Yes” (if evopo_record_ip is ‘yes’) or “No” (if not).
  • Purpose: Shows whether anonymous votes are tracked via IP (stored in vote_location). Configured globally in EventON > Settings > Polls. If “No,” anonymous votes aren’t tracked unless users log in.
• When to Show the Poll:
  • Field: Dropdown (display_type).
  • Options:
    • Always (‘def’): Poll is always visible and open for voting (default).
    • Before Event Start (‘pre’): Poll shows before the event starts and closes at the event start time.
    • During Event (‘dur’): Poll is active from event start to end (or a custom duration).
    • After Event Ends (‘post’): Poll opens after the event ends and closes after a set duration.
  • Purpose: Controls poll visibility and voting period. Also defines when the poll closes for new votes.
• Duration (Conditional):
  • Field: Duration picker (display_duration), appears if “When to Show” is ‘pre’, ‘dur’, or ‘post’.
  • Options: Days, hours, minutes (e.g., [0, 1, 0] for 1 hour), defaults to 0 (no limit).
  • Purpose: Sets how long the poll is visible relative to the selected display type:
    • ‘pre’: Duration before event start (e.g., 1 day before).
    • ‘dur’: Duration from event start (e.g., 2 hours into the event).
    • ‘post’: Duration after event end (e.g., 1 day after).
    • If 0, visibility aligns with event start/end without a custom limit.
• Poll Question:
  • Field: Text input (required).
  • Purpose: Defines the question users will vote on (e.g., “How was the event?”).
• Poll Answers:
  • Field: Dynamic multi-input with:
    • Answer Content: Text input for each answer (required, max 60 characters).
    • Option Color: Color picker for each answer’s display color.
    • Add/Remove: Buttons to add new answers or delete existing ones.
  • Purpose: Lists the voting options. Answers are stored as JSON in wp_evo_polls with a slug (s), color (c), and name (n). Colors enhance front-end visuals (e.g., result bars).
• Poll Description:
  • Field: Textarea (optional).
  • Purpose: Adds context or instructions below the question on the front-end (e.g., “Select one option”).

---

Setting Poll Results Settings

Poll results visibility is controlled via the event’s settings, not the poll itself, and is stored as event meta data.

Results Settings Options

• When to show results for the poll:
  • Default (“After Voting”): Results show only after the user votes (stored as _evopo_show_results = ‘def’).
  • After Poll Closes (“1”): Results display once the poll is closed.
  • Always (“2”): Results are always visible, even before voting.
  • Never (“3”): Results hidden from non-admins (admin-only via current_user_can(‘manage_options’)).
• Results visible duration:
  • Field: Select a duration (e.g., “1 Hour,” “1 Day”) or custom seconds.
  • Purpose: Limits how long results are visible after the poll closes (e.g., _evopo_show_results_duration = [0, 1, 0] for 1 hour).
  • Behavior: If set to “0” (0 seconds), results remain visible indefinitely post-close (for “After Poll Closes”).

Saving Results Settings

• Update the event to save these settings as event meta (e.g., _evopo_show_results and _evopo_show_results_duration).

---

How Poll Data is Saved

The Polls Addon uses two dedicated database tables to manage poll data, alongside event meta for results settings:

Poll Configuration in wp_evo_polls

• Table Structure:
  • poll_id: Unique identifier for each poll (auto-incremented).
  • event_id: The event’s post ID linking the poll to an event.
  • repeat_index: The repeat instance of the event (e.g., 0 for main event, 1 for first repeat).
  • question: The poll question text.
  • answers: JSON-encoded array of answer options (e.g., [{“s”:”slug”,”c”:”color”,”n”:”name”}, …]).
  • description: Optional poll description text.
  • display_type: Enum defining when the poll is shown (‘def’, ‘pre’, ‘dur’, ‘post’).
  • display_duration: JSON-encoded duration array (e.g., [days, hours, minutes]) for poll visibility.
  • created_at: Datetime of poll creation.
• Purpose: Stores the poll’s structure and settings. Each row represents a single poll tied to an event or its repeat instance.
• Saving Process: When you create or update a poll via the event edit page’s Poll Settings box, a row is inserted or updated in wp_evo_polls via the EVOPO_Polls::create_poll() or update_poll() methods.

Vote Data in wp_evo_votes

• Table Structure:
  • vote_id: Unique identifier for each vote (auto-incremented).
  • poll_id: References the poll in wp_evo_polls.
  • event_id: The event’s post ID.
  • user_id: Voter’s ID (default 0 for anonymous users).
  • answer_id: Index of the chosen answer (e.g., 0 for first answer).
  • repeat_index: The repeat instance (matches wp_evo_polls).
  • vote_location: IP address for anonymous voters (if evopo_record_ip is ‘yes’).
  • vote_time: Datetime of the vote.
• Purpose: Records individual votes for tallying and tracking. Each row is a single vote linked to a poll and event.
• Saving Process: When a user votes on the front-end EventCard, an AJAX call (e.g., evopo_save_vote) inserts a row into wp_evo_votes.

Results Settings in Event Meta

• Storage: wp_postmeta table, tied to the event’s post ID.
  • _evopo_show_results: Stores the visibility option (e.g., ‘def’, ‘1’, ‘2’, ‘3’).
  • _evopo_show_results_duration: Stores the duration array (e.g., [0, 1, 0] for 1 hour, processed into seconds).
• Why Event Meta?: These settings are event-specific configurations, not poll or vote data, aligning with EventON’s practice of storing options in wp_postmeta.
• Accessing: Retrieved via $EVENT->get_prop(‘_evopo_show_results’) or similar in PHP.

---

Example Workflow

1. Create a Poll:
   • Edit an event, add a poll with question “Rate this event” and answers “Great,” “Good,” “Okay.”
   • Set closing time to match the event end.
2. Configure Results:
   • Set “Show Results” to “After Poll Closes” and duration to “1 Day.”
3. Add to EventCard:
   • In EventCard Designer, add the “Poll” field below “Event Details.”
4. Front-End Behavior:
   • Users vote while the poll is open.
   • Post-close, results show for 24 hours, then hide (or expire if duration is set).
5. Poll Stats:
   • Poll final results can be viewed on front-end (If enabled to show results) or the admin can see extensive Poll Stats from event edit page in Polls settings box.

---

Troubleshooting

• Poll Not Showing: Ensure the “Poll” field is enabled in the EventCard Designer and a poll is created for the event.
• Votes Not Saving: Check wp_evo_votes for entries and verify evopo_record_ip or user login settings.
• Results Not Displaying: Confirm _evopo_show_results aligns with your intent (e.g., ‘def’ requires a vote).

For detailed support, visit docs.myeventon.com or the EventON support desk at www.myeventon.com/support.