DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: Advanced Surveys

Author:Kasper Skårhøj
Created:2002-11-01T00:32:00
Changed:2005-01-10T08:56:42
Author:Michael Scharkow
Email:mscharkow@gmx.net
Info 3:
Info 4:

EXT: Advanced Surveys

Extension Key: ms_survey

Copyright 2004, 2005, Michael Scharkow, <mscharkow@gmx.net>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.com

Table of Contents

EXT: Advanced Surveys 1

Introduction 1

What does it do? 1

Features 1

Screenshots 2

Users manual 4

Basic setup 4

Creating survey items (or questions) 4

Two-dimensional items 4

Getting the data 4

Configuration 5

Reference 5

FAQ 5

Known problems 6

To-Do list 6

Changelog 6

Introduction

What does it do?

The extension provides a simple and powerful way to generate online surveys which are then displayed as a frontend plugin. It also contains a backend module to get the survey results as CSV files and display general statistics about a given survey, like the number of cases and variables used.

Features

  • different question types, default values for radio and checkbox items, flexible field dimensions
  • surveys can be split in parts, textual and graphical progress bar available
  • powerful two-dimensional items for common question types, special features for Social Network Analysis
  • anonymous surveys or based on given FE username/user input, notification emails are possible
  • output is completely customizable with a template file and CSS
  • BE module exports CSV files with cleanup functions

Screenshots

Creating a survey item

img-1 Inserting the content element with FlexForm configuration

img-2 Some sample output

img-3

Users manual

Basic setup

Setting up a survey is pretty straightforward:

Create a sysfolder in which the survey items will be stored. This is optional but I really recommend to do it.

Create survey items (questions) inside the sysfolder, like with any other content record. Cl

Create a page with the content element survey, set the starting point to the sysfolder with the items, maybe configure the plugin via the FlexForm (see Configuration section for details on the various fields) and you're done.

Creating survey items (or questions)

When creating a survey item, you will have a number of different fields, depending on the question type. String and text items are self-explanatory. The item nameis required and must be unique since variable names are derived from it. Question and description should be self-explanatory as well.

When your item requires the selection of options (checkbox, radiobuttons, selectbox), put the options each in a single line in the values field. Default values are marked with @ appended to the value. In the following example the option Green will be selected by default in the survey form.

RedGreen@Blue

If you would like to split up the survey into multiple parts (which is a very good idea), check the Break afterbox in the item you want to break after.

The item height and width are used in the output where appropriate, e.g. string items can have a width but no height, whereas selectboxes can have a height of 3 rows etc.

Two-dimensional items

The two-dimensional item is a very simple but powerful way of putting together items which need some repetition of questions. For example, you might want to ask the following question:

How do yo rate the following aspects of our website (from very good to very bad):

Design:

a

Design:

b

○ very good

c

○ good

d

○ bad

e

○ very bad

Usability:

a

Usability:

b

○ very good

c

○ good

d

○ bad

e

○ very bad

Speed:

a

Speed:

b

○ very good

c

○ good

d

○ bad

e

○ very bad

Instead of creating a question for each item, you can:

Create one question with the flag in two-dimensionalwhich is just a radio item with the values very good to very bad.

You can than create a two-dimensional item with the rows Design, Usability and Speed and select the radiobutton item from the selector.

Note: You can select as many questions in a two-dimensional item as you like but keep in mind that each item takes one table column, and your table might get very wide.

Getting the data

The extension provides a BE module called Survey Resultsin which you can retrieve the results as a comma-separated values (CSV) file which is a standard format which most spreadsheets and statistical tools can import.

Select Page>Survey Results and choose the page on which the survey is displayed (notthe Sysfolder!), you'll see some basic statistics, like number of variables and cases, and an export button which will give you a CSV file you can save or open in your spreadsheet. The filename consist of the page name and a timestamp, so you can save data in the same directory without trouble.

It seems impossible to directly open the file with MS Excel which screws up the columns. Instead, you have to save the file and then Import Data. Openoffice Calc does this much better. The file contains variable names in the first row, and then the values separated by commas, with “ as text delimiter.

If you select the checkbox Clean CSV for SPSSthe variable names will be stripped of all illegal non-alphanumeric chars because SPSS is picky about variable names. In the results, quotation marks will be replaced because the SPSS csv-parser is really bad and chokes on quotation marks withina table value. This cleanup may also be useful for other programs.

Configuration

There is not much configuration to do: The following configuration values can be changed either as TS constants or in the plugin's FlexForm configuration form which is displayed if you add the content element to the page. Look at the template file if you want to change the HTML output of the survey.

The plugin comes only with minimal default CSS-styles which are only used for the progress bar, clear or modify plugin.tx_mssurvey_pi1._CSS_DEFAULT_STYLE in your template setup if you want custom styles.

Reference

allow_anonymous

Property

allow_anonymous

Data type

boolean

Description

If set, surveys may be filled out anonymously. Otherwise, either the username of a logged in FE user is used or a username form is displayed before the survey is shown.

Default

true

progressBar

Property

progressBar

Data type

boolean

Description

Display a css-styled progress bar above the survey form. This works only for surveys with at least one page break.

Default

false

templateFile

Property

templateFile

Data type

string

Description

The template file to be used for displaying the survey form.

Default

EXT:ms_survey/pi1/template.tmpl
successRedirectPID

Property

successRedirectPID

Data type

integer

Description

After successfully filling out the survey, the user is redirected to this page.

Default

emailNotification

Property

emailNotification

Data type

boolean

Description

If set, notification emails are sent out when the survey data is saved.

A survey item namedemailis required for the mail to be sent.

Default

false

emailName

Property

emailName

Data type

string

Description

The sender's name to be used in the email.

Default

emailFrom

Property

emailFrom

Data type

string

Description

The sender's email address to be used in the Fromfield.

Default

emailAddHeader

Property

emailAddHeader

Data type

boolean

Description

Set 'Sender:' And 'Return path:' to sender's email address. This is a workaround to some problems with php mail(). Only set in TS!

Default

emailSubject

Property

emailSubject

Data type

string

Description

The subject text of the notification mail.

Default

emailBody

Property

emailBody

Data type

string

Description

The bodytext of the notification mail. Please remember to use the brackets for enclosing multi-line TypoScript values.

Example:

plugin.tx_mssurvey_pi1.emailBody = (
Your answers have successfully been saved. Thank you very much for participating in our survey.
)

Default

emailTemplateFile

Property

emailTemplateFile

Data type

string

Description

NOT AVAILABLE ANYMORE.This option is obsolete, please use emailSubject and emailBody instead.

Default

FAQ

Can I make certain items mandatory? -- Currently, there is no way to force users to fill out certain fields. This was offered to be implemented by a community member but nothing has happened yet. Since I don't have enough JavaScript knowledge to write such a script and I don't need this feature, this won't be implemented until someone sends a patch.

(Where) Can I display the results of the survey? -- You can't. This extension is meant for collecting data only, not for statistical analysis or fancy charts. If you need this feature, either use tt_poll or write a second FE plugin for result display. Although I am willing to integrate such a script, I will definitely not write this plugin myself, there are several reasons for this:

  • If you don't know the structure of the data (i.e. scales), useful automated analysis is nearly impossible. Do we output frequencies, means, correlations of the various items?
  • There's no need to re-implement statistical software in TYPO3 because this is done on the client side. If you need professional analysis you need professional tools, like GNU R, SPSS or some spreadsheet program.

When are variables stored? Can I save the data after each item break? -- All survey variables are onlystored when a survey is successfully filled out to the end. In between parts of the survey, variables are not stored in the database.

Can I use FE-Users for authentication? -- Yes. If allow_anonymous is disabled, the survey user is either the current FE-User or must fill a name before the survey starts.

What does the option exclude user from itemdo? -- The two-dimensional item was originally created for Social Network Analysis (SNA), in which a set of questions is often asked relating to the members of an ego-centered network (e.g. colleagues, friends) of the survey participant. As an example your questions might be: How often do you see person X. 2. Do you ask X for help, 3. How much time do you spend talking at work...These questions are asked for every member of the network, like Kasper, Robert and Ingmar.The creation of such a question is described above, and one special feature isexclude user from item. If the survey user is among the people to be asked about (e.g. Kasper fills out the survey), then he'll be excluded from the item (You would not answer questions about how often you ask yourself for help, would you?). This feature only makes sense in non-anonymous surveys, of course.

Known problems

The extension has been used for several projects but features are still added and some things may break. I try to provide backwards compatibility and stability but please read the release notes carefully if you update on a production system.

I'm reallyinterested in user reports. Please report bugs and feature requests to mscharkow@gmx.net .

To-Do list

  • Question filtering with a userfriendly interface
  • Add short names for item rows in checkboxes, multi-items and maybe multi-selectors
  • Add possibility to render items in multi-item context differently than stand-alone (trivial, but breaks existing template file)
  • Add possibility to make an item mandatory (need help with this)

Changelog

0.2.0 01/10/2005

added FlexForm configuration, progress bar with default CSS

  • fixed a bug that made the survey form break framesets
  • removed emailTemplateFile hack, instead have emailSubject and emailBody
  • fixed BE module to properly sort items, added cleaning function for SPSS
  • extended documentation a lot

- 6