Developers / CalendarWP

Hook reference

These hooks are present in core 1.0.58-rc27. Parameter lists below are in callback order. The first parameter of a filter is the value you must return. Paths identify files in the editable source package, not public web endpoints.

Upcoming Events

Source: includes/packages/class-rhc-package-upcoming-events.php.

Occurrence rows contain post_id, event_start, event_end, allday and number. $now and $horizon are date objects from the query. Preserve those fields if filtering rows. The renderer checks public visibility after the occurrence filter; that does not make arbitrary replacement HTML or metadata safe.

Example: add a public note to each matching card

add_filter( 'calendarwp_upcoming_events_item_meta', 'acme_cwp_card_note', 10, 4 );

function acme_cwp_card_note( $meta, $event_id, $occurrence, $attributes ) {
    $note = get_post_meta( $event_id, '_acme_cwp_public_note', true );
    if ( is_array( $meta ) && is_string( $note ) && '' !== trim( $note ) ) {
        $meta[] = '<span class="acme-cwp-note">' . esc_html( $note ) . '</span>';
    }
    return $meta;
}

The note must be explicitly public. This example reads an existing field; it does not create an editor control or save handler. The complete example add-on adds those pieces.

Event and term overlays

Source: includes/REST/class-rhc-rest.php.

$post is a WP_Post; $term is a WP_Term. Overlay occurrence context is resolved by the REST controller and is not the same contract as an Upcoming Events index row. Do not copy an assumed timestamp format between them. Append escaped content or return the original content unchanged. These filters change overlays, not every single-event template.

Public event knowledge

Source: includes/class-calendarwp-event-knowledge.php.

calendarwp_event_knowledge_public_sections( $sections, $event_id ) returns an array keyed by a stable, prefixed identifier. Each item must contain non-empty title and text strings.

add_filter( 'calendarwp_event_knowledge_public_sections', 'acme_cwp_knowledge', 10, 2 );

function acme_cwp_knowledge( $sections, $event_id ) {
    $note = get_post_meta( $event_id, '_acme_cwp_public_note', true );
    if ( is_array( $sections ) && is_string( $note ) && '' !== trim( $note ) ) {
        $sections['acme-public-note'] = array(
            'title' => __( 'Visitor note', 'acme-calendarwp-note' ),
            'text'  => wp_strip_all_tags( $note ),
        );
    }
    return $sections;
}

The core checks public-event eligibility before collection. Your callback is still responsible for contributing only public facts. Do not include remaining capacity, attendee records, credentials or instructions for the AI to follow. Knowledge is reference data, not a system prompt, and adding a fact does not guarantee its use in every answer.

Ordinary event metadata changes queue refreshes. When an external source owned by your add-on changes public facts across events, signal do_action( 'calendarwp_public_knowledge_changed' ); once after the actual change, not on every page load. The listener in includes/class-calendarwp-knowledge-builder.php restarts a bounded background scan. No callback arguments are required.

Occurrence updates

calendarwp_event_occurrences_updated( $event_id ) is an action emitted after occurrence regeneration in includes/class-rhc-save-post-generate-event-meta.php.

Use it to invalidate your own derived data or enqueue bounded work. It can run repeatedly for an event. Make handlers idempotent and avoid updating the same event recursively. It is not a booking-confirmation event.

Add-on registration

calendarwp_options_addons_registry( $addons ) returns add-on definitions keyed by an ID. See includes/admin/class-rhc-admin-options.php and Build an add-on.

Use a unique ID rather than replacing a built-in entry. Built-in commercial entries retain their package and entitlement metadata; installed add-ons can augment their navigation links but cannot redefine those catalog rules through this filter.

Advanced boundaries

Other hooks exist, including integration-provider registration, options schemas and permission filters. Their presence alone is not a complete integration contract. This guide intentionally does not provide examples that bypass event visibility, licensing or booking locks. Verify the corresponding source and tests before depending on those internals.