Involvements - TenthPres/TouchPoint-WP GitHub Wiki

Small Groups? Classes? List and manage any kind of involvement.

Setup & Usage

To enable, go to Settings > TouchPoint-WP > Basic Settings and select "Enable Involvements."

Involvements are imported to WordPress based on the Program/Division they belong to, and are imported as any number of separate post types. Two sample post types we'll reference throughout this guide are "Small Groups" and "Sunday School Classes".

You will probably have two default Involvement Post Types by default, which you can adapt to your needs. Or, you can create a new one.

If you want to show the names of you Involvement leaders (e.g. small group leaders), you must also enable the People Lists feature.

Most of the settings should be fairly self-explanatory. A few highlights:

Divisions to Import

You can import any number of divisions into a single Involvement Post type, and each Division can be imported into multiple Involvement Post Types if you need that. However, we recommend keeping the structure pretty boring. We use one Division for each Involvement Post Type, "Small Groups" for Small Groups, and "Adult Bible School" for our adult classes.

Use Geographic Location

If geography is relevant (e.g. Small Groups that meet in homes throughout the area), check this box to import geographical information and enable mapping.

Leader Member Types

Select the Member Types for people who should have their name visible on the class. At Tenth, we have two Member Types we use for Small Group Leaders: "Leader" and "Leader + Host". The "Contact Leader" button will create a task assigned to one of these people.

Host Member Types

Only visible if Use Geographic Location is enabled. Select the Member Types for people who should have their home address used for the map marker. At Tenth, we have two Member Types we use for Small Group Hosts: "Host" and "Leader + Host". The "Host" does not have their name on the group, but their home address is used for the group's location. The "Leader + Host" both has their name on the group and also has their home address used for the group's location.

Default Filters

On the Involvement listing pages (an Archive page, in WordPress terms), you can have a Filter bar which allows the user to narrow the options based on certain criteria. Which filters are available can be changed via shortcode parameters, or you can set some defaults. The demographic items on this list (Prevailing Marital Status and Age Group) are based on the actual Marital Statuses and Age Groups of the members of the Involvements.

Contact Leader Keywords

When someone clicks the Contact Leader button, a task is created with the user's message and these keywords.

Join Task Keywords

When someone clicks the Contact Leader button, a task is created with these keywords to encourage the leader to reach out to the prospective member. If the Involvement has a registration (meaning, it has registration questions or a registration type other than "Join Involvement"), no task will be created and the "Join" button is replaced with some version of a "Register" button.

Shortcodes

In addition to the Archive pages that list involvements, there are also a few special shortcodes.

TP-Inv-Nearby

Use this shortcode to list the Involvements of a particular type that are closest to the user's location. At Tenth, we use this for a "Small Groups Nearby" section on our homepage.

Parameters

  • type - string - Required. The Involvement type that should be listed.
  • count - int - The number of Involvements to list. Defaults to 3.

Example

This example shows the three nearest smallgroup involvements to the user.

[TP-Inv-Nearby count=4 type="smallgroup"]

TP-Inv-List

Use this shortcode to list involvements that match particular criteria. At Tenth, we use this to show Small Groups that are affiliated with a specific ministry on that ministry's separate page.

Parameters

  • type - string - Required, unless the page is an Involvement archive page. Use this field to specify the Involvement type that should be listed.
  • div - int - If you would like to filter the list down to only show one involvement, put the Involvement ID here.

Example

This example shows the Involvements of the 'smallgroup' type which are also in Division 18. At Tenth, this is College ministry Small Groups.

[TP-Inv-List type=smallgroup div=18]

Filters

tp_involvement_actions

Use this filter to change the generated HTML for actions on an Involvement. The parameters are:

  1. The existing string after it's generated
  2. The Involvement object, which can be used for fetching other details
  3. An optional Context variable which is passed from the Involvement::getActionButtons($context)

tp_adjust_time_string

Use this filter to adjust how time strings are rendered dynamically. The value passed to the filter is the time string as provided. There is one argument provided, which is an object that implements the DateTimeInterface representing the time needing to be put into a string. (For example, we use this to remove :00, so times like 7:00pm becomes 7pm.)

tp_inv_allow_contact

Use this filter to prevent "Contact Leader" option from appearing. Return false to prevent contact buttons from appearing. The Involvement Post Type is provided as a parameter.

tp_allow_contact

Use this filter to prevent "Contact Leader" option from appearing on Involvements AND also prevent "Contact" button from appearing on People Lists. Return false to prevent contact. There is no parameter provided. The example below is what we use to prevent contact from outside the US to reduce spam.

function tenth_allowContact($value): string
{
    // Prevent public caching, unfortunately.
    \tp\TouchPointWP\TouchPointWP::doCacheHeaders(\tp\TouchPointWP\TouchPointWP::CACHE_PRIVATE);
    $country = $_SERVER['HTTP_CF-IPCountry'] ?? null;

    if ($country === null) {
        $geoObj = \tp\TouchPointWP\TouchPointWP::instance()->geolocate(true, true);
        $country = $geoObj->raw->country_code ?? "";
    }

    if (!in_array($country, ['US', 'T2'])) {
        return false;
    }

    return $value;
}
add_filter('tp_allow_contact', 'tenth_allowContact');