Hooks & Filters

Community Listings provides a comprehensive set of hooks and filters to let developers extend and customize the plugin without modifying its source code.

Filters

cl_default_image_{ category_slug }

Override the default fallback image for a specific category. The category slug is appended to the filter name (e.g., cl_default_image_food-dining).

add_filter( 'cl_default_image_food-dining', function( $image_url ) {
    return get_template_directory_uri() . '/images/custom-food.svg';
} );

cl_listing_types

Modify the registered listing types. Use this to add custom listing types beyond "visual" and "structured".

add_filter( 'cl_listing_types', function( $types ) {
    $types['premium'] = array(
        'label'    => __( 'Premium Listing', 'my-theme' ),
        'template' => 'listing-premium.php',
    );
    return $types;
} );

cl_categories

Modify the default category list that is created on activation.

add_filter( 'cl_categories', function( $categories ) {
    $categories[] = array(
        'name' => __( 'Education', 'my-theme' ),
        'slug' => 'education',
        'type' => 'structured',
    );
    return $categories;
} );

cl_listing_query_args

Modify the WP_Query arguments used to fetch listings in shortcodes and blocks.

add_filter( 'cl_listing_query_args', function( $args, $atts ) {
    // Only show listings from the current month
    $args['date_query'] = array(
        array(
            'after'     => '1 month ago',
            'inclusive' => true,
        ),
    );
    return $args;
}, 10, 2 );

cl_listing_card_html

Filter the final HTML output for an individual listing card (visual listings).

add_filter( 'cl_listing_card_html', function( $html, $post_id, $type ) {
    // Add a badge for featured listings
    if ( get_post_meta( $post_id, '_cl_featured', true ) ) {
        $badge = '<span class="cl-badge">Featured</span>';
        $html  = str_replace( '<div class="cl-listing-card">',
                              '<div class="cl-listing-card">' . $badge, $html );
    }
    return $html;
}, 10, 3 );

cl_submit_form_fields

Add, remove, or modify fields in the frontend submission form.

add_filter( 'cl_submit_form_fields', function( $fields, $category ) {
    // Add a custom "Hours of Operation" field
    $fields['hours'] = array(
        'label'    => __( 'Hours of Operation', 'my-theme' ),
        'type'     => 'textarea',
        'required' => false,
        'meta_key' => '_cl_hours',
    );
    return $fields;
}, 10, 2 );

cl_notification_email

Customize the admin notification email sent when a new listing is submitted.

add_filter( 'cl_notification_email', function( $email, $listing_id ) {
    $email['subject'] = 'New Listing: ' . get_the_title( $listing_id );
    $email['headers'][] = 'CC: manager@example.com';
    return $email;
}, 10, 2 );

cl_allowed_mime_types

Control which file types are allowed for image uploads in the frontend submission form.

add_filter( 'cl_allowed_mime_types', function( $types ) {
    $types['webp'] = 'image/webp';
    return $types;
} );

Actions

cl_before_listings

Fires before the listings grid is rendered. Useful for adding custom markup, search forms, or filter UI.

add_action( 'cl_before_listings', function( $atts ) {
    echo '<div class="my-custom-filter-bar">';
    // Custom filter UI
    echo '</div>';
} );

cl_after_listings

Fires after the listings grid is rendered. Useful for adding pagination, CTAs, or supplementary content.

add_action( 'cl_after_listings', function( $atts ) {
    echo '<p><a href="/submit/">Add your listing</a></p>';
} );

cl_listing_submitted

Fires after a new listing is successfully submitted via the frontend form. Useful for integrations, analytics, or additional notifications.

add_action( 'cl_listing_submitted', function( $listing_id, $user_id ) {
    // Log submission to external service
    wp_remote_post( 'https://api.example.com/webhook', array(
        'body' => array(
            'listing_id' => $listing_id,
            'title'      => get_the_title( $listing_id ),
        ),
    ) );
}, 10, 2 );

cl_listing_approved

Fires when an admin approves (publishes) a pending listing. Useful for sending confirmation emails to the submitter.

add_action( 'cl_listing_approved', function( $listing_id ) {
    $user_id = get_post_meta( $listing_id, '_cl_submitted_by', true );
    $user    = get_user_by( 'id', $user_id );
    if ( $user ) {
        wp_mail( $user->user_email, 'Your listing has been approved!',
            'Your listing "' . get_the_title( $listing_id ) . '" is now live.' );
    }
} );

cl_before_submit_form

Fires before the submission form is rendered. Use for adding instructions or notices.

cl_after_submit_form

Fires after the submission form is rendered.

Quick Reference Table