Table of Contents

What's On – Events Plugin Documentation

Overview

What’s On is a modern, lightweight events management plugin for WordPress. It features:

  • Custom Events Post Type – Manage events separately from blog posts
  • Beautiful Layouts – Card and list view display options
  • Responsive Design – Configurable columns for mobile, tablet, and desktop
  • Lightbox Support – Event flyers and videos open in elegant lightboxes
  • Smart Filtering – Search, date range, category, and upcoming/past filters
  • Add to Calendar – One-click add to Google, Apple, Outlook, and Yahoo calendars
  • Recurring Events – Daily, weekly, bi-weekly, monthly, and yearly recurrence
  • Social Integration – Link to Facebook, Instagram, Twitter/X, and websites
  • Schema Markup – Automatic SEO-friendly structured data
  • Countdown Timers – Optional countdown display on event cards
  • Color Themes – Light, Dark, Minimal, Vibrant, or custom colors

Installation

  1. Upload the whats-on folder to /wp-content/plugins/
  2. Activate the plugin via Plugins → Installed Plugins
  3. Navigate to What’s On in your admin sidebar
  4. Start creating events!

Creating Events

Adding a New Event

  1. Go to What’s On → Add New
  2. Enter a title and description (using the standard WordPress editor)
  3. Set a Featured Image (this becomes the event card image)
  4. Fill in the event details below

Event Details

Field Required Description
Start Date Required The date the event begins
End Date Optional For multi-day events. Leave empty for single-day events.
Start Time Optional Event start time (e.g., 19:00)
End Time Optional Event end time
Venue Name Optional Name of the venue or location
Address Optional Full address (enables the Map link on event cards)
Ticket Price Optional Display text (e.g., "£20", "Free", "$25-$50")
Buy Tickets URL Optional External URL for ticket purchases
Video URL Optional YouTube or Vimeo URL (opens in lightbox)
Event Flyer Optional Upload a flyer/poster image (opens in lightbox)
Badge Text Optional Custom label (e.g., "HOT", "NEW", "FEATURED")
Badge Color Optional Custom badge background color
Show Countdown Optional Display countdown timer (days/hours) on the event card
Sold Out Optional Mark event as sold out (shows badge, disables ticket button)
Repeat Optional Recurring pattern: Daily, Weekly, Bi-weekly, Monthly, or Yearly
Social Links Optional Facebook, Instagram, Twitter/X, and Website URLs

Recurring Events

Set events to repeat automatically:

  • Daily – Every day
  • Weekly – Same day each week (select specific days)
  • Every 2 Weeks – Bi-weekly (select specific days)
  • Monthly – Same date each month
  • Yearly – Same date each year

Set a Repeat Until date to end the recurrence.

Event Badge

Add a custom badge/label to highlight events:

