Survey
Author: Andy Gardner
1. Introduction
This guide will quickly walk you through installing and configuring a custom survey 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 Sever. 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 a number of components to the survey, but each one is fairly simple. The chain of events for the survey begins when a user fills out the survey and submits it. The submission is then parsed by a php script and written out to an XML file containing the results of every survey 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 survey results.A detailed breakdown of the components follows.
3. Survey Data Definition
The data definition for the survey 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 survey. The 'Action' chooser has you select the script the form will execute on submission. For us, this is the survey.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').
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 survey page, make sure the 'Maintain absolute links' option is enabled. Without it, survey.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 survey to parse correctly. Be careful when modifying.
- When filling out the survey, 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 survey.
- If number 4 applies, then in order to use the survey you must attach the survey-region-include block to the region you want the survey to show in. Adjust the blocks parameters so it points to the survey-config file and the survey-region.php file (see below).
4. Survey in a non-Default region
The survey-region.php file extracts the html from the survey page and displays it in the region containing the survey-region-include block.5. The Survey Script
The survey script's purpose is to parse the submitted form into XML and then write that XML out to a file called 'surveyresults.xml'. The XML, in addition to the answers the user provides, also includes the user’s IP address and the timestamp for the submission. These two pieces of data are used to prevent a user from submitting the survey more than once in a 24-hour period.NOTES:
- You do not need to create the surveyresults.xml file ahead of time. If it does not exist, then the script will create it.
- You may notice a '3Q3' string attached to some of the questions in surveyresults.xml. This is an identifier signaling the script that the question has a question mark.
6. The Survey 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 your 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 Survey 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 surveyresults.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
'survey-formatted-results'.
NOTE:
You do not need to create the survey-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 an XML block using
the following XML:
<?xml version='1.0'?>
<results></results>
8. The Survey Results Graph
The survey-results-graph stylesheet takes the data from the
survey-formatted-results block and makes a bar graph giving a
visual representation of the survey results. The
stylesheet currently supports two views of the results, one for
surveys with one question, and one for surveys 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 you like. The script files must be kept in the same folder together.
- Create a page for your survey. Use the survey-data-definition and survey-stylesheet pair for its Default region. See section 3 note 5 for details.
- If you want, create your graph results page now. Make the survey-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.
Survey Files
- survey-aspx.cs
This is the .NET survey code. - survey-data-synchronizer-aspx.cs
This is the .NET data synchronizer. - survey-config-data-definition.xml
Contains the XML data to make a survey configuration data definition. Once you have created the data definition, you can remove the file. - survey-config.xml
A sample file showing what a survey configuration file will look like. - survey-data-definition.xml
Contains the XML data to make a survey data definition. Once you have created the data definition, you can remove the file. - survey-data-synchronizer.php
This is the script that runs on a schedule. It parses surveyresults.xml and creates a CMS block called survey-formatted-results that can be read by XSL. - survey-formatted-results.xml
A sample file showing what the XML generated by survey-data-synchronizer.php looks like. - survey-region-include.xml
Contains sample XML of what your block should look like. - survey-region.php
The script that pulls the html from the survey page for use in a non-Default region. - survey-results-graph.xsl
The stylesheet that uses survey-formatted-results to generate a bar graph of the survey results. - survey-stylesheet.xsl
Stylesheet used to generate the HTML for the survey. - survey.php
This is the survey script. Create a folder in your CMS to contain it and the other script files. - surveyresults.xml
A sample file showing what the XML generated by survey.php looks like. - survey.zip
ZIP file containing all of the necessary files for the survey to work.
Last modified on Mon, 30 Oct 2006 12:47:34 -0500
Top / Up / Table of Contents