Create a process list drop down menu – Part II

Welcome back for another CCB Tutorial.

This week’s tutorial picks up from where we left off last: Create a process list drop down menu.

It was a fairly simple tutorial to retrieve the entire list of CCB processes and place the list into a key-value pair select list, also known as a drop down menu.

But the simplicity stops there at the last tutorial, and time for a bit more challenging assignment.

Today’s tutorial combines the process list drop menu tutorial with the list retrieval of queues for a specific process tutorial.

Intermingling both process and queue tutorials is going to provide an opportunity to learn a new scripting language (if you didn’t already know it): Javascript.

That’s right! You’re going to learn a bit of Javascript, using jQuery library, to make some magic happen on the screen. 🙂

We won’t complete the overarching goal of this tutorial today, but do hang in there. This tutorial series will likely take us through the end of June to complete.

Hang in there… it’ll be well worth it in the end and likely spark a few ideas for some other custom projects for your church.

We have a lot to cover, so let us get started.

Prepare variables and includes

And we’re off… Open a text editor of your choice, naming and saving the following PHP file: pq-jump-menu.php.

As usual, add the necessary comments as well as the including the config.php file. Next, include the following variables:

  • processDomID – this variable and its value is used to uniquely identify the process select / drop down menu
  • procQueueDomID – this variable and its value is used to uniquely identify the process queue select / drop down menu
  • procListOne – this variable and its value contains the select / drop down menu options of CCB processes

Be sure to set each variable to its respective value as shown below:

  • Set proccessDomID variable equal to processSelect string text
    Set procQueueDomID variable equal to queueSelect string text
    Set procListOne variable equal to getProcessSelect() function

Prepare the HTML5 DOM and DOM Elements

Next, it’s time to create a HTML5 doc using the code below. One of the first things to note about the code is that Google’s CDN is used to include the jQuery javascript library.

We’re using Javascript and jQuery to hide/show and populate the queue select / drop down menu, and to hide/display the error message.

Become quite familiar with jQuery because it has the “power for the hour” to allow for awesome and intuitive user experience and interactiveness.

Then next thing to note is the assignment DOM ids to specific HTML elements within our HTML5 document.

Notice we’ve assigned message as an id on the table cell just underneath the title in H1 tag. This area is used to display our error message.

Next, create another table row with two cell columns.

The first column is for the process select / drop down menu, which the procListOne variable is echoed. The second column is for the process queue select / drop down menu, which is a select element that has assigned to it the procQueueDomID as its id and name respective values.

Retrieving list of CCB processes using getProcessSelect function

To retrieve a list of CCB processes, we’ll use the code created in last week’s tutorial. That’s right! We are going to refactor or recycle your efforts from last week.

So copy and paste last week’s code into your pq-jump-menu.php file (at the very end after the closing HTML tag).

Now remove the comments, include, and the processDomID variable lines. The remaining code will now be transformed into a reusable function we’ll name getProcessSelect.

Define the getProcessSelect function without any arguments to be passed. Be sure the is within the getProcessSelect function curly brackets.

Next set a global variable within the getProcessSelect function so that we can access the processDomID variable.

The final change is change the word echo to return at the very bottom of the function. And there you have it. You now have a reusable function that retrieves the entire list of CCB functions.

For now, keep this function within the pq-jump-menu.php file. But in the future, you’ll likely want to include it in the general.php file since it’ll be reused quite often. 😉

Time to make the screen dance with jQuery

Okay, time for jQuery. A few sections back we added Google’s CDN for jQuery to our code. I won’t go into all the jQuery details, but will provide links for you to read up on at your leisure.

It’s time to write a few lines of jQuery to hide/show DOM elements and retrieve a list of CCB queues for a selected process.

Let’s start with hiding and showing DOM elements. Right now, your page looks like the following:

This is okay, but we really shouldn’t show the second select empty until a selection is made. To hide the element, we’ll use jQuery.

Just after the close body tag, create open and close script tags, giving the open script tag’s type the following value: text/javascript. Next, use jQuery’s Document Ready function.

Next, create a message variable to access the div used to show error and success messages to the user. This div id is message as well.

Next, create and initialize the hideAll() function. We’ll use this function to hide the message div and select menu containing selected CCB queues for a selected process. Each element uses the jQuery hide method.

Don’t you like jQuery and how efficient it is. No worries, more to come. You’ll like it because it’ll reduce the lines of code we’ve all spent long days writing.

Now that our hideAll function is created and initialized, it’s time to bind action to our process select / drop down menu.

When a user makes a change or selection, we’ll want it to retrieve the selected value, submit that value to another script to retrieve and return a respective list of queues. Easier said that done, but I’ll show you how to do it. 😉

To bind an action to the process select / drop down menu’s id, use jQuery’s change method. Notice that we’re using PHP within javascript too to specify which id should possess the change method. This allows your code to be reusable. 😉

Once a change, simply a click and selection of drop down value, happens, we’re now ready to retrieve the selected value. To do so, create a pid variable, setting it equal to the following:

Now, go ahead and also initialize the hideAll function because we don’t want the user seeing their last known selection when making a new selection.

Now it’s time for a bit of if else logic for handle the default option and actual CCB process selection. If the user makes the default selection, then display a message to them to “Please select a process from the drop down menu.” using the following code within the if statement:

Notice that we’re making use of the $messageDiv variable we created a few lines up, and using jQuery built-in methods (i.e., text, show, delay, fadeOut) to inject and show the user a message.

