Customizing & Hooks

For developers extending Best Classifieds. Reference list of every action and filter the theme + Pro plugin expose, plus the recommended customization pattern (child theme or small custom plugin).

Recommended approach

Don’t edit the theme directly

Edits to /wp-content/themes/best-classifieds/ get wiped when the theme updates. Use one of these instead:

Pattern	When to use
Child theme	You’re overriding template files (single.php, archive.php, etc.) or adding template-parts
Small custom plugin	You’re adding hooks, filters, custom post types, REST endpoints. Most customizations belong here.
Code Snippets plugin	One-off filter tweaks, no version control needed

Child theme starter

/wp-content/themes/best-classifieds-child/
├── style.css         (Template: best-classifieds)
├── functions.php     (load parent's main stylesheet)
└── single.php        (your override; copy from parent and edit)

style.css:

/*
Theme Name:  Best Classifieds Child
Template:    best-classifieds
Version:     1.0.0
*/

functions.php:

<?php
add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_style( 'best-classifieds-parent', get_template_directory_uri() . '/style.css' );
} );

Theme action hooks

Hook	Position	Args	Purpose
`best_classifieds_before_header`	Before site header	—	Inject announcement bars
`best_classifieds_after_header`	After site header	—	Inject sticky promos
`best_classifieds_after_card_image`	After listing card image	`$post_id`	Add badges to cards (Pro adds Featured/Verified)
`best_classifieds_after_card_meta`	After listing card meta	`$post_id`	Add favorite button (Pro does this)
`best_classifieds_after_listing_image`	After single listing’s main image	`$post_id`	Add gallery thumbnails (Pro)
`best_classifieds_after_listing_content`	After single listing’s description	`$post_id`	Add map, similar listings (Pro)
`best_classifieds_after_listing_sidebar`	After single listing’s sidebar info card	`$post_id`	Add messaging widget, reviews (Pro)
`best_classifieds_listing_actions`	Inside sidebar info card	`$post_id`	Replace default contact buttons (Pro adds Message Seller)
`best_classifieds_before_footer`	Before site footer	—	Inject newsletter signup, ad slots

Theme filters

Filter	Default	Purpose
`best_classifieds_listing_post_type`	`post`	Override the post type used for listings
`best_classifieds_listings_category_slug`	`listings`	Slug of the parent “Listings” category
`best_classifieds_post_ad_url`	customizer value	The “Post Free Ad” button URL (Pro filters this)
`best_classifieds_pro_active`	false	True if a Pro license is active (Pro overrides)
`best_classifieds_is_listing`	derived	Whether a given post should be rendered as a listing
`best_classifieds_price_html`	formatted	Final HTML for the price display
`best_classifieds_currency_code`	`USD`	ISO currency code for schema.org JSON-LD
`best_classifieds_currency_symbol`	`$`	Symbol used in price formatting
`best_classifieds_color_palettes`	2 palettes	Add custom palettes
`best_classifieds_category_icon`	mapping	Per-slug Tabler icon
`best_classifieds_smart_icon_keywords`	mapping	Keyword → icon for smart search results
`best_classifieds_search_post_types`	listing PT	Post types included in live search
`best_classifieds_search_listings_limit`	8	Listings returned by live search
`best_classifieds_search_categories_limit`	4	Categories returned by live search
`best_classifieds_homepage_categories_args`	get_terms args	Modify the homepage Categories grid query

Pro plugin filters

Filter	Purpose
`best_classifieds_submission_post_args`	Modify post args before insert (frontend submission)
`best_classifieds_submission_validate`	Add custom validation rules
`best_classifieds_submission_locked_fields`	Lock fields after publish
`best_classifieds_after_submission`	React to a successful submission (action)
`best_classifieds_dashboard_tabs`	Add/remove dashboard tabs
`best_classifieds_visible_custom_fields`	Filter which custom fields render
`best_classifieds_render_custom_field`	Custom HTML for a specific field
`best_classifieds_message_strip_patterns`	Regex patterns to strip from messages
`best_classifieds_payment_gateways`	Register new gateways (PayPal, Square, etc.)
`best_classifieds_payment_amount`	Modify amount before charge (taxes, discounts)
`best_classifieds_use_pro_reviews`	Force standard comments instead of Pro reviews
`best_classifieds_similar_listings_count`	How many similar listings to show
`best_classifieds_map_zoom`	OSM map default zoom
`best_classifieds_map_tile_url`	OSM tile server URL

Common customization recipes

Add a custom badge to listings

add_action( 'best_classifieds_after_card_image', function( $post_id ) {
    if ( get_post_meta( $post_id, '_certified_dealer', true ) ) {
        echo '<span class="bc-badge bc-badge-certified">Certified Dealer</span>';
    }
} );

Style it via your child theme’s CSS.

Force a category for new submissions

add_filter( 'best_classifieds_submission_post_args', function( $args, $data ) {
    // Auto-tag everything submitted on Mondays as "weekly-special"
    if ( 1 === (int) date( 'N' ) ) {
        $args['tax_input']['post_tag'] = array( 'weekly-special' );
    }
    return $args;
}, 10, 2 );

Add a third color palette

add_filter( 'best_classifieds_color_palettes', function( $palettes ) {
    $palettes['ocean-blue'] = array(
        'label'      => 'Ocean Blue',
        'primary'    => '#1E3A8A',
        'accent'     => '#06B6D4',
        'background' => '#F0F9FF',
        'text'       => '#0F172A',
    );
    return $palettes;
} );

The new palette appears in the customizer dropdown automatically.

Inject a banner above the homepage hero

add_action( 'best_classifieds_before_header', function() {
    if ( is_front_page() ) {
        echo '<div class="bc-announcement">Black Friday: 50% off Featured slots!</div>';
    }
} );

Restrict Featured upgrades to specific user roles

add_filter( 'best_classifieds_packages_for_user', function( $packages, $user_id ) {
    $user = get_user_by( 'id', $user_id );
    if ( in_array( 'subscriber', $user->roles, true ) ) {
        // Subscribers can't pay for Featured slots
        unset( $packages['boosted'], $packages['premium'] );
    }
    return $packages;
}, 10, 2 );

Template overrides

To override a template part from a child theme, copy the file to the same path inside your child:

/wp-content/themes/best-classifieds-child/template-parts/hero.php

Best Classifieds checks the child theme first, then falls back to the parent. You can override any of:

template-parts/hero.php
template-parts/featured-categories.php
template-parts/latest-listings.php
template-parts/cta-banner.php
template-parts/trust-strip.php
template-parts/how-it-works.php
template-parts/testimonial.php
template-parts/listing/card.php
template-parts/content.php

For top-level templates: single.php, archive.php, index.php, header.php, footer.php — same pattern.

REST API extension

The theme registers /wp-json/best-classifieds/v1/search. To add your own endpoint with the same namespace:

add_action( 'rest_api_init', function() {
    register_rest_route( 'best-classifieds/v1', '/popular', array(
        'methods'             => 'GET',
        'permission_callback' => '__return_true',
        'callback'            => function() {
            $query = new WP_Query( array(
                'post_type'      => 'post',
                'posts_per_page' => 5,
                'meta_key'       => '_bc_views',
                'orderby'        => 'meta_value_num',
                'order'          => 'DESC',
            ) );
            $out = array();
            foreach ( $query->posts as $p ) {
                $out[] = array( 'id' => $p->ID, 'title' => $p->post_title );
            }
            return $out;
        },
    ) );
} );

Hit /wp-json/best-classifieds/v1/popular to test.