Filter System

This document explains the CP Sermon Library’s filter system, its capabilities, and how to use it effectively in different contexts.

New in Version 1.6.0: The filter system has been completely refactored to support multiple post types (sermons and series), with improved accessibility, error handling, and SEO features. For migration from previous versions, see Filter System Migration.

New Features in 1.6.0

• Multi-Post Type Support: Filter both sermons and series content
• Enhanced Accessibility: Full keyboard navigation and screen reader support
• SEO Optimization: Structured data for filtered results
• Improved Error Handling: Standardized error handling throughout
• Developer Friendly: More extensible architecture

Additional Documentation

For information specific to the new filter system features:

• Filter System Reference – Quick reference guide
• Filter System Migration – Upgrade from legacy filters
• Filter System Examples – Code examples
• SEO Enhancements – SEO features for filters
• Error Handling – Error management system

User Documentation

Filter Functionality Overview

The filter system allows users to quickly narrow down sermon content by various criteria:

• Scripture References – Find sermons by Bible book
• Topic Tags – Filter by sermon topics
• Seasons – Filter by church seasons or series themes
• Speakers – Find sermons by specific speakers
• Service Types – Filter by service formats (Sunday morning, midweek, etc.); shown only when sermons are assigned to service types
• Year – Filter by the year a sermon was published
• Search – Text search across sermon titles and content

Using Filters on Sermon Archives

When browsing the main sermon archive (/messages/ by default), you can:

1. Click the “Filter” button to view available filter options
2. Select criteria from any of the dropdown menus
3. Choose multiple filters across different categories
4. View the applied filters above your search results
5. Remove specific filters by clicking the filter tag
6. Use the search box for keyword searches

Using Filters with Service Types

When viewing sermons within a specific service type:

1. Navigate to a service type page
2. Use the filter options to narrow down sermons within that service type
3. Filters will only apply to sermons in the current service type
4. The Service Type filter is automatically disabled in this context

Filter Display Settings

To customize how filters appear and function:

1. Navigate to Series → Settings → Advanced, or under Messages if Series is turned off
2. Find the Filters section
3. Options include:
   • Filter Sorting – Sort filters by sermon count or alphabetically
   • Count Threshold – Minimum number of sermons for a filter to display
   • Show/Hide Count Numbers – Toggle display of sermon counts
   • Disable Specific Filters – Prevent certain filters from appearing

Developer Documentation

Filter System Architecture

The CP Sermon Library’s flexible filter system is built with a context-aware approach that allows filters to work consistently across different parts of the site.

Key Components

1. PHP Filter API Class (CP_Library\Filters\Filters, available as cp_library()->filters)

   • Manages filter registration
   • Renders filter forms and selected filters
   • Processes AJAX requests for filter options

2. JavaScript Filter Component (CPLibraryFilter)

   • Handles client-side filter behavior
   • Loads filter options via AJAX
   • Manages filter state and form submission

3. Context System

   • Allows filters to adapt to different contexts (archive, service type, etc.)
   • Provides context-specific query parameters
   • Supports extensibility for custom contexts

Using Filters in Custom Templates

Note: The cp_library()->filters API is a compatibility layer that operates on the sermon (cpl_item) filter manager only. For series filters, use TemplateHelpers::render_series_filters() instead.

To add sermon filters to a custom template:

<?php
// Render filter form with context
echo cp_library()->filters->render_filter_form([
    'context' => 'custom-context', // Unique context identifier
    'context_args' => [
        'custom_param' => 'value',  // Context-specific parameters
    ],
    'disabled_filters' => ['service-type'], // Filters to disable
    'container_class' => 'my-custom-filter', // Custom CSS class
]);

// Render selected filters
echo cp_library()->filters->render_selected_filters([
    'context' => 'custom-context',
    'context_args' => [
        'custom_param' => 'value',
    ],
]);
?>

Adding Custom Facets

To register a custom facet:

