EVC Contest Form Plugin Documentation

Plugin Name: EVC Contest Form
Author: Anthony Acosta
Version: 1.7
License: GPL2
Compatibility: WordPress 5.9+ (tested up to WP 6.5+)

🧩 Overview

The EVC Contest Form plugin allows Entravision news and radio sites to easily create and manage giveaways and promotional contests via a shortcode-based form. Submissions are stored in a custom table, viewable and filterable in the WordPress admin panel.

Built for TV and radio campaigns, this plugin supports:

  • Custom contest titles and client branding
  • Optional photo uploads and story entries
  • Email notifications to contest admins
  • Admin dashboard widget
  • Random winner selection tool
  • Duplicate entry removal
  • GDPR-style data consent

⚙️ Features

✅ Shortcode-Based Contest Form

Shortcode Format:

[evc_contest_form 
    title="Your Contest Title"
    keyword_of_the_day="true"
    tell_us_your_story="true"
    show_photo_upload="true"
    client_name="Acme Corp"]

Parameters:

AttributeDescriptionDefault
titleDisplay name of the contest(required)
keyword_of_the_dayAdds a text input for daily keywordfalse
tell_us_your_storyAdds a textarea for contest storiesfalse
show_photo_uploadEnables photo upload to the Media Libraryfalse
client_nameOptional label for sponsor/client name(blank)

🏁 Winner Selector Shortcode

Shortcode Format:

[evc_pick_winner contest="Your Contest Title" show_count="true"]

Behavior:

  • Displays total number of entries (optional)
  • Shows a large “Pick Winner” button
  • Visually “flashes” names randomly for 3–5 seconds
  • Displays randomly selected entry (name + city)
  • Offers a “Pick Another Winner” option
  • Winner pool is tracked per page load to avoid repeats

🛡️ Admin Settings Page

Location: Settings → EVC Contest Settings

Fields:

  • Contest Admin Email: Who receives new entry notifications
  • Remove Duplicates: One-click button that:
    • Deduplicates entries by email per contest
    • Retains only the first (earliest) submission per email

🗃️ Admin Dashboard Widget

Provides quick access to:

  • View entries
  • Shortcode instructions
  • Publishing checklist

📥 Admin Entries Viewer

Location: Contest Entries in admin menu

Features:

  • Filter by contest title
  • View name, email, city, phone, keyword, story, client
  • Links to uploaded photos
  • Select and delete multiple entries
  • Print filtered entries
  • Bulk deduplication via settings

Permissions: Only users with edit_others_posts can access

📤 Email Notifications

  • Sent to the contest admin email (from settings)
  • Includes all submitted data
  • Supports custom message formatting
  • Emails are triggered only on successful submission

📸 Photo Uploads

  • Files are saved to the Media Library
  • Uses media_handle_upload() to integrate natively with WordPress
  • Shown in admin list as a “View” link

🧪 Data Privacy

  • Uses terms_accepted checkbox (required)
  • Optional data_sharing_consent for photo/story uploads
  • Fully sanitized and validated:
    • sanitize_text_field(), sanitize_email(), sanitize_textarea_field()
    • Uses $wpdb->prepare() for DB safety

🛠️ Installation

  1. Upload plugin ZIP via WP admin or extract into /wp-content/plugins/evc-contest-form/
  2. Activate the plugin
  3. Visit Settings → EVC Contest Settings to:
    • Set your contest admin email
    • Use the “Remove Duplicates” tool if needed
  4. Add [evc_contest_form ...] to a Page or Post

🧼 Code Structure

  • Database Table: wp_evc_contest_entries
    • Created via register_activation_hook
  • Includes:
    • partials/form-html.php for HTML form template
  • Main Functions:
    • evc_handle_form_submission() – handles form POST
    • evc_contest_entries_callback() – renders admin list
    • evc_render_pick_winner_shortcode() – renders randomizer
    • evc_handle_remove_duplicates() – removes duplicates by email

💡 Tips for Editors

  • Use clear contest titles for easy filtering
  • If running similar contests, vary titles slightly to keep data clean
  • Remind users to confirm their email address to avoid disqualification
  • Only pick winners from the list when all entries are verified

📦 Developer Notes

  • Fully uses WordPress APIs (no external libraries)
  • Sanitized and escaped per WordPress standards
  • Custom DB table avoids cluttering WP posts/comments
  • Supports future expansion via:
    • REST API endpoints
    • Gutenberg block integration
    • CSV export functions

📞 Support & Maintenance

This plugin is maintained by:
Anthony Acosta – anthonyacosta.me
For requests, updates, or additional customizations, please contact directly.