Now it’s time to address the else section of the statement when a selection has been made by the user and is not the default selection.

To retrieve the list of CCB queues for a selected process, we’ll use jQuery’s post method, also known as AJAX.

Create a post_data variable and set it equal to a JSON object that binds processid label to the pid variable. The processid is an arbitrary value that I created to pass the value from the select menu to the post method.

Next, create the post call, setting your URL (required), the data to be passed (optional), the function and it’s respective attributes (optional), and the dataType (optional, but I’m choosing to use JSON due to it’s efficiency).

For now, don’t worry about the URL and the code with the pq-queue-dd.php file. I’ll cover that in a section or two. 😉

Within the post method, let’s do a bit of simple error checking (always a good idea). This will require a if else statement based on the function’s response attribute of the post method.

Simply put, if the response.type is equal to error, then we know something bad happened when making our jQuery ajax call to pq-queue-dd.php.

Within the if statement, we’ll make use of the $messageDiv variable using jQuery built-in methods (i.e., text, show) to inject and show the user a message (sound familiar). Love the ability to refactor yet? 🙂

For the else statement, we know we must have a non-error data response due to simple error checking. Within the else statement, we’re now ready to access the process queue select / drop down menu using it’s id (i.e., queueSelect).

Create a $selectMenu variable and set it equal to the id of the process queue select / drop down menu.

Notice PHP is used to access the div id for the process queue select / drop down menu. Love refactoring yet? 😉

Next, we’ll use do some heavy lifting with easy jQuery methods. Use jQuery find and remove methods, we find and remove all the previous select / drop down menu options for process queues while appending new options to the end of process queue select / drop down menu.

Once done, we use the jQuery show method to display the process queue select / drop down menu that was once hidden due to the hideAll function.

And that’s all there is to jQuery, but only the beginning. This tutorial barely scratches the surface on all you can do with jQuery. But I caution you to make use of MVC-friendly frameworks such as React, Vue, Node, or Angular. jQuery is good for simple backyard or prototype projects, but shouldn’t be used (in my opinion) to build skyscrapers. 😉

So, here’s what you should have so far… look at you code your little heart out. 🙂

Oh before I forget, the queue data in pq-queue-dd.php

And you thought you we’re down, aye? Not by a long shot. There still remains the retrieval of the selected process’ list of queues when a selection is made.

Remember the pq-queue-dd.php file I mentioned early? It’s time to bring it to life. The good news is that we’ve already covered how to retrieve list of queues for a a specific process in a previous tutorial (whew).

Create a new php document, naming and saving it pq-queue-menu.php (in the same directory with pq-jump-menu.php). Be sure to include the config.php just as we normally would.

We’re going to do some things a bit different with this file and some the same as we’ve always done.

For the bit different, we’re going to use PHP’s built-in json_encode method to return our data as a JSON object. Remember setting the post method dataType to JSON earlier?

After you’ve included config.php, create an output variable and it to the following:

This is a catchall variable should something horrendously go wrong and we’re not able to pinpoint exactly where. It encapsulates key-value pair data in an array encapsulated by json_encode method.

Next, we want to add a bit of simply error checking. We don’t want users simply accessing the pq-queue-menu.php file directly via a web browser without a POST call being made. To ward off any suspicious activity and behaviors, use a if not POST statement to redirect the user the to the pq-jump-menu.php file. Safety first… 😉

Next, create a selectPid variable to retrieve and access the processid variable passed from pq-jump-menu.php’s jQuery post call (remember that from a few sections back?).

Remember to ALWAYS sanitize $_POST and all input data submitted from users. Safety first. 😉

Time for another round of simple error checking to ensure that a process id was passed via the jQuery post call. Use a simple if statement to check that the selectPid variable is empty. If it is empty, then create a specific error message stating that the process id was not passed. Then we’ll kill or stop the script in it’s track using the PHP’s built-in die method.

Now that we’re safe, secure, and reduced the risk for errors, we can now turn to a previous tutorial for retrieving queues into a function just like we did for processes.

Create a objectReturned variable and set it equal to getQueueListDD function, passing to the function the selectPid variable as the one and only argument.

Next, create a output variable so that we can return the objectReturned variable’s data as a JSON response using the die method once more.

That’s it! Here’s what your code looks like:

Yes, you’ve survived and overcome this tutorial… YAY! I’m so happy for you.

Wait, so what now?

I figured you were thinking this. I would be too if I were you. What does this tutorial accomplish, right?

As of now, you are able to retrieve a list of processes in a drop down menu. Based on your process selection from the drop down menu, then you are able to see a list of queues associated to a process in a secondary process queue (see below).

And once the queue for the given process is selected:

Well, the next part of this tutorial (coming soon) will be to obtain and display a list of individuals associated with a queue. And that’s all I’m letting you know for now.

You’ll have to tune in next week to see where and how we’re expanding the functionality of this tutorial. For now, rest up and review.

Don’t forget to let me know if you have any questions or challenges along the way. Drop me a comment below. See ya next week. 😉

getQueueListDD function

Just like we did for the process function, create a getQueueListDD function with a pid variable as the single function argument.

Copy the work we did form this tutorial into the function. Be sure to use the queue_list CCB API service and don’t forget to set the processID variable equal to the pid variable.

Take note of the changes I made to the file, adding the HTML DOM elements to creation option tags for the select menu via the response_object variables.

Also, don’t forget to change the echo to return too. 😉

Please comment if this tutorial has helped you.