Surveyor

Summary

PHP Surveyor is a set of PHP scripts aimed at allowing people to develop online Surveys.

INDEX

Installation

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.

5. Configure PHPSurveyor
Edit the config.php file in the /phpsurveyor/admin directory using your preferred text editor. The following settings should be adjusted:

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.

 

INSTALLATION FAQ

What if my server has "safe_mode" turned on?
If your server has safe_mode turned on (a sensible security option, if somewhat annoying to those of us who want extra functionality) you will not be able to use some of the built-in functions of PHPSurveyor. These include the capacity to create and manage your Apache server's security settings, and the ability to do a straight dump of survey responses from MySQL. Neither of these functions could be considered a major element of PHPSurveyor - they're there to make life a bit simpler. You can setup Apache's security settings manually, and you could use a script like phpMyAdmin to dump survey responses from MySQL.

What if I can't create a database through a script?
Normally, the script creates a new database, and then the table structure, however if your server/ISP doesn't give you admin rights to create a new database in MySQL, you will need to contact your server admin people to create the necessary database. They should create a blank database for you that gives you the appropriate access rights (ie: read/write/create). Enter the name of this database, and your user name and password in the config.php script, and run the admin.php script. The script will then create each required table in the database one at a time.

What permissions should I set?
The /phpsurveyor/tmp directory needs to be given read/write/execute access (chmod 777) - this directory is where all uploaded files, and temporary files are created. All other directories and files can be set to read/execute only (chmod 755) exept if you want to use the built-in apache security tools (to create htpasswd and htaccess files) the admin directory still needs to be set to read/write/execute (777). The files within it, however, may be set to read/execute only (chmod 755).

Security Issues

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.

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 seperately 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.

Survey Design and Structure

A survey in PHPSurveyor has three integral elements. Every survey must have:

Optional elements to a survey include:

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:

Creating Surveys

  1. Creating a NEW SURVEY

    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:

    1. 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.

    2. 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.

    3. 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.

    4. 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.

    5. 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.

    6. 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.

    7. 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.

    8. 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

    9. 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.

    10. 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

    11. 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.

    12. 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.

    13. 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.

    14. 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.

    15. 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.

    16. 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.

    17. 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.)

    18. 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).

    19. 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).

    20. 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).

    21. URL Descrip: The description for the link using the End URL.

    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.

    (B) Creating a NEW GROUP

    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.

    (C) Adding a QUESTION

    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.

    1. 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.
       

    2. 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.

      (C)(i) 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}

      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.
       

    3. 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.
       

    4. Question Type: This determines the type of response the survey allows. View the "Question Types" section for a description of the various options available.
       

    5. 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.
       

    6. 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.

    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-07bPlease specify which disease(s) IF
    02-07: Have workers or former workers.. (qid510) Equals
    Yes (YES)
     
    Copy Conditions
    Condition   Question
    copy to
     
     
    Add Condition
    Question   Answer
    Equals
     
     
     
    Help - Using PHPSurveyor Help - Using PHPSurveyor PHPSurveyor Logo
    Ver 0.98final-rc1

     

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:

Copy Conditions

Condition

 

Question

copy to

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.
  1. Once a single condition has been set for a question, that question WILL NOT DISPLAY unless that condition is met.
  2. Conditions can only be set based on questions that appear BEFORE the question on which the condition is set.
  3. 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".
  4. 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 the icon 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".
(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. The button 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.

Testing a Survey

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.

Templates

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

This template can be modified- - - - - -

-|-Screen:  

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:

Other Files:

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:

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.

Localisation

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 to suit.

Activating a Survey

Once you are happy with the structure of your survey you can activate it. Activating a survey does a number of things.

  1. It creates a seperate MySQL table to hold all survey responses, and gives each possible answer to the survey a field in that table.

  2. It allows people to enter data into that table, and gives you access to other features for the survey, including browse and token facilities.

  3. It gives you access to the "tokens" feature. Once a survey is activated, the "tokens" button will be available (see section on Tokens).

  4. 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:

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.

Safely Running a Survey

Once you have activated a survey and are receiving responses it is worthwhile considering the following:

Browsing Survey Responses

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:

Data View Control:

  

Records Displayed: Starting From:

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?
This might be something new, an improvement to existing conditions, or ongoing inclusion of a condition you value.

What is your Top Priority for outcomes of the next Enterprise Agreement?
This might be something new, an improvement to existing conditions, or ongoing inclusion of a condition you value. (comment)

1

A

A

A

F

A

I

Please pay us more money.

2

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?
This might be something new, an improvement to existing conditions, or ongoing inclusion of a condition you value.

Increased Salaries [I]

What is your Top Priority for outcomes of the next Enterprise Agreement?
This might be something new, an improvement to existing conditions, or ongoing inclusion of a condition you value.
[Comment]

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!

Tokens

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:

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:

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:
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

Sort by IDID

Sort by IDFirst

Sort by IDLast

Sort by IDEmail

Sort by IDToken

Sort by IDInvite?

Sort by IDDone?

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

erice@cleeland.org

R193857398

Y

Y

Actor

USA

 

 
The "Action" column gives a list of specific tasks that can be performed on that 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".

DataEntry

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).

Exporting Results

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.

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.
 

Statistics

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  What is your Employment Type?
Agency / Temp Casual Fixed Term Ongoing

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)!
There are 187 records in your survey. This query represents 78% of your total results

SELECT count(*) FROM survey_4 WHERE 4X6X22 IN ('A') AND 4X6X23 IN ('A')

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

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.

License

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