// Register your custom facet via the registration hook
add_action('cpl_register_facets_cpl_item', function($filter_manager) {
    $filter_manager->register_facet('my-custom-facet', [
        'label' => 'My Custom Filter',
        'param' => 'facet-custom',
        'type' => 'custom',
        'query_callback' => function($query, $values, $config) {
            // Modify the WP_Query based on selected values
        },
        'options_callback' => function($args) {
            // Return available filter options
            return [
                (object)[
                    'title' => 'Option 1',
                    'value' => 'option-1',
                    'count' => 5
                ],
            ];
        }
    ]);
});

Custom facets appear in filter forms rendered with render_filter_form(). The built-in sermon archive filter shows only Scripture, Topic, Season, Speaker, Service Type and Year, so a custom facet does not appear there.

Creating Custom Filter Contexts

To register a custom context:

// Register your custom context after the filter managers load
add_action('cpl_register_filter_managers', function() {
    cp_library()->filters->register_context('my-custom-context', [
        'label' => 'My Custom Context',
        'query_callback' => function($query_args, $context_args) {
            // Prepare query arguments for this context
            return $query_args;
        }
    ]);
});

Filter Hooks and Actions

The filter system provides several hooks for customization:

// Register filter managers for custom post types
add_action('cpl_register_filter_managers', function() {
    CP_Library\Filters\FilterManager::register_filter_manager(
        'your_post_type',
        YourNamespace\CustomFilterManager::class
    );
});

// Register facets for a specific post type
add_action('cpl_register_facets_cpl_item', function($filter_manager) {
    // Add custom facets to the sermon filter manager
});

// Filter query variables for a specific post type
add_filter('cpl_filter_query_vars_cpl_item', function($query_vars, $facet_id, $context) {
    return $query_vars;
}, 10, 3);

// Filter query arguments for a specific post type
add_filter('cpl_filter_query_args_cpl_item', function($query_args, $facet_id, $context, $args) {
    return $query_args;
}, 10, 4);

JavaScript API

The JavaScript filter component is not exposed as a global. It initializes itself for every filter form the plugin renders (each .cpl-filter container output by render_filter_form()) and stores the instances in window.cpLibraryFilters. The filter script is enqueued as build/src/filters.js, so a check for filters.js matches that script’s URL.

// Inspect the filter instances on the page
console.log(window.cpLibraryFilters);

// Access the filter query context (nested by post type)
console.log(window.cplFilter.query_context['cpl_item']);

Performance Optimizations

The filter system includes several performance optimizations:

1. Caching System

   • Filter options are cached to reduce database queries
   • Cached options expire after one hour

2. Lazy Loading

   • Filter options are loaded via AJAX after the page loads
   • Initial page load is not impacted by filter complexity

3. Query Optimization

   • Custom SQL queries are used for efficient option retrieval
   • Threshold setting prevents excessive options

Technical Implementation Details

Database Queries

The system uses custom SQL queries to efficiently retrieve filter options:

1. Taxonomy Filters – Query WordPress term relationships with proper joins
2. Source Filters – Query custom source tables for relationships
3. Custom Filters – Support custom query callbacks

State Management

Filter state is managed primarily through URL parameters, allowing:

• Bookmarkable filter states
• Sharable filtered views
• Compatibility with page reloads

AJAX Processing

The AJAX handler (cpl_filter_options) processes requests with:

1. Context-specific parameter processing
2. Filter-specific option retrieval
3. Consistent option formatting

Extending the Filter System

To extend the filter system with new functionality:

1. Add Facets – Use register_facet() for new filter criteria
2. Create Contexts – Use register_context() for new integration points
3. Custom Rendering – Override the render methods using provided hooks

Troubleshooting Filters

Common Issues and Solutions

1. Filters Not Appearing

   • Check Disable Filters on the Messages tab (sermons) or the Series tab (series) of the Settings page
   • Verify threshold setting isn’t too high for your content volume
   • Ensure the context is properly registered

2. Filter Options Not Loading

   • Check browser console for JavaScript errors
   • Verify AJAX URL is correctly configured
   • Check server logs for PHP errors

3. Filter Not Working in Custom Context

   • Verify context registration
   • Check context arguments are passed correctly
   • Ensure JavaScript initialization occurs after DOM is ready

4. Performance Issues

   • Increase count threshold to reduce options
   • Check for inefficient custom query callbacks
   • Consider caching plugin for high-traffic sites