SurveyManager

Summary and Download

SurveyManager is a flexible survey module for PostNuke. Administrators may construct multi-page surveys with many different types of questions. The module will collect responses from the general public, which are stored in a database and may be easily browsed or exported to CSV format.

SurveyManager can be used for traditional surveys, but it's also a great tool for simpler feedback/contact forms. No technical knowledge (beyond the ability to install a PostNuke module and do some basic file permissions) is required. Unlike the popular formicula module, there is no need to mess with Xanthia templates to get custom questions. The administrative interface takes care of everything for you.

Current SurveyManager version: 0.10.4.2 (changelog)
Project State: Beta. This software is being tested and developed. It may not work perfectly, but it probably works pretty well.
Requires: PostNuke .764 or PostNuke 0.8 (RC3), AJAX Support Package (for PostNuke 0.764 only), Zikula
Download: SurveyManager 0_10.4.2.zip
Documentation updated: November 6th, 2008
Mailing list: Subscribe
Author: Tilson Technology Management (Contact)

A Quick Overview

Surveys contains Pages. Pages are the children of Surveys.

Pages contain Questions. Questions are the children of Pages. Questions are where you collect survey data from users.

Responses are the data you get back from your survey.

Glossary

Administrator

A user that has access the the administrative sections of the website. Administrators may browse, manage and export survey responses, and may construct or edit surveys.

CAPTCHA

Completely Automated Public Turing test to tell Computers and Humans Apart. It's the little image verification that you sometimes fill out on web forms. SurveyManager supports CAPTCHA via ProtectWebForm.com. Read more about it here.

Dependency

Questions may only appear if certain other questions have been chosen by the user in a previous step. The criteria for a question to appear are called "Dependencies". If a question has several dependencies, they must all be satisfied before the question will appear on screen.

Email (From)

Many surveyors are interested in the email contact information of their respondants. A particular Question entry (see below) may be set as an Email (From) question in which case the values of responses to that question will be considered the official email address of the respondant. In administrative interfaces, the Email (From) will appear in the main response list, along with the Name ID field.

Name ID

Many surveyors are interested in the names of their respondants. A particular Question entry (see below) may be set as a Name ID, in which case the values of responses to that question will be considered the name identifier for the entire response. In administrative interfaces, the Name ID will appear in the main response list, along with the Email (From) field.

Page

An ordered collection of questions that appear together on a single page load.

Question

A single data collection unit. A question may have one of several different types - for instance, "Single Selection" or "Multiple Selection". For more information on questions and types, see the section of this documentation entitled "Create/Edit a Question".

Response

A collection of data points given by a visitor to your site in response to a particular survey.

Response, Featured

A response that you share with the general public.

Survey

An ordered collection of pages that collects and stores data.

User

For the purposes of this documentation, a "User" is someone who makes use of the front-end SurveyManager tools to respond to a survey.

Installation Guide

SurveyManager is in a beta state. That means there may be bugs, but it works well enough for me to give it to you. If you find a bug, please report it to me. Also, check back here from time to time for updates.

Get the files

Download SurveyManager from this site. Unzip it into your modules directory. If you're using PostNuke 0.764 or prior, also get the PostNuke AJAX Support Package.

Upload the files

Use an FTP client to upload the files. The SurveyManager module folder should go in modules/, and it should be renamed to "SurveyManager".

Don't forget AJAX Support Package!

SurveyManager's validation will not work without the AJAX Support Package installed. (Users of PostNuke 0.8 don't need to install the AJAX Support Package, as it is part of the 0.8 core release.)

Install and activate the modules

