PHPSurveyor
(V0.99)
Documentation
INDEX
1.
Make sure you can use
PHPSurveyor on your website.
You need access to a web server,
with PHP 4.1.0 or better and access to a MySQL database. You will
need about 2 to 2.5 Megabytes of disk space for the scripts.
2.
Download the PHPSurveyor
package
Visit the sourceforge website to
download the latest
PHPSurveyor package. http://sourceforge.net/projects/phpsurveyor/
The
package is around 300kb to
400kb in size.
Download the zip file and save it to your local disk.
3.
Unpack the PHPSurveyor
package
Uncompress the zip file into a
dedicated
directory/folder using your preferred compression program. Ensure
that your compression program uncompresses the directory structure
with the files (this is default behaviour for most compression
programs). The unzipped package will have the following directory
structure:
/phpsurveyor* |
/templates |
/default |
|
|
|
/edgyblue |
|
|
|
/bubblegum |
|
|
/lang |
|
|
|
/tmp |
|
|
|
/admin |
/images |
|
/lang | /english | ||
|
|
/classes |
|
*this folder named by you |
Directory
Permissions
The scripts
need
to have 'write' access to the admin directory in order to import
surveys. The "/phpsurveyor/tmp" directory is used for
uploads and should be set to read/write/execute all. In linux or unix
it should be chmod to 777. If you wish to use PHPSurveyor to iontrol
Apache Directory Security, the /phpsurveyor/admin
directory should be set to read/write/execute all; in linux/unix
chmod 777. If you plan to set Apache Directory Security using other
methods (ie: manually or using a web admin tool) you can leave this
directory set to read/execute - chmod 755. The other directories can
be set to read only or in linux/unix chmod 755.
You may wish
to set the permissions on each file within the /phpsurveyor/admin
directory to 755.
4.
Collect
information about your server
You will need to know the
following things to install PHPSurveyor on your web server correctly.
Your intended website URL where your scripts will reside (ie: 'http://my.domain.com/phpsurveyor')
The physical disk location on your server where your scripts will reside (ie: '/home/usr/htdocs/phpsurveyor')
The IP/net location of your MySQL database server (ie: 'localhost')
If your MySQL database server uses a non-standard port, you should find out what port this is.
Your username and password for your MySQL database server
If your web server is hosted on a Windows based Operating System, try and find out the location of the mysql binary files. (ie: 'c:/mysql/bin')
5.
Configure
PHPSurveyor
Edit the config.php file in the
/phpsurveyor/admin
directory using your preferred text editor. The following settings
should be adjusted:
$databaselocation: Set this to the IP/net location of your MySQL database server. In most cases "localhost" will work.
$databaseport: Set this to the port used by your MySQL database server. In most cases "3306" is used (this is the MySQL default).
$databasename: The name of the database on your MySQL database server that you will be using for PHPSurveyor. If you have high level permissions on the MySQL server, you can create a database from PHPSurveyor. In this case, put whatever the database will be called into this setting. Alternatively, you can use the name of a previously created MySQL database here.
$databaseuser: Your username for MySQL
$databasepass: Your password for MySQL
$databasetabletype:
The default table type to use
when creating tables - default is "MyISAM"
$useidprefix: Default setting is 0 (zero). If you set this to 1 (one) then responses to surveys will use a prefix in their unique id number, set by the following string $idprefix. You can use this to set up multiple copies of PHPSurveyor using the same survey, then merge the results from different servers into one single responses table at a later date.
$idprefix:
The prefix to add to the unique id for
each survey response on this server.
$rooturl: This should be set to the URL location of your phpsurveyor scripts. The default setting will attempt to do this for you, so often you won't need to change anything here (the section {$_SERVER['SERVER_NAME']} tries to do this automatically. If it doesn't work, type the server url location in manually - for example "http://www.mydomain.com/phpsurveyor".
$rootdir: This should be set to the physical disk location of your scripts. The default setting will attempt to do this for you, so often you won't need to change anything here (the section {$_SERVER['DOCUMENT_ROOT']} tries to do this automatically. If it doesn't work, type the disk location in manually - for example "/home/public_html/phpsurveyor".
The subsequent location settings will work without modification for any standard PHPSurveyor installation (ie: where you use the normal directory structure) so don't modify these unless you've renamed directories.
$homeurl: This should be set to the URL location of your administration scripts. These are the scripts in the /phpsurveyor/admin folder. This should be set to the WEB URL location - for example "http://www.mydomain.com/phpsurveyor/html/admin". Don't add a trailing slash to this entry. The default setting in config.php attempts to detect the name of your server automatically using a php variable setting - {$_SERVER['SERVER_NAME']}. In most cases you can leave this and just modify the remainder of this string to match the directory name you have put the PHPSurveyor scripts in.
$publicurl: This should be set to the URL location of your 'public scripts'. The public scripts are those located in the "phpsurveyor" folder (or whatever name you gave to the directory that all the other scripts and directories are kept in).
$tempurl: This should be set to the URL location of your "/phpsurveyor/tmp" directory - or a directory which you would like PHPSurveyor to use to store temporary files, including uploads. This directory must be set to world read/write/execute (ie: chmod 777)
$imagefiles: By default you should leave this pointing to the URL location of /phpsurveyor/admin/images - where the images are installed initially. You may, however, prefer to move these images to another location and if so point this to the URL directory where they are stored.
$homedir: This should be set to the physical disk location of your administration scripts - for example "/home/usr/htdocs/phpsurveyor/admin". Don't add a trailing slash to this entry. The default setting in config.php attempts to detect the default root path of all your documents using the php variable setting - {$_SERVER['DOCUMENT_ROOT']}. In most cases you can leave this and just modify the remainder of this string to match the directory name you have put the PHPSurveyor scripts in.
$publicdir: This should be set to the physical disk location of your 'public scripts'.
$tempdir:
This should be set
to the physical disk location of your /phpsurveyor/tmp directory so
that the script can read and write files.
$sitename: This is the name that will be displayed in the administration web pages for your site. Name it anything you want (ie: "My Organisations Surveying Tool")
$scriptname: Leave this as "admin.php" unless you have changed the name of the main administration script. If you prefer to have your main administration script titled "index.php", you can rename the admin.php file, and the script will know you've done this by changing this setting to "index.php".
$accesscontrol: This setting determines whether PHPSurveyor tries to apply security settings for you. A setting of "1" turns this feature on, and "0" turns it off. Having security turned off here does not stop you from using your Web Servers built in security capacity, but means that PHPSurveyor does not attempt to detect or control any of it. If you are using a non Apache web server you should set this to "0".
$defaultuser: When the script has accesscontrol turned on this is the default user that is created when PHPSurveyor first sets up your security settings.
$defaultpass: When the script has accesscontrol turned on this is the default password that is created when PHPSurveyor first sets up your security settings.
$siteadminemail: The email address of the site administrator
$siteadminname: The name of the site administrator
$surveyfaxnumber:
The fax number used when producing a
'printable' survey.
$dropdowns: This can be set to either "L" or "R". Setting it to "R" will result in List type questions being displayed as radio buttons, whereas "L" will result in List type questions being displayed in a 'dropdown' list box.
$lwcdropdowns: This works in the same way as the previous setting, however for 'List with Comment' type questions.
$dropdownthreshold: When you have selected "R" for $dropdowns, this allows you to set a maximum number of options that will display as radio buttons, before converting back to a dropdown list. If you have a question that has a large number of options, displaying them all as radio buttons can look unweildy, and be counter-intuitive to users. Setting this to a maximum of, say 25 (which is the default) means that large lists are easier for the survey participant to use.
$repeatheaders:
With the array (flexible) type
question, often you'll have a lot of answers, which - when displayed on
screen - take up more than one page. The repeatheaders setting lets you
decide how many answers should be displayed before repeating the header
information for the question. A good setting for this is around 15. If
you don't want the headings to repeat at all, set this to 0 (which is
the default).
$maxemails: When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities, and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a php script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting.
$defaultlang: This should be set to the default language to be used in your administration scripts, and also the default setting for language in the public surveys. You can change this setting for public surveys on a survey-by-survey basis from the admin scripts.
$OS: Leave this setting alone. It detects the operating system of your web server.
$apachedir: This setting tells PHPSurveyor the location of your “htpasswd” executable file. If your server is Linux/Unix based and you leave this setting blank (“”;) PHPSurveyor will attempt to find the location automatically. Windows servers probably need this filled in to work. (eg: $apachedir = “c:/program files/apache group/apache/bin”;)
$mysqldir: This setting tells PHPSurveyor the location of the mysql binary files (in particular, “mysqldump”). If your server is Linux/Unix based and you leave this setting blank (“”;) PHPSurveyor will attempt to find the location automatically. Windows servers need this entry filled in. (eg: $mysqldir = “c:/mysql/bin”;)
$timeadjust: If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia but use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses.
$dbprefix: Leave this setting blank (ie: $dbprefix="";) if you are using a separate database for PHPSurveyor alone. If you want to share a database between PHPSurveyor and other database applications, add a prefix to this setting. My recommended prefix is "phpsv_", but really - this is up to you.
$allowmandbackwards: A setting of 1 for this variable will allow survey participants to move to a previous question even if they haven't answered a mandatory question. If it is set on 0, then participants will have to answer that question even to move to a previous question.
$deletenonvalues: This is a fairly difficult setting to explain. If set to 0, if a question (let's call it question "b") is only displayed conditionally (ie: based on the answer to a previous question - let's call it question "a"), and a survey user answers that question (question "b"), but then moves backwards through the script and changes the previous question (question "a") such that this question (question "b") no longer displays, the survey will still remember and save their answer to the no longer applicable question (question "b"). I generally prefer this to be the case, on the basis that it may be interesting to know this information anyway. But, if you would prefer that the script be consistent and refuse to store information that shouldn't logically display you can change this setting to 1, and the script will not save this redundent information.
$shownoanswer:
When a
question of a radio button/select type that contains editable answers
(ie: List, Array questions) is not mandatory and $shownoanswer is set
to 1, an additional entry is shown for "N/A" - so that participants may
choose to not answer the question. Some people prefer this not to be
available. Set this to 0 to turn this off.
$usejpgraph: If you have a correctly configured jpgraph class set up on your server, you can turn this feature on (1=on, 0=off) and the statistics script will display pie chart graphs in its summary results. This feature is currently in development, so expect a few weird outcomes.
$jpgraphdir:
The physical disk
location of the jpgraph class scripts. This setting is only required if
$usejpgraph is equal to 1.
$btstyle: You can generally leave this setting alone. It sets the default CSS button style in the administration scripts.
$slstyle: You can generally leave this setting alone. It sets the default CSS style for text inputs.
6.
Upload the
files to your webserver.
Using your FTP program, connect
to
your webserver and create a directory to store your scripts. Then
upload the files using the directory structure they are in.
7.
Connect to
the
admin script for the first time
After uploading the files, you
are ready to set up PHPSurveyor from a web browser. Open your browser
and enter the url of your admin.php script. Assuming you used
phpsurveyor as the directory name to store the files in, this will be
something like
"http://your.domain.com/phpsurveyor/admin/admin.php"
The
first time you use PHPSurveyor, the script will connect to the
database you set in the config.php file. If the appropriate table
structure doesn't yet exist, PHPSurveyor will give you a button to
press that will create the necessary tables within this database. If
you have trouble doing this, you will need to use a database
administration program or script (like phpmyadmin) and run the sql
file included in the package called "maketables.sql". Once
these tables exist, you will be able to PHPSurveyor.
8.
What if I
have
problems.
Like all computer programs, most
of the time things
will work just like the instructions say, but sometimes they just
won't. There are too many possible reasons for things not going
according to plan to describe here. If you have trouble, post your
problem and any error messages in the PHPSurveyor forums on
sourceforge.net and more likely than not someone will be able to help
you.
What
if my server has
"safe_mode" turned on? What
if I can't create a
database through a script? What
permissions
should I set? |
PHPSurveyor relies on Apache's web server directory security system. There is no additional security beyond that. This security is often adequate, however if security is a serious issue for you then you should read up about Apache's security from their website. The author of this software takes no responsibility and makes no claims in relation the appropriateness, or secureness of this software. In short, you should consider this script to be insecure unless you can take steps otherwise.
If you do not use Apache (ie you use Microsoft IIS) you will need to disable the security setting ($accesscontrol = 0) in the config.php script, and make any desired security settings using IIS instead.
Linux
File
Permissions
If you are using a Linux server
you should use the
following file permissions.
For your phpsurveyor directory (or whatever you call it) - chmod 755 (read, execute permission to whole world)
For files in the phpsurveyor directory - chmod 755 (read, execute permissions to whole world)
For the tmp directory - chmod 777 - this directory will be empty when created, and is used to store uploaded files, images created by jpgraph and temporary template files from the new template editor script
For your admin directory - chmod 777
(read, write,
execute permission to whole world) or chmod 755 (read/execute)
This folder needs to have write permissions for the creation of a
.htpasswd and .htaccess file. If you plan (or need) to set your
directory security manually, you can set the directory to 755
For files
in the admin directory - chmod 755 (read, execute permissions to whole
world)
The standard files in this folder do not need to have write permissions
- in fact shouldn't because there is no need for them to change during
the use of the script.
Windows
File
Permissions
If you are using a windows server your should
ensure that the admin folder allows the owner of the webserver
process can write files to this directory, however all other files
can be set to read-only and execute.
Other
security
issues
The config.php file contains a username and password
for your MySQL folder. This poses certain security issues,
particularly if you are using a login that has high level
administrative access to MySQL. As a very minimum, therefore, you
should use the security features of the PHPSurveyor script to
password protect the admin web directory. Another thing you could do
to minimise risk (a little) is to create your database separately and
set up a specific login to MySQL that only has rights to your
phpsurveyor database.
The best way to secure this information would be to put the config.php file in a non-web directory. For apache users this means putting it in a directory above the htdocs folder. I have not tested the script with such a configuration, however do not see why it shouldn't work. If you do so, you will need to modify every php file in the script, changing the line (that will occur near the top of the file) that reads `include ("config.php");` to the full path of your config.php file (eg: `include("c:/program files/apache group/apache/phpsafe/config.php");`. As I said, this is not tested, and if you give it a try, could you let me know how it goes? (Email to jason-at-cleeland.org). Future versions of PHPSurveyor will consider a simpler way to refer to this file.
A survey in PHPSurveyor has three integral elements. Every survey must have:
A survey name
At least one group
At least one question
Optional elements to a survey include:
A list of answers to applicable questions
Modifiable labels
Conditions that determine whether a question should or should not be displayed
The Survey Name is fairly self-explanatory. This is the name of the survey, and the place where various options are set that relate to the survey as a whole. Options such as the “welcome” message, the “description” of the survey, contact information for the survey administrator, what “format” the survey will appear in, and so forth.
Each survey divides the questions into groups. This allows for logical organisation of the survey into groupings of similar questions. A group has a title and an optional description. You must have at least one group in each survey, even if you don’t wish to divide the survey into multiple groups.
Questions are the core of your survey and fit into a group, as explained above. There are no technical limits to the number of questions you can have in your survey, or the number of questions per group. Questions include the actual question itself, as well as settings that determine what type of answer you expect. You can also include a short “help” explanation for each question and determine whether the question is mandatory (ie: must be answered before continuing).
Question
Types
The different types of question available in PHPSurveyor
are as follows:
5
Point Choice:
Allow a single rating of
between 1 and 5 for the question at
hand.
Eg: How much do you like fried eggs (1 for
none, 5 for lots)
Date:
Enter a date
Eg: What is your birthdate
Gender:
Offers participants a
pre-defined gender option:
Eg: Are you male or female?
List
Allows you to add a series
of possible answers / options from
which the survey participant may choose only 1
Eg: Where do you sleep?
Bed
Couch
Floor
List
with Comment
Allows you to add a series
of possible answers / options from
which the survey participant may choose only one. The question includes
an area to explain the choice.
Eg: Where do you sleep? Please explain why
you sleep there.
Bed
Couch
Floor
Comment:
Multiple
Options
Allows you to add a series
of possible answers/options from
which the survey participant may choose any that apply (ie: none, one
or more).
Eg: Where do you like to sleep (choose any
that apply)
Bed
Couch
Floor
Multiple
Options with Comment
Allows you to add a series
of possible answers/options from
which the survey participant may choose any that apply, as well as add
a comment explaining each choice!
Eg: Where do you like to sleep (choose any
that apply). Please explain each one you choose.
Bed
Couch
Floor
Multiple Short Text
Allows you to ask for multiple short
text answers to match a series of pre-defined titles.
Eg: What are your three favourite books?
Book 1
Book 2
Book 3
Numerical
Input
Requires an answer that
contains only numbers. These questions
will only accept the following characters: 1 2 3 4 5 6 7 8 9 0 , .
Eg: What is your age in years?
Ranking
Allows you to present your
participants with a list of possible
answers/options, which they may then rank in order of preference
Eg: Please rank the following movies in
order of your preference:
Short
Free Text
Allows a short answer (100
Characters Maximum)
Long
Free Text
Allows a long text answer
Yes/No
Presents the participant
with a simple Yes / No option
Array
(5 Point Choice)
Allows you to present your
participant with a list of possible
answers/options which they may then rank between 1 and 5
Eg: To what extent do you agree with the
following comments (1=Strongly Agree, 5=Strongly Disagree)
- Elephants look better with large
ears
1 2 3 4 5
- The Southern Hemisphere is
groovy
1 2 3 4 5
- My ears hurt when it is
cold
1 2 3 4 5
Array
(10 Point Choice)
The same as above, only with
10 instead of 5
Array
(Yes/No/Uncertain)
Allows you to present your
participant with a list of possible
answers/options against which they may respond
“Yes”,
“Uncertain” or “No”
Eg: Do you agree with the following
proposals:
- All staff should wear a pink
uniform Yes
Uncertain No
- Coffee Breaks should be only 5
minutes Yes
Uncertain No
- My boss should be
sacked
Yes Uncertain No
Array
(Increase/Same/Decrease)
As above, only presenting
the options Increase/Same/Decrease.
Array
(Flexible Labels)
An array of flexible labels
allows you to select from a
pre-defined label (see section 5) as your headings, and let your
participants respond to a series of possible answers/options using
those headings.
Eg: Please rate the following proposals:
- My left arm is longer than my
right Preposterous
Unlikely Possibly Definitely
- The magnetism of the earth is
changing
Preposterous
Unlikely Possibly Definitely
- My socks stay up all
day Preposterous
Unlikely Possibly Definitely
Array
(Flexible Lables by Column)
Basically the same as the
Array (Flexible Labels) question,
except the answers and labelset are displayed in columns instead of
rows. So, for the same example as previously it would be laid out like:
Eg: Please rate the following proposals:
Preposterous
My left
arm is longer than my right The magnetism
of the
earth is changing My socks stay up all day
Unlikely
My left arm is longer than my right The
magnetism of
the earth is changing My socks stay up all day
Possible
My left arm is longer than my right The
magnetism of
the earth is changing My socks stay up all day
Definitely
My left arm is longer than my right The
magnetism of
the earth is changing My socks stay up all day
Boilerplate
This is not really a
question at all, but more of a place
holder that has the qualities of a question. No "answer" can be
collected to a boilerplate question, however the question text will
display as in other questions. You can use this in conjunction with the
conditions tool to make comments or statements that display based on
answers to previous questions.
To create a new survey click
on the button at the
right hand side
of the administration button bar.
The "Create New Survey" screen will appear below. Following is a description of each field:
Title: This is the brief descriptive name of the survey (ie: "Enterprise Bargaining Survey 2003", or "Views on Ice Cream"). This title will be displayed on every page of the public survey script.
Description: This allows you to enter a description of the survey. (ie: "A survey to collect your ideas on the next round of enterprise bargaining" or "A survey to find out the popularity of chocolate ice cream"). You can use html markup in this section.
Welcome: This allows you to enter a message that will display when a participant first logs into your public survey screen. (ie: "Thank you for taking the time to participate in this survey..") You can use html markup in this section.
Administrator: This is the name of the contact person who administrates the survey. It will be included in any emails sent out inviting participants to respond.
Admin Email: This is the email address of the administrator (as above) and is used as the 'reply to:' address on any emails sent out.
Fax To: This field is used to give a fax number on the "printable survey" - ie: when you want to send someone a hardcopy because they cannot use the online survey.
Format: Choose from "One at a time", "Group at a time" or "All in one".
One at a time Public survey will display one question per page.
Group
at a time Public survey will
display all
questions in a group per page.
Group at a time surveys still have a separate "welcome" page and
"submit" page, like "One at a time" surveys.
All
in one Public survey will
display all questions in
one single page
All in one surveys do not have a "welcome" page or "submit" page - the
welcome message and submit button all appear on the same page.
Template: Choose from the installed templates in your system. The default template is rather dull, but functional. More information on creating your own templates is available in the PHPSurveyor Templates Guide
Use Cookies?: If you choose "Use Cookies" and your survey does not use a tokens table to control participant access, then a cookie will be saved to the client computer of each survey participant once they have submitted a survey. This cookie will stop the same computer from accessing the survey more than once. There are inherent limitations in the 'security' strenght of such a system, but on a general basis it allows public surveys to retain some control over multiple entries.
Allow Saves?: If you set this option to "Yes" then users can save unsubmitted surveys and return to them later.
Show [<< Prev] button: This option defaults to yes, however if you set it to "No" then users will not have the option of moving to a previous page while completing the survey.
Notification: Options to allow the administrator to be emailed when each individual survey response is saved. You can choose from:
No email notification - self explanatory
Basic email notification - an email is sent informing the administrator that a survey response has been saved
Send email notification with response codes - sends the full answers to the survey after saving
Anonymous: This allows you to determine whether responses to your survey are matched up with information from your surveys tokens table, or kept 'anonymous'. The default is yes. If you choose "No" for anonymous, you must also have a tokens table for your survey when you activate it.
Invitation Email Subject: The subject line for the invitation email that gets sent out when tokens are used with your survey.
Invitation
Email: This is the text for the
invitation
email that gets sent out when tokens are used with your survey. This is
initially filled by the default invitation message (from the language
files) but you can modify it to suit yourself. Of course if you don't
plan to use tokens on your survey, whatever is in this field is
irrelevent.
You can use the following "form" fields to insert individualised
information in each email:
{FIRSTNAME} - gets replaced with the token table's "firstname" value
{LASTNAME} - gets replaced with the token table's "lastname" value
{SURVEYNAME} - gets replaced with your surveys name
{SURVEYDESCRIPTION} - gets replaced with your surveys description
{ATTRIBUTE_1} - gets replaced with the token table's "attribute_1" value
{ATTRIBUTE_2} - gets replaced with the token table's "attribute_2" value
{SURVEYURL} - gets replaced with the fully qualified URL to this particular survey
Note that these "form fields" apply to the following email fields.
Email Reminder Subject: The subject line for the reminder email that gets sent out from the tokens tool
Email Reminder: This is the text for the reminder email that gets sent out when tokens are used with your survey. See "invitation email" for specific details on how this field is used.
Confirmation Email Subject: When tokens are used, this is the subject line of the email that gets automatically sent to participants after completion of the survey
Confirmation Email: This is the text of the email that gets sent to users after completion of the survey.
Allow Public Registration: If you use tokens to control access to your survey, the only people who can use the survey are those who have an entry and a unique token from the token table. If you would like to use the tokens but allow public registration, use this field. Setting "Yes" to this will allow a visitor to your Survey URL to register their name and email address. The script will create a new entry in your tokens table for this person, then send them an invitation email. The script will ensure that only one person per email address can complete your survey.
Public Registration Email Subject: This is the subject line for the invitation email sent to members of the public who register for a survey.
Public Registration Email: This is the text for the invitation email sent to members of the public who register for a survey. The same "form fields" apply in this email as in the earlier ones.
Token attribute names: The tokens table has two "spare" fields for storing additional information about users. When using the public registration system, you can use these two fields to give your attribute fields a nice name for the public. So, if you are using "attribute_1" to store the participants department name, you can label it appropriately.
Datestamp?: This field allows you to determine whether the survey will datestamp all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response indicating the time and date that the response was made. (See configuration settings for $timeadjust setting.)
Language: A list of the possible language files will be shown next to this option. Changing the language setting here will change the default language used when participants use the public survey scripts (but will not change the administration language).
Expires: This is the last date on which the public survey script will let people participate. (Read this twice... if you set it for the 31 of December, then people will no longer be able to use the survey script on the 1st of January).
End URL: This URL will be presented as a link at the end of the survey, and allows you to direct your participants back to your home page (or, in fact, anywhere).
URL Descrip: The description for the link using the End URL.
Automatically Load URL when survey complete: If you choose "Yes" for this option, the script will automatically load the URL as set in "End URL" after completion of the survey, instead of displaying the usual "Completed" page. Do not use this if you are using assessments.
Importing
a Survey
If you have previously
exported a survey, you can import it
from the "New Survey" screen. Click on the browse button to choose the
sql file, and then click on the button.
The import process reads a 'sql' file created by PHPSurveyor and
'intelligently' (I use the term advisedly) renumbers the survey, group,
question, answer and condition id's so that they all match each other.
See section on Exporting a
Survey for more information.
Before
you can add any questions to your survey you must create a group.
If you will only have one group in your survey, then how you name this
group is irrelevant (except of course for show). If, however, you are
going to have multiple groups, you should note that the survey
questions will be displayed by group, and the groups
will be
displayed in alphabetical order.
So, if you really need the
groups to be displayed in a particular order, consider naming them with
an alphabetic start such as "A)
Questions about you" and "B)
Questions about health". Doing
it this way will ensure that your
groups are displayed in order. If, for example, you entered the group
names as "Questions about you"
and "Questions about health",
the "Questions about health"
group will display first, because
alphabetically it comes first. PHPSurveyor
is designed to do this deliberately, because it allows you to add extra
groups in later, and arrange their positioning by adjusting the title.
For example, you could squeeze an extra group between the two by naming
it "A1) Questions about your
history".
You can create as many groups as you like.
Groups can also include a "description". This field allows you to publish an explanatory note for any set of questions. If you add a description, then when the public are using the public survey system, they will be presented with that explanation before commencing any of the questions in that group. If you do not include any text here, then public participants will simply move on to the first question in the group with no stop.
Create a new group by
clicking on the icon in the Survey
Button Bar.
Once
you
have created your groups, you can start adding questions
within
each group. Create a new
question by clicking on the add icon () on
the right hand side of the "Group" menu
bar.
When adding a question, you will be asked for a "Question Code", the
"Question", "Help" and a "Question Type". All new questions are
assigned to the Group you were viewing when you clicked "Add Question",
however you can change the group the question belongs too at a later
point.
Question
Code:
Your ID, or number or code for
the question. This field is important, because the entry in this will
determine the positioning of the question in your survey. Again,
numbering this "Q1", and following questions "Q2" and "Q3" will ensure
that they appear in the correct order. Using this system allows you to
add in extra questions as an afterthought by giving them a code such as
"Q1a". Try to be consistent with your coding in this field. Planning
makes this process a lot easier.
Question: This is the actual question being asked. There is no real limit to the length of the question here, however if you want to explain the question, leave that for the next field.
Fields Within Questions
TOKEN INFORMATION
From PHPSurveyor release 0.98finalRC1 you can insert information/text
from the tokens table into your question so that it can show context
related information. For PHPSurveyor to do this, the survey needs to be
set as NOT Anonymous (ie: tracked), and it needs to have a tokens table.
The fields available for this are:
{TOKENS:FIRSTNAME} - inserts the value from the "firstname" field in the tokens table
{TOKENS:LASTNAME} - inserts the value from the "lastname" field in the tokens table
{TOKENS:EMAIL} - inserts the value from the "email" field in the tokens table
{TOKENS:ATTRIBUTE_1} - inserts the value from the "attribute_1" field in the tokens table
{TOKENS:ATTRIBUTE_2} - inserts the value from the "attribute_2" field in the tokens table
To use this functionality you must type the
field text into
your question exactly as listed above. For example:
Hello
{TOKENS:FIRSTNAME}. We sent an email to you using this
address {TOKENS:EMAIL}. Is this correct?
If there are spaces or typing mistakes, the script will not replace
your field with the appropriate information.
PREVIOUS ANSWERS
There is currently also
the capacity to insert the answer
of previous questions into the text of an answer with the following
provisos:
The question must have been answered in a previously displayed PAGE in the survey - answers to questions on the current page are not available
You
refer to the exact Survey ID, Group ID and Question ID for the question
to which the answer was made - in the form: {INSERTANS:SIDXGIDXQID} -
ie {INSERTANS:1X2X3}. How to find out the according ID? It's easy. Just
navigate to the questions whose answer you would like to use and look
at the adress-bar of your browser. If the URL is e.g. http://foobar.com/phpsurveyor/admin/admin.php?sid=1&gid=12&qid=8
then you have to
insert
{INSERTANS:1X12X8}
in the later question
text.
IMPORTANT:
The capacity to use
perviously provided answers in questions is currently only considered
"proof of concept" and so should be used with caution as future
releases of PHPSurveyor may involve significant changes in the way that
it is used and/or works.
Help:
This is an optional field. It is useful
if a question needs some explanation, or you want to explain how it
should be answered. When you put text in this field, a "Question Mark"
icon appears on the survey entry screens, and clicking on this allows
the survey participant (or data entry person) to read the help.
Question
Type:
This
determines the type of response the survey allows. View
the "Question
Types" section for a description
of the various options available.
Validation:
This
feature is available on all free text type questions ("Short Free
Text", "Long Free Text", "Date" or "Numerical"). You can use standard
Perl Regex expressions in this field to validate the responses to the
question, and if the responses don't validate against this expression,
the user will be prompted to try again before they can progress.
Perl Regex expressions must start and finish with a forward slash
("/"). You can find a good library of regex expressions at http://www.regxlib.net/.
These
patterns will almost all work if surrounded with the forward slash.
Examples (note that
these are all one line):
/(\w[-._\w]*\w@\w[-._\w]*\w\.\w{2,3})/
/^[0-9]{4}/
/^(?:\([2-9]\d{2}\)\
?|[2-9]\d{2}(?:\-?|\
?))[2-9]\d{2}[- ]?\d{4}$/
/^(?:\([0]\d{1}\)\
?|[0]\d{1}(?:\-?|\ ?))[8-9]\d{3}[- ]?\d{4}$/
/^[0-9]{5}([- /]?[0-9]{4})?$/
Other?
Depending upon your
chosen 'question
type' this option may appear. It allows you to specify that an "other"
option be presented in some of the list question types.
Mandatory? For all question types, except the text ones, this setting allows you to require users to answer the question, before they can move on to the next question.
Question
Attributes
This
is a new feature as of PHPSurveyor release
0.99dev01.
Question Attributes are an
extensible way of adding extra
controls to the presentation and/or workings of questions. Additional
question attributes can be developed relatively easily by PHP
programmers and added to the list of options for a question.
Different question types have different possible question attributes.
Each attribute can have a "value" attached to it. This value may
indicate whether the attribute is applied or not (usually a "1" to
apply), or it may indicate a value used by the attribute.
display_columns:
This attribute is
available for radio button list and
multiple choice type questions. It allows you to display the answers
for the question in more than 1 column. Add this attribute, and a value
indicating the number of columns you wish the question to use.
hide_tip
This attribute allows
you to turn off the "tip" for certain
question types. For example, List type questions will usually include a
tip that says "Please choose one of the following". Adding the
"hide_tip" attribute with any value will turn this tip off so that it
will not display.
random_order
This attribute applies
to any question type that has a list
of possible answers. It causes PHPSurveyor to ignore the existing order
of those answers, and instead it orders the answers randomly. It is
important to note that this random order will be reordered each time
the question is displayed, so if someone returns to a question, the
order will probably be different from the first time they saw it.
Having the answers display randomly is useful to remove the possibility
of bias from answers to questions.
code_filter
Can be used to filter
the answers displaying based on the
answer to a previous question. The attribute was added for the purpose
of being able to narrow down possible options.
permission
Currently unused
attribute that will eventually be
integrated with the public display of results, so you can indicate
whether a questions results are public or not
maximum_chars
Available for text based
questions. Allows you to set the
maximum number of characters that can be entered for a text based
question. Entering a value of, say, 20 will mean that the participant
cannot enter any more than 20 characters as their answer.
text_input_width
Available for short text
and numerical text type questions.
Sets the width of the html text box, but does not limit the number of
characters that can be entered.
You can create as
many questions as you like.
When you have created a question that uses pre-determined answers (ie:
dropdown list) you can then add answers
to that question.
(D) Setting Conditions (Branching)
A
question can be set to display ONLY IF certain conditions are met. You
can set these conditions by clicking on the
icon in the question
button bar,
when viewing a question.
When you choose "Set Conditions" a new window will appear allowing you to delete or create conditions for the current question. An example is show below.
PHP Surveyor |
Condition Designer |
Only
show question 02-07b![]() |
||||
02-07: Have workers or former workers.. (qid510) | Equals |
|
||
Copy Conditions | ||||
Condition | Question | |||
---|---|---|---|---|
copy to | ||||
Add Condition | ||||
Question | Answer | |||
Equals | ||||
Existing
Conditions
The top part of the window shows any conditions
already set for this question, and the bottom part allows you to
create new conditions.
In the
example above, Q04b ("Do you like being female?") is set to
only display if the answer to the previous question Q04("What is
your gender") is "F" (Female). You can delete this
condition by clicking on the "Del" button.
New
Conditions
To create a new condition,
click on the question
(left hand column) that you wish to use for your condition. When you
have chosen a question the Answer section on the right hand side will
display the possible answers for that question. Choose the answer
that you want to use, then click on the "Add Condition"
button. You can choose multiple answers in one go by using the CTRL
button and clicking on more than one answer in the right hand select
list.
Multiple
Conditions
You can set more than one
condition to apply for a
question. Conditions can be based on more than one previous question.
So, for example, you can set a question to display only if the answer
to Question 1 is "Y" and question 2 is "N". Or
only if the answer to Question 1 is "Y" or "No answer"
and the answer to question 2 is "N".
Copying Conditions to Later Questions
It is not uncommon for a group of questions to have the same condition. From release 0.98rc9 if you set a condition for one question, you can copy this condition to any subsequent question from the conditions designer. Once a condition has been set, the following screen will be displayed:
The select box on the left displays the conditions already set on this question, and the select box on the right shows all subsequent questions in the survey. Highlight all the conditions on the left side that you wish to copy (using the CTRL key to select multiples) and then highlight all the questions you wish to copy these conditions to on the right hand side (using the CTRL key to select multiples). The click on the "Copy Conditions" button to copy them across. It is usually best to leave this until you have finished entering all your survey questions, and are satiisfied with the question order.
Things
to watch out for
If you set conditions on a
question that,
itself, has conditions, then there may arise occasions where the
survey behaves in ways you might not have predicted. So if you are
designing a complicated survey with large numbers of conditions, make
sure you test the survey for as many different combinations of
results as you can think of. In the above example, a question is
displayed 'Do you like being male?' which has conditions set, and
which will only display if the answer to "what is your gender?"
is "M". If you were to add a condition to this question
requiring a specific answer from the "Do you like being male?"
question, then this question will never display, because the question
"Do you like being male" will not be presented. If this
seems confusing, don't worry too much, because when you are designing
your survey the logics of these conditions will make themselves far
more clear.
There are
a few basic rules you should keep in mind before setting conditions
on a question.
-
Once a single condition has been set
for a question, that question WILL NOT DISPLAY unless that condition is
met.
-
Conditions can only be set based
on questions
that appear BEFORE the question on
which
the condition is set.
-
Multiple conditions based on a single
earlier question are evaluated using boolean "OR" principles. Multiple
conditions based on multiple earlier questions are based on boolean
"AND" principles. This is important because it means you cannot (for
example) set a condition that a question will only display if either
previous question a is "Y" OR previous question b is "N".
-
You
can modify conditions even after a survey has been activated. This
should be done with caution, as there is no "consistency checking"
applied here.
(E)
Adding ANSWERS
Various question types require you to add a list of 'answers' from which the survey participant chooses, or which are used as headings for responses. To add answers to one of these question types click on theicon in question button bar.
When
adding an answer you will be asked for an "Answer Code", an
"Answer" and whether that answer is the "Default".
Answer Code: This is the data that will usually be exported to your spreadsheet when compiling results. You may choose whatever code you want (5 character maximum). The code can only contain standard alpha-numeric characters.
Answer:
The answer that
will be displayed.
Sortorder: This is a hidden field in versions 0.98rc2 and better. You can use the "Up" and "Dn" buttons next to each answer to change the position of that answer in the list.
Default:
One answer from all can be chosen as the default answer (ie: this one
will be chosen and entered into your survey results unless it is
changed). Change the Default field to "Y" if you want this answer to be
the default answer. If you don't choose any default answer the survey
result will record nothing if one of the answers is not specifically
chosen.
(F)
Exporting a survey
Naturally once you've finished a small masterpiece of a survey, with branching, hundreds of questions that has taken you 5 days to create you'll want to make a backup. Thebutton in the survey button bar will dump all the groups, questions, answers and conditions for your survey into a standard sql dump file. This dump file can be used with the 'Import Survey' feature.
Note:
While
the dump file creates a standard sql file, it is not
recommended that you run this file on an existing PHPSurvey database
directly (ie through phpMyAdmin) because various internal pointers in
the survey need to be reset.
You can test a survey at any point while you are creating it, by choosing the "Test Dataentry" or "Test Survey" buttons in the 'Survey' section of the web page. This allows you to check how the survey looks and feels, before you actually initialise it. When testing a survey your responses will not be saved.
A new feature in 0.99dev01 is the ability to create "assessments" on your survey. Assessments are rules which evaluate the responses to the survey immediately after it is submitted, and can then display text based on that.
As an example, consider the following. You have two questions in your survey, the first question asks if the user smokes: "Do you smoke?". The question has 3 possible answers, "Yes more than 10 per day" with an answer code of "10", "Yes, but less than 10 per day" with an answer code of "5" and "No, I don't smoke at all" with an answer code of "0".
The second question "Do you exercise?" has three possible answers; "Yes, I exercise for at least half an hour three times a week" with a value of "0", "Yes, I exercise every now and then" with a value of "5" and "No, I don't ever do any exercise" with a value of "10".
If we were to add the totals of the values for each possible answer at the end of the survey, we'd have a good indication of the general health of the respondent. Someone who smokes and doesn't ever do any exercise will have scored 10 in each of their answers, giving a sum of 20 when we add the values together. Someone who doesn't smoke and exercises regularly will have scored 0 in each of the answers with a total of 0 when we add the values together.
The assessments tool allows you to set some rules based on the summed values of the questions in the survey, either for the Total survey, or for each Group within the survey.
If we visit the
assessments tool from the survey administration toolbar, we can create
some assessments for this survey. From this screen you can view, edit
or delete existing assessments or create new assessments.
If you create any assessments in this page, for the currently selected survey, the assessment will be performed at the end of the survey after submission | ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
In the "Add/Edit" box you can choose the following:
Scope: The scope of the assessment. Choose either "Total" which will create an assessment based on the sum of all the answers in the entire survey, or "Group" which will create an assessment based on the sum of all the answers in a group (chosen in the next row)
Group: If the scope of this assessment is for the current "Group", this is where you choose which group to assess.
Minimum: The minimum "sum" of answers to which this assessment will apply
Maximum: The maximum "sum" of answers to which this assessment will apply
Heading: The heading of the assessment which will display if this assessment is shown
Message: The actual message for this assessment (it may include html code)
URL: A URL link which will display with this asssessment.
You can create as many assessments as you like, and you can create more than one assessment to display for a given score.
It is important to note that if you use assessments, you must ensure that you have not chosen to autoload the URL at the end of the survey in the general survey setup, because the assessments only show on the final "completed" page after submitting a survey.
A number of the 'public' elements of PHPSurveyor can be adjusted by a series of templates.
This section provides a very brief explanation of these templates, however more detailed information - especially regarding the editing/creation of new templates is available in the PHPSurveyor Templates Guide.
The
PHPSurveyor Template Editor
The
PHPSurveyor Template Editor allows you to edit the contents of your
templates online. Start the Template Editor by clicking on the
"Template Editor" icon in the PHPSurveyor Administration
toolbar ()
The main screen is similar to the PHPSurveyor Survey Administration screen. It allows you to select the template to edit/view. Once this has been selected you can then select from one of the different public survey pages. You are then presented with a list of the template files that make up that particular page.
The Template Menu
Template: default |
|
|
|
The "traffic" light
icon indicates whether or not the template is editable or not. A red
light indicates that the template is read only, green indicates you
may make modifications.
The "edit" icon allows you to
change the name of the template, and the "copy" icon allows
you to make a new template by copying the current one.
The
"Screen" dropdown list on the right allows you to choose
which particular survey page you are currently looking at.
The File Control Section
File Control: |
|||||||
Standard
Files: |
Now
editing: |
|
|||||
In the "file control" window on the left, you can click on one of the template files that is used to compile the page. The html code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.
The "Other Files" window shows a list of all other files in the template directory. You can use this side to upload image files or other files needed to create your template. Note that to refer to any of these files in your template, instead of using - say "<img src='/phpsurveyor/templates/yourtemplate/mypicture.jpg'>" you can use, "<img src='{TEMPLATEURL}mypicture.jpg'>".
A "sample" of the template page you are editing will be visible at the bottom of the screen.
There is no capacity to delete a template from the template editor. This must be done using ftp by deleting the directory.
The "default" template cannot be edited using the Template Editor, although you can edit it manually.
Replacements / Field Strings
The following strings will be replaced by PHPSurveyor when parsing the template file and presenting it to survey users. These field strings will almost every template except for the 'Completed Page'.
Field |
Replaced With |
{SURVEYNAME} |
The survey's name |
{SURVEYDESCRIPTION} |
The survey's description |
{WELCOME} |
The survey's welcome message |
{PERCENTCOMPLETE} |
A graph (table) charting the percent completed of the survey |
{GROUPNAME} |
The name of the current group |
{GROUPDESCRIPTION} |
The description of the current group |
{QUESTION} |
The question (text) |
{QUESTION_CODE} |
The question (code) |
{ANSWER} |
The answer(s) to the current question |
{THEREAREXQUESTIONS} |
Replaced with the statement "There are X questions in this survey" - where X is the total number of questions in the survey. |
{NUMBEROFQUESTIONS} |
The total number of questions in the survey |
{TOKEN} |
The current "token id" |
{SID} |
The current "survey id" |
{QUESTIONHELP} |
The help text for the current question, in a javascript pop-up box |
{QUESTIONHELPPLAINTEXT} |
The help text for the current question |
{NAVIGATOR} |
The "Next >>" and "<< Prev" buttons |
{SUBMITBUTTON} |
The "submit" button |
{COMPLETED} |
"Survey is completed and saved" - from language file |
{URL} |
The URL/URL Title for this survey |
{PRIVACY} |
Inserts the contents of the privacy.pstpl template |
{PRIVACYMESSAGE} |
The privacy message from the language file |
{CLEARALL} |
The URL to "Exit and clear responses" |
{TEMPLATEURL} |
The URL to the current template location (useful for referencing image files in your template) |
{SUBMITCOMPLETE} |
The statement (from the lang files) that tells the user they have completed the survey, and to press the "Submit" button |
{SUBMITREVIEW} |
The statement (from the lang files) that tells the user they can review/change the answers they have made by clicking "<< prev" |
{TOKEN:FIRSTNAME} |
If survey is NOT ANONYMOUS - gets replaced with the users first name from the tokens table |
{TOKEN:LASTNAME} |
If survey is NOT ANONYMOUS - gets replaced with the users last name from the tokens table |
{TOKEN:EMAIL} |
If survey is NOT ANONYMOUS - gets replaced with the users email from the tokens table |
{TOKEN:ATTRIBUTE_1} |
If survey is NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table |
{TOKEN:ATTRIBUTE_2} |
If survey is NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table |
{ANSWERSCLEARED} |
The "Answers Cleared" statement from the lang files |
{RESTART} |
URL to restart the survey |
{CLOSEWINDOW} |
URL to close current window |
{REGISTERERROR} |
Shows any error messages in the register page (ie: "You must include an email address") |
{REGISTERMESSAGE1} |
The statement "You must be registered to complete this survey" from the lang files |
{REGISTERMESSAGE2} |
Details about registering from the lang files |
{REGISTERFORM} |
The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set. |
The public survey screens can be localised so that built-in messages and text will appear in your preferred language. For example "yes" and "no" in the Deutsch/German version would appear as "ja" and "nein". A number of language files come with PHPSurveyor, however you can create your own by making a copy of an existing file in the /phpsurveyor/lang directory and modifying it with an UTF-8 capable editor to suit.
There is one trick about UTF-8 files: To maintain backward compatibilty your UTF-8 file may not contain a BOM (byte order mark). BOMs are two bytes at the beginning of an UTF-8 file to describe the correct encoding. We recommend two editors to edit and write files without BOMs: there is "UltraEdit" (Shareware, devactivate writing of BOM in the options) and "Notepad2 " (Freeware, choose Encoding UTF-8 without signature). Download Notepad2 here: http://www.flos-freeware.ch/notepad2.html.
Once you are happy with the structure of your survey you can activate it. Activating a survey does a number of things.
It creates a separate MySQL table to hold all survey responses, and gives each possible answer to the survey a field in that table.
It allows people to enter data into that table, and gives you access to other features for the survey, including browse and token facilities.
It gives you access to the "tokens" feature. Once a survey is activated, the "tokens" button will be available (see section on Tokens).
If your survey is set to "not anonymous", a tokens table will be created automatically.
Before you activate a survey you should note the following points:
When the survey is initialised you can change the text for questions, answers, the survey etc, but not the type of question or the type of answer.
You cannot add new questions or delete questions. Nor can you add answers to any of the array or multiple choice questions, however you can add answers to the basic list type questions.
Activate
a survey by clicking on the
button in the survey button bar. If this icon is not shown, then your
survey is not yet capable of being activated. Once clicking on this
icon, PHPSurveyor will run a quick consistency check to make sure
that your survey will work properly.
Once you have activated a survey and are receiving responses it is worthwhile considering the following:
Export the survey structure immediately and save the sql file somewhere.
Regularly visit the "browse" screen and use the "backup survey x results" to create a sql backup of the responses table.
Regularly export the responses and keep a copy of the file.
Try not to make changes to the survey. There are some parts of the survey that can still be changed after it has been activated, and while these shouldn't cause problems, its better safe than sorry. Fully test your survey before you activate it and then try to leave it exactly as it is.
From release 0.98finalRC1, you can backup your entire PHPSurveyor database (with all surveys, responses, tokens etc) by clicking on the backup icon in the administration button bar. This will export a sql file that can be imported into an empty MySQL database, creating all required tables, and data - effectively restoring your entire PHPSurveyor database.
If you have access to phpMyAdmin or a similar facility, try making regular backups of the entire PHPSurveyor database (structure and data). If the worst happens and the whole database disappears, you could re-create the database and import the backed-up tables, and PHPSurveyor will likely be able to pick up where it left off.
Once a survey has been activated, and survey responses have been submitted, you will want to be able to view those responses, maybe edit some of them (or possibly delete some), export them, get some information about the responses received so far, and so on. All of this is done through the "browse" function.
When
your survey is active, a 'Browse' button (
)will appear in
the Survey Information portion of the main admin screen. Clicking
this button will open the "Browse" screen. An example is
shown below.
Browse Responses: CPSU EB2003 Survey | |
![]() ![]() ![]() ![]() |
2319 responses in this database |
The main screen (Survey Summary) gives you just a quantity of responses to this survey so far. The other options are described below:
Admin: Return to the main admin screen for surveys
Survey Summary: Just show the total responses so far (initial screen)
Browse All: Display all the results to the survey (note: the browse shows full descriptive question names, but only abbreviated answers. See section below (editing and deleting responses).
Browse last 50: Display
the last 50 responses to the survey,
ordered from most recent to least recent.
When you are browsing responses, the first entry for each row (the "id"
number will be a hyperlinked number. Clicking on this hyperlink allows
you to veiw that specific response on an individual basis. From here
you can edit or delete a response. See section below (editing
and deleting
responses).
Data Entry: Go to the data entry screen to add a new survey (this option is also available from the admin screen)
Printable Version: A fairly basic, but hopefully useable version of the survey that can be printed off for people to fill in by hand.
Statistics: A simple method for filtering and getting summaries of responses. (See section on Statistics)
Export Data: Export all the responses to this survey to a Word, Excel or CSV file. (See section on Exporting Results)
Backup Survey X Results: Dump the table structure and contents to a standard MySQL *.sql file
Editing
and Deleting
Responses
When viewing your reponses, you
will be able to view
a specific response by clicking on the id number. An example of
'browse' responses is shown below.
id |
What is your Employment Type? |
What are your Hours of Work? |
What is your Spread of Hours? |
What is your Gender? |
What is your Classification? |
What
is your Top
Priority for outcomes of the
next Enterprise Agreement? |
What
is your Top
Priority for outcomes of the
next Enterprise Agreement? |
A |
A |
A |
F |
A |
I |
Please pay us more money. |
|
B |
A |
A |
F |
B |
J |
Possibility of further tertiary study and working that in with my current job. |
Clicking
on the hyperlinked id number will present the 'view record' screen:
Viewing Answer ID 1 |
|
id |
1 |
What is your Employment Type? |
Full Time [A] |
What are your Hours of Work? |
76 Hours Per Fortnight [A] |
What is your Spread of Hours? |
9 to 5 [A] |
What is your Gender? |
Female [F] |
What is your Classification? |
Administrative Officer [A] |
Do you manage staff in your current job? |
No [N] |
What is your Region/Division? |
Health Sector [H] |
What
is your Top Priority
for
outcomes of the next Enterprise Agreement? |
Increased Salaries [I] |
What
is your Top Priority
for
outcomes of the next Enterprise Agreement? |
Please pay us more money. |
From this point you can choose to "Edit" or "Delete" this response.
Deleting the responses is, of course, fairly self-explanatory - and as anyone who regularly runs surveys would know, is not recommended, unless you've got a pretty good reason (ie: a doubled up entry, or some sufficiently serious reason as to why it should be deleted). Don't click on this button thinking it will give you a second chance. If you click "Delete", the entry will be deleted with no second guessing or second checks.
Editing the response is also fairly self-explanatory. It will take you to a 'data-entry' screen with the responses provided, and allow you to make and save any modifications. Again, in a survey you generally don't want to make changes to the responses made by the participants - but hey - it's your survey. Do what you want!
On many occassions you will want to invite a group of people to participate in your survey, keep track of who has completed the survey, and ensure that each person can only participate once. Tokens can be setup once a survey has been activated. The tokens feature allows you to do the following:
Import a list of names and email addresses for participants (from a CSV file) or add/remove individuals
Generate a unique token number for each participant
Send an email invitation to each person in your list, either en-masse or individually
Send a reminder email to each person in your list who has not yet responded, either en-masse or individually
Track who from your list has responded
Restrict access against people who have not got a token, and those with a token who have already voted.
Edit/change any details in your list
Once you enable tokens for a survey, then the only people who can access the survey are those who have been issued a token number. Access to the public script will rely on the participant being able to provide their unique token id.
Tokens can be matched to surveys that have been set up as "not-anonymous". This is determined when creating a survey. If a survey is not anonymous (or 'tracked') then the token list can be used to find the particular response that an individual has made to the survey. If the survey is anonymous, then no link is available between the tokens table and the responses.
The following is a brief rundown of the menu options in the tokens screen:
admin: Returns to the main survey admin screen;
summary: Displays just the brief summary of tokens in the table (no. of tokens, how many have been sent an invite, how many have responded). Also provides access to the 'Database Admin functions' (see below). This is the default screen;
browse: Displays the complete list of participants in the tokens table. From the browse screen you can edit or delete individual entries in the token table as well as perform a number of other useful functions (see browse section below)
add: Allows you to add an entry to the tokens table;
import: Allows you to import information from a csv file
invite: Sends bulk email invitations to all participants in the tokens table who have not already been sent an invitation.
remind: Sends bulk email reminders to all participants in the tokens table who have not yet responded, but have been sent their first invitation.
tokenify: A new word for the english language, specifically invented for this script (come on OED, get to work). Creates unique tokens for all individual entries in the tokens table that do not yet have one.
Database
Admin
While the summary
screen shows a brief
summary of tokens in the table, it also provides access to the
"Database Admin" features which include:
clear invites: Sets all records that an invitation has been sent out to 'N'. Obviously shouldn't normally be used.
clear tokens: Clears all tokens. Similarly shouldn't normally be used.
drop tokens: Allows you to remove the tokens feature from your script. Deletes the entire table and all records, and allows the survey to be accessed by anybody who knows the URL.
Using
the browse screen
The browse screen will show
you a list of
all entries in the tokens table, as well as giving you some 'action'
buttons that can perform specific tasks for that individual entry.
The top
row of the table gives options for displaying a number of records,
and a starting point.
The second row of the table includes the
field name, and a green arrow that - if clicked - will refresh the
screen showing the tokens ordered by that field.
The last row of
the table lets you move backwards or forwards through your list
(based on the settings at the top).
Showing |
records starting at |
|
|
|
|
|
|
|
attribute_1 |
attribute_2 |
Action |
|
---|---|---|---|---|---|---|---|---|---|---|
1 |
Jason |
Cleeland |
jason@cleeland.org |
0829007266 |
Y |
Y |
Administrator |
Australia |
|
|
2 |
Bob |
Jones |
jason@cleeland.org |
1371896219 |
Y |
|
Interpreter |
Botswana |
||
3 |
Eric |
Estrada |
R193857398 |
Y |
Y |
Actor |
USA |
|
|
The
"Action" column gives a list of specific tasks that can be
performed on that individual entry.
E: Edit this entry
D: Delete this entry
S: Do the survey using this entries unique token
R: Send a reminder to this individual entry (only available if invite has already been sent)
I: Send an invitation to this individual entry (only available if invite has not already been sent)
V: If the survey is a 'tracked' (ie: not anonymous) survey, the "V" button will appear, allowing you to view the response from this individual entry.
Allowing
Public Registration
You may want to open your
survey to the
public, but utilise the sort of respondent control available when
using tokens. This is possible from version 0.98rc9 onwards. If you
initialise your tokens table, and have chosen to Allow Public
Registration in the main survey setup, people who visit your survey's
URL without a token, will be given the opportunity to register. If
they provide an email address that is not already in the current
survey's tokens table, an entry in the tokens table will be created,
and they will be emailed an invitation containing their unique Token.
All tokens provided to "registering" visitors will begin
with the letter "R".
This function is not intended to be available to participants in your surveys. When PHPSurveyor was first developed, it was intended as a dataentry system for paper based surveys. The dataentry screen is intended to be used when entering returned surveys on a mass basis, and subsequently is designed to allow for keyboard based entry (using tabs, and keystrokes).
You can export responses by selecting "Export Data" from the Browse screen.
When you choose this option, you will be presented with a new window, showing the various export options.
Abbreviated Headings: Just exports the question id, group id and survey id
Full
Question Headings: Exports the Question title itself as the heading
Brief Answers: Just exports the relevant codes for each answer
Extended
Answers: Exports the answer text matching codes
Microsoft Word Format: Exports the data as a 'document' (at this point, unformatted and with just tabs between data)
Microsoft Excel Format: Exports the data as a 'spreadsheet'
CSV Comma Delimited Format: Exports the data as a comma delimited file
The export screen also allows you to select which fields to export, and if the survey is not anonymous, allows you to merge the token information for each response with the export.
VVExport and VVImport
Once you've begun collecting responses, there may be occasions where you need to be able to directly edit and modify large quantities of data from your responses table, where a spreadsheet tool may be more useful.
VVExport and VVImport (the "VV" stands for vertical verification) allow you to export your responses table into a "tab separated values" (tsv) file. So long as the general structure of the file remains intact, you can then edit values within it, and the import the file again into your responses table using the "VVImport" feature.
Exporting a VV
survey file
When you choose to export
responses using VVExport you will be
given the option of either exporting the results and leaving the survey
active, or exporting the results and de-activating the survey.
If you choose to deactivate the survey, the responses table will be renamed and become unavailable without direct MySQL access (it will be renamed in the same way as de-activating a survey does).
If your survey uses tokens you should note that deactivating the survey also causes the tokens table to be renamed and made unavailable. It is probably best not to deactivate a survey that uses tokens unless you know how to rename tables in MySQL and can move the tokens table back manually.
The ability to deactivate the survey is important because a 'vv survey file' allows you to import the responses to a survey when the question/answer combinations have changed. Effectively this allows you to add or remove questions in an active survey.
Clicking on "Export Responses" will then produce a tab delimited file that can be opened by Excel or similar style spreadsheet program. The first two rows of the spreadsheet are the column labels. The first row is a "human readable" column heading that details the name of the question/answer field. The second row is the internal PHP column name for that response.
You should not modify the first two rows of this spreadsheet if you want to be able to "import" the data back into PHPSurveyor at a later point.
Importing a VV
survey file
As long as the first two lines
are intact, you can then import the
data in your vv survey file back into an active PHPSurveyor survey. If
you deactivated the survey when you exported the data you will need to
activate the survey in the normal way when doing this.
Then, from the browse screen, choose the "Import a VV Survey file" icon.
The "Import a VV Survey File" screen needs you to choose the "vvexport" you are importing. If you choose to "Exclude Record IDs" the records will be imported and brand new Record ID's will be generated for them. If you untick this box, then the original record id's will be imported.
There are
a range of options you can choose that tell PHPSurveyor how to deal
with double or multiple entries.
The statistics feature is available from the menu of the browse screen, which - of course - is only available once a survey has been activated.
What
is the statistics
feature?
Lets say you've got a survey
running, or it's
finished, and you want to start analysing the results. PHPSurveyor
can dump all the results into an Excel spreadsheet (or CSV file, or
Microsoft Word file) for you, and you can do whatever takes your
fancy with the data then. Alternatively you can use the statistics
feature to have a look at your data, and start getting some useful
information from it.
The statistics feature allows you to
'filter' your data and retrieve numbers, and summaries of different
fields from it. The statistics script doesn't attempt to do highly
complex filtering - but you'd be surprised at the sort of information
that can be easily obtained.
Filtering data
When you first start using the statistics feature, it will present you with a list of the questions that can be used to filter your data. An example is shown below. Each question box gives the question code, a 'radio' button that can be selected in order to show a summary of this table, and a loudspeaker icon that when clicked (or if the mouse hovers over it) will give you the full text of the question. Then it gives a list of the pre-defined answers for that question. The list allows multiple selections. So, for example in the case shown below, you could choose to filter all results where "ongoing" has been chosen, or by using the control button, you could add "Fixed Term" or "Casual". Go through all the boxes filtering in your preferred way.
Q01 |
Image 1: Question box |
Selecting "View Stats" will then present you with a results table showing you the total number of responses that match your criteria, and a percentage of the total responses for the survey. An example of 'Results' table is shown below.
Results |
|
Your
query returns 146 record(s)! |
|
Viewing
Field Summaries
While
this can be pretty useful
information on its own, often in a survey you will want to get a
summary of all results for a question, when particular criteria are
met. To do this, select the radio button at the top of the question
you want to see a summary for, set the criteria in the other boxes,
and select "View Stats". From
release
0.97 there is also the option of viewing a summary of all fields.
You will then be given both the 'Results' table, indicating the number of responses matching your criteria, and also a "Field Summary" table (as shown below) which will summarise all possible answers in the question you chose, their totals and their percentage. It is important to note that these results are a subset of your total responses. So, for example, if your criteria display 146 records out of a total 180, the summary will show the breakdown of just those 146 records for that table.
Field Summary for Q04: |
||
What is your Gender? |
||
Answer |
Count |
Percentage |
No Answer |
1 |
00% |
Female (F) |
49 |
33% |
Male (M) |
96 |
65% |
Things to be cautious of
If you set criteria on the same question that you ask for a summary, then that question will only present answers matching your criteria. So it is good practise not to set any criteria on the same question you are getting a summary of.
To select multiple entries for a question hold down the CTRL button when clicking. To 'unselect' the last criteria (if you want to clear all criteria from a question) click on the last highlighted answer with the CTRL button.
Browsing / Exporting filtered results
If you want to export the responses that match your criteria, click on the "export" button at the bottom of the 'Results' table. This will bring up the usual export screen, however when you export the results you will only receive the responses that match your criteria. Similarly, click on browse to view the matching responses in the browse screen.
This program is free software;
you can redistribute it and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will
be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
the GNU General Public License for more details.
http://www.gnu.org/licenses/gpl.html