Documentation

Church Community Builder Core API

Getting Started #

The plugin can be installed using the Plugins Screen in your WordPress admin menu under Plugins > Add New. You can also download the plugin from the WordPress Plugin Directory.

After you install the plugin, all you need to do is Activate it.

Activate Plugin

Yes No

Configure API Settings #

  1. First you’ll need to setup a dedicated API User in your Church Community Builder software. Follow the instructions on the support portal.
  2. When assigning services to this user, you’ll need to enable the group_profiles service for Groups functionality and the public_calendar_listing service for Public Events functionality.
  3. Under CCB Core API > API Settings enter
    1. Your Church Community Builder software subdomain. (Without http:// and without .ccbchurch.com).
    2. Your API Credentials (username and password which was setup in step 1 above).
    3. Click Save Changes.

API Settings

After you have saved your changes you will be able to test your API Credentials.

API Settings

Yes No

Configure Groups #

Basic Settings

Under CCB Core API > Groups you can enable Groups synchronization. This will synchronize your publicly listed groups.

Important: The most common mistake with group synchronization is the group settings in your Church Community Builder software:

In order to make a group public you’ll need to Edit the group. On the Group’s Options tab, check the Public Search checkbox. More info is available on the Church Community Builder support portal.

You can customize the Display Name and the URL Name (slug) of the Groups Custom Post Type. For example, some churches may call their groups “Small Groups”, “Life Groups”, “Meet-ups”, etc. The slug is the last part of the URL where the Custom Post Type’s archive page will be located.

More information about Custom Post Types (and how to create a template for their pages) can be found here.

If you plan to display the Group’s image on your site you can enable the Group Images setting. When groups are synchronized, this will download a copy of the group image to your Media Library and attach it to the Custom Post Type as a Featured Image.

plugin_groups

Advanced Settings (Optional)

The Advanced Settings are preconfigured with the most common settings. These control how the Groups Custom Post Type will be available throughout WordPress (front and back end). These control the arguments sent to register_post_type.

plugin_groups_02

Yes No

Configure Public Events #

Basic Settings

Under CCB Core API > Public Events you can enable Public Events synchronization. This will synchronize your publicly listed events (aka your Public Calendar).

You can customize the Display Name and the URL Name (slug) of the Public Events Custom Post Type. For example, some churches may call their events “Meetups”, “Hangouts”, etc. The slug is the last part of the URL where the Custom Post Type’s archive page will be located.

More information about Custom Post Types (and how to create a template for their pages) can be found here.

plugin_events

Advanced Settings (Optional)

The Advanced Settings are preconfigured with the most common settings. These control how the Public Events Custom Post Type will be available throughout WordPress (front and back end). These control the arguments sent to register_post_type.

Date Range Type (Relative Range)

When Public Events are synchronized, the plugin will fetch events that start after the “How Far Back” setting and that start before the “How Far Into The Future” setting. This is the best setting for most churches. It will continually import / remove events on your WordPress site on a rolling basis.

plugin_events_02

Date Range Type (Specific Range)

When Public Events are synchronized, the plugin will fetch the events that start after your Specific Start Date and that start before your Specific End Date. You might use this setting if you want to tightly manage which events appear on your site.

plugin_events_03

Yes No

Synchronization #

You have two options for synchronizing your Church Community Builder data: Manual Sync or Auto Sync.

Manual Sync

Under CCB Core API > Synchronize you can click the Synchronize button.

The synchronization runs in the background so you can safely navigate away while the synchronization takes place. Once the synchronization is complete, you’ll receive a notice on this page with the latest results (and if there were any errors).

plugin_sync

Auto Sync

Under CCB Core API > Synchronize you can Enable Auto Sync.

The plugin has a Cache Expiration setting. This is how often the plugin will connect to the Church Community Builder API to check for updates. (About 90 minutes is recommended).

This runs as a background task so your site performance should be unaffected.

plugin_sync_02

Yes No

Using The Custom Post Types #

Now that your Groups and/or Events are stored in WordPress as Custom Post Types, what’s next? WordPress has several options for displaying Custom Post Types, and here are some resources to help you get started.

Creating Custom Post Type Templates

The two most common templates give you an archive page (a listing of all groups or events) and a single page (an individual group or event).

You can also create templates for the Group & Event Categories & Tags (called “taxonomy templates”). For example, you’ll be able to display “All Groups in the ‘Married Couples’ category” or “All Events in the ‘Missions’ Group category” or “All Groups with the ‘Child Care Available’ tag.

Templates

Custom Post Type Templates (WordPress Codex)

Elegant Themes – Creating Custom Post Types (Beginning on Step 3)

Tuts+ A Guide To WordPress Custom Post Types – Part 1 (Ignore any steps about creating custom post types)
Tuts+ A Guide To WordPress Custom Post Types – Part 2 (Ignore any steps about creating custom post types)

Creating Custom Content (WPMU Dev, Beginning at “Displaying Your Post Type on the Front End”)

Custom Fields

Custom Fields (WordPress Codex)

WordPress Custom Fields 101: Tips, Tricks, and Hacks (WPBeginner)

Custom Taxonomies (Categories & Tags)

Custom Taxonomies (WordPress Codex)

Creating Custom Content – Taxonomies & Fields (WPMU Dev, Ignore any steps about creating taxonomies and fields)

Yes No

Group Custom Post Type #

The Group Custom Post Type is registered with the name: ccb-core-groups.

So for example, when using WP_Query you might do:

$args = array(
	'post_type' => array( 'ccb-core-groups' )
);
$query = new WP_Query( $args );

The data is mapped like so:

Group Name -> Post Title
Group Description -> Post Content
Group Image -> Post Featured Image (Optional)

So for example, when displaying basic Group information you might do:

$query = new WP_Query( $args );
if ( $query->have_posts() ) {
	echo '<div>';
	while ( $query->have_posts() ) {
		$query->the_post();
		echo '<p>' . get_the_title() . '<br>'; // group name
		echo get_the_content() . '</p>'; // group description
		if ( has_post_thumbnail() ) {
			the_post_thumbnail(); // group image
		} 
	}
	echo '</div>';
}
Yes No

Group Taxonomies #

By default, the following Church Community Builder Group Properties are mapped as these Custom Taxonomies:

CCB PropertyWordPress Taxonomy SlugWordPress Display NameTaxonomy Type
 Areagroup_areasAreaCategory
Meeting Daygroup_daysDaysCategory
Group Typegroup_typesTypeCategory
Meeting Timegroup_timesTimeCategory
Departmentgroup_departmentsDepartmentCategory
Childcare Providedgroup_tags > childcare-providedGroup TagTag

So for example, you might create a Taxonomy Template file named taxonomy-group_types.php to customize the Group Type archive view.

Yes No