It’s been one of those weeks. Many personal and professional obligations to obliged, and only so much time to complete them all with and at a level of excellence to admire.
Today’s tutorial will focus on the Church Community Builder’s group needs. Group needs are tasks associated with a group.
Needs could be anything from prayer requests, finances, meals and more.
Needs are a unique way to keep group members involved and engaged while helping keep group leaders and members organized.
Setup includes and variables
There’s not really much complexity in retrieving a group’s needs list from Church Community Builder using it’s API.
It’s very straightforward, says the guy behind the curtain. 🙂
You know the drill by now. If not and this is your first tutorial rodeo, then simply open a text editor of your, naming and saving the following php file: group-needs.php.
To begin with, include the config.php. Next, define the following variables and set their respective values:
- apiService variable value is set to group_needs
- groupId variable value is set to <specific group’s id> (e.g. 24)
This tutorial hardcodes the groupId variable’s value. However, a simple dynamic look up could be created using the group_profiles service to retrieve each group id.
<?PHP
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'group_needs'; // CCB api service
$groupId = '24'; // sample group id to search for (See CCB API documentation for more $apiService fields)
?>Time to prep for making API call
It’s now time to bind the variables defined in the last section to the API parameters or labels.
To accomplish this feat and make the API call, define urlData variable and set it equal to an array that binds the following labels to their respective variables as a key-value pair array encapsulated in PHP’s built-in array_filter method.
- srv is binded to apiService variable
- id is binded to groupId variable
Next, it’s time to make the API call. To do so, define rss variable and set it equal to the ccbDetails function.
This is where the API call magic happens. The ccbDetails function does all the heavy lifting to POST and GET data from within Church Community Builder.
Pass the ccbDetails function get as its first argument and urlData variable as the second argument.
To learn more about the PHP magic and heavy lifting of the ccbDetails function, click here.
<?
$urlData = array_filter( array(
'srv' => "$apiService",
'id' => "$groupId"
) );
$rss = ccbDetails('get',$urlData); // transform to XML
?>Ready for nested parsing of API XML response?
If you’ve made it this far, then know that the CCB API call has been made. You’re now ready to parse the API’s XML response.
Use PHP’s built-in xpath query method and the following expression to parse the XML response: //groups/group.
To parse the group data, define a nodes variable, setting it equal to the rss variable pointed to the xpath query as shown below.
Then prepare for the output of data by defining an empty response_object variable.
Now we’re ready to parse for group, needs, and items.
To parse the nodes variable array value, create a foreach statement as shown below.
One of the first things within the foreach statement is to set the response_object variable and have it, using the “.=“ operator to concatenate, capture saved group needs data.
The first information to capture is the group name shown between the H3 tag.
// xpath for groups/group
$nodes = $rss->xpath('//groups/group');
$response_object = '';
foreach ($nodes as $node)
{
// now print the group's
$response_object .= '<h3>'.$node->name.'</h3>';
}Nested needs parsing
Right below the response_object variable, define the procdata variable as shown below.
The procdata variable allows for verification that a group does have active needs listed in Church Community Builder.
Knowing this, create an if statement for the procdata variable. Basically if the needs do exist for a group, then prepare to list each needs name and description.
To do so, create a foreach statement within the if statement, and iterate each procdata array value.
Within the foreach statement for each need, re-define the response_object variable twice to concatenate a horizontal rule or line separator as the first variable value and to list both the need name and description as the second variable value.
<?PHP
foreach ($nodes as $node)
{
// now print the group's
$response_object .= '<h3>'.$node->name.'</h3>';
$procdata = $node->needs->need;
// if needs exist, then list each need by name and description
if($procdata){
foreach($procdata as $data){
$response_object .= '<hr>';
$response_object .= '<h4>'.$data->name.'</h4> ('.$data->description.')';
}
}
}Nested needs’ items parsing
Now here’s where things can seem a bit tricky and odd.
We’ll need to retrieve a list of the items or tasks associated with a specific need.
It’s actually quite simple, retrieving the needs’ items list. It’s a repeat of the last section starting with defining to the procdata, and including a if and foreach statement. Okay, I make it sound easy. 😜
In short, define itemdata variable as shown below. The itemdata variable allows for verification that a group’s specific need has active items associated and listed in Church Community Builder.
Knowing this, create an if statement for the itemdata variable. Basically if an item exists for a group need, then prepare to list each item’s name, assignee, and date as the following bulleted-list sentence:
<Item> is assigned <Person> and is due <Date>.
To do so, create a foreach statement within the if statement, and iterate each itemdata array value.
However, before creating the foreach statement, create the html to create and capture a bulleted list of needs’ list items. To do so, re-define the response_object variable and set it equal to concatenate bulleted-list ul open tag.
Within the foreach statement for each need, re-define the response_object variable to capture the sentence above (see indented sentence) as the variable value. Close the foreach statement loop.
Now to close the bulleted list of needs’ list items. To do so, re-define the response_object variable and set it equal to concatenate bulleted-list ul closed tag.
We’re coming down the home stretch. Close the if, foreach, if, and foreach statement loops.
I told you it was going to be a bit tricky, but you survived to tell the story. 😃
And before I forget, don’t forget to echo the response_object variable so that data can be displayed to web browser when executing script.
<?PHP
$itemdata = $data->current_items->current_item;
// if items exist, then list each item by name, date and person assigned to
if($itemdata){
$response_object .= '<ul>';
foreach($itemdata as $idata){
$response_object .= '<li><b>'.$idata->name.'</b> is assigned to <b>'.$idata->assigned_to.'</b> and is due <b>'.$idata->date.'</b>.</li>';
}
$response_object .= '</ul>';
}
}
}
}
echo $response_object;
?>Time to save and test
You’ve persevered and overcame today’s tutorial. Your code in its entirety should look like the code below.
<?PHP
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'group_needs'; // CCB api service
$groupId = '24'; // sample group id to search for (See CCB API documentation for more $apiService fields)
$urlData = array_filter( array(
'srv' => "$apiService",
'id' => "$groupId"
) );
$rss = ccbDetails('get',$urlData); // transform to XML
// xpath for groups/group
$nodes = $rss->xpath('//groups/group');
$response_object = '';
foreach ($nodes as $node)
{
// now print the group's
$response_object .= '<h3>'.$node->name.'</h3>';
$procdata = $node->needs->need;
// if needs exist, then list each need by name and description
if($procdata){
foreach($procdata as $data){
$response_object .= '<hr>';
$response_object .= '<h4>'.$data->name.'</h4> ('.$data->description.')';
$itemdata = $data->current_items->current_item;
// if items exist, then list each item by name, date and person assigned to
if($itemdata){
$response_object .= '<ul>';
foreach($itemdata as $idata){
$response_object .= '<li><b>'.$idata->name.'</b> is assigned to <b>'.$idata->assigned_to.'</b> and is due <b>'.$idata->date.'</b>.</li>';
}
$response_object .= '</ul>';
}
}
}
}
echo $response_object;
?>Save the code, and open and execute your group-needs.php script via a web browser. Your result should look similar to the following screenshot when successfully executed:
Congratulations! That’s it for today’s tutorial. I’ll see you back here next week. We’ll likely expound a bit upon this tutorial, or we may have something new to learn in its entirety. See you next week.