MyListing Show Recurring Events
The {CODICTS} MyListing Show Recurring Events plugin changes how recurring events are displayed on the explore page by expanding each recurring event into separate listing preview cards — one card per occurrence — rather than showing a single card for the entire recurring series.
By default, MyListing shows a recurring event as a single listing card regardless of how many future occurrences it has. With this plugin, a weekly event recurring for 10 weeks will appear as 10 individual cards on the explore page, each showing its own correct date. The plugin also provides a shortcode for displaying the correct date on each card, enhances Google Calendar links with listing descriptions, and orders related listings by their upcoming event date.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
On activation, the plugin automatically copies template override files to your child theme and begins working immediately. There is no settings page — the recurring event expansion, Google Calendar enhancement, and related listing date ordering all activate automatically.
Key Features
| Feature | Description |
|---|---|
| Recurring Event Expansion | Each occurrence of a recurring event is displayed as a separate listing preview card on the explore page. A weekly event with 10 future occurrences shows as 10 individual cards. |
| Date-Ordered Results | Explore page results are ordered by the computed recurring start date in ascending order — the nearest upcoming event appears first. |
| Date Shortcode | The [codicts-recurring-event-date] shortcode displays the correct date for each recurring instance on preview cards and single listing pages. |
| Google Calendar Enhancement | Automatically adds the listing’s description text to Google Calendar event details when users click “Add to Google Calendar” on single listing pages. |
| Related Listing Date Ordering | Related listings on single listing pages are automatically sorted by their next upcoming event date — the nearest future event appears first. |
| All Recurrence Types | Supports DAY, WEEK, MONTH, and YEAR repeat units, as well as one-off (non-recurring) events. Up to 100 occurrences per event. |
How It Works
Recurring Event Expansion on the Explore Page
When a user searches or browses the explore page and the listing type has recurring date filters configured, the plugin intercepts the query and expands each recurring event into individual results — one per occurrence.
| Without Plugin | With Plugin |
|---|---|
| A weekly event running for 4 weeks shows as 1 card on the explore page. | The same event shows as 4 separate cards, each with the correct date for that occurrence. |
| Results are ordered by post date or default sort. | Results are ordered by the computed recurring start date — nearest upcoming event first. |
| Users see the original start date on the card. | Each card shows the specific date for that occurrence (using the date shortcode). |
Google Calendar Enhancement
On single listing pages, the plugin automatically enriches Google Calendar “Add to Calendar” links by injecting the listing’s description and page URL into the calendar event details. This happens automatically with no configuration needed.
Related Listing Date Ordering
Related listings displayed on single listing pages are automatically sorted by their next upcoming event date instead of the order they were added. The nearest future event appears first.
Note: When this plugin is active, the manual ordering of related listings (the order you arrange them in the listing editor) is replaced by date-based ordering. Related listings are always sorted by upcoming event date.
Date Shortcode
The plugin provides the [codicts-recurring-event-date] shortcode for displaying the correct recurring event date on listing preview cards and templates. This is essential for showing each expanded card’s specific date rather than the original event start date.
Basic Usage
[codicts-recurring-event-date id="[[:id]]"]Place this shortcode inside your MyListing listing card template or single listing page template where the listing ID is available via the [[:id]] dynamic tag.
Shortcode Attributes
| Attribute | Default | Description |
|---|---|---|
id | required | The listing ID to retrieve the date from. Use MyListing’s [[:id]] dynamic tag. |
field_key | event_date | The field key of the date/event field to read from. Change this if your date field uses a different key. |
format | MMM D | The date format string using Moment.js format tokens (see table below). |
Date Format Tokens
| Token | Output | Example |
|---|---|---|
YYYY | 4-digit year | 2024 |
YY | 2-digit year | 24 |
MMMM | Full month name | January |
MMM | Abbreviated month | Jan |
MM | 2-digit month | 01 |
DD | 2-digit day | 07 |
D | Day (no leading zero) | 7 |
dddd | Full weekday name | Monday |
ddd | Abbreviated weekday | Mon |
HH | 24-hour (2-digit) | 13 |
hh | 12-hour (2-digit) | 01 |
h | 12-hour (no leading zero) | 1 |
mm | Minutes (2-digit) | 05 |
A | Uppercase AM/PM | PM |
a | Lowercase am/pm | pm |
Usage Examples
Default format (abbreviated month + day):
[codicts-recurring-event-date id="[[:id]]"]Output: Jan 15
Full date with weekday:
[codicts-recurring-event-date id="[[:id]]" format="dddd, MMMM D, YYYY"]Output: Monday, January 15, 2024
Date with time:
[codicts-recurring-event-date id="[[:id]]" format="MMM D, h:mm A"]Output: Jan 15, 2:30 PM
Using a custom date field key:
[codicts-recurring-event-date id="[[:id]]" field_key="custom_event_date" format="MM/DD/YYYY"]Output: 01/15/2024
Date range display: If the event has different start and end dates, the shortcode automatically displays both separated by a dash:
Jan 15 - Jan 17Tip: The shortcode first looks for the next upcoming occurrence of the recurring event. If no upcoming instance exists, it falls back to the most recent past instance.
Example Setup
1. Activate the plugin with the MyListing theme and a child theme active. Template files are automatically copied.
2. Create or edit a listing type that uses recurring events (e.g., “Events”). Ensure the listing type has a recurring date field (e.g., event_date) and that recurring date filters are configured in the Search Forms.
3. To display the correct date on each expanded card, edit your listing type’s preview card template and add the date shortcode:
[codicts-recurring-event-date id="[[:id]]" format="ddd, MMM D"]4. Create a test event listing. Set it as a weekly recurring event for the next 4 weeks.
5. Visit the explore page. Instead of seeing one card for the event, you’ll see 4 separate cards — one for each weekly occurrence — ordered by date with the nearest date first. Each card shows its specific occurrence date (e.g., “Mon, Jan 8,” “Mon, Jan 15,” “Mon, Jan 22,” “Mon, Jan 29”).
6. Visit the single listing page. If the listing has a Google Calendar button, clicking it now pre-fills the calendar event with the listing’s description and page URL.
7. If the listing has related listings that are also events, those related listings are now sorted by their next upcoming event date — nearest first.
Frequently Asked Questions
Does this require a child theme?
Yes. The plugin copies template override files into the child theme directory. Without a child theme, the plugin cannot install its templates and will show an error notice.
Is there a settings page?
No. The plugin works automatically once activated. The only configurable aspect is the date shortcode’s attributes (id, field_key, format).
Why do I see duplicate listing cards on the explore page?
This is the intended behavior. Each occurrence of a recurring event is displayed as a separate card. A weekly event with 4 future occurrences shows as 4 separate cards, each with the correct date for that specific occurrence.
How do I display the correct date on each card?
Use the [codicts-recurring-event-date] shortcode in your listing card template. For example: [codicts-recurring-event-date id="[[:id]]" format="MMM D"]. The shortcode reads the date from each card and formats it accordingly.
Can I customize the date format?
Yes. Use the format attribute with Moment.js format tokens. For example, format="dddd, MMMM D, YYYY" displays “Monday, January 15, 2024.” See the Date Format Tokens table for all available options.
How many recurring occurrences can the plugin handle?
Up to 100 occurrences per event per query. Events with more than 100 recurrences will not display all instances.
What recurrence types are supported?
The plugin supports DAY, WEEK, MONTH, and YEAR repeat units, as well as one-off (non-recurring) events. All recurrence types configured in MyListing’s event date fields are handled automatically.
What does the Google Calendar enhancement do?
On single listing pages, the plugin automatically adds the listing’s description text and page URL to the “Add to Google Calendar” link. When users click it, the calendar event is pre-filled with this information. This happens automatically with no configuration.
Why are my related listings sorted by date instead of my custom order?
The plugin overrides the related listing ordering to sort by upcoming event date — the nearest future event appears first. This replaces the manual item order. This is by design to ensure the most relevant upcoming events are shown first.
Will this conflict with other plugins that modify the explore page?
It may conflict with plugins that also modify the explore listings query handler. Since this plugin replaces MyListing’s default explore handler, other plugins hooking into the same system may not work as expected.
What happens to the template files when I deactivate the plugin?
The plugin removes its template override files from the child theme. MyListing reverts to its default templates automatically. Reactivating copies them again.
Does the plugin affect single listing pages?
The recurring event expansion only affects the explore page. Single listing pages are not modified except for the Google Calendar enhancement and the date shortcode (both of which work on single listing pages).
Does the plugin create any database tables?
No. The plugin reads from existing MyListing tables and stores a single value in the options table to track the installed template version.
Troubleshooting
Recurring Events Not Expanding on the Explore Page
| Cause | Solution |
|---|---|
| No recurring date filters configured | The listing type must have recurring date filters set up in the Search Forms for the plugin to intercept the query. Verify your listing type’s search form configuration includes a recurring date filter. |
| Event not set as recurring | The listing must have a recurring event date field with a repeat unit (DAY/WEEK/MONTH/YEAR) and a repeat end date configured. One-off events (repeat unit “NONE”) will show as a single card. |
| Plugin not activated | Go to Plugins → Installed Plugins and verify the plugin is active. |
| MyListing or child theme not active | Both the MyListing theme and a child theme must be active. Check Appearance → Themes. |
Dates Not Displaying on Preview Cards
| Cause | Solution |
|---|---|
| Shortcode not added to card template | You must add the [codicts-recurring-event-date id="[[:id]]"] shortcode to your listing type’s preview card template for dates to appear on each card. |
| Wrong field key | Ensure the field_key attribute matches your event date field’s key. The default is event_date. If your field uses a different key, specify it: field_key="your_field_key". |
| Moment.js not loaded | The date formatting requires Moment.js, which is loaded by the MyListing theme. If another plugin or customization has dequeued Moment.js, dates cannot be formatted. |
Date Shortcode Showing Wrong Date
| Cause | Solution |
|---|---|
| Wrong field key | Verify the field_key attribute matches the exact key of your recurring date field in the listing type configuration. |
| No upcoming instances | If all occurrences are in the past, the shortcode falls back to the most recent past instance. This is expected behavior. |
| Format tokens incorrect | Ensure you’re using valid Moment.js format tokens. For example, use YYYY for 4-digit year (not yyyy). See the Date Format Tokens table. |
Google Calendar Link Not Enhanced
| Cause | Solution |
|---|---|
| No Google Calendar button | The enhancement only works on single listing pages that have an “Add to Google Calendar” button. Verify your listing type includes this feature. |
| No description block | The plugin reads the listing description from the description content block on the single listing page. If no description block is present, the enhancement is skipped. |
| Not on a single listing page | The Google Calendar enhancement only works on single listing pages, not on the explore page. |
Related Listings Not Sorted by Date
| Cause | Solution |
|---|---|
| Template files missing | Deactivate and reactivate the plugin to re-copy the template override files to the child theme. |
| Related listings are not events | The date-based ordering only applies to related listings that have event date fields with data in the events table. Non-event related listings may not sort as expected. |
| No upcoming dates | The ordering filters to future dates. If all related listings have only past events, they may not appear or may appear in an unexpected order. |
Performance Issues on the Explore Page
| Cause | Solution |
|---|---|
| Many recurring events | The recurring event expansion involves complex database queries. Sites with many events or long recurrence periods may experience slower query times. Monitor database performance and consider limiting recurrence periods. |
| High occurrence count | Events with very long recurrence periods (up to 100 occurrences) generate more result rows. Shorter recurrence periods or fewer events will improve performance. |
Template Overwrite Warning
The following template files in your child theme are managed by this plugin and will be overwritten on activation and updates:
includes/src/forms/fields/related-listing-field.php
includes/src/queries/related-listings.phpDo not customize these files directly — changes will be lost when the plugin updates or reinstalls templates.
“MyListing Theme Not Detected” or “Child Theme Not Detected” Error
The MyListing theme and a child theme must both be installed and active. Go to Appearance → Themes to verify.
For further support, visit codicts.com or contact us at support@codicts.com.