Church Community Builder has delivered a long awaited mobile preview experience.
You’re probably wondering what that has to do with anything, especially concerning a CCB Tutorial.
I can’t tell you how many times I’ve longed to use CCB with my iPhone 6 Plus and 6s to simply lookup a person’s profile, review their notes or even add notes to the person’s profile (see below).
Although not quite complete or comprehensive, I do believe CCB is headed in the right direction with it’s mobile preview experience.
Now pertaining to today’s tutorial, we’re going to discuss and walk through an example of how to retrieve and display notes for all CCB Profiles or a given CCB profile.
Let’s get started.
Setup includes and variables
One of the first actions to be taken is opening a text editor of choice, and creating, saving and naming the following PHP file: person-notes.php.
Add the necessary opening file comments, include config.php, and define the following variables:
- apiService variable is set to individual_notes
- personID variable is set to specific person’s CCB ID (OPTIONAL)
The individual_notes API service allows all notes, with the exception of notes marked private), written about an individual to be retrieved and returned using the CCB API.
If an individual’s CCB ID is not defined, then all notes, with the exception of notes marked private), for ALL individuals in the CCB system will be returned.
In my humble opinion, it’s best to make good and effective use of the following optional parameters when using CCB API to retrieve individual notes:
- individual_id
- include_private_notes
- start_date
- end_date
Check the Church Community Builder Public API for more detailed description about the individual_notes API service and its respective optional parameter usage and definitions.
Notice this tutorial hardcodes the personID variable value. This was done to simplify the tutorial, yet could easily be made dynamic using a CCB person lookup.
Now that our includes and variables are executed, it’s time to prepare and execute the CCB API call.
<?PHP
/**
* Individual Notes
*/
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'individual_notes'; // CCB api service
$personID = '3224'; // Person's ID
?>Making the API call and prepping the response data
To make the CCB API call, the CCB API fields for individual_notes must be binded to their respective variables.
To do so, define a 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.
- src label binds to apiService variable
- individual_id label binds to personID variable
Again, if you have additional parameters to scope your API call data, then be sure to add each label binded to its respective variable accordingly.
Now simply make the API call by defining a rss variable and setting it equal to the ccbDetails function, passing it get as the first argument and urlData as the second argument.
To learn more about the PHP magic and heavy lifting of ccbDetails, click here.
<?PHP
$urlData = array_filter( array(
'srv' => "$apiService",
'individual_id' => "$personID"
) );
$rss = ccbDetails('get',$urlData); // transform to XML
?>Parsing and displaying CCB notes information
The CCB API call for individual_notes has been successfully executed up to this point of the tutorial.
Next, it’s time to parse the CCB API call response data using PHP’s built-in XPATH query method and the following expression: //individuals/individual.
Define a nodes variable and set it equal to the rss variable pointed to the xpath query of the expression above (see code below).
Next, define an empty response_object variable. This variable will be used to capture our display data for the CCB person’s name and notes.
<?PHP
$nodes = $rss->xpath('//individuals/individual'); // xpath for individual
$response_object = '';
?>Next, it’s time to create a foreach statement to parse each person’s notes available for viewing.
Within the foreach statement, we’ll capture the person’s name (i.e., $node->name) using the response_object variable and the “.=“ operator to concatenate data.
Next, it’s time to check to ensure a person does have notes to be displayed. To execute this verification, define a procdata variable and set it equal to the following reference: $notes->notes->note.
<?PHP
foreach ($nodes as $node)
{
// now print the person's full name and id
$response_object .= '<h4>'.$node->name.'</h4>';
$procdata = $node->notes->note;
}
?>Now use the procdata variable in an if else statement. If there are notes, then proceed to capture and display each note. If there are no notes for a person, this simply display a no notes available message for the respective person.
Within the if statement section of the procdata variable, redefine the response_object variable and set it to display a horizontal rule using the “.=“ operator.
<?PHP
// if notes exist, then list each note and its respective data
if($procdata){
$response_object .= '<hr>';
} else {
}
?>Next, create a foreach statement using the procdata variable to prepare and display notes information for each note.
Within the foreach statement, redefine the response_object on three (3) different lines to capture the following notes details:
- context
- sharing_level
- note
- date_created
Check the Church Community Builder Public API for more detailed description about the individual_notes API service and its respective optional parameter usage and definitions.
<?PHP
foreach($procdata as $data){
// context
// sharing_level
// note
// date_created
$response_object .= $data->context.' ('.$data->sharing_level.')<br>';
$response_object .= 'Note created on '.$data->date_created.'<br>';
$response_object .= $data->note.'<hr>';
}
?>Close the foreach statement and that’s it for the if and foreach statements.
Before we move on to close out this tutorial, don’t forget to redefine the response_object within the else of the if else statement to read the following: No notes available.
Close the else statement and foreach statement, and the finally echo the response_object variable to display captured data to the web browser.
<?PHP
$nodes = $rss->xpath('//individuals/individual'); // xpath for individual
$response_object = '';
foreach ($nodes as $node)
{
// now print the person's full name and id
$response_object .= '<h4>'.$node->name.'</h4>';
$procdata = $node->notes->note;
// if notes exist, then list each note and its respective data
if($procdata){
$response_object .= '<hr>';
foreach($procdata as $data){
// context
// sharing_level
// note
// date_created
$response_object .= $data->context.' ('.$data->sharing_level.')<br>';
$response_object .= 'Note created on '.$data->date_created.'<br>';
$response_object .= $data->note.'<hr>';
}
} else {
$response_object .= 'No notes available.';
}
}
echo $response_object;
?>Time to test your code
It’s now time you bring everything together and test. Your code should resemble the code below. Save your code and open the file in a web browser.
<?PHP
/**
* Individual Notes
*/
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'individual_notes'; // CCB api service
$personID = '3224'; // Person's ID
$urlData = array_filter( array(
'srv' => "$apiService",
'individual_id' => "$personID"
) );
$rss = ccbDetails('get',$urlData); // transform to XML
$nodes = $rss->xpath('//individuals/individual'); // xpath for individual
$response_object = '';
foreach ($nodes as $node)
{
// now print the person's full name and id
$response_object .= '<h4>'.$node->name.'</h4>';
$procdata = $node->notes->note;
// if notes exist, then list each note and its respective data
if($procdata){
$response_object .= '<hr>';
foreach($procdata as $data){
// context
// sharing_level
// note
// date_created
$response_object .= $data->context.' ('.$data->sharing_level.')<br>';
$response_object .= 'Note created on '.$data->date_created.'<br>';
$response_object .= $data->note.'<hr>';
}
} else {
$response_object .= 'No notes available.';
}
}
echo $response_object;
?>If using the hardcoded person ID as I did in this tutorial, then you’re output will look much like my output screenshot below. If not specifying a CBB person id, then you should see multiple outputs based on the optional parameters specified.
And that’s all there is to retrieving notes for a specific individual or group of individuals using the CCB API service individual_notes.
I look forward to seeing you back here next week. Talk soon and do let me know if you have any comments/questions with this tutorial.