Field Description
Badge Text Short label to highlight the event (e.g., HOT NEW FEATURED)
Badge Color Custom background color for the badge. Use the color picker or enter a hex code (e.g., #e94560)
Show Countdown Display a countdown timer on the event card showing days and hours until the event starts. Automatically hides once the event begins.
Sold Out Mark the event as sold out. This displays a SOLD OUT badge on the event card and replaces the ticket button with a disabled "Sold Out" button.

Event Flyer

Upload a flyer/poster image that opens in a lightbox when visitors click the “Flyer” link.

Links & Social

Field Description
Video URL YouTube or Vimeo URL for a promo video. Displays a "Video" link on the event card that opens in a lightbox.
Example: https://www.youtube.com/watch?v=XXXXX
Buy Tickets URL External link for ticket purchases. When set, displays a ticket button with the price (if specified) on the event card.
Example: https://tickets.example.com/event/123
Facebook Link to Facebook event page or profile. Displays a Facebook icon in the social links area.
Example: https://facebook.com/events/123456
Instagram Link to Instagram profile or post. Displays an Instagram icon in the social links area.
Example: https://instagram.com/yourevent
Twitter/X Link to Twitter/X profile or post. Displays an X icon in the social links area.
Example: https://x.com/yourevent
Website Link to an external website. Displays a globe icon in the social links area.
Example: https://yourevent.com

Event Categories

Use the Event Categories taxonomy to organize events. Categories can be used to filter events in shortcodes and the filter bar.

Displaying Events

Quick Start
Add this shortcode to any page or post:

[whats_on]

This displays all upcoming events in card view with the default settings.

Shortcode Reference

The primary shortcode for displaying events with full filtering capabilities.

Parameters

Parameter Values Default Description
view card or list card Display layout style
limit Any number 12 Maximum number of events to load
columns 1, 2, 3, or 4 3 Number of columns in card view (desktop)
filter upcoming, past, or all upcoming Initial date filter for events
category Category slug(s) All categories Filter by category. Use comma-separated slugs for multiple categories.

Examples

Basic usage:

[whats_on]

List view with 6 events:

[whats_on view="list" limit="6"]

4-column grid showing all events:

[whats_on columns="4" filter="all"]

Only music events:

[whats_on category="music"]

Multiple categories:

[whats_on category="music,comedy,theatre"]

Past events only:

[whats_on filter="past" limit="20"]

Widget Shortcodes

Three additional shortcodes for embedding events in sidebars, footers, or anywhere you need a compact display.

What’s On Cards

[whats_on_cards]

Displays event cards (same style as main shortcode) without the filter bar.

Parameter Values Default Description
limit Any number 3 Number of events to display
columns 1 – 4 3 Number of columns to display
category Category slug(s) All Filter by category slug(s)
title Any text None Optional heading above the cards

Example:

[whats_on_cards limit="3" columns="3" title="Upcoming Events"]

What’s On List

Compact horizontal list cards with thumbnail, date, title, and venue.

[whats_on_list]
Parameter Values Default Description
limit Any number 5 Number of events to display
columns 1 – 3 1 Number of columns to display
category Category slug(s) All Filter by category slug(s)
title Any text None Optional heading above the list

Example:

[whats_on_list limit="5" title="Coming Up"]

Two-column layout:

[whats_on_list limit="6" columns="2"]

What’s On Featured

Highlights a single event in a large featured card format.

[whats_on_featured]
Parameter Values Default Description
id Event post ID Auto (next upcoming) Specific event ID to display. Leave empty for the next upcoming event.
style horizontal or vertical horizontal Layout orientation. Horizontal places image on the left, vertical stacks image on top.

Example – Next upcoming event:

[whats_on_featured]

Example – Specific event:

[whats_on_featured id="123" style="vertical"]

Gutenberg Block

The Events List block provides a visual way to add events in the block editor.

Adding the Block

  1. Open the page/post in the block editor
  2. Click the + button to add a block
  3. Search for “Events List” or find it under the Widgets category
  4. Configure settings in the right sidebar

Block Settings

Display Settings:

  • View – Card or List
  • Columns – 1-4 (card view only)
  • Number of Events – 1-50
  • Show Filter Bar – Toggle filter visibility

Filter Settings:

  • Default Filter – Upcoming, Past, or All
  • Category – Select a specific category

Settings

Access settings via What’s On → Settings in your admin menu.

Layout Settings

Setting Options Description
Image Aspect Ratio 1:1 Square
4:3 Landscape
3:4 Portrait
16:9 Widescreen
2:3 Photo 		Sets the proportions for event card images. All images are cropped to fit this ratio.
Default View Cards or List The initial view when events are loaded. Users can switch views using the toggle (if enabled).
Responsive Columns Mobile: 1 – 2
Tablet: 1 – 3
Desktop: 1 – 4 		Set how many columns to display at each screen size. Mobile is under 768px, tablet is 768-1023px, desktop is 1024px and above.
Single Event Page
Setting Options Description
Page Width Auto Inherits width from your theme (recommended)
1200px Standard content width
1400px Larger/wide content area
Full Width 100% width with side padding
Custom Enter any custom pixel value (e.g., 1600px)

Color Theme

Choose from preset themes or create your own:

Theme Primary Color Description
Light #6366f1 Clean white background with indigo accent
Dark #8b5cf6 Dark gray background with purple accent
Minimal #374151 Subtle gray tones, understated design
Vibrant #e94560 White background with coral/red accent
Custom Your choice Choose your own primary color and select light or dark background mode

Filter Bar Settings

Toggle individual filter bar components:

  • Show filter bar
  • Show “Past” filter option
  • Show card/list view toggle
  • Show search box
  • Show date range filter
  • Show category filter

Pagination

Setting Values Default Description
Events Per Page 1 – 50 6 Number of events to display before the "Load More" button appears. When clicked, the next batch of events loads dynamically without refreshing the page.

Styling & Customization

CSS Custom Properties

Override the plugin’s colors in your theme’s CSS:

				
					:root {
    --wo-primary: #6366f1;        /* Primary/accent color */
    --wo-primary-hover: #4f46e5;  /* Primary hover state */
    --wo-primary-light: #e0e7ff;  /* Primary light background */
    --wo-text: #1f2937;           /* Main text color */
    --wo-text-muted: #6b7280;     /* Secondary text color */
    --wo-border: #e5e7eb;         /* Border color */
    --wo-bg: #ffffff;             /* Background color */
    --wo-bg-alt: #f9fafb;         /* Alternate background */
    --wo-radius: 12px;            /* Border radius */
    --wo-radius-sm: 8px;          /* Small border radius */
}

CSS Classes Reference

Class Element
Containers
.wo-events Main events container wrapper
.wo-events-grid Grid container holding all event cards
.wo-view-card Applied to container when in card view mode
.wo-view-list Applied to container when in list view mode
Event Card
.wo-event-item Individual event card container
.wo-event-image Event image wrapper (contains img, badges, overlays)
.wo-event-content Event content area (title, meta, excerpt)
.wo-event-title Event title heading
.wo-event-meta Meta information row (date, time, flyer, video, map links)
.wo-event-excerpt Event description/excerpt text
.wo-event-actions Actions row (social icons, calendar dropdown, ticket button)
.wo-event-venue Venue name with location icon
Badges & Overlays
.wo-custom-badge Custom badge label (HOT, NEW, FEATURED, etc.)
.wo-sold-out-badge Sold out badge on event image
.wo-date-overlay Date box overlay on event image (day/month)
.wo-countdown Countdown timer overlay on event image
.wo-category-tag Category tag/pill
Filter Bar
.wo-filter-bar Filter bar container
.wo-filter-btn Filter button (Upcoming/Past/All)
.wo-filter-btn.active Active/selected filter button state
.wo-search-input Search input field
.wo-view-toggle Card/list view toggle container
.wo-category-select Category dropdown select
Buttons
.wo-btn Base button class
.wo-btn-primary Primary button (ticket button)
.wo-btn-secondary Secondary button (calendar dropdown)
.wo-btn-sold-out Disabled sold out button
.wo-btn-load-more Load more pagination button
Widgets
.wo-widget Widget container base class
.wo-widget-featured Featured event widget container
.wo-widget-list Compact list widget container
.wo-widget-title Widget heading/title
Single Event Page
.wo-single-event Single event page container
.wo-single-main Main content column
.wo-single-sidebar Sidebar column (date, venue, actions)
.wo-single-hero Hero image section

FAQ

How do I show only specific categories?

Use the category parameter with the category slug:

—

No events found.

Yes, uncheck “Show filter bar” in What’s On → Settings, or the filter bar won’t appear when using widget shortcodes.

Make sure you’re using a full YouTube or Vimeo URL:

  • ✓ https://www.youtube.com/watch?v=XXXXX
  • ✓ https://vimeo.com/XXXXX
  • ✗ Short URLs or embed codes

When you set an event to repeat:

  1. The original event shows the base date
  2. The calendar links and schema automatically include recurrence rules
  3. A small repeat icon appears next to the date

The plugin automatically generates links for:

  1. Google Calendar
  2. Apple Calendar (iCal download)
  3. Outlook
  4. Yahoo Calendar

Edit the event and check the Sold Out checkbox in the Event Badge section. This will:

  • Display a “Sold Out” badge on the card
  • Disable the ticket button
  • Show “Sold Out” instead of the ticket price

Yes! The plugin is fully internationalized. Translation files can be placed in /wp-content/languages/plugins/ or your theme’s languages folder.

Support