Families PHP Reporting Search Tutorials XML XPATH

Last Families Modified Report and Dashboard

Alvin Brown

Welcome back to this week’s tutorial where we’ll cover the last families modified report.

If you’re a growing church with a large number of families joining the fold, then this is likely the tutorial you’ll want to implement.

Today’s tutorial will allow you to create a ongoing report that tracks families modified over the last 7 days.

This is a great internal report to help gauge and understand CCB usage at the family level.

This tutorial is not detailed, nor do we cover ALL there is you could do with this point.

I simply want to intro you to a few CCB API services built around gathering family detail.

You’ll likely be able to make the connection with all the many ways to use both services to enhance operations and processes using CCB.

Let’s get started!

Setup Variables and Includes

Open a text editor of your choice, naming and saving the following PHP file: family-list.php.

Be sure to include the appropriate comments and include files as shown below.

Next, define apiService and modDate variables as shown below:

  • apiService variable value is family_list
  • modDate variable value is date(‘Y-m-d’, strtotime(‘-7 days’));

The apiService variable value should be set to the CCB API service family_list. The modDate variable is used to return family results that have modified since a specified date.

As you can see below, we’ve not hardcoded a value for the modDate variable, but we’ve chosen to use two built-in PHP methods: date and strtotime.

Not hard coding the dates will allow for this page to be dynamically display the last seven (7) days from the current date when the report is executed.

As a stretch goal, you could create a drop down where a user specifies dates or selects a pre-populated date selection (i.e., last 7 days, last 14 days, last 30 days, etc.). This drop could then set the modDate variable to the selected value as chosen by the user via the drop down menu/select.

Nevertheless, read up on the family_list and its respective parameters via the CCB Public Web API documentation.

<?PHP

/**
 * Family List
 */

// contains resusable globals and functions
include("includes/config.php");

$apiService = 'family_list'; // CCB api service
$modDate = date('Y-m-d', strtotime('-7 days')); // date last modified

?>

Prepping and Making API Call, and Prepping Response Data

Now that the input variables are defined, it’s time to prepare to make the CCB API call.

But before we can make the call, the variables in the last section must be binded to their respective CCB API label or parameter.

Create a urlData variable so that we can define its value as a binded labels and variables. This binding is a key-value pair array encapsulated using PHP’s built-in array_filter method, using the following:

  • srv label binds to apiService variable
  • modified_since label binds to modDate variable

Now that the urlData has been successfully defined, it’s time to define the rss variable and it’s value to make the CCB API call.

Set the rss variable equal to the ccbDetails function, passing it get as the first argument and the urlData variable as the second argument.

If you’re not familiar with the ccbDetails function, then feel free to read and review the heavy lifting magic this function provides here.

<?PHP

$urlData = array_filter( array(
	'srv' => "$apiService",
	'modified_since' => "$modDate"
	) );

$rss = ccbDetails('get',$urlData); // transform to XML

?>

Parsing and display the family_list data

Up to this point, we’ve successfully made the CCB API call to retrieve results for family_list API service. Now, it’s time to parse the data response.

To parse the response, we’ll use a PHP built-in XPATH query method and the following response: //families/family.

You’ll have to refer to CCB’s Public Web API documentation for specific schema information.

<?PHP

$nodes = $rss->xpath('//families/family');  // xpath for families


?>

Next, lets prepare a concatenating response_object variable for when we view the report via a web browser.

Create an empty response_object variable and then using the “.=” operator to provide concatenation, create the following lines:

<?PHP

$response_object = '';

$response_object .= '<h1>Families Modified Last 7 Days Report</h1>';
$response_object .= '<h2>Since: '.$modDate.'</h2>';
$response_object .= '<h2>Total Families: '.sizeof($nodes).'</h2>';

?>

We simply gave the report a title, displayed date from 7 days ago, and the total number of families by using PHP’s built-in sizeof method to tally the nodes variable.

Speaking of nodes variable, it’s time to parse each node or family that was returned in the result.

For reporting sake, I’ve opted to return a box for each family, displaying family last name and email for now.

You can choose to show more such as totaling the number of individuals in a family. However, for the sake of time and this tutorial, I only wanted to show family name and email.

Create a foreach statement so that we can iterate through each family collected and return to the nodes variable.

Within the foreach statement, we’re going to introduce another CCB API service via the getFamilyDetail functions: family_detail.

Because family_list doesn’t return specific enough detail (i.e., email, picture, etc.), we must use family_detail to gain access to such data.

Create a data_object variable and set it equal to the getFamilyDetail function, passing $node[‘id’] as the one and only argument.

In short, we’re passing the ccbDetails function the unique family id and returning specific family attributes via an array.

Below the data_object variable, create a few concatenated response_object variables that encapsulate the data_object variable array values for name and email.

Close the foreach statement and echo the response_object variable. That’s it for this for this tutorial. Easy huh?

<?PHP

foreach ($nodes as $node)
{
    $data_object = getFamilyDetail($node['id']);

    $response_object .= '<div style="padding: 8px; margin: 4px 8px; position:relative: display: inline; float: left; max-width: 200px: max-height: 200px; border: 1px solid #000; border-radius: 4px;';
    $response_object .= '<p><a href="#">'.$data_object[1].'</a></p>';
    $response_object .= '<p><a href="#">'.$data_object[3].'</a></p>';
    $response_object .= '</div>';
}

echo $response_object;

?>

Time to save, open and test in a web browser

Following this tutorial section by section and step by step, you should have code in your family-list.php that resembles the following:

<?PHP

/**
 * Family List
 */

// contains resusable globals and functions
include("includes/config.php");

$apiService = 'family_list'; // CCB api service
$modDate = date('Y-m-d', strtotime('-7 days')); // date last modified

$urlData = array_filter( array(
	'srv' => "$apiService",
	'modified_since' => "$modDate"
	) );

$rss = ccbDetails('get',$urlData); // transform to XML

$nodes = $rss->xpath('//families/family');  // xpath for families

$response_object = '';

$response_object .= '<h1>Families Modified Last 7 Days Report</h1>';
$response_object .= '<h2>Since: '.$modDate.'</h2>';
$response_object .= '<h2>Total Families: '.sizeof($nodes).'</h2>';

foreach ($nodes as $node)
{
    $data_object = getFamilyDetail($node['id']);

    $response_object .= '<div style="padding: 8px; margin: 4px 8px; position:relative: display: inline; float: left; max-width: 200px: max-height: 200px; border: 1px solid #000; border-radius: 4px;';
    $response_object .= '<p><a href="#">'.$data_object[1].'</a></p>';
    $response_object .= '<p><a href="#">'.$data_object[3].'</a></p>';
    $response_object .= '</div>';
}

echo $response_object;



function getFamilyDetail($id){

	$apiService = 'family_detail'; // CCB api service

	$urlData = array_filter( array(
		'srv' => "$apiService",
		'family_id' => "$id"
		) );

	$rss = ccbDetails('get',$urlData); // transform to XML

	$nodes = $rss->xpath('//items/item');  // xpath for family detail

	$response_object = array();

	foreach ($nodes as $node)
	{

		// this is a zero index array - https://en.wikipedia.org/wiki/Zero-based_numbering
	    $response_object[] = $node->id;
	    //$response_object[] = $node->sync_id;
	    $response_object[] = $node->name;
	    $response_object[] = $node->picture;
	    //$response_object[] = $node->picture_privacy;
	    $response_object[] = $node->email;
	    //$response_object[] = $node->email_listed;
	    //$response_object[] = $node->area_id;
	    //$response_object[] = $node->area_name;
	    //$response_object[] = $node->mailing_street;
	    //$response_object[] = $node->mailing_city;
	    //$response_object[] = $node->mailing_state;
	    //$response_object[] = $node->mailing_zip;
	    //$response_object[] = $node->address_country;
	    //$response_object[] = $node->mailing_carrier;
	    //$response_object[] = $node->address_listed;
	    //$response_object[] = $node->address_privacy;
	    //$response_object[] = $node->phone;
	    //$response_object[] = $node->phone_listed;
	    //$response_object[] = $node->phone_privacy_lvl;
	    //$response_object[] = $node->listed;
	    //$response_object[] = $node->creator_id;
	    //$response_object[] = $node->modified_id;
	    //$response_object[] = $node->date_created;
	    //$response_object[] = $node->date_modified;
	}

	return $response_object;

}

?>

Save the code and open the file in a web browser, and it should look like the following:

This tutorial barely scratches the surface on all that you can display via the web browser. Let you imagination run wild with all the options of where you can take this tutorial.

Personally, I envision a dashboard to be used in our church to help staff and deacons get accustomed on a weekly basis to the new families joining our congregation, seeing we can get families to upload a picture.

I’ll leave you be and let you have it, extending this tutorial. See you back here next week. Have a blessed week.

getFamilyDetail Function

This function returns specific details about a given family using the family_detail CCB API service. I’ve commented out a quite a few fields below within the function to show what type of information can be returned.

<?PHP

function getFamilyDetail($id){

	$apiService = 'family_detail'; // CCB api service

	$urlData = array_filter( array(
		'srv' => "$apiService",
		'family_id' => "$id"
		) );

	$rss = ccbDetails('get',$urlData); // transform to XML

	$nodes = $rss->xpath('//items/item');  // xpath for family detail

	$response_object = array();

	foreach ($nodes as $node)
	{

		// this is a zero index array - https://en.wikipedia.org/wiki/Zero-based_numbering
	    $response_object[] = $node->id;
	    //$response_object[] = $node->sync_id;
	    $response_object[] = $node->name;
	    $response_object[] = $node->picture;
	    //$response_object[] = $node->picture_privacy;
	    $response_object[] = $node->email;
	    //$response_object[] = $node->email_listed;
	    //$response_object[] = $node->area_id;
	    //$response_object[] = $node->area_name;
	    //$response_object[] = $node->mailing_street;
	    //$response_object[] = $node->mailing_city;
	    //$response_object[] = $node->mailing_state;
	    //$response_object[] = $node->mailing_zip;
	    //$response_object[] = $node->address_country;
	    //$response_object[] = $node->mailing_carrier;
	    //$response_object[] = $node->address_listed;
	    //$response_object[] = $node->address_privacy;
	    //$response_object[] = $node->phone;
	    //$response_object[] = $node->phone_listed;
	    //$response_object[] = $node->phone_privacy_lvl;
	    //$response_object[] = $node->listed;
	    //$response_object[] = $node->creator_id;
	    //$response_object[] = $node->modified_id;
	    //$response_object[] = $node->date_created;
	    //$response_object[] = $node->date_modified;
	}

	return $response_object;

}

?>

Related posts:

  1. Creating a Queue overdue list of persons report
  2. Retrieve a list of significant events for individuals
  3. How many families are in CCB?
  4. Your Church’s CCB Zip Code Dashboard

Related Posts

Finance Giving PHP Profiles Reporting REST Tutorials XML

How to Retrieve All Batches or Batches by Modified Date

Alvin Brown
Finance Gifts Giving PHP Reporting Search Tutorials XML XPATH

How to Retrieve Batch Details

Alvin Brown

Subscribe and receive the following...

  • Inside CCB tips and tricks
  • Instant CCB tutorial alerts and updates
  • CCB How To's, Videos, Webinars and more...