Developer Guide

This guide covers hooks, filters, and customization points for developers working with CP Staff.

Plugin Architecture

CP Staff follows the standard ChurchPlugins architecture:

• Post type: cp_staff with custom meta fields
• Taxonomy: cp_department (hierarchical)
• Namespace: CP_Staff\
• Singleton pattern: Access via cp_staff() global function
• Template override path: yourtheme/cp-staff/

Settings Access

Retrieve plugin settings programmatically:

// Staff tab settings (labels, archive toggle)
$value = \CP_Staff\Admin\Settings::get_staff( 'singular_label', 'Staff' );
$value = \CP_Staff\Admin\Settings::get_staff( 'plural_label', 'Staff' );
$value = \CP_Staff\Admin\Settings::get_staff( 'disable_archive', false );

// Advanced tab settings
$value = \CP_Staff\Admin\Settings::get( 'click_action', 'none' );
$value = \CP_Staff\Admin\Settings::get( 'use_email_modal', false );
$value = \CP_Staff\Admin\Settings::get( 'enable_captcha', 'on' );

Post Meta Fields

Meta Key	Type	Description
title	string	Staff member’s role/position
email	string	Email address
phone	string	Phone number
acronyms	string	Credentials/abbreviations
social	array	Social links (each with url and network keys)
alt_image	string	Alternate image URL
alt_image_id	int	Alternate image attachment ID

Available Filters

Display Filters

// Customize the archive page title
add_filter( 'cp_staff_archive_title', function( $title ) {
    return 'Meet Our Team';
});

// Change the starting heading level for departments (default: 3)
add_filter( 'cp_staff_archive_starting_heading_level', function( $level ) {
    return 2;
});

// Disable the archive page programmatically
add_filter( 'cp_staff_disable_archive', '__return_true' );

// Customize the default page template wrapper classes
add_filter( 'cp_staff_default_template_classes', function( $classes ) {
    $classes[] = 'my-custom-class';
    return $classes;
});

Label Filters

// Customize post type labels (note: cploc_ prefix is inherited)
add_filter( 'cploc_single_cp_staff_label', function( $label ) {
    return 'Team Member';
});

add_filter( 'cploc_plural_cp_staff_label', function( $label ) {
    return 'Our Team';
});

// Customize taxonomy labels
add_filter( 'cp_department_single_label', function( $label ) {
    return 'Ministry';
});

add_filter( 'cp_department_plural_label', function( $label ) {
    return 'Ministries';
});

Query Filters

// Modify the [cp_staff_list] shortcode query
add_filter( 'cp_staff_list_query_args', function( $args, $atts ) {
    $args['posts_per_page'] = 6;
    return $args;
}, 10, 2 );

// Customize department ordering in the archive
add_filter( 'cp_staff_departments_args', function( $args, $parent_id, $depth ) {
    $args['orderby'] = 'term_order';
    return $args;
}, 10, 3 );

Email Filters

// Customize the email subject line
add_filter( 'cp_staff_email_subject', function( $subject, $raw_subject ) {
    return '[Website Contact] ' . $raw_subject;
}, 10, 2 );

// Add a custom suffix to all contact form emails
add_filter( 'cp_staff_email_message_suffix', function( $suffix ) {
    return '<br><br>--<br>Sent via our website contact form.';
});

// Modify the full email message body
add_filter( 'cp_staff_email_message', function( $message ) {
    return $message;
});

Taxonomy Filters

// Add the department taxonomy to additional post types
add_filter( 'cp_department_taxonomy_types', function( $types ) {
    $types[] = 'custom_post_type';
    return $types;
});

Available Actions

// Fires after all CP Staff post types are registered
add_action( 'cp_register_post_types', function() {
    // Post types are now available
});

// Fires after all CP Staff taxonomies are registered
add_action( 'cp_register_taxonomies', function() {
    // Taxonomies are now available
});

// Template hooks for the default page template
add_action( 'cp_staff_default_template_after_header', function() {
    echo '<div class="custom-banner">Staff Directory</div>';
});

add_action( 'cp_staff_default_template_before_footer', function() {
    echo '<div class="custom-cta">Join our team!</div>';
});

CP Locations Integration

When the CP Locations plugin is active, CP Staff automatically registers the cp_staff post type with the location taxonomy. This enables assigning staff members to locations. No additional configuration is required.

Template Override Reference

Override any template by copying it to yourtheme/cp-staff/:

Template	Purpose
archive.php	Staff directory with department grouping
single.php	Individual staff member page
parts/staff-card.php	Staff card in grid layouts
parts/email-modal.php	Contact form modal
parts/info-modal.php	Staff info modal popup

For full template override instructions, see Template Overrides.