"I highly recommend"
— Michael Dexter What They Say

Church Content Plugin Developer Guide

The Church Content WordPress plugin provides compatible themes with church-related post types, taxonomies and fields. All of our themes use this plugin and so can yours.

This is a developer guide. Regular users only need to install the plugin to use it with a compatible theme.

Purpose

The plugin provides functionality enabling the user to manage sermonseventspeople and locations to be displayed by a compatible theme.

Experienced WordPress developers agree that functionality like this does not belong in themes since themes are intended only for controlling the appearance of a WordPress site. Content that users might expect to take with them if they switch themes should “live” in a plugin in order to avoid the lock-in effect.

Similarly, our approach is not to display content using the plugin since themes offer more control for that purpose.

Developers

The Church Content plugin was made in a way that other church theme developers can take advantage of it. A couple benefits are that you will save time and be helping to accomplish better data portability among church websites powered by WordPress.

This guide assumes you have some proficiency with WordPress Theme Development or are willing to learn (here are some good resources).

Basic Usage

You can do this in your theme’s functions.php file using the after_setup_theme hook.

Note: While the plugin has been renamed from “Church Theme Content” to “Church Content”, the correct strings to use in development are still church-theme-content and ctc. Only the public name changed.

Recommended Usage

Notice the comment above says, “It is recommended to explicitly specify taxonomies and fields used by theme so plugin updates don’t reveal unsupported features.” Below is an example from one of our themes showing how to do that. This code would replace the block of code under Plugin Features above.

Field Overrides

Did you notice field_overrides above? You can use this to change how a field is presented to the user. Maybe you want to change the title or description. Here’s one example of doing so for a couple Person fields.

You can change other things like the field’s default value and whether or not it can be left empty. Look into the {feature}-fields.php files in includes/admin to see which field settings you can override.

Showing Content

Showing content is the territory of your theme. This plugin simply provides the user with a way to manage church-related content. We believe in a clear separation of functionality and presentation. Content should be theme-independent and belongs in a plugin like this. Similarly, themes are best for showing content.

You can refer to Theme Development in the WordPress Codex for information on showing custom post types, taxonomies and fields. It is the same with any theme so we do not reiterate what is already provided in the official resources.

Post Types, Taxonomies and Fields

You can get full details on the post types and taxonomies that the plugin registers in:

Church Theme Framework

If you’d like an extra hand in presenting content from this plugin, have a look at our Church Theme Framework. Like this plugin, you can enable many useful features with a flick of add_theme_support. Helper functions also make development quicker and easier. The framework is not required for using the Church Content plugin (using the plugin alone is a simpler approach).

Event Dates and Times

Here are some tips for using the event date and time fields. It is important that you understand their purpose and ideal for all themes to treat these fields in the same way.

  • _ctc_event_start_date – Date event starts in YYYY-MM-DD format (e.g. 2016-10-01 for October 1, 2016)
  • _ctc_event_end_date –Date event ends in YYYY-MM-DD format (completing a date range)
  • _ctc_event_start_time – Time of day event starts in 24-hour time format (e.g. 14:00 is 2:00 pm)
  • _ctc_event_end_time – Time of day event ends in 24-hour time format (completing a time range)
  • _ctc_event_hide_time_range – Do not show Start Time and End Time with theme when this is set. The user prefers to show Time Description instead and only use the precise times for ordering.
  • _ctc_event_timeTime Description field for free text (e.g. “After Second Service” or “9:30 am and 11:00 am”). Sometimes the precise start and end time is not descriptive enough).

Additionally, there are hidden fields that are updated whenever the user saves an event. These hidden fields are intended for ordering events only so you do not need to specify them with add_theme_support. It is best to order by date and time instead of date only so that the order is correct for same-day events.

  • _ctc_event_start_date_start_time – Start date and start time of event in DATETIME format (e.g. 2016-10-01 14:00:00 for October 1, 2016 at 2:00 pm)
  • _ctc_event_start_date_end_time – Start date and end time of event in DATETIME format
  • _ctc_event_end_date_start_time –End date and start time of event in DATETIME format
  • _ctc_event_end_date_end_time –End date and end time of event in DATETIME format

See the ctfw_get_events function in the Church Theme Framework for an example of how you can query events in a way that considers both date and time for the order. This function also considers backwards-compatibility with versions of Church Content earlier than 1.2 (the version in which the start/end time fields and these hidden fields were introduced).

See the ctfw_event_data function in the Church Theme Framework for outputting event dates and times. This function formats date and time for you, with consideration for all possible field values provided by the user (e.g. with or without start and/or end time, using or not using option to hide those fields and with or without a time description).

Monthly Events Calendar

See ctfw_event_calendar_data and related functions in the Church Theme Framework. This function returns a month’s headings (Sunday – Saturday), weeks, days and each day’s events. You can create a page template that loops this data in order to render a monthly calendar.

Google Maps

You can use _ctc_location_map_lat, _ctc_location_map_lng, _ctc_location_map_type, _ctc_location_map_zoom (similar fields exist for events) for rendering a map using the Google Maps API. It is assumed that if longitude and latitude are not both provided, a map is not to be shown.

Google Maps now requires an API Key. The plugin has a setting for this in Settings > Church Content > Locations which is used by the “Get From Address” button and map preview on the event and location screens. You can use the plugin’s setting instead of adding your own Customizer setting. Here is some example code from the Church Theme Framework.

Complete Example

It’s not required but may be beneficial to browse the code from one of our commercial themes for a complete example of a finished theme using this plugin.

Modifying Post Types

You may want to change the name or slug of a post type. There are filters used throughout the the Church Content plugin that let you do things like this. Please see the code in includes/post-types.php. Notice for the sermon post type the filter is ctc_post_type_sermon_args. Using that, you can change the labels, slug, etc. You can do this with your own functionality plugin so that changes are not lost during updates. Other post types have a similar filter. Here is example code.

The easiest approach, however, is for the user to install the Pro Add-on which allows for changes to “Sermon” wording (e.g. change to “Message”) and post type / taxonomy URL slugs for all post types.

Related: A Quick Introduction to Using Filters by Pippin Williamson

Church Content Pro

Church Content Pro is an optional plugin that adds additional features like sermon podcasting and recurring events to the Church Content plugin. It should be compatible with third-party themes so long as the following is true.

  • Always retrieve a post type’s label for sermons, events, etc. This way when a user uses Pro to do something like change “Sermon” to “Message”, the change can take effect everywhere (the post type label is filtered by Pro on registration). The Church Theme Framework has some wording functions you can use to make this easy.
  • Optionally you may wish to have your theme describe an events recurrence pattern in full (e.g. show “Last Sunday of every month” instead of just “every month”. The Church Theme Framework’s  ctfw_event_recurrence_note function can help you generate a “recurrence note”.

If you would like a copy of Pro to test with your theme, just let us know.

Promotion

Please let us know when you release your theme. We use churchthemes.com/third-party-themes to keep track of themes that support the Church Content plugin. This site is linked to from the plugin’s page on WordPress.org.

Changelog

View the releases on GitHub.