Alright, buckle up because we’re diving into an exciting tutorial that will make you a bona fide tech ninja of the CCB API!
Today, we’ll learn how to update custom field labels in the Church Community Builder (CCB) system using their REST API with PHP.
Whether you’re a seasoned developer or trying to navigate the tech waters for the first time ever, this step-by-step guide will have you customizing field labels like a pro in no time.
Prepping The Ol’ Tech Toolkit
Before we jump into the fun stuff, make sure you’ve got:
- A text editor (VS Code, Notepad++, or even plain ol’ Notepad will do!).
- A web server (local or public) to execute PHP files.
If you’re scratching your head about any of these, check out the Getting Started Toolbox for the basics. Ready? Let’s roll!
Setting Up Your PHP File
First, crack open your text editor and create a new file named:update-custom-field-labels.php
.
Now, include any necessary files or configs from earlier tutorials (if you’ve followed those). Here’s a quick skeleton to get us going:
<?php /** * Update custom field labels in CCB */ include("includes/config.php"); // Reusable globals and functions $apiService = 'update_custom_field_labels'; // API service name
Ok, we’re off to a great start! 🎉
Let’s Talk API Service Parameters
This part’s key: the update_custom_field_labels
API service doesn’t require parameters, but oh boy, does it offer optional parameters—52 of them, to be exact.
These parameters allow you to tweak labels across text fields, dates, pulldowns, and more. Don’t worry, though. You don’t need to use all of them. Just what fits your needs.
For example, here’s a sample setup of optional parameters:
<?PHP $udfTextLabelOne = 'Preferred Contact Method'; // Example text label $udfTextAdminOne = true; // Admin access toggle (true/false) $udfDateLabelOne = 'Follow-up Date'; $udfDateAdminOne = false; $udfPulldownLabelOne = 'Membership Status'; $udfPulldownAdminOne = true; ?>
Feel free to define as many or as few as needed. Here’s the full list of 50+ optional parameters:
<?PHP // REQUIRED & OPTIONAL PARAMETERS // text label and admin $udfTextLabelOne = 'String text'; $udfTextLabelTwo = 'String text'; $udfTextLabelThree = 'String text'; $udfTextLabelFour = 'String text'; $udfTextLabelFive = 'String text'; $udfTextLabelSix = 'String text'; $udfTextLabelSeven = 'String text'; $udfTextLabelEight = 'String text'; $udfTextLabelNine = 'String text'; $udfTextLabelTen = 'String text'; $udfTextLabelEleven = 'String text'; $udfTextLabelTwelve = 'String text'; $udfTextAdminOne = boolean; $udfTextAdminTwo = boolean; $udfTextAdminThree = boolean; $udfTextAdminFour = boolean; $udfTextAdminFive = boolean; $udfTextAdminSix = boolean; $udfTextAdminSeven = boolean; $udfTextAdminEight = boolean; $udfTextAdminNine = boolean; $udfTextAdminTen = boolean; $udfTextAdminEleven = boolean; $udfTextAdminTwelve = boolean; // Date label and admin $udfDateLabelOne = 'String text'; $udfDateLabelTwo = 'String text'; $udfDateLabelThree = 'String text'; $udfDateLabelFour = 'String text'; $udfDateLabelFive = 'String text'; $udfDateLabelSix = 'String text'; $udfDateAdminOne = boolean; $udfDateAdminTwo = boolean; $udfDateAdminThree = boolean; $udfDateAdminFour = boolean; $udfDateAdminFive = boolean; $udfDateAdminSix = boolean; // Pulldown lablel and admin $udfPulldownLabelOne = 'String text'; $udfPulldownLabelTwo = 'String text'; $udfPulldownLabelThree = 'String text'; $udfPulldownLabelFour = 'String text'; $udfPulldownLabelFive = 'String text'; $udfPulldownLabelSix = 'String text'; $udfPulldownAdminOne = boolean; $udfPulldownAdminTwo = boolean; $udfPulldownAdminThree = boolean; $udfPulldownAdminFour = boolean; $udfPulldownAdminFive = boolean; $udfPulldownAdminSix = boolean; // Group pulldown label and admin $udfGroupPulldownLabelOne = 'String text'; $udfGroupPulldownLabelTwo = 'String text'; $udfGroupPulldownLabelThree = 'String text'; $udfGroupPulldownAdminOne = boolean; $udfGroupPulldownAdminTwo = boolean; $udfGroupPulldownAdminThree = boolean; // Resource pulldown label and admin $udfResourcePulldownLabelOne = 'String text'; $udfResourcePulldownAdminOne = boolean; ?>
Binding API Parameters to PHP Variables
Well, let’s link those parameters to the data the API expects. Use PHP’s array_filter()
to cleanly map your parameter values:
<?PHP $urlData = array_filter([ 'udf_text_1_label' => $udfTextLabelOne, 'udf_text_1_admin' => $udfTextAdminOne, 'udf_date_1_label' => $udfDateLabelOne, 'udf_date_1_admin' => $udfDateAdminOne, 'udf_pulldown_1_label' => $udfPulldownLabelOne, 'udf_pulldown_1_admin' => $udfPulldownAdminOne ]); ?>
This ensures only non-empty values are passed to the API. Comment/uncomment parameters as needed to customize your request.
Making the API Call to Update
Ready for a little programming magic!?
We’ll use the ccbDetails
function to send our API call. Unlike previous tutorials where we used GET
, this time we’re going with a POST
request. Why? Because we’re not just fetching data—we’re making changes.
<?PHP $rss = ccbDetails('post', $urlData, [ 'srv' => $apiService ]); ?>
This function handles all the backend heavy lifting—authentication, authorization, and calling the API.
Processing the API Call Response
Once the API responds, it’s time to parse the returned data. We’ll use PHP’s XPATH
query method to extract the juicy details:
<?PHP $nodes = $rss->xpath("//custom_fields/custom_field"); foreach ($nodes as $field) { echo "Field ID: " . $field->id . "\n"; echo "Field Name: " . $field->name . "\n"; echo "Updated Successfully!\n"; } ?>
This snippet loops through the custom fields and prints their details. Think of it as your “mission accomplished” report.
Let’s test and tweak
Here’s what your script should look like in its entirety. Save and run your script on your server or in your local development environment, and watch the magicical update unfold.
<?PHP
?>
Don’t forget to check the CCB system to confirm the updates. Congratulations! 🎉 You’ve just conquered one of the trickiest parts of the CCB API. Pat yourself on the back—you’ve earned it.
If something doesn’t work as expected:
- Double-check your parameter names.
- Confirm that your server is properly set up to make API calls.
- Consult the CCB API Documentation for any quirks.
Remember, this tutorial is just the beginning. With a little tweaking and experimenting, you can extend this script to cover even more complex use cases.
Now go forth and customize those labels like a champ! 🚀