====== Plugins ======

SoSci Survey supports several plugins for use in survey projects or for server management. This chapter describes how to install plugins onto a server.


===== EMFF for mp3 Audio Files =====

EMFF ([[http://emff.sourceforge.net|Easy Musicplayer For Flash]]) is one of the best solutions if you want to play audio files in mp3 format in the questionnaire. In order to avoid every project manager having to upload player files and juggling HTML code, SoSci Survey is able to respond directly to EMFF. The following steps are necessary to use EMFF.

**Note:** SoSci Survey's installation package already contains the EMFF player in the ''plugins/emff/'' directory .

  - Copy EMFF's SWF files (/skins in the directory in the package) into a SoSci Survey directory, preferably ''plugins/emff/''.
   - Enter the directory, e.g. "plugins/emff" and save this in **Server Management** under **Server Settings** in **Plugins**. If SoSci Survey cannot find the EMFF in the directory specified, an error message will appear.
  - If saving has worked properly, mp3 files can then be dragged into the questionnaire from the selection list in **Compose Questionnaire**.

===== reCaptcha =====

A captcha can be used in the questionnaire to check if the participant is a real person or just a computer. SoSci Survey is able to insert the [[http://www.google.com/recaptcha| reCaptcha]] module from Google in order to display captchas in the questionnaire. The following are necessary to do so...

  - A private and public key to access reCaptcha. This can be obtained from Google on the  [[http://www.google.com/recaptcha| reCaptcha Homepage]].
  - The [[https://code.google.com/p/recaptcha/|reCAPTCHA PHP library]], unzipped in plugins/reCaptcha. Only the ''recaptchalib.php'' file is necessary for this. 

**Note:** SoSci Survey's installation package already contains the ''recaptchalib.php'' file in the ''plugins/reCaptcha/'' directory -- as well as 4 image files that serve as image previews for the different display options.

Afterwards, the relative path for the reCaptcha plugin (e.g. plugins/reCaptcha) has to be entered in **Server Management** in **Plugins**, as well as both of the keys. The captcha question can then be used in the questionnaire just like every other question.


===== Google Translate =====

SoSci Survey actively supports questionnaires being translated in **Language Versions** -> **Translation Assistant**. The text elements are forwarded to Google Translate to be translated automatically. The project manager can then check, correct and use these translations.

An API key is required to use the Google fee-based translation service. A Google account is needed to generate the key, which is used to login to the [[https://code.google.com/apis/console/?api=translate|Google API Console]]. The "Translate API" function has to be enabled for the (new) API key. The API key is then entered in SoSci Survey's server settings.

**Note:** The API key entered is saved in SoSci Survey's configuration unencrypted. Only use this key for Google Translate, and a different key for other services.

**Note:** When texts are translated automatically, they are transmitted to Google's API (Application Programming Interface), processed and, if need be, saved and analyzed.

===== Banned Email Addresses =====

If certain email addresses or domains should be blocked upon registering, lists of these can be saved, e.g. in the ''plugins/trashmail/'' directory. The directory (not the list) has to be entered in **Server Settings** -> **Plugins**.

SoSci Survey loads all data into the directory during the registration process. The lines can either be...


  * an email address (e.g. john.doe@example.com),
  * a domain (z.B. exampledomain.com) or
  * contain a comment beginning with a sharp symbol (#)(e.g. # list from 24.12.2010)

If something follows the email address or domain (e.g. a tab, semi-colon, comment), this will be ignored.

[[http://www.mogelmail.de|mogelmail.de]] takes care of a list of trash email addresses. However, this list is no longer retrievable as a file. SoSci Survey's installation packet contains an outdated list of this provider.


===== Panel Module =====

SoSci Survey has a question type that collects participants' email addresses separately from other data. On request, this question type can also enter these email addresses into a participant pool. This feature is being developed for [[https://www.soscisurvey.de/panel|SoSci Panel]]: a sister project of SoSci Survey.

A panel plugin has to be installed to display this option. In principle, this module can also be used for other participant pools other than SoSci Panel (OpenPool software). The module is just a PHP script with the name ''interface.OpenPool.php''. This script has to be saved in the plugin directory (e.g. ''plugins/OpenPool/'') and an ''OpenPool::addParticipant($email, $ref)'' function has to be made available. This function is called up as soon as an email addresses is entered into the panel. The email address and a reference for the current survey project (its directory) is passed as the parameter. 




===== Question Module =====

SoSci Survey uses individual modules to display questions which can be found in the ''modules/'' directory. In principle, new question types can be integrated in this way -- however, the function of the module has not been documented thus far. 