Log in to your PostNuke back end and go to the Modules administrative panel. (It's usually in the System tab, unless you moved it .) Go to the "S" section and click the "Regenerate" link. Find SurveyManager in the list and click "Initialize", then "Activate".

Set up some permissions

There are two group permissions you need to set before you start using SurveyManager. They do not necessarily need to go in the order listed here, nor do they need to be the 1st and second rules in your permissions list. #1 should be pretty high up there, though - I usually put it right under the Administrator group rules.

1. All Groups      SurveyManager::Admin              .*        None
(This bars all groups from seeing your administrative interfaces. This should go below the rule that gives members of your administrative group Admin rights on everything.

2. All Groups      SurveyManager::(Respond|Response|Datum)         .*        Add      
(This lets all users, including Unregistered, enter responses to the survey)

Rule #1 is especially important, since most PostNuke sites run with All Groups given Read access on .* (everything). If you mess up and forget this rule, unregistered users will be able to see the top-level administrative interfaces. (They won't be able to change anything, since they don't have Add, Edit or Delete access, but it's still a bit embarrassing if your administrative interfaces end up indexed on Google. Don't let this happen to you.)

Make one directory web-writeable

The following directory needs to be writeable by your web server in order to process response exports:

/[PostNuke root]/modules/SurveyManager/pntemp

Zikula users: also remove the .htaccess file in your modules/ directory if you intend to export survey responses to CSV format. See the section on bug-fixes. This is a temporary issue.

Short URLs

If you use Xanthia short URLs, add the following to your .htaccess file, nearish to the top of the module-related rewrite rules:

#SurveyManager
RewriteRule ^Survey-([0-9]+)-Page-([0-9]+)\.html$ /index.php?module=SurveyManager&func=display&sid=$1&pid=$2 [L,NC,NS]
RewriteRule ^Survey-([0-9]+)\.html$ /index.php?module=SurveyManager&func=display&sid=$1 [L,NC,NS]
RewriteRule ^ViewSurveys\.html$ /index.php?module=SurveyManager&func=view [L,NC,NS]
RewriteRule ^ClearResponses\.html$ /index.php?module=SurveyManager&func=clear_responses [L,NC,NS]
RewriteRule ^ThankYou-Survey-([0-9]+)\.html$ /index.php?module=SurveyManager&func=thankyou&sid=$1 [L,NC,NS]
RewriteRule ^FeaturedResponses-([0-9]+)-Detail-([0-9]+)\.html$ /index.php?module=SurveyManager&func=display_featured&sid=$1&detail=$2 [L,NC,NS]
RewriteRule ^FeaturedResponses-([0-9]+)\.html$ /index.php?module=SurveyManager&func=display_featured&sid=$1 [L,NC,NS]

Xanthia and pnRender Caching

SurveyManager is fully pnRender compatible, and makes use of pnRender caching where appropriate. If you use Xanthia and pnRender caching, I recommend you add SurveyManager to the list of modules which Xanthia caching ignores. You can do this in System -> Xanthia -> Configure Xanthia -> Modules to exclude from caching.

Installing without FCKeditor

FCKeditor is a great visual editor, but it's not right for everyone. You may wish to run SurveyManager without it. You can safely delete the "FCKeditor" directory from the SurveyManager module folder, and SurveyManager will replace the FCKeditor screens with normal textboxes. It will even translate linebreaks into regular HTML linebreak tags for you when displaying the content you put in.

User Interfaces

Survey List

How to get there: Select the SurveyManager administration module

The main administrative interface lists all the surveys currently active. You may use the up () and down () arrows to change the ordering of any elements on this screen. Use the expand/collapse arrows ( and ) to see 'children' of any element. (For instance, to see the pages in a survey, or the questions on a page.) If the expand/collapse arrows don't appear, then that element doesn't have any children yet. You can add a page to a survey or a question to a page using the icon to the right of its name. You can delete an element - and all of its children - using the icon.

To edit any element, click its title. To create a new survey, click the link that says "Add new Survey". Items for which you may use the Quick Survey Wizard will have a "Wizard" link as well, which you may also use to edit the survey.

To export all of the collected responses from a given survey into a CSV file, click the Export link to the right of the survey's name.

Create/Edit a Survey

How to get there:  Survey List -> Add new Survey

NAME: The name of the survey. This will only appear on the survey index screen (http://www.example.com/index.php?module=SurveyManager OR http://www.example.com/ViewSurveys.html)
DESCRIPTION: Text describing the survey. This will only appear on the survey index screen, above.
THANK-YOU CONTENT: This content will be displayed after a user is finished filling out the survey. It's nice to say thank you.
ALT. COMPLETION LINK: You can specify an alternate location to go to after the user is finished filling out the survey. If you put a URL here, Thank-You Content will never be displayed. You can use "__RESID__" in this URL to encode and send the ID of a newly created response someplace.

MAX. RESPONSES PER IP: If you want to limit how many times a user can fill out the survey, enter a maximum number here. He will only be a be allowed to fill out the survey that many times from a single IP address. It's not perfect, but it makes it quite inconvenient to fill out the form more times than is allowed.
EMAIL SUBMISSION TO: The email addresses listed in this box (one on each line) will receive email notifications of responses to the survey.

Create/Edit a Page

How to get there: Survey List -> '+' icon to the right of a survey.

NAME: The name of the page. This appears as a title.
DESCRIPTION: A description of the contents of the page. This appears until the page's title.

Create/Edit a Question

How to get there: Survey List -> '+' icon to the right of a page.

NAME: The name of the question. This usually ends with a '?' character.
DESCRIPTION: Optional descriptive text that will appear under the question's title but before the input field.
TYPE: Select a type from this list. The various options are:

• Heading: The question will not have a response field, but will appear as a section heading with a horizontal line under it. Use this to group items logically on the page.
• Short Text: The question will present a short, one-line text field
• Long Text: The question will present a multi-line text field
• Rich Text: The question will present a multi-line text field with style editing tools.
• Integer value: The question will present a short text field in which the user will only be allowed to enter integers.
• Decimal value: The question will present a short text field in which the usr will only be allowed to enter valid decimal values.
• File: The question will present a file upload field. The maximum file size and storage directory are controlled in the Modify Configuration screen.
• Single Selection: The question will present a drop-down menu from which the user may make a single selection. See the Values field, below.
• Multiple Selection: The question will present a series of check boxes from which the user may make multiple selections. See the Values field, below.

VALUES: If you chose Single Selection or Multiple Selection for the question's type, enter the values from which the user may select, each separated by a return.

ONLY AVAILABLE IF...: Here you may select the dependencies for this question. This section only appears if there are questions in a previous page of the survey. If you are adding/editing a question in the first page, you will not see this.

You may select a required response value from any and all previous questions that are of type Single Selection or Multiple Selection. The question you are adding/editing will not appear to users unless ALL of the dependencies have been met.

Types other than Single Selection or Multiple Selection may not be used as dependencies, because their values are too variable.

Quick Survey Wizard

The Quick Survey Wizard allows you to easily edit the most important details of a one-page survey from a single screen. (Details that you don't edit through the Wizard are still accessible through the other survey management interfaces, above.)

How to get there: Survey List -> Quick Survey Wizard OR Survey List [Wizard link to the right of any existing one-page survey]. Note: The Quick Survey Wizard will only work for single-page surveys. Multiple page surveys must be edited using the regular tool set.

Within the Wizard, you will see one red and several green blocks. The red block contains the details of the survey itself, including its Title, Thank-You Content, and the list of email recipients. Green blocks contain details of individual questions. (Note that these block colors correspond to the colors of items in the main survey list.) To see the details of any one block, click the right-facing arrow to the left of its name.

The lowest block contains only a link called "Add a question". Click this link to add a new question to the survey.

You may reorder questions by dragging anywhere in the green box that is not a control. You may delete question by clicking the "Delete" link to the right of the question. Note: No changes are saved until you click "Add Survey" or "Update Survey" at the bottom of the screen. To return to the survey index without saving your changes, simply click "Surveys" in the module's main menu bar.

Response List

How to get there: Survey List -> Response (in the links under the module title)

In this screen you can browse the responses you've collected.

To jump directly to a Response ID, enter it in the box labelled "Jump to a Response ID" and click "Go".
To filter the responses by status, select the status you want to see from the "Filter by status" list and click "Filter".
To filter the responses by the survey to which they are attached, select the name of the survey from the "Filter by survey" list and click "Filter".
To see the details of a response, click the "Edit" link on its row.

Featured Response List

How to get there: Survey List -> Featured Response (in the links under the module title). This will not appear unless you activate Featured Responses in Modify Configuration -> General.

In this screen you can browse the responses you've flagged as "Featured". You may also change the order in which they appear. Responses won't appear in this list until you have flagged them as "Featured" in the response editing screen.

Featured Responses will appear at the following URL:

http://www.example.com/FeaturedResponses-[Survey ID].html
or
http://www.example.com/index.php?module=SurveyManager&func=display_featured&sid=[Survey ID] (without short URLs)

Edit a Response

How to get there: Response List -> Edit

You may edit any fields of a response. You may not want to if you're interested in really accurate data, but the tool can also be used as a PR device; in that case, you may want to correct typos or apply judicious censoring to a response which will be come Featured.

You may also apply any status (defined in Modify Configuration) to a responses, and may flag it as Featured (if you have chosen to use Featured Responses, also in Modify Configuration).

For most printers, this screen is also a good one from which to print a hard copy of the response.

Modify Configuration

How to get there: Survey List -> Modify Configuration (in the links under the module title)

GENERAL: In this screen you can edit module-wide configuration settings.

GENERAL -> RESULTS PER PAGE: The results list will display this many results per page.
GENERAL -> FEATURED RESPONSES: Featured Response controls will not appear in the administrative interface unless this is checked. If you don't intend to use Featured Responses, leave it turned off.
GENERAL -> VISUAL EDITOR: In the future, SurveyManager may support more than one visual editor. For now, only FCKeditor is supported, but you can turn it off if you like. Select "None" instead of "FCKeditor".
GENERAL -> EMAIL SUBMISSIONS TO: Enter a list of emails to which new responses should be emailed, separated by returns. Distinct from the "Email Submissions To" field of an individual survey, the recipients in this box will receive email notifications of all surveys on the site.
GENERAL -> STATUS CODES: You may create as many custom status codes as you like. Enter them in this box, separated by returns. The values you enter here will be available to assign to responses. If you delete a status code to which responses are assigned, they will still have that status until you change them. It's better to work out which status codes you want to use before you start assigning them to responses.

MEDIA: In this screen you can edit module-wide media settings. This affects files that visitors upload in response to your surveys. If your surveys don't invite users to upload files, you don't need to mess with this screen.

MEDIA -> MAXIMUM UPLOAD FILE SIZE: "File" and "Photo" type questions will only allow files of this size or less to be uploaded.
MEDIA -> FILE UPLOAD DIRECTORY: This is the directory on your web server where uploaded files will be stored. It should be writeable by the web server; see the instructions in the Installation Guide under "Make one directory web-writeable".
MEDIA -> MAX PHOTO WIDTH/HEIGHT: Responses to "Photo" type questions which are valid photo files (JPEG, GIF or PNG) will have a "display version" generated that is this size. The original file will remain untouched. This is most useful for surveys that will have Featured Responses and which allow a photo upload.
MEDIA -> MAX THUMBNAIL WIDTH/HEIGHT: Same as above, but generates a thumbnail of this size. The thumbnail will be displayed on the Featured Responses listing page.

CAPTCHA:  SurveyManager can use CAPTCHA technology ("Completely Automated Public Turing Test to tell Computers and Humans Apart") to filter out robots and spammers from your survey. To use this feature, you must create a free account at www.protectwebform.com. Create a pair of verification URLs. Then paste the "Image URL" and "Verification URL" into the appropriate boxes in this configuration screen. Check the radio button to turn on CAPTCHA. Now you can activate CAPTCHA for individual Surveys, in the Survey editing screen.

Blocks

SurveyManager currently offers two content blocks.

Featured Response

You may create a SurveyManager/featured_response block to display the contents of a single featured response. After creating the block, you may select the specific response you want to feature. Each block may only display one featured response, but you may create multiple blocks. The default template usually works best in the center position, but you can use your Xanthia theme to override this template if you need the block to appear in some different way.

Display Survey

You may create a SurveyManager/display block to display the first page of a survey in a block. After creating the block, select the specific survey you would like to display in the block. You may have multiple Display Survey blocks.

Release 0.10.4.2 fixes several conflicts that might arrive if you have a SurveyManager/display block that appears when SurveyManager is the active module (for instance, when a visitor is filling out a survey using the standard SurveyManager_user_display() function). Webmasters running a Display block on releases prior to 0.10.4.2 should upgrade; see the download link at the top of this document.

Known Bugs

• Response exporting does not work well in Zikula. Because SurveyManager needs to access several files in its own directory, Zikula's .htaccess file in the modules/ directory interferes with this exporting process. We intend to rewrite the exporting process to be compatible with Zikula in an upcoming release. A temporary workaround is to remove the .htaccess file from modules/.
• Got a bug? Email us.