Welcome back! Today’s tutorial mixes a bit of HTML and PHP with CCB’s API to achieve a process list drop down menu.
Of course, the drop down menu of processes is not much to write home about.
Lord willing, I’ll show you various ways to use the process list drop down menu to automate a few things or two over the next couple of weeks.
Nothing too complex to learn today, so let’s get started.
Setup variables and includes
Open a text editor of your choice, naming and saving the following PHP file: process-list.php.
As shown below, include the appropriate opening file comments. Also include the config.php file that contains reusable global variables and functions for making the CCB API.
To retrieve a list of processes using the CCB API process_list service, refer to the Church Community Builder API Documentation.
There are no required parameters, yet the following are optional parameters:
- campus_id – integer
- modified_since – datetime
We will not use the optional parameters in today’s tutorial. But if you wanted too, you could simply create variables just like the ones I’m about to show you next.
We’ll create two variables to be used. The first is the CCB API service variable, and the second is a variable for the drop down menu id.
Just as in previous tutorials, define the apiService variable and set it equal to process_list. This service allows a retrieval of all CCB Processes.
The second variable to define is the processDomID with a value of processSelect. There won’t be much done with this variable today in terms of capability and functionality. You’ll have to stick around a few weeks to see how we use it. 😉
Nevertheless, the processDomID variable value is used to give a distinct or unique id to the select drop down menu.
Think of it as giving a social security to someone. There is a one-to-one relationship.
We’ll cover this more in weeks to come, but do feel free to read up on HTML DOM classes and ids.
Now that we have our variables and includes set appropriately, it’s time to make the CCB API call.
<?PHP
/**
* Process List
*/
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'process_list'; // CCB api service
$processDomID = 'processSelect'; // HTML DOM id for drop down
?>Make the CCB API Call
To make the CCB API Call that retrieves all Processes, the apiService variable must be binded to the respective CCB API label.
To do this, define a urlData variable, setting it equal to a binded array encapsulated in PHP’s built-in array_filter method. The array should contain the following binded labels and variables:
- src label binded to apiService variable
Remember that this is also where you can bind additional optional parameter variables to their respective API labels (check CCB API documentation).
Now we’re ready to make the CCB API call. To setup the API call, define a rss variable.
The rss variable’s value will be that of the ccbDetails function (learn more here). This is a very powerful function that does all the heavy lifting to authenticate, make the API call, and return the API response.
Make sure to set the first argument of the ccbDetails function to get and the urlData variable as its second. That’s it! The API call can now be made. Easy huh?
<?PHP
$urlData = array_filter( array(
'srv' => "$apiService"
) );
$rss = ccbDetails('get',$urlData); // transform to XML
?>Parse the CCB API Call Response Data
At this point, your CCB API call should be successfully returning an array of a XML data response.
To access data within the response, we’ll use PHP’s built-in XPATH query function and the following express: //processes/process.
To access the process information respectively, define a nodes variable and set it equal to the rss variable pointed to the xpath query of the expression above (see code below).
<?PHP
$nodes = $rss->xpath('//processes/process'); // xpath for processes
?>Now that we’ve targeted the process data within the response, we can iterate to retrieve and return both the process id and name using a foreach statement (as shown below).
Don’t forget to define the empty response_object variable as it is used to capture the process data for each processing within the foreach statement.
Iterating over the nodes variable, you’ll notice that the process id and name are wrapped within html code that represents a select menu option tag.
This allows each process to be shown in the select drop menu as an option. The name is the value shown and read from the web browser by users, and the value is the process id which we’ll use in next week’s tutorial to perform an action. Don’t forget to use the “.=“ operate to concatenate each process data selection.
That’s it for this step. Close the foreach statement and we’re now ready to create the drop down.
<?PHP
foreach ($nodes as $node)
{
$response_object .= '<option value="'.$node['id'].'">'.$node->name.'</option>';
}
?>Process list drop down menu
The final step is creating the drop down menu of processes. If you’re not familiar with select drop down menus, then view an example of a drop down menu.
Define a menu variable. Notice that the processDomID is set to be the name and id of the select tag.
Next are the option tags. Notice we define a “Please select a process” option as the default or first option. This instructs the user to use the drop to make a selection from the menu when viewing in a web browser.
Next step is to set the response_object with contains a concatenated list of option tags with respective process id and name data.
Finally, we close the select tag and then echo the menu. That’s all there is to it, and you should now be ready test your code.
<?PHP // create the select drop down menu $menu = '<select name="'.$processDomID.'" id="'.$processDomID.'">'; $menu .= '<option value="#">Please select a process</option>'; $menu .= $response_object; $menu .= '</select>'; echo $menu; ?>
Time to test your technical prowess
If you’ve followed along step by step, then you’re ready to save and execute your code via a web browser. Your code should resemble the following:
<?PHP
/**
* Process List
*/
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'process_list'; // CCB api service
$processDomID = 'processSelect'; // HTML DOM id for drop down
$urlData = array_filter( array(
'srv' => "$apiService"
) );
$rss = ccbDetails('get',$urlData); // transform to XML
$nodes = $rss->xpath('//processes/process'); // xpath for processes
$response_object = '';
foreach ($nodes as $node)
{
$response_object .= '<option value="'.$node['id'].'">'.$node->name.'</option>';
}
// create the select drop down menu
$menu = '<select name="'.$processDomID.'" id="'.$processDomID.'">';
$menu .= '<option value="#">Please select a process</option>';
$menu .= $response_object;
$menu .= '</select>';
echo $menu;
?>When successful, your web browser should display the following:
Click the drop down and you should see a list of process names that are the same name listed in the Processes and Queues section of native CCB web interface
Well, that’s all I have for now. Join me next week when we take the next steps to discover queues associated with each process. See you back here soon!