Quiz
Author: Andy Gardner
1. Introduction
This guide will quickly walk you through installing and configuring a custom quiz on your site. It assumes that you have a recent version* of PHP installed on your web server and that you are comfortable with Cascade. Knowledge of PHP is also useful, but not necessary to use this guide.
*You must have PHP 5 or later. Only those versions support SimpleXML, which is required for this widget to operate.
2. Components
There are many components to the quiz, but each one is fairly simple. The chain of events for the quiz begins when a user fills out the quiz and submits it. The submission is then parsed by a PHP script and written out to an XML file containing the results of every quiz that has been submitted. Then another PHP script, running on a schedule set by you, will periodically parse the XML from that file and write it into an XML block. That block, when combined with its corresponding stylesheet, will generate HTML code displaying a bar graph that represents the quiz results.
A detailed breakdown of the components follows.
3. Quiz Data Definition
The data definition for the quiz page is fairly self explanatory when filling it out. The 'Thank You' page should be the page the user is redirected to after he/she submits the quiz. The 'Action' chooser has you select the script the form will execute on submission. For us, this is the quiz.php file.
When making form items, use the drop down to choose its type. The 'Name' field is where you put the question and 'Value' is where you put your possible answers. 'Default Value' is typically only used for multiple choice questions, and its value does not need to be repeated amongst the 'Value' assets (i.e. If your 'Default Value' is 'Green', then you do not need to include 'Green' as a 'Value'). You must include the correct answer, and it must match one of the values you list.
The stylesheet that parses the data definition generates an HTML table containing the form. The stylesheet can be edited so the form displays the way you want it to. Be careful not to alter the XSL too much; it performs some operations that are necessary for the scripts to work. Pair the stylesheet with a 'current page' block.
NOTES:
- When publishing the quiz page, make sure the 'Maintain absolute links' option is enabled. Without it, quiz.php will not be able to find the 'Thank You' page.
- In the stylesheet you will notice several hidden fields included in the form, as well as javascript and an extra template that are called. These must remain enabled for the quiz to parse correctly. Be careful when modifying.
- When filling out the quiz, only use alphanumerics for the questions and answers. However, the script does support question marks for questions.
- Make sure the 'Title' metadata field is filled in with the name of the quiz.
- If number 4 applies, then in order to use the quiz you must attach the quiz-region-include block to the region you want the quiz to show in. Adjust the blocks parameters so it points to the quiz-config file and the quiz-region.php file (see below).
4. Quiz in a non-Default region
The quiz-region.php file extracts the html from the quiz page and displays it in the region containing the quiz-region-include block.5. The Quiz Script
The quiz script's goal is to parse the submitted form into XML and then write that XML out to a file called 'quizresults.xml'. The XML, in addition to the answers the user provided, also includes the users IP address and the timestamp for the submission. These two pieces of data are used to prevent a user from submitting the quiz more than once in a 24 hour period.
NOTES:- You do not need to create the quizresults.xml file ahead of time. If it does not exist the script will create it.
- You may notice a '3Q3' string attached to some of the questions in quizresults.xml. This is an identifier signaling the script that the question has a question mark.
6. The Quiz Configuration
The data definition for the configuration file is very short. It includes the basic access parameters for your CMS. These fields must be filled in order for the synchronizer script to update our CMS.
NOTE: These fields must be filled out carefully as the synchronizer code is sensitive. Use the default values included in the data definition to help guide you. An extra trailing or leading slash will prevent the script from accessing the CMS.
7. The Quiz Data Synchronizer
The data synchronizer script is executed periodically according to a schedule set by you. It's goal is to take the XML from the quizresults.xml file and rewrite the XML into a format easily parsed by a stylesheet. This new XML data is then uploaded to a block in the CMS called 'quiz-formatted-results'.
NOTE: You do not need to create the quiz-formatted-results block ahead of time. If it does not exist the script will create it. However, if you wish to set up your graph results page ahead of time, go ahead and create the block. Make it an XML block, and for its contents give it: "<?xml version='1.0'?> <results></results>" (no quotes).
8. The Quiz Results Graph
The quiz-results-graph stylesheet takes the data from the quiz-formatted-results block and makes a bar graph giving a visual representation of the quiz results. The stylesheet currently supports two views of the results, one for quizzes with one question, and one for quizzes with multiple questions.
NOTE: The HTML code in the stylesheet can be modified to your liking. However, you will need to be careful with what code you change. See the comments in the stylesheet.
9. Setup and Use
- Import all of the files into your CMS. The XML for the data definitions should be used to create those data definitions. The stylesheets can be placed anywhere in the CMS the you like. The script files must be kept in the same folder together.
- Create a page for your quiz. Use the quiz-data-definition and quiz-stylesheet pair for its Default region. See section 3 note 5 for details.
- If you want, create your graph results page now. Make the quiz-formatted-results just as described in the notes for section 6.
- If you decide to not make the graph results page now, you can make it after the synchronizer script has run for the first time.
- When in doubt, publish the page with 'Maintain absolute links' checked.
Quiz Files
- quiz-PHP.zip
This zip file contains all the necessary PHP scripts, XML, and XSL. - quiz-php.txt
This is the main PHP scripts that does the form processing. - quiz-config.xml
This is an example XML config file. - quiz-config-data-definition.xml
This is a data definition to visually configure the XML configuration file. - quiz-data-definition.xml
This is a data definition used to visually build quizzes. - quiz-data-synchronizer.php
This is a PHP script to synchronize the quiz responses with the CMS on a regular basis. - quiz-formatted-results.xml
This is an example XML results file from quiz responses. - quiz-region-php.txt
This is PHP code to place in a region to include the quiz output. - quiz-region-include.xml
This is an example include to pull in the quiz region. - quizresults.xml
This is a generic XML quiz results file. - quiz-results-graph.xsl
This is an XSLT to output the quiz results as a graph. - quiz-stylesheet.xsl
This is an XSLT to output all the quiz results.