Add to Calendar for Listeo: Developer Guide

Scope

This guide is for developers extending Add to Calendar for Listeo from a child theme, site plugin, or mu-plugin. It covers real rendering paths, data sources, shortcodes, filters, ICS downloads, and safe override points.

Runtime requirements

• WordPress 5.8 or newer.
• PHP 7.4 or newer.
• Listeo Core active. The plugin does not initialize frontend/admin classes if Listeo_Core is missing.
• Listings stored as the listing post type.
• Event data stored in Listeo listing meta.

Important files

Constants and options

• LISTEO_ATC_VERSION, LISTEO_ATC_PATH, LISTEO_ATC_URL, LISTEO_ATC_BASENAME.
• listeo_atc_enabled: global frontend enable flag.
• listeo_atc_button_text: default button label.
• listeo_atc_button_position: after_title, sidebar, before_content, after_content, or shortcode.
• listeo_atc_show_icon: button icon flag.
• listeo_atc_button_style: primary, secondary, or minimal.
• listeo_atc_show_google, listeo_atc_show_apple, listeo_atc_show_outlook, listeo_atc_show_office365, listeo_atc_show_yahoo, listeo_atc_show_ics: provider visibility flags.
• listeo_atc_listing_types: allowed Listeo listing types, default event.

Event data model

Listeo_Calendar_Generator reads event data from listing post meta and WordPress post data.

Rendering paths

Listeo hook mapping

Shortcodes and helpers

[listeo_add_to_calendar listing_id="123" button_text="Save Event" show_icon="true"]
[listeo_atc_archive limit="20" listing_type="event"]

<?php
listeo_add_to_calendar_button(123, [
    'button_text' => 'Save Event',
    'show_icon' => true,
]);

$html = get_listeo_add_to_calendar_button(123);
?>

ICS downloads

The plugin registers the rewrite rule ^calendar/([^/]+)\.ics$ and maps it to the query var listeo_calendar_download. Public download URLs look like this:

/calendar/event-slug.ics?t=generated-token

The token is generated with HMAC from the listing ID and WordPress AUTH_KEY. Invalid tokens return 403. Missing listings or missing event data return 404.

The legacy AJAX action listeo_download_ics exists for backward compatibility and redirects to the clean URL after nonce validation.

Supported filters

Safe override examples

Load assets on a custom event landing page:

add_filter('listeo_atc_enqueue_assets', function (bool $enqueue): bool {
    return $enqueue || is_page('events');
});

Hide the button for one listing:

add_filter('listeo_atc_show_button', function (bool $show, int $listing_id): bool {
    if ($listing_id === 123) {
        return false;
    }

    return $show;
}, 10, 2);

Change the sidebar widget title and icon:

add_filter('listeo_atc_sidebar_title', function (string $title, int $listing_id): string {
    return 'Save This Event';
}, 10, 2);

add_filter('listeo_atc_sidebar_icon_class', function (string $class, int $listing_id): string {
    return 'fa-regular fa-calendar-check';
}, 10, 2);

Change button copy from a site plugin:

add_filter('listeo_atc_button_args', function (array $args, int $listing_id): array {
    $args['button_text'] = 'Save to Calendar';
    return $args;
}, 10, 2);

Frontend JavaScript

The dropdown script listens for clicks on .listeo-add-to-calendar-btn, moves the dropdown to a portal when needed, handles keyboard navigation, closes on outside click, and dispatches listeo:calendar_add after a provider link is selected.

document.addEventListener('listeo:calendar_add', function (event) {
    console.log(event.detail);
});

Debugging checklist

1. Confirm Listeo_Core exists and the plugin initialized.
2. Confirm the listing post type is listing.
3. Check _event_date and verify the date format can be parsed.
4. Check _listing_type and the listeo_atc_listing_types option.
5. Confirm at least one provider option is enabled.
6. Confirm frontend assets are enqueued on the current page.
7. Test the clean ICS URL and check for 403 token errors or 404 event data errors.
8. Temporarily switch Button Position to Shortcode only and render a known listing by ID.

Do not customize here

• License activation and deactivation AJAX handlers.
• License key/status options or remote validation responses.
• Plugin update checker callbacks.
• HMAC token validation for ICS downloads.
• ICS output escaping and CRLF injection protections.
• Any code that grants paid behavior to an unlicensed site.