"...outstanding support!"
— Ivaylo Zhelev What They Say

Church Theme Content Plugin Developer Guide

The Church Theme 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.f

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 Theme 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.

This will enable all post types, taxonomies and fields.

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 Theme 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 Theme 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.

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 Theme 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.

Related: A Quick Introduction to Using Filters by Pippin Williamson

Additional Notes

  • Sermon audio podcasting is built-in. When an audio URL is provided, it is used in the sermons feed as an enclosure. See Sermon Podcasting for details.
  • Events can be set to automatically recur. This is accomplished with WordPress’s scheduling feature.
  • Please let us know when you release your theme. We use churchthemes.guide to keep track of themes that support the Church Theme Content plugin. This site is linked to from the plugin’s page on WordPress.org.

Changelog

View the releases on GitHub.