Creating a custom spiritual gifts assessment questionnaire – PART III

Welcome back to this week’s tutorial. We’re picking back up from where we left off last week.

As a quick recap, Part I and Part II covered the following aspects:

  • Creating a php form
  • Creating an excel/csv spreadsheet of spiritual gift questions and a CCB spiritual gifts key
  • Parsing excel/csv spreadsheet of display questions for form viewing via a web browser
  • Submitting and validating form data
  • Excluding certain question categories based on category key
  • Summing, grouping, sorting and storing results via an excel/csv spreadsheet

Today’s tutorial focuses on completing the following items:

  • Creating a page to view a list of completed spiritual gifts assessments
  • Emailing a summary to download spiritual gifts excel/csv file

Ready to get started? Let’s do this then!

For starters, below is a simple screenshot of what we’re producing in today’s tutorial, minus the Assessment Manager and Take SGA links. We’ll cover both of those in the coming week(s).

Google’s Content Delivery Network

I know you’re wondering what Google has to do with a tutorial about spiritual gifts assessments, right?

Well, do you see the Email Report (see screenshot above) text just to left of the linked SGA CSV results file?

Today, I’ll show you how to use Google’s Content Delivery Network (CDN), specifically jQuery javascript library, to trigger the email to be sent.

To start, using a text editor of your choice, open and save a php file named sga-reports.php. Make sure the file, sga-reports.php, is saved in the same directory as the spiritual gifts assessments form mentioned in Part I.

Start a HTML5 file and include the Google’s CDN for jQuery link within the <head></head> tags (as shown below).

Yes, you’re going to learn a bit of Javascript magic today to go along with your PHP magic.

In addition, enter titles in between the <title></title> and <h1></h1> tags.

Listing completed spiritual gifts assessments

Okay, we have our base HTML5 code ready.

It’s now time to prepare and retrieve the list of completed spiritual gifts assessments files. The files that we’re in search of are CSV summaries of each person’s tabulated results.

Just under the <h1></h1> tags, enter the following code:

In short, the prepareReports function retrieves a list of CSV files. It also returns a html list of linked CSV files with text buttons next to each link for triggering a link to be sent via email.

Yes, this tutorial is just that easy. That simple line of code above will produce every single CSV in a html linked list.

Okay, okay… I know, I should explain in greater detail. No worries, I will. 🙂

I’ll explain about the heavy lifting both the prepareReports and getReports functions are completing at the end of this tutorial.

Triggering the email to send completed spiritual gifts assessments

Okay, so about this emailing of the completed spiritual gifts assessments results.

I won’t show you how to deliver the results as an email attachment (try this tutorial) because most email clients might flag attachments as spam when coming from an unknown source.

But what I will show how to trigger the email button to send a download link via email.

Although we won’t use a form in this tutorial, you could, with a bit of elbow grease and time, modify this tutorial to accept a user’s email as input when clicking on the Email Report button for the respective spiritual gifts assessments results.

Like I said, I’ll leave this part up to you to figure out and learn. 🙂

Nevertheless, it’s time for a bit of Javascript magic.  Start with the following code, ensuring that we use jQuery’s $(documents).ready method so that our Javascript is initiated on page load:

Next, if you look closely to the response_object’s HTML in the prepareReports function, you’ll see that the Email Report text has been placed in between a <span></span> element.

The span element has an id, and this id is used to capture and trigger the email event.

In this example, the id happens to be the name of the spiritual gifts assessments results CSV file.

To capture and trigger email event of the span text being clicked, we’ll use the following javascript jQuery code:

Within the span click function, add an if confirm statement to be sure to send an email of the report using Javascript confirm method.

Within the if confirm statement, use jQuery’s $.post method to submit the spiritual gifts assessments results CSV filename and email address  as POST data to another php file (sga-emailer.php covered in next section).

Since we made the span id to be the spiritual gifts assessments results CSV filename, then accessing the span id is as simple as using this.id.

To obtain the email address, as I said before, you can use a form if you would like, or you can simply hardcode the email address if only emailing to yourself.

I mention using a form because you may decide in the future that you would like to one-click email each participant directly from the reports page.

So, bind both the spiritual gifts assessments results CSV filename and email address to the appropriate labels:

Finally, we add success and failure functions, and add alert messages to their respective functions:

Emailing completed spiritual gifts assessments

Now that you have the Javascript in place for triggering the email action, it’s time to send the email.

To send the email, the jQuery $.post method submitted form data to a PHP file: sga-emailer.php. Crack open your text editor, and name and save the sga-emailer.php file.

One of the first actions in this newly create file is sanitizing the input data using PHP’s built in filter_var method.

Next, define a url variable that creates a url that links to the spiritual gifts assessments results CSV filename that is to be used in the email as the download link.

From here, it’s pretty simple. Define the following variables and set their values accordingly:

  • to variable is equal to email variable (email recipient’s email)
  • from is equal to sent by email address string (email from person’s email)
  • from_name is equal to sent by name of person/organization (email from organization/person name)
  • message is equal to HTML Download Text that is linked to url variable
  • subject is equal to text of email subject line

Last but not least, the email should contain headers for the message to be sent using a certain type of format (think html or text email).

Once those items are defined and values set accordingly, then use PHP’s built-in mail method to send the email, passing to the method the to, subject, message, and headers variables in their respective order.

And that’s it. Of course, you could add a bit more error checking to see that the email was actually sent, but I’ll let you read up on that one. 😉

Now, your entire email code should look like the following:

Ready to save and test?

Save your pages, both sga-reports.php and sga-emailer.php.

For now, don’t worry about the spiritual gifts assessments results CSV file name being linked to the chart.php file.

We’ll cover the chart.php file in next week’s tutorial. For now, study up on this tutorial because we have covered a lot of ground today.

Okay, I’ll see you back here next week!

P.S. Your sga-reports.php code in its entirety should resemble the code below:

prepareReports function

The prepareReports function does quite a bit of heavy lifting to retrieve the spiritual gifts assessments results CSV files, and then create HTML links and email link for each file.

getReports function

The getReports function simply uses PHP’s built-in glob function to find files of a certain search parameter. In this tutorial, you can see we used *sga-results*.csv as the text parameter to search by. The function then returns an array of each filename.

 


Please comment if this tutorial has helped you.