.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ===================== 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: EXT: Advanced Surveys ===================== Extension Key: **ms\_survey** Copyright 2004, 2005, Michael Scharkow, 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: 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: Introduction ------------ .. _What-does-it-do: 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: 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: Screenshots ^^^^^^^^^^^ Creating a survey item |img-1| Inserting the content element with FlexForm configuration |img-2| Some sample output |img-3| .. _Users-manual: Users manual ------------ .. _Basic-setup: 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: 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. :code:`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: 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: :title:`How do yo rate the following aspects of our website (from very good to very bad):` .. ### BEGIN~OF~TABLE ### .. _Design: Design: """"""" .. container:: table-row a Design: b ○ very good c ○ good d ○ bad e ○ very bad .. _Usability: Usability: """""""""" .. container:: table-row a Usability: b ○ very good c ○ good d ○ bad e ○ very bad .. _Speed: Speed: """""" .. container:: table-row a Speed: b ○ very good c ○ good d ○ bad e ○ very bad .. ###### END~OF~TABLE ###### 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: 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 :code:`“` 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: 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: Reference ^^^^^^^^^ .. ### BEGIN~OF~TABLE ### .. _allow-anonymous: allow\_anonymous """""""""""""""" .. container:: table-row 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: progressBar """"""""""" .. container:: table-row 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: templateFile """""""""""" .. container:: table-row 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: successRedirectPID """""""""""""""""" .. container:: table-row Property successRedirectPID Data type integer Description After successfully filling out the survey, the user is redirected to this page. Default .. _emailNotification: emailNotification """"""""""""""""" .. container:: table-row 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: emailName """"""""" .. container:: table-row Property emailName Data type string Description The sender's name to be used in the email. Default .. _emailFrom: emailFrom """"""""" .. container:: table-row Property emailFrom Data type string Description The sender's email address to be used in the Fromfield. Default .. _emailAddHeader: emailAddHeader """""""""""""" .. container:: table-row 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: emailSubject """""""""""" .. container:: table-row Property emailSubject Data type string Description The subject text of the notification mail. Default .. _emailBody: emailBody """"""""" .. container:: table-row 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: emailTemplateFile """"""""""""""""" .. container:: table-row Property emailTemplateFile Data type string Description NOT AVAILABLE ANYMORE.This option is obsolete, please use emailSubject and emailBody instead. Default .. ###### END~OF~TABLE ###### .. _FAQ: 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: 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: 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: 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 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 512 .. :hspace: 19 .. :id: Graphic4 .. :name: Graphic4 .. :vspace: 19 .. :width: 436 .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :height: 275 .. :hspace: 19 .. :id: Graphic5 .. :name: Graphic5 .. :vspace: 19 .. :width: 636 .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 343 .. :hspace: 19 .. :id: Graphic1 .. :name: Graphic1 .. :vspace: 2053 .. :width: 412