LimeSurvey Manual - User contributions [en]

Translations:Survey participants/12/fr

2014-04-06T22:20:50Z

Courtm: Created page with "File:token-menu2.png"

[[File:token-menu2.png]]

Translations:Survey participants/3/fr

2014-04-06T22:19:29Z

Courtm: Created page with "=Introduction="

=Introduction=

Survey participants/fr

2014-04-06T21:44:01Z

Courtm:

<languages /> __TOC__

<div class="simplebox">'''Remarque''': Le système des invitations a beaucoup changé depuis la version 1.85 et versions ultérieures. Donc, si vous utilisez une version antérieure, il y aura des différences entre votre version et la documentation. Nous vous recommandons de mettre à niveau dès que possible.</div>

=Introduction=

En de nombreuses occasions, vous voulez inviter un groupe de personnes pour participer à votre sondage, garder la trace des répondants ayant terminé le sondage, et vous assurer que chaque personne ne peut participer qu'une seule fois. Le système des invitations vous permet d'effectuer les opérations suivantes:
*Créez manuellement des invitations (nom, adresse email, ...)
*Importer une liste de noms et d'adresses email pour les participants (à partir d'un fichier CSV ou une interrogations LDAP)
*Ajouter / Supprimer des invitations
*Générer un numéro unique pour le jeton de chaque participant (code d'invitation)
*Envoyez une invitation par courriel à chaque personne de votre liste, par groupe ou individuellement
*Envoyer un courriel de rappel à chaque personne de votre liste qui n'a pas encore répondu, par groupe ou individuellement
*Suivi les répondants de votre liste qui ont répondu
*Interdire l'accès aux personnes qui n'ont pas de ceode d'invitation, et ceux qui ont déjà répondu
*Modifier / changer tous les détails dans votre liste d'invitation

Une fois le questionnaire en accès restreint (vous avez activé les invitations pour ce questionnaire), alors '''seules les personnes avec une invitation valide (pas encore utilisée) peuvent accéder au questionnaire'''.

Si vous activez ''Permettre l'enregistrement public ?'' dans les propriétés du questionnaire, les participants pourront s'inscrire à votre sondage et avoir leur code d'invitation personnel généré automatiquement.

{{Hint|Text=Some token settings are set in survey settings, see [[Creating a new survey#Tokens]]}}

==Est-ce qu'une sondage utilisant les invitations peut assurer des réponses anonymes?==

La réponse à cette question est '''Oui'''. Les invitations peuvent être utilisées tant pour les sondages anonymes que non anonymes. Ceci est déterminé lors de la création du questionnaire. Si un questionnaire n'est pas anonyme (ou 'suivi') alors le code d'invitation peut être utilisé pour trouver les réponses que le répondant a faites au questionnaire. Si le sondage est anonyme, alors aucun lien n'est disponible entre la table des invitations et la table des réponses (techniquement: pas de relation de clé étrangère).

=Comment activer les invitations ?=

Il y a deux manières d'activer les invitations:
#Juste après l'activation du questionnaire, il vous sera demandé si vous souhaitez activer les invitations: {IMG(attId="84",imalign="center")}
# '''Ou''' vous pouvez cliquer sur le symbole de gestion des invitations [[File:tokens.png]] - avant même que le sondage soit activé.

=Les outils de contrôle des invitations=

[[File:token-menu2.png]]

Après la création de la table des invitations, vous pouvez cliquer sur l'icône pour administrer les codes d'invitation. Voici un bref aperçu des options de menu de l'écran de gestion des invitations:
*'''Administration''': Retourne à l'écran d'administration principal du questionnaire
*'''Résumé''': Affiche un résumé des invitations de la table nombre de codes d'invitation, nombre d'invitation envoyée, et nombre de réponse. Permet également d'accéder aux fonctions de d'administration de la base de données voir ci-dessous. C'est l'écran par défaut.
*'''Parcourir''': Affiche la liste complète des participants de la table des invitations. Depuis l'écran d'affichage, vous pouvez modifier ou supprimer des entrées individuelles dans la table ainsi qu'un certain nombre d'autres fonctions utiles voir la section Parcourir ci-dessous
*'''Ajouter une nouvelle invitation''': Permet d'ajouter une entrée à la table des invitations
*'''Ajouter des codes factices''': Permet d'ajouter une ou plusieurs codes d'invitations à la table des invitations trèsb rapidement.
*'''Gérer les champs des attributs supplémentaire:''': Permet d'ajouter des champs supplémentaires à la table des invitations pour stocker des données personnalisées liés aux participants
*'''Importer à partir d'un CSV''': Permet d'importer les informations des invitations depuis un fichier CSV
*'''Importer à partir de LDAP''': Permet d'importer les informations d'une requête LDAP testé sur openLDAP, mais devrait fonctionner dans tous annuaire compatible LDAP, dont ActiveDirectory.
*'''Export les invitations vers un fichier CSV''': Crée un fichier standard CSV (délimité par des virgules) avec la liste complète des participants de la table des invitations en cours.
*'''Éditer les modèles de courriel''': Pour personnaliser les textes et contenus utilisés pour les invitations, les rappels, confirmations, et les courriels d'inscription.
*'''Envoyer les courriels d'invitation''': Envoi global des invitations par courriel à tous les participants de la table des invitations qui n'ont pas déjà reçu une invitation.
*'''Envoyer les courriels de rappel''': Envoi global des courriels de rappel à tous les participants ayant reçu une invitation et n'ayant pas encore répondu.
*'''Générer les codes''': Crée les codes d'invitation uniques pour toutes les entrées individuelles de la table des invitations qui n'en disposent pas encore.
*'''Effacer la tabe des inviations''': Supprimer la table des invitations et passer le questionnaire en accès libre ou ouvert.
*'''Paramètres de rejet''': Paramètrage du courriel recevant les courriels de rejet. Ces paramètres peuvent être modifié à ce niveau ou au niveau général. Ce dispositif a été ajouté dans la version 1.91.

=Modification et ajout d'une invitation=

Une entrée typique d'invitation contient les champs suivants:

{IMG(attId="83",imalign="center")}
*'''Prénom et Nom''' : ... du participant (peut être utilisé dans les courriels et les questionnaires).
*'''Courriel''': l'adresse courriel du participant
*'''Statut du courriel''': un champ pour conserver une trace des mauvaises adresses de courriels. Par exemple, si l'administrateur du sondage ont reçu des notifications d'erreur par courriel à partir de ce courriel, ce qu'il peut définir ce champ à autre chose que 'OK' (par exemple 'utilisateur inconnu', ou 'quota dépassé'). Le marquage cette invitation avec un autre statut que 'OK', permettra d'ignorer cette entrée lors de l'envoi d'invitation ou de couriel de rappel. Notez que ceci est entièrement manuel à moins vous décidez de mettre en place un script qui met à jour ce champ automatiquement.
*'''Code''': c'est le code de l'invitation. Il est généralement généré automatiquement avec le bouton 'Générer les codes d'invitations'.
*'''Langue''': pour configurer la langue par défaut pour ce participant.
*'''Invitation envoyée?''': par défaut a 'N', sinon contient la date à laquelle l'invitation a été envoyée par courriel.
*'''Rappel envoyé?''': par défaut a 'N', sinon contient la date à laquelle le rappel a été envoyée par courriel.
*'''Complété?''': par défaut a 'N', sinon contient la date à laquelle le questionnaire a était validé pour les questionnaire non anonyme ou Y pour les questionnaires anonyme.
*'''Utilisations restantes''': compteur du nombre de fois que le code d'invitation peut être utilisé.
*'''Valable à partir de & Valide jusqu'à''' : Vous pouvez définir une plage de date/heure durant laquelle ce code d'invitation pourra être utilisé. Vous pouvez laisser ces champs vides si vous ne souhaitez pas limiter les dates pour certains utilisateurs. Remarque: Si l'utilisateur répond au questionnaire au moment ou la date arrive à échéance, l'invitation est verrouillé immédiatement, le répondant ne pourra pas terminer le sondage.
*'''Attribute 1 to Attribute X''': Ce sont les champs d'attribut définissables par administrateur - voir ci dessous.

=Codes factices=

Le système des codes factices a été ajouté à partir de la version 1.91.

{IMG(attId="85",imalign="center")}
*'''Nombres de jetons''': Nombre de codes d'invitations à ajouter. Par défaut à 100.
*'''Longueur du code''': Nombre de caractères ou la longueur des codes d'invitations. Par défaut à 15.
*'''Prénom et Nom''': .. des participants.
*'''Couriel''': l'adresse de courriel des participants
*'''Langue''': Si vous voulez configurer la langue par défaut pour ce participant.
*'''Utilisations restantes''': compteur du nombre de fois ou le code pourra être utilisé
*'''Valable à partir de & jusqu'à''' : la plage de date / l'heure où les codes pourront être utilisés.
*'''Attribute 1 to Attribute X''': Champs d'attribut définissables par l’administrateur

Veuillez noter que le nom, l'adresse de courriel, la langue seront fixés à la même valeur pour tous les codes factices.

=Bounce Settings{{NewIn|1.91}}=

Les paramètres de rejet ont été ajoutés à partir de la version 1.91

[[File:surveyBounseSettings.png]]
*'''Survey bounce email''': A valid email address for return mail. For faster bounce back processing, this email box should be limited to bounce back only.
*'''Bounce settings to be used''': There are three options: 1- None (default) - no bounce back processing, 2- Use settings below - Will set bounce back processing at the survey level, or 3- Use global settings -- Settings based on the system level.
*'''Server type''': Three options: 1- Off, 2- IMAP or 3- POP
*'''Server name & port''': Host name and port number. Port number isn't typically needed unless the email host uses a non-standard port. Example: mail.example.net:25 or imap.gmail.com:995
*'''User name''': User Name or User ID of the email account
*'''Password''': password of the email account
*'''Encryption type''': Three options: 1- None (default), 2- SSL, or 3- TLS

=Champs des attributs personnalisés=

It is possible to add a number of additional fields to the tokens table to save additional data for a participant. By clicking on the [[File:token_manage.png]] icon you can manage these fields. You can add more attribute fields (by default they have a a length of 255 chars) and also set descriptions for each field - so they look nicer in the administration, when you browse tokens, when creating [[Setting conditions|conditions]] based on attribute fields or even when you export results for non-anonymous surveys.

Il est possible d'ajouter un certains nombre de champs supplémentaires à la table des invitations pour enregistrer des données supplémentaires concernant les participants. En cliquant sur l'icône [[File:token_manage.png]], vous pouvez gérer ces champs. Vous pouvez ajouter des champs d'attributs (par défaut, ils ont une longueur de 255 caractères) et des descriptions pour chaque champ - pour qu'ils soient plus explicite dans l'interface d'administration, lorsque vous consultez la tables des invitations, ou loirs de conditions basées sur des attributs ou lorsque vous exportez un questionnaire non anonyme.

=Utilisation de l'écran d'affichage des invitations et édition des réponses=

L'écran d'affichage montre une liste de toutes les entrées de la table des invitations, ainsi que des boutons d'action pour effectuer des tâches spécifiques sur une entrée individuelle.

La ligne du haut du tableau est composée de 3 parties: celle de droite permet de sélectionner le nombre de lignes affichées, ainsi que le point de départ; au centre un formulaire de recherche; les boutons sur le coté gauche permettent de naviguer dans la liste.

La deuxième ligne de la table comprend le nom du champ, et une flèche verte qui - s'il est cliqué - permet de trier par rapport à ce champs.

La colonne "Actions" donne une liste de tâches spécifiques qui peuvent être effectuées sur cette entrée individuelle:

[[File:token-actions.png]]
*Lancer le questionnaire pour cette invitation
*Éditer cette invitation
*Supprimer cette invitation
*Envoyer un courriel d'invitation ou de rappel à cette netrée
*Si le questionnaire est non-anonyme, un bouton supplémentaire apparait pour visualiser la réponse correspondante.

=Administration de la base de donnée=

[[File:token-summary.png]][[File:token-db-mgt.png]]

{IMG(attId="91",imalign="center")}

En plus d'afficher un bref résumé de l'état de votre table d'invitation, l'écran d'accueil vous permet aussi d'effectuer quelques manipulations sur cette table.
*'''Mettre toutes les invitations à 'Non envoyée'''' Défini l'ensemble des invitations à "Non envoyée" ( à 'N' ). Ne devrait normalment ne pas être utilisé.
*'''Supprimer tous les codes uniques''': Efface tous les codes des invitations, n'efface que les codes, pas les invitations. Ne devrait pas être utilisé en situation normale.
*'''Supprimer toutes les invitations''': Supprime complétement la table d'invitation. Ouvre le sondage aux personnes connaissant l'adresse du questionnaire.

= Import/export des inviations=

== Import via un fichier CSV==

L'import se fait via cet écran

[[File:uploadtoken.jpg]]

Votre fichier CSV doit être à la norme des [http://fr.wikipedia.org/wiki/Comma-separated_values fichiers CSV ('Comma Separated Value')] , c'est à dire séparé par des virgule (,). La première ligne de texte est toujours l'en-tête et sera utilisé pour identifier les colonnes de la table. Les champs de données possibles sont:

firstname,lastname,email,emailstatus,token,language code,tid,attribute_1,attribute_2, attribute_...

Pour obtenir une liste complète des noms de champs de la table d'invitation, vous pouvez exporter une table existante.

Les champs peuvent être dans n'importe quel ordre, mais les colonnes pour le nom, pour le prénom et pour le courriel sont obligatoires. Vous pouvez importer les champs supplémentaire des attributs au même moment.

Un fichier CSV au strict minimum pourrait ressembler à ceci:

firstname,lastname,email
John,Doe,john@doe.net

'''Date format for token import'''

The date format for the "validfrom" and "validuntil" fields in the CSV token inport file is "YYYY-MM-DD HH:MM", e.g.:

2012-01-01 00:00

--would correspond to 1st January, 2012, at 12:00 AM.

'''Filtering duplicates'''

En activant l'option pour filtrer les doublons, vous pouvez définir les champs qui sont utilisés pour identifier les doublons. Par défaut le 'Nom, Prénom et Adresse de Courriel' sont présélectionnés. Si un doublon est trouvé lors de l'importation de la ligne liée est omise.

'''Dépannage pour l'import des invitations'''

A common error when users try to import tokens is an invalid CSV file. This is often caused by Microsoft Excel. Many users have a list of e-mail addresses saved as an XLS document. A file can be saved as CSV in Excel, however, depending on the locale of the OS Microsoft may use semi-colon (;) as the comma separator, while a standard CSV file uses comma (,) as the separator. If not sure just open the file with a standard text editor and check what separator was used. Starting in version 2.00 can you select the used separator during import.

Vous pouvez aussi utiliser [http://fr.libreoffice.org/libreoffice/calc/ Libre Office Calc] pour importer votre fichier xls et exporter un fichier CSV au bon format.

You can use [http://www.libreoffice.org/features/calc/ LibreOffice Calc] to export import your xls file and export your csv file.

'''Add additional attributes at import'''
It is also possible to add new custom attributes when import a CSV file. It is still needed to define what attributes will be added. The way to do this is:
firstname,lastname,email
attribute_1 <Casenr>; token; attribute_2 <Title>; attribute_3 <destination>; lastname; firstname; attribute_4 <Sender>;

== Creating CSV file with Excel on the Mac==

When you create a CSV file with Excel 2011 on the MAC and use the standard "save as" option, you loose special characters such as ü, ë, é etc. when importing into LimeSurvey Token Table.

To make this work properly choose to save the file as a Windows text CSV file (tested on the Dutch version of Excel, saved as "Door lijstscheidingstekens gescheiden Windows tekst (.CSV)").

Then when importing the file in the LimeSurvey token table, under "character set of file" choose "Mac West European". The special characters will be imported correctly.

Testé seulement sur la version 2.0 de LimeSurvey

== Export au format CSV ==

Quand vous exporter votre table au format CSV, les champs sont exportés dans l'ordre suivant:

tid,prénom,nom,email,emailstatus,invitation,langue,code,attribut_1,attribut_2,...

== Import depuis un annuaire LDAP ==

[[File:token-Ldap-import.png]]
* Les requêtes sont définies manuellement par administrateur du système dans le fichier config-ldap.php
* Les doublons sont identifiés par le prénom, le nom et l'adresse de courriel. Si un doublon est trouvé, lors de l'importation la ligne concernée est omise, sauf si vous avez décoché la case de filtre des doublons.

== Un truc pour générer un nombre important de fausses adresses de courriels==

Quelquefois, vous pouvez avoir besoin d'un grand nombre d'adresses de courriel et d'invitations. Vous pouvez utiliser les fonctions de votre tableur ( par exemple OpenOffice Calc) pour les fabriquer. Supposons que vous souhaitiez des milliers d'adresses de courriel de la forme : 1@test.com, 2@test.com,3@test.com,... Vous aller entrer une liste consécutive de nombres dans la colonne A en indiquant à partir de la ligne 2 : =A1+1, ensuite copier/coller A2 autant de fois que vous le souhaitez. Dans la colonne B, en entête, vous indiquez email et à partir de B2: =A2&"@example.org". Vous pouvez ensuite enregistrer ce fichier au format CSV et l'importer dans votre table d'invitation.

Depuis la version 1.91, vous pouvez directement utiliser la génération automatique de code factices.

== Une astuce pour générer un grand nombre de liens individuels incluant l'invitation ==

La structure du lien pour un sondage est la suivante :

Limesurvey 1.x: http://url-vers-votre-installation-limesurvey/index.php?sid=XXXX&lang=fr&token={TOKEN}

Limesurvey 2.x: http://url-vers-votre-installation-limesurvey/index.php/survey/index/sid/xxxx/newtest/Y/lang/FR/token/{TOKEN}

So you proceed similar to the example above for generating email adresses.
*First column: http://url-to-your-limesurvey-installation/index.php?sid=XXXX&lang=en&token= (for version 1.x) OR http://url-to-your-limesurvey-installation/index.php/survey/index/sid/xxxx/newtest/Y/lang/EN/token/ (for version 2.x) (same URL for all, as long as the language is the same!)
*Second column: {TOKEN} (put your tokens here, of course they must be individual)
*Third column: use the CONCATENATE function to join the first column with the second column.

= L'envoi des courriels=

== Les champs réservés des courriels==

Les textes suivants sont autorisés dans des modèles des courriels d'invitation ou de rappel et sont saisi dans les propriétés du sondage. Lors de l'envoi des courriels ces champ seront déjà remplacé dans l'aperçu de votre invitation ou de votre courriel de rappel.

{|
|{ADMINEMAIL}||courriel de l'adminsitrateur
|-
|{ADMINNAME}||Nom de l'administrateur
|-
|{SURVEYNAME}||Titre du questionnaire
|-
|{SURVEYDESCRIPTION}||Description du questionnaire
|}

Les champs suivants sont aussi permis dans les courriels d'invitation ou de rappel et seraont remplacé lors de l'envoi du courriel

{|
|{EMAIL}||Adresse de courriel de l'invité
|-
|{FIRSTNAME}||Prénom
|-
|{LASTNAME}||Nom
|-
|{SURVEYURL}||L'adresse URL pour démarrer le questionnaire - en cas d'envoi au format HTML, ce sera un lien HTML complet
|-
|@@SURVEYURL@@||L'adresse URL pour démarrer le questionnaire au format texte - c'est l'adresse brute. Utilisable dans le corps HTML par exemple (disponible à partie de la version 1.90)
|-
|{TOKEN}||Le code pour accéder au questionnaire
|-
|{ATTRIBUTE_1}||Attribut 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...continuant pour chaque attributs)
|}

If your survey is NOT anonymous, the following field names are available to insert token data in survey text and javascript. You can use these fields in confirmation and notification email template, too.

{|
|{TOKEN:EMAIL}||Adresse de courriel de l'invité
|-
|{TOKEN:FIRSTNAME}||Prénom
|-
|{TOKEN:LASTNAME}||Nom
|-
|{TOKEN}||Le code pour accéder au questionnaire
|-
|{TOKEN:ATTRIBUTE_1}||Attribut 1
|-
|{TOKEN:ATTRIBUTE_2}||Attribut 2 (...continuant pour chaque attributs)
|}

===Additional hints===
*If your survey is using anonymized responses then token-related placeholders will not work in notification email templates.
*You can use [[Expression Manager|Expression Manager]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[Expression Manager HowTos|Expression Manager HowTos]] for an example.
Also have a look at the examples on using [[Adding a question#Information from tokens table|information from tokens table]].

==Paramètres des courriels==
#'''Objet du courriel d'invitation :''': La ligne du sujet de votre courriel d'invitation en cas de table d'invitation.
#'''Courriel d'invitation :''': C'est le texte du courriel d'invitation qui sera envoyé. Il est par défaut rempli par un message d'invitation par défaut ( provenant du fichier de langue). Vous pouvez utiliser les champs suivants pour insérer des informations personnalisées dans chaque courriel.
**'''{FIRSTNAME}''' - sera remplacé par le prénom
**'''{LASTNAME}''' - sera remplacé par le nom
**'''{SURVEYNAME}''' - sera remplacé par le titre du questionnaire
**'''{SURVEYDESCRIPTION}''' - sera remplacé par la description du questionnaire
**'''{ATTRIBUTE_1}''' - sera remplacé par la valeur de l'attribut 1
**'''{ATTRIBUTE_2}''' - sera remplacé par la valeur de l'attribut 2, etc ...
**'''{SURVEYURL}''' - sera remplacé par l'adresse d'accès au sondage en HTML
**'''@@SURVEYURL@@''' - sera remplacé par l'adresse brute d'accès au sondage (à partir de la v1.90)
**'''{OPTOUTURL}''' - sera remplacé par l'adresse peremattant au répondant de se désinscrire (opt-out) du questionnaire

Noter que ses champs reservés sont possible dans les champs des courriels suivant.
#'''Objet du courriel de rappel''': Le sujet du courriel de rappel
#'''Courriel de rappel''': Texte du contenu du courriel de rappel, éventuellement en HTML
#'''Objet du courriel de confirmation''' Quand les invitations sont utilisée, un courriel de confirmation est envoyé au participant à la validation du questionnaire. C'est ici le sujet de ce courriel.
#'''Courriel de confirmation''': Le texte du courriel de confirmation. Effacer ce texte permet de ne pas envoyer de confirmation.
#'''Objet du courriel d'enregistrement public''': C'est le sujet envoyé suite à une inscription sur un questionnaire.
#'''Courriel d'enregistrement public''': C'est le texte du courrier de confirmation envoyé suite à une inscription, il contient le nécessaire pour accède r directement au questionnaire.

==Envoi des courriels==

=== Envoyer les invitations===

{IMG(attId="88",imalign="center")}

Vous pouvez ignorer les invitations pour lesquelles le statut du courriel est différent de "OK", en choisissant "Sauter les invitations avec une adresse de courriel invalide"

==== Renvoyez une invitation====

Quelquefois vous voulez renvoyer des courriels d'invitation à certaines personnes. Quand vous utilisez '''Envoyer les courriels d'invitation''' seules les personnes auxquelles vous n'avez pas encore envoyé d'invitation vont recevoir un courriel.

Vous pouvez donc renvoyer aussi des invitations à des utilisateurs en particulier en éditant leur invitation et en indiquant '''N''' dans la case '''Invitation envoyée?''', en remplaçant la date existante.

==== Désinscription d'un participant (opt-out)====

Lorsque vous utilisez le tag { OPTOUTURL} dans votre courriel d'invitation ou de rappel , vos participants ont la possibilité de se retirer de cette enquête en particulier en cliquant simplement sur cette adresse URL. Cela permet de ne pas harceler les utilisateurs avec des courriels de rappel. Un participant qui a opté de votre enquête aura 'Opt Out' l'état électronique indiquée dans le jeton.

=== Envoi des rapppels===

{IMG(attId="92",imalign="center")}

Quand vous envoyez des rappels, vous pouvez:
*Passer les invitations avec une adresse invalide
*Passer les invitations pour laquelle un courriel a été 'récemment' envoyé.
*Passer les invitations pour lequel un nombre donné de courriels ont déjà été envoyés.

Note: A reminder will only be send to tokens where the "completed" field is not "N" (this means the respondent has either not taken or has not completed the survey).

=== Envoi groupé de courriel===

Quand vous avez un grand nombre de courriel à envoyer en même temps, LimeSurvey va limiter les envois par groupe de N courriel ( ceci est paramétrable dans les options générales, par défaut à 50)

Vous devez cliquer sur suivant jusque ce que l'ensemble des courriels soient envoyés.

=== Courriel de confirmations===

Quand vous utiliser les invitations, un courriel de confirmation lui est envoyé à la validation du questionnaire.

If you don't want this message to be sent, just deactivate this in the General survey settings.

=== Spam problems===

Often users complain not having received an invitation/reminder email because the user’s spam filter treated the email as spam.

If an email is treated as spam mostly depends on the spam filter being used and its settings. A spam filter usually checks the sender address and the email subject and content, so there are ways and means to influence how they treat your LimeSurvey invitation and reminder emails.

At [http://www.limesurvey-consulting.com/how-to-prevent-limesurvey-email-invitations-or-reminders-being-treated-as-spam/ this blog post] on limesurvey-consulting.com a lot of possible issues and solutions are listed.

===Wrong domain in invitation/reminder email link===

LimeSurvey automatically tries to determine the URL for the invitation link by looking at the URL by which you logged in to the LimeSurvey administration. However with some server (mis-)configurations this might not work properly and you will have to set this manually.

You can edit application/config/config.php to change the default base URL value. Add hostInfo property like this to the existing 'components' array.

<syntaxhighlight lang="php" enclose="div"> 'components' => array(
...
'request' => array(
'hostInfo' => 'http://www.example.com',
),
)
</syntaxhighlight>

Regarding the source of the problem: LimeSurvey tried to determine the domain from the server PHP variable $_SERVER<nowiki>[</nowiki>'HTTP_HOST'] or $_SERVER<nowiki>[</nowiki>'SERVER_NAME'].

Some web server software do not properly seem to provide this information or are mis-configured.

= Enregistrement public=

==Permettre l'enregistrement public==

Vous pouvez vouloir ouvrir votre questionnaire à tous mais avoir le système de contrôle utilisable avec les invitations. Ceci est possible : si vous initialiser la table des invitations et que vous choisissez OUI à Permettre l'enregistrement public? dans les paramètres du questionnaire alors les répondants vont pouvoir s'inscrire avant de répondre à votre questionnaire. Aprèsn s'éêtre inscrit, il recevront une adresse URL pour remplir le questionnaire.

Tous les codes d'invitations provenant d'un enregistrement public commence par la lettre R.

==Les 'captchas' dans l'enregistrement public==

Pour protéger votre sondage d'inscription par des robits, il y a une fonction de 'captcha' pour l'enregistrement, la sauvegardez et le chargelent des questionnaires (à partir de la version 1.48). Cette fonctionnalité n'est disponible que si vous avez le support GD d'activé dans votre configuration de PHP (voir [[Installation|Prérequis d'Installation]] ).

Translations:Survey participants/22/fr

2014-04-06T21:44:00Z

Courtm:

Les paramètres de rejet ont été ajoutés à partir de la version 1.91

Survey participants/fr

2014-04-06T21:43:13Z

Courtm:

<languages /> __TOC__

<div class="simplebox">'''Remarque''': Le système des invitations a beaucoup changé depuis la version 1.85 et versions ultérieures. Donc, si vous utilisez une version antérieure, il y aura des différences entre votre version et la documentation. Nous vous recommandons de mettre à niveau dès que possible.</div>

=Introduction=

En de nombreuses occasions, vous voulez inviter un groupe de personnes pour participer à votre sondage, garder la trace des répondants ayant terminé le sondage, et vous assurer que chaque personne ne peut participer qu'une seule fois. Le système des invitations vous permet d'effectuer les opérations suivantes:
*Créez manuellement des invitations (nom, adresse email, ...)
*Importer une liste de noms et d'adresses email pour les participants (à partir d'un fichier CSV ou une interrogations LDAP)
*Ajouter / Supprimer des invitations
*Générer un numéro unique pour le jeton de chaque participant (code d'invitation)
*Envoyez une invitation par courriel à chaque personne de votre liste, par groupe ou individuellement
*Envoyer un courriel de rappel à chaque personne de votre liste qui n'a pas encore répondu, par groupe ou individuellement
*Suivi les répondants de votre liste qui ont répondu
*Interdire l'accès aux personnes qui n'ont pas de ceode d'invitation, et ceux qui ont déjà répondu
*Modifier / changer tous les détails dans votre liste d'invitation

Une fois le questionnaire en accès restreint (vous avez activé les invitations pour ce questionnaire), alors '''seules les personnes avec une invitation valide (pas encore utilisée) peuvent accéder au questionnaire'''.

Si vous activez ''Permettre l'enregistrement public ?'' dans les propriétés du questionnaire, les participants pourront s'inscrire à votre sondage et avoir leur code d'invitation personnel généré automatiquement.

{{Hint|Text=Some token settings are set in survey settings, see [[Creating a new survey#Tokens]]}}

==Est-ce qu'une sondage utilisant les invitations peut assurer des réponses anonymes?==

La réponse à cette question est '''Oui'''. Les invitations peuvent être utilisées tant pour les sondages anonymes que non anonymes. Ceci est déterminé lors de la création du questionnaire. Si un questionnaire n'est pas anonyme (ou 'suivi') alors le code d'invitation peut être utilisé pour trouver les réponses que le répondant a faites au questionnaire. Si le sondage est anonyme, alors aucun lien n'est disponible entre la table des invitations et la table des réponses (techniquement: pas de relation de clé étrangère).

=Comment activer les invitations ?=

Il y a deux manières d'activer les invitations:
#Juste après l'activation du questionnaire, il vous sera demandé si vous souhaitez activer les invitations: {IMG(attId="84",imalign="center")}
# '''Ou''' vous pouvez cliquer sur le symbole de gestion des invitations [[File:tokens.png]] - avant même que le sondage soit activé.

=Les outils de contrôle des invitations=

[[File:token-menu2.png]]

Après la création de la table des invitations, vous pouvez cliquer sur l'icône pour administrer les codes d'invitation. Voici un bref aperçu des options de menu de l'écran de gestion des invitations:
*'''Administration''': Retourne à l'écran d'administration principal du questionnaire
*'''Résumé''': Affiche un résumé des invitations de la table nombre de codes d'invitation, nombre d'invitation envoyée, et nombre de réponse. Permet également d'accéder aux fonctions de d'administration de la base de données voir ci-dessous. C'est l'écran par défaut.
*'''Parcourir''': Affiche la liste complète des participants de la table des invitations. Depuis l'écran d'affichage, vous pouvez modifier ou supprimer des entrées individuelles dans la table ainsi qu'un certain nombre d'autres fonctions utiles voir la section Parcourir ci-dessous
*'''Ajouter une nouvelle invitation''': Permet d'ajouter une entrée à la table des invitations
*'''Ajouter des codes factices''': Permet d'ajouter une ou plusieurs codes d'invitations à la table des invitations trèsb rapidement.
*'''Gérer les champs des attributs supplémentaire:''': Permet d'ajouter des champs supplémentaires à la table des invitations pour stocker des données personnalisées liés aux participants
*'''Importer à partir d'un CSV''': Permet d'importer les informations des invitations depuis un fichier CSV
*'''Importer à partir de LDAP''': Permet d'importer les informations d'une requête LDAP testé sur openLDAP, mais devrait fonctionner dans tous annuaire compatible LDAP, dont ActiveDirectory.
*'''Export les invitations vers un fichier CSV''': Crée un fichier standard CSV (délimité par des virgules) avec la liste complète des participants de la table des invitations en cours.
*'''Éditer les modèles de courriel''': Pour personnaliser les textes et contenus utilisés pour les invitations, les rappels, confirmations, et les courriels d'inscription.
*'''Envoyer les courriels d'invitation''': Envoi global des invitations par courriel à tous les participants de la table des invitations qui n'ont pas déjà reçu une invitation.
*'''Envoyer les courriels de rappel''': Envoi global des courriels de rappel à tous les participants ayant reçu une invitation et n'ayant pas encore répondu.
*'''Générer les codes''': Crée les codes d'invitation uniques pour toutes les entrées individuelles de la table des invitations qui n'en disposent pas encore.
*'''Effacer la tabe des inviations''': Supprimer la table des invitations et passer le questionnaire en accès libre ou ouvert.
*'''Paramètres de rejet''': Paramètrage du courriel recevant les courriels de rejet. Ces paramètres peuvent être modifié à ce niveau ou au niveau général. Ce dispositif a été ajouté dans la version 1.91.

=Modification et ajout d'une invitation=

Une entrée typique d'invitation contient les champs suivants:

{IMG(attId="83",imalign="center")}
*'''Prénom et Nom''' : ... du participant (peut être utilisé dans les courriels et les questionnaires).
*'''Courriel''': l'adresse courriel du participant
*'''Statut du courriel''': un champ pour conserver une trace des mauvaises adresses de courriels. Par exemple, si l'administrateur du sondage ont reçu des notifications d'erreur par courriel à partir de ce courriel, ce qu'il peut définir ce champ à autre chose que 'OK' (par exemple 'utilisateur inconnu', ou 'quota dépassé'). Le marquage cette invitation avec un autre statut que 'OK', permettra d'ignorer cette entrée lors de l'envoi d'invitation ou de couriel de rappel. Notez que ceci est entièrement manuel à moins vous décidez de mettre en place un script qui met à jour ce champ automatiquement.
*'''Code''': c'est le code de l'invitation. Il est généralement généré automatiquement avec le bouton 'Générer les codes d'invitations'.
*'''Langue''': pour configurer la langue par défaut pour ce participant.
*'''Invitation envoyée?''': par défaut a 'N', sinon contient la date à laquelle l'invitation a été envoyée par courriel.
*'''Rappel envoyé?''': par défaut a 'N', sinon contient la date à laquelle le rappel a été envoyée par courriel.
*'''Complété?''': par défaut a 'N', sinon contient la date à laquelle le questionnaire a était validé pour les questionnaire non anonyme ou Y pour les questionnaires anonyme.
*'''Utilisations restantes''': compteur du nombre de fois que le code d'invitation peut être utilisé.
*'''Valable à partir de & Valide jusqu'à''' : Vous pouvez définir une plage de date/heure durant laquelle ce code d'invitation pourra être utilisé. Vous pouvez laisser ces champs vides si vous ne souhaitez pas limiter les dates pour certains utilisateurs. Remarque: Si l'utilisateur répond au questionnaire au moment ou la date arrive à échéance, l'invitation est verrouillé immédiatement, le répondant ne pourra pas terminer le sondage.
*'''Attribute 1 to Attribute X''': Ce sont les champs d'attribut définissables par administrateur - voir ci dessous.

=Codes factices=

Le système des codes factices a été ajouté à partir de la version 1.91.

{IMG(attId="85",imalign="center")}
*'''Nombres de jetons''': Nombre de codes d'invitations à ajouter. Par défaut à 100.
*'''Longueur du code''': Nombre de caractères ou la longueur des codes d'invitations. Par défaut à 15.
*'''Prénom et Nom''': .. des participants.
*'''Couriel''': l'adresse de courriel des participants
*'''Langue''': Si vous voulez configurer la langue par défaut pour ce participant.
*'''Utilisations restantes''': compteur du nombre de fois ou le code pourra être utilisé
*'''Valable à partir de & jusqu'à''' : la plage de date / l'heure où les codes pourront être utilisés.
*'''Attribute 1 to Attribute X''': Champs d'attribut définissables par l’administrateur

Veuillez noter que le nom, l'adresse de courriel, la langue seront fixés à la même valeur pour tous les codes factices.

=Bounce Settings{{NewIn|1.91}}=

Please also check out the [[Email bounce tracking system]] page for more information how to correctly configure this feature.

[[File:surveyBounseSettings.png]]
*'''Survey bounce email''': A valid email address for return mail. For faster bounce back processing, this email box should be limited to bounce back only.
*'''Bounce settings to be used''': There are three options: 1- None (default) - no bounce back processing, 2- Use settings below - Will set bounce back processing at the survey level, or 3- Use global settings -- Settings based on the system level.
*'''Server type''': Three options: 1- Off, 2- IMAP or 3- POP
*'''Server name & port''': Host name and port number. Port number isn't typically needed unless the email host uses a non-standard port. Example: mail.example.net:25 or imap.gmail.com:995
*'''User name''': User Name or User ID of the email account
*'''Password''': password of the email account
*'''Encryption type''': Three options: 1- None (default), 2- SSL, or 3- TLS

=Champs des attributs personnalisés=

It is possible to add a number of additional fields to the tokens table to save additional data for a participant. By clicking on the [[File:token_manage.png]] icon you can manage these fields. You can add more attribute fields (by default they have a a length of 255 chars) and also set descriptions for each field - so they look nicer in the administration, when you browse tokens, when creating [[Setting conditions|conditions]] based on attribute fields or even when you export results for non-anonymous surveys.

Il est possible d'ajouter un certains nombre de champs supplémentaires à la table des invitations pour enregistrer des données supplémentaires concernant les participants. En cliquant sur l'icône [[File:token_manage.png]], vous pouvez gérer ces champs. Vous pouvez ajouter des champs d'attributs (par défaut, ils ont une longueur de 255 caractères) et des descriptions pour chaque champ - pour qu'ils soient plus explicite dans l'interface d'administration, lorsque vous consultez la tables des invitations, ou loirs de conditions basées sur des attributs ou lorsque vous exportez un questionnaire non anonyme.

=Utilisation de l'écran d'affichage des invitations et édition des réponses=

L'écran d'affichage montre une liste de toutes les entrées de la table des invitations, ainsi que des boutons d'action pour effectuer des tâches spécifiques sur une entrée individuelle.

La ligne du haut du tableau est composée de 3 parties: celle de droite permet de sélectionner le nombre de lignes affichées, ainsi que le point de départ; au centre un formulaire de recherche; les boutons sur le coté gauche permettent de naviguer dans la liste.

La deuxième ligne de la table comprend le nom du champ, et une flèche verte qui - s'il est cliqué - permet de trier par rapport à ce champs.

La colonne "Actions" donne une liste de tâches spécifiques qui peuvent être effectuées sur cette entrée individuelle:

[[File:token-actions.png]]
*Lancer le questionnaire pour cette invitation
*Éditer cette invitation
*Supprimer cette invitation
*Envoyer un courriel d'invitation ou de rappel à cette netrée
*Si le questionnaire est non-anonyme, un bouton supplémentaire apparait pour visualiser la réponse correspondante.

=Administration de la base de donnée=

[[File:token-summary.png]][[File:token-db-mgt.png]]

{IMG(attId="91",imalign="center")}

En plus d'afficher un bref résumé de l'état de votre table d'invitation, l'écran d'accueil vous permet aussi d'effectuer quelques manipulations sur cette table.
*'''Mettre toutes les invitations à 'Non envoyée'''' Défini l'ensemble des invitations à "Non envoyée" ( à 'N' ). Ne devrait normalment ne pas être utilisé.
*'''Supprimer tous les codes uniques''': Efface tous les codes des invitations, n'efface que les codes, pas les invitations. Ne devrait pas être utilisé en situation normale.
*'''Supprimer toutes les invitations''': Supprime complétement la table d'invitation. Ouvre le sondage aux personnes connaissant l'adresse du questionnaire.

= Import/export des inviations=

== Import via un fichier CSV==

L'import se fait via cet écran

[[File:uploadtoken.jpg]]

Votre fichier CSV doit être à la norme des [http://fr.wikipedia.org/wiki/Comma-separated_values fichiers CSV ('Comma Separated Value')] , c'est à dire séparé par des virgule (,). La première ligne de texte est toujours l'en-tête et sera utilisé pour identifier les colonnes de la table. Les champs de données possibles sont:

firstname,lastname,email,emailstatus,token,language code,tid,attribute_1,attribute_2, attribute_...

Pour obtenir une liste complète des noms de champs de la table d'invitation, vous pouvez exporter une table existante.

Les champs peuvent être dans n'importe quel ordre, mais les colonnes pour le nom, pour le prénom et pour le courriel sont obligatoires. Vous pouvez importer les champs supplémentaire des attributs au même moment.

Un fichier CSV au strict minimum pourrait ressembler à ceci:

firstname,lastname,email
John,Doe,john@doe.net

'''Date format for token import'''

The date format for the "validfrom" and "validuntil" fields in the CSV token inport file is "YYYY-MM-DD HH:MM", e.g.:

2012-01-01 00:00

--would correspond to 1st January, 2012, at 12:00 AM.

'''Filtering duplicates'''

En activant l'option pour filtrer les doublons, vous pouvez définir les champs qui sont utilisés pour identifier les doublons. Par défaut le 'Nom, Prénom et Adresse de Courriel' sont présélectionnés. Si un doublon est trouvé lors de l'importation de la ligne liée est omise.

'''Dépannage pour l'import des invitations'''

A common error when users try to import tokens is an invalid CSV file. This is often caused by Microsoft Excel. Many users have a list of e-mail addresses saved as an XLS document. A file can be saved as CSV in Excel, however, depending on the locale of the OS Microsoft may use semi-colon (;) as the comma separator, while a standard CSV file uses comma (,) as the separator. If not sure just open the file with a standard text editor and check what separator was used. Starting in version 2.00 can you select the used separator during import.

Vous pouvez aussi utiliser [http://fr.libreoffice.org/libreoffice/calc/ Libre Office Calc] pour importer votre fichier xls et exporter un fichier CSV au bon format.

You can use [http://www.libreoffice.org/features/calc/ LibreOffice Calc] to export import your xls file and export your csv file.

'''Add additional attributes at import'''
It is also possible to add new custom attributes when import a CSV file. It is still needed to define what attributes will be added. The way to do this is:
firstname,lastname,email
attribute_1 <Casenr>; token; attribute_2 <Title>; attribute_3 <destination>; lastname; firstname; attribute_4 <Sender>;

== Creating CSV file with Excel on the Mac==

When you create a CSV file with Excel 2011 on the MAC and use the standard "save as" option, you loose special characters such as ü, ë, é etc. when importing into LimeSurvey Token Table.

To make this work properly choose to save the file as a Windows text CSV file (tested on the Dutch version of Excel, saved as "Door lijstscheidingstekens gescheiden Windows tekst (.CSV)").

Then when importing the file in the LimeSurvey token table, under "character set of file" choose "Mac West European". The special characters will be imported correctly.

Testé seulement sur la version 2.0 de LimeSurvey

== Export au format CSV ==

Quand vous exporter votre table au format CSV, les champs sont exportés dans l'ordre suivant:

tid,prénom,nom,email,emailstatus,invitation,langue,code,attribut_1,attribut_2,...

== Import depuis un annuaire LDAP ==

[[File:token-Ldap-import.png]]
* Les requêtes sont définies manuellement par administrateur du système dans le fichier config-ldap.php
* Les doublons sont identifiés par le prénom, le nom et l'adresse de courriel. Si un doublon est trouvé, lors de l'importation la ligne concernée est omise, sauf si vous avez décoché la case de filtre des doublons.

== Un truc pour générer un nombre important de fausses adresses de courriels==

Quelquefois, vous pouvez avoir besoin d'un grand nombre d'adresses de courriel et d'invitations. Vous pouvez utiliser les fonctions de votre tableur ( par exemple OpenOffice Calc) pour les fabriquer. Supposons que vous souhaitiez des milliers d'adresses de courriel de la forme : 1@test.com, 2@test.com,3@test.com,... Vous aller entrer une liste consécutive de nombres dans la colonne A en indiquant à partir de la ligne 2 : =A1+1, ensuite copier/coller A2 autant de fois que vous le souhaitez. Dans la colonne B, en entête, vous indiquez email et à partir de B2: =A2&"@example.org". Vous pouvez ensuite enregistrer ce fichier au format CSV et l'importer dans votre table d'invitation.

Depuis la version 1.91, vous pouvez directement utiliser la génération automatique de code factices.

== Une astuce pour générer un grand nombre de liens individuels incluant l'invitation ==

La structure du lien pour un sondage est la suivante :

Limesurvey 1.x: http://url-vers-votre-installation-limesurvey/index.php?sid=XXXX&lang=fr&token={TOKEN}

Limesurvey 2.x: http://url-vers-votre-installation-limesurvey/index.php/survey/index/sid/xxxx/newtest/Y/lang/FR/token/{TOKEN}

So you proceed similar to the example above for generating email adresses.
*First column: http://url-to-your-limesurvey-installation/index.php?sid=XXXX&lang=en&token= (for version 1.x) OR http://url-to-your-limesurvey-installation/index.php/survey/index/sid/xxxx/newtest/Y/lang/EN/token/ (for version 2.x) (same URL for all, as long as the language is the same!)
*Second column: {TOKEN} (put your tokens here, of course they must be individual)
*Third column: use the CONCATENATE function to join the first column with the second column.

= L'envoi des courriels=

== Les champs réservés des courriels==

Les textes suivants sont autorisés dans des modèles des courriels d'invitation ou de rappel et sont saisi dans les propriétés du sondage. Lors de l'envoi des courriels ces champ seront déjà remplacé dans l'aperçu de votre invitation ou de votre courriel de rappel.

{|
|{ADMINEMAIL}||courriel de l'adminsitrateur
|-
|{ADMINNAME}||Nom de l'administrateur
|-
|{SURVEYNAME}||Titre du questionnaire
|-
|{SURVEYDESCRIPTION}||Description du questionnaire
|}

Les champs suivants sont aussi permis dans les courriels d'invitation ou de rappel et seraont remplacé lors de l'envoi du courriel

{|
|{EMAIL}||Adresse de courriel de l'invité
|-
|{FIRSTNAME}||Prénom
|-
|{LASTNAME}||Nom
|-
|{SURVEYURL}||L'adresse URL pour démarrer le questionnaire - en cas d'envoi au format HTML, ce sera un lien HTML complet
|-
|@@SURVEYURL@@||L'adresse URL pour démarrer le questionnaire au format texte - c'est l'adresse brute. Utilisable dans le corps HTML par exemple (disponible à partie de la version 1.90)
|-
|{TOKEN}||Le code pour accéder au questionnaire
|-
|{ATTRIBUTE_1}||Attribut 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...continuant pour chaque attributs)
|}

If your survey is NOT anonymous, the following field names are available to insert token data in survey text and javascript. You can use these fields in confirmation and notification email template, too.

{|
|{TOKEN:EMAIL}||Adresse de courriel de l'invité
|-
|{TOKEN:FIRSTNAME}||Prénom
|-
|{TOKEN:LASTNAME}||Nom
|-
|{TOKEN}||Le code pour accéder au questionnaire
|-
|{TOKEN:ATTRIBUTE_1}||Attribut 1
|-
|{TOKEN:ATTRIBUTE_2}||Attribut 2 (...continuant pour chaque attributs)
|}

===Additional hints===
*If your survey is using anonymized responses then token-related placeholders will not work in notification email templates.
*You can use [[Expression Manager|Expression Manager]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[Expression Manager HowTos|Expression Manager HowTos]] for an example.
Also have a look at the examples on using [[Adding a question#Information from tokens table|information from tokens table]].

==Paramètres des courriels==
#'''Objet du courriel d'invitation :''': La ligne du sujet de votre courriel d'invitation en cas de table d'invitation.
#'''Courriel d'invitation :''': C'est le texte du courriel d'invitation qui sera envoyé. Il est par défaut rempli par un message d'invitation par défaut ( provenant du fichier de langue). Vous pouvez utiliser les champs suivants pour insérer des informations personnalisées dans chaque courriel.
**'''{FIRSTNAME}''' - sera remplacé par le prénom
**'''{LASTNAME}''' - sera remplacé par le nom
**'''{SURVEYNAME}''' - sera remplacé par le titre du questionnaire
**'''{SURVEYDESCRIPTION}''' - sera remplacé par la description du questionnaire
**'''{ATTRIBUTE_1}''' - sera remplacé par la valeur de l'attribut 1
**'''{ATTRIBUTE_2}''' - sera remplacé par la valeur de l'attribut 2, etc ...
**'''{SURVEYURL}''' - sera remplacé par l'adresse d'accès au sondage en HTML
**'''@@SURVEYURL@@''' - sera remplacé par l'adresse brute d'accès au sondage (à partir de la v1.90)
**'''{OPTOUTURL}''' - sera remplacé par l'adresse peremattant au répondant de se désinscrire (opt-out) du questionnaire

Noter que ses champs reservés sont possible dans les champs des courriels suivant.
#'''Objet du courriel de rappel''': Le sujet du courriel de rappel
#'''Courriel de rappel''': Texte du contenu du courriel de rappel, éventuellement en HTML
#'''Objet du courriel de confirmation''' Quand les invitations sont utilisée, un courriel de confirmation est envoyé au participant à la validation du questionnaire. C'est ici le sujet de ce courriel.
#'''Courriel de confirmation''': Le texte du courriel de confirmation. Effacer ce texte permet de ne pas envoyer de confirmation.
#'''Objet du courriel d'enregistrement public''': C'est le sujet envoyé suite à une inscription sur un questionnaire.
#'''Courriel d'enregistrement public''': C'est le texte du courrier de confirmation envoyé suite à une inscription, il contient le nécessaire pour accède r directement au questionnaire.

==Envoi des courriels==

=== Envoyer les invitations===

{IMG(attId="88",imalign="center")}

Vous pouvez ignorer les invitations pour lesquelles le statut du courriel est différent de "OK", en choisissant "Sauter les invitations avec une adresse de courriel invalide"

==== Renvoyez une invitation====

Quelquefois vous voulez renvoyer des courriels d'invitation à certaines personnes. Quand vous utilisez '''Envoyer les courriels d'invitation''' seules les personnes auxquelles vous n'avez pas encore envoyé d'invitation vont recevoir un courriel.

Vous pouvez donc renvoyer aussi des invitations à des utilisateurs en particulier en éditant leur invitation et en indiquant '''N''' dans la case '''Invitation envoyée?''', en remplaçant la date existante.

==== Désinscription d'un participant (opt-out)====

Lorsque vous utilisez le tag { OPTOUTURL} dans votre courriel d'invitation ou de rappel , vos participants ont la possibilité de se retirer de cette enquête en particulier en cliquant simplement sur cette adresse URL. Cela permet de ne pas harceler les utilisateurs avec des courriels de rappel. Un participant qui a opté de votre enquête aura 'Opt Out' l'état électronique indiquée dans le jeton.

=== Envoi des rapppels===

{IMG(attId="92",imalign="center")}

Quand vous envoyez des rappels, vous pouvez:
*Passer les invitations avec une adresse invalide
*Passer les invitations pour laquelle un courriel a été 'récemment' envoyé.
*Passer les invitations pour lequel un nombre donné de courriels ont déjà été envoyés.

Note: A reminder will only be send to tokens where the "completed" field is not "N" (this means the respondent has either not taken or has not completed the survey).

=== Envoi groupé de courriel===

Quand vous avez un grand nombre de courriel à envoyer en même temps, LimeSurvey va limiter les envois par groupe de N courriel ( ceci est paramétrable dans les options générales, par défaut à 50)

Vous devez cliquer sur suivant jusque ce que l'ensemble des courriels soient envoyés.

=== Courriel de confirmations===

Quand vous utiliser les invitations, un courriel de confirmation lui est envoyé à la validation du questionnaire.

If you don't want this message to be sent, just deactivate this in the General survey settings.

=== Spam problems===

Often users complain not having received an invitation/reminder email because the user’s spam filter treated the email as spam.

If an email is treated as spam mostly depends on the spam filter being used and its settings. A spam filter usually checks the sender address and the email subject and content, so there are ways and means to influence how they treat your LimeSurvey invitation and reminder emails.

At [http://www.limesurvey-consulting.com/how-to-prevent-limesurvey-email-invitations-or-reminders-being-treated-as-spam/ this blog post] on limesurvey-consulting.com a lot of possible issues and solutions are listed.

===Wrong domain in invitation/reminder email link===

LimeSurvey automatically tries to determine the URL for the invitation link by looking at the URL by which you logged in to the LimeSurvey administration. However with some server (mis-)configurations this might not work properly and you will have to set this manually.

You can edit application/config/config.php to change the default base URL value. Add hostInfo property like this to the existing 'components' array.

<syntaxhighlight lang="php" enclose="div"> 'components' => array(
...
'request' => array(
'hostInfo' => 'http://www.example.com',
),
)
</syntaxhighlight>

Regarding the source of the problem: LimeSurvey tried to determine the domain from the server PHP variable $_SERVER<nowiki>[</nowiki>'HTTP_HOST'] or $_SERVER<nowiki>[</nowiki>'SERVER_NAME'].

Some web server software do not properly seem to provide this information or are mis-configured.

= Enregistrement public=

==Permettre l'enregistrement public==

Vous pouvez vouloir ouvrir votre questionnaire à tous mais avoir le système de contrôle utilisable avec les invitations. Ceci est possible : si vous initialiser la table des invitations et que vous choisissez OUI à Permettre l'enregistrement public? dans les paramètres du questionnaire alors les répondants vont pouvoir s'inscrire avant de répondre à votre questionnaire. Aprèsn s'éêtre inscrit, il recevront une adresse URL pour remplir le questionnaire.

Tous les codes d'invitations provenant d'un enregistrement public commence par la lettre R.

==Les 'captchas' dans l'enregistrement public==

Pour protéger votre sondage d'inscription par des robits, il y a une fonction de 'captcha' pour l'enregistrement, la sauvegardez et le chargelent des questionnaires (à partir de la version 1.48). Cette fonctionnalité n'est disponible que si vous avez le support GD d'activé dans votre configuration de PHP (voir [[Installation|Prérequis d'Installation]] ).

Translations:Survey participants/19/fr

2014-04-06T21:43:12Z

Courtm:

{IMG(attId="85",imalign="center")}
*'''Nombres de jetons''': Nombre de codes d'invitations à ajouter. Par défaut à 100.
*'''Longueur du code''': Nombre de caractères ou la longueur des codes d'invitations. Par défaut à 15.
*'''Prénom et Nom''': .. des participants.
*'''Couriel''': l'adresse de courriel des participants
*'''Langue''': Si vous voulez configurer la langue par défaut pour ce participant.
*'''Utilisations restantes''': compteur du nombre de fois ou le code pourra être utilisé
*'''Valable à partir de & jusqu'à''' : la plage de date / l'heure où les codes pourront être utilisés.
*'''Attribute 1 to Attribute X''': Champs d'attribut définissables par l’administrateur

Survey participants/fr

2014-04-06T21:42:08Z

Courtm:

<languages /> __TOC__

<div class="simplebox">'''Remarque''': Le système des invitations a beaucoup changé depuis la version 1.85 et versions ultérieures. Donc, si vous utilisez une version antérieure, il y aura des différences entre votre version et la documentation. Nous vous recommandons de mettre à niveau dès que possible.</div>

=Introduction=

En de nombreuses occasions, vous voulez inviter un groupe de personnes pour participer à votre sondage, garder la trace des répondants ayant terminé le sondage, et vous assurer que chaque personne ne peut participer qu'une seule fois. Le système des invitations vous permet d'effectuer les opérations suivantes:
*Créez manuellement des invitations (nom, adresse email, ...)
*Importer une liste de noms et d'adresses email pour les participants (à partir d'un fichier CSV ou une interrogations LDAP)
*Ajouter / Supprimer des invitations
*Générer un numéro unique pour le jeton de chaque participant (code d'invitation)
*Envoyez une invitation par courriel à chaque personne de votre liste, par groupe ou individuellement
*Envoyer un courriel de rappel à chaque personne de votre liste qui n'a pas encore répondu, par groupe ou individuellement
*Suivi les répondants de votre liste qui ont répondu
*Interdire l'accès aux personnes qui n'ont pas de ceode d'invitation, et ceux qui ont déjà répondu
*Modifier / changer tous les détails dans votre liste d'invitation

Une fois le questionnaire en accès restreint (vous avez activé les invitations pour ce questionnaire), alors '''seules les personnes avec une invitation valide (pas encore utilisée) peuvent accéder au questionnaire'''.

Si vous activez ''Permettre l'enregistrement public ?'' dans les propriétés du questionnaire, les participants pourront s'inscrire à votre sondage et avoir leur code d'invitation personnel généré automatiquement.

{{Hint|Text=Some token settings are set in survey settings, see [[Creating a new survey#Tokens]]}}

==Est-ce qu'une sondage utilisant les invitations peut assurer des réponses anonymes?==

La réponse à cette question est '''Oui'''. Les invitations peuvent être utilisées tant pour les sondages anonymes que non anonymes. Ceci est déterminé lors de la création du questionnaire. Si un questionnaire n'est pas anonyme (ou 'suivi') alors le code d'invitation peut être utilisé pour trouver les réponses que le répondant a faites au questionnaire. Si le sondage est anonyme, alors aucun lien n'est disponible entre la table des invitations et la table des réponses (techniquement: pas de relation de clé étrangère).

=Comment activer les invitations ?=

Il y a deux manières d'activer les invitations:
#Juste après l'activation du questionnaire, il vous sera demandé si vous souhaitez activer les invitations: {IMG(attId="84",imalign="center")}
# '''Ou''' vous pouvez cliquer sur le symbole de gestion des invitations [[File:tokens.png]] - avant même que le sondage soit activé.

=Les outils de contrôle des invitations=

[[File:token-menu2.png]]

Après la création de la table des invitations, vous pouvez cliquer sur l'icône pour administrer les codes d'invitation. Voici un bref aperçu des options de menu de l'écran de gestion des invitations:
*'''Administration''': Retourne à l'écran d'administration principal du questionnaire
*'''Résumé''': Affiche un résumé des invitations de la table nombre de codes d'invitation, nombre d'invitation envoyée, et nombre de réponse. Permet également d'accéder aux fonctions de d'administration de la base de données voir ci-dessous. C'est l'écran par défaut.
*'''Parcourir''': Affiche la liste complète des participants de la table des invitations. Depuis l'écran d'affichage, vous pouvez modifier ou supprimer des entrées individuelles dans la table ainsi qu'un certain nombre d'autres fonctions utiles voir la section Parcourir ci-dessous
*'''Ajouter une nouvelle invitation''': Permet d'ajouter une entrée à la table des invitations
*'''Ajouter des codes factices''': Permet d'ajouter une ou plusieurs codes d'invitations à la table des invitations trèsb rapidement.
*'''Gérer les champs des attributs supplémentaire:''': Permet d'ajouter des champs supplémentaires à la table des invitations pour stocker des données personnalisées liés aux participants
*'''Importer à partir d'un CSV''': Permet d'importer les informations des invitations depuis un fichier CSV
*'''Importer à partir de LDAP''': Permet d'importer les informations d'une requête LDAP testé sur openLDAP, mais devrait fonctionner dans tous annuaire compatible LDAP, dont ActiveDirectory.
*'''Export les invitations vers un fichier CSV''': Crée un fichier standard CSV (délimité par des virgules) avec la liste complète des participants de la table des invitations en cours.
*'''Éditer les modèles de courriel''': Pour personnaliser les textes et contenus utilisés pour les invitations, les rappels, confirmations, et les courriels d'inscription.
*'''Envoyer les courriels d'invitation''': Envoi global des invitations par courriel à tous les participants de la table des invitations qui n'ont pas déjà reçu une invitation.
*'''Envoyer les courriels de rappel''': Envoi global des courriels de rappel à tous les participants ayant reçu une invitation et n'ayant pas encore répondu.
*'''Générer les codes''': Crée les codes d'invitation uniques pour toutes les entrées individuelles de la table des invitations qui n'en disposent pas encore.
*'''Effacer la tabe des inviations''': Supprimer la table des invitations et passer le questionnaire en accès libre ou ouvert.
*'''Paramètres de rejet''': Paramètrage du courriel recevant les courriels de rejet. Ces paramètres peuvent être modifié à ce niveau ou au niveau général. Ce dispositif a été ajouté dans la version 1.91.

=Modification et ajout d'une invitation=

Une entrée typique d'invitation contient les champs suivants:

{IMG(attId="83",imalign="center")}
*'''Prénom et Nom''' : ... du participant (peut être utilisé dans les courriels et les questionnaires).
*'''Courriel''': l'adresse courriel du participant
*'''Statut du courriel''': un champ pour conserver une trace des mauvaises adresses de courriels. Par exemple, si l'administrateur du sondage ont reçu des notifications d'erreur par courriel à partir de ce courriel, ce qu'il peut définir ce champ à autre chose que 'OK' (par exemple 'utilisateur inconnu', ou 'quota dépassé'). Le marquage cette invitation avec un autre statut que 'OK', permettra d'ignorer cette entrée lors de l'envoi d'invitation ou de couriel de rappel. Notez que ceci est entièrement manuel à moins vous décidez de mettre en place un script qui met à jour ce champ automatiquement.
*'''Code''': c'est le code de l'invitation. Il est généralement généré automatiquement avec le bouton 'Générer les codes d'invitations'.
*'''Langue''': pour configurer la langue par défaut pour ce participant.
*'''Invitation envoyée?''': par défaut a 'N', sinon contient la date à laquelle l'invitation a été envoyée par courriel.
*'''Rappel envoyé?''': par défaut a 'N', sinon contient la date à laquelle le rappel a été envoyée par courriel.
*'''Complété?''': par défaut a 'N', sinon contient la date à laquelle le questionnaire a était validé pour les questionnaire non anonyme ou Y pour les questionnaires anonyme.
*'''Utilisations restantes''': compteur du nombre de fois que le code d'invitation peut être utilisé.
*'''Valable à partir de & Valide jusqu'à''' : Vous pouvez définir une plage de date/heure durant laquelle ce code d'invitation pourra être utilisé. Vous pouvez laisser ces champs vides si vous ne souhaitez pas limiter les dates pour certains utilisateurs. Remarque: Si l'utilisateur répond au questionnaire au moment ou la date arrive à échéance, l'invitation est verrouillé immédiatement, le répondant ne pourra pas terminer le sondage.
*'''Attribute 1 to Attribute X''': Ce sont les champs d'attribut définissables par administrateur - voir ci dessous.

=Codes factices=

Le système des codes factices a été ajouté à partir de la version 1.91.

{IMG(attId="85",imalign="center")}
*'''Nombres de jetons''': Nombre de codes d'invitations à ajouté. Par défaut à 100.
*'''Longueur du code''': Nombre de caractères ou la longueur des codes d'invitations. Par défaut à 15.
*'''Prénom et Nom''': .. des participants.
*'''Couriel''': l'adresse de courriel des participants
*'''Langue''': Si vous voulez configurer la langue par défaut pour ce participant.
*'''Utilisations retantes''': compteur du nombre de fois ou le code pourra être utilisé
*'''Valable à partir de & jusqu'à''' : la plage de date / l'heure où les codes pourront être utilisé.
*'''Attribute 1 to Attribute X''': Champs d'attribut définissables par l'adminitrateur

Veuillez noter que le nom, l'adresse de courriel, la langue seront fixés à la même valeur pour tous les codes factices.

=Bounce Settings{{NewIn|1.91}}=

Please also check out the [[Email bounce tracking system]] page for more information how to correctly configure this feature.

[[File:surveyBounseSettings.png]]
*'''Survey bounce email''': A valid email address for return mail. For faster bounce back processing, this email box should be limited to bounce back only.
*'''Bounce settings to be used''': There are three options: 1- None (default) - no bounce back processing, 2- Use settings below - Will set bounce back processing at the survey level, or 3- Use global settings -- Settings based on the system level.
*'''Server type''': Three options: 1- Off, 2- IMAP or 3- POP
*'''Server name & port''': Host name and port number. Port number isn't typically needed unless the email host uses a non-standard port. Example: mail.example.net:25 or imap.gmail.com:995
*'''User name''': User Name or User ID of the email account
*'''Password''': password of the email account
*'''Encryption type''': Three options: 1- None (default), 2- SSL, or 3- TLS

=Champs des attributs personnalisés=

It is possible to add a number of additional fields to the tokens table to save additional data for a participant. By clicking on the [[File:token_manage.png]] icon you can manage these fields. You can add more attribute fields (by default they have a a length of 255 chars) and also set descriptions for each field - so they look nicer in the administration, when you browse tokens, when creating [[Setting conditions|conditions]] based on attribute fields or even when you export results for non-anonymous surveys.

Il est possible d'ajouter un certains nombre de champs supplémentaires à la table des invitations pour enregistrer des données supplémentaires concernant les participants. En cliquant sur l'icône [[File:token_manage.png]], vous pouvez gérer ces champs. Vous pouvez ajouter des champs d'attributs (par défaut, ils ont une longueur de 255 caractères) et des descriptions pour chaque champ - pour qu'ils soient plus explicite dans l'interface d'administration, lorsque vous consultez la tables des invitations, ou loirs de conditions basées sur des attributs ou lorsque vous exportez un questionnaire non anonyme.

=Utilisation de l'écran d'affichage des invitations et édition des réponses=

L'écran d'affichage montre une liste de toutes les entrées de la table des invitations, ainsi que des boutons d'action pour effectuer des tâches spécifiques sur une entrée individuelle.

La ligne du haut du tableau est composée de 3 parties: celle de droite permet de sélectionner le nombre de lignes affichées, ainsi que le point de départ; au centre un formulaire de recherche; les boutons sur le coté gauche permettent de naviguer dans la liste.

La deuxième ligne de la table comprend le nom du champ, et une flèche verte qui - s'il est cliqué - permet de trier par rapport à ce champs.

La colonne "Actions" donne une liste de tâches spécifiques qui peuvent être effectuées sur cette entrée individuelle:

[[File:token-actions.png]]
*Lancer le questionnaire pour cette invitation
*Éditer cette invitation
*Supprimer cette invitation
*Envoyer un courriel d'invitation ou de rappel à cette netrée
*Si le questionnaire est non-anonyme, un bouton supplémentaire apparait pour visualiser la réponse correspondante.

=Administration de la base de donnée=

[[File:token-summary.png]][[File:token-db-mgt.png]]

{IMG(attId="91",imalign="center")}

En plus d'afficher un bref résumé de l'état de votre table d'invitation, l'écran d'accueil vous permet aussi d'effectuer quelques manipulations sur cette table.
*'''Mettre toutes les invitations à 'Non envoyée'''' Défini l'ensemble des invitations à "Non envoyée" ( à 'N' ). Ne devrait normalment ne pas être utilisé.
*'''Supprimer tous les codes uniques''': Efface tous les codes des invitations, n'efface que les codes, pas les invitations. Ne devrait pas être utilisé en situation normale.
*'''Supprimer toutes les invitations''': Supprime complétement la table d'invitation. Ouvre le sondage aux personnes connaissant l'adresse du questionnaire.

= Import/export des inviations=

== Import via un fichier CSV==

L'import se fait via cet écran

[[File:uploadtoken.jpg]]

Votre fichier CSV doit être à la norme des [http://fr.wikipedia.org/wiki/Comma-separated_values fichiers CSV ('Comma Separated Value')] , c'est à dire séparé par des virgule (,). La première ligne de texte est toujours l'en-tête et sera utilisé pour identifier les colonnes de la table. Les champs de données possibles sont:

firstname,lastname,email,emailstatus,token,language code,tid,attribute_1,attribute_2, attribute_...

Pour obtenir une liste complète des noms de champs de la table d'invitation, vous pouvez exporter une table existante.

Les champs peuvent être dans n'importe quel ordre, mais les colonnes pour le nom, pour le prénom et pour le courriel sont obligatoires. Vous pouvez importer les champs supplémentaire des attributs au même moment.

Un fichier CSV au strict minimum pourrait ressembler à ceci:

firstname,lastname,email
John,Doe,john@doe.net

'''Date format for token import'''

The date format for the "validfrom" and "validuntil" fields in the CSV token inport file is "YYYY-MM-DD HH:MM", e.g.:

2012-01-01 00:00

--would correspond to 1st January, 2012, at 12:00 AM.

'''Filtering duplicates'''

En activant l'option pour filtrer les doublons, vous pouvez définir les champs qui sont utilisés pour identifier les doublons. Par défaut le 'Nom, Prénom et Adresse de Courriel' sont présélectionnés. Si un doublon est trouvé lors de l'importation de la ligne liée est omise.

'''Dépannage pour l'import des invitations'''

A common error when users try to import tokens is an invalid CSV file. This is often caused by Microsoft Excel. Many users have a list of e-mail addresses saved as an XLS document. A file can be saved as CSV in Excel, however, depending on the locale of the OS Microsoft may use semi-colon (;) as the comma separator, while a standard CSV file uses comma (,) as the separator. If not sure just open the file with a standard text editor and check what separator was used. Starting in version 2.00 can you select the used separator during import.

Vous pouvez aussi utiliser [http://fr.libreoffice.org/libreoffice/calc/ Libre Office Calc] pour importer votre fichier xls et exporter un fichier CSV au bon format.

You can use [http://www.libreoffice.org/features/calc/ LibreOffice Calc] to export import your xls file and export your csv file.

'''Add additional attributes at import'''
It is also possible to add new custom attributes when import a CSV file. It is still needed to define what attributes will be added. The way to do this is:
firstname,lastname,email
attribute_1 <Casenr>; token; attribute_2 <Title>; attribute_3 <destination>; lastname; firstname; attribute_4 <Sender>;

== Creating CSV file with Excel on the Mac==

When you create a CSV file with Excel 2011 on the MAC and use the standard "save as" option, you loose special characters such as ü, ë, é etc. when importing into LimeSurvey Token Table.

To make this work properly choose to save the file as a Windows text CSV file (tested on the Dutch version of Excel, saved as "Door lijstscheidingstekens gescheiden Windows tekst (.CSV)").

Then when importing the file in the LimeSurvey token table, under "character set of file" choose "Mac West European". The special characters will be imported correctly.

Testé seulement sur la version 2.0 de LimeSurvey

== Export au format CSV ==

Quand vous exporter votre table au format CSV, les champs sont exportés dans l'ordre suivant:

tid,prénom,nom,email,emailstatus,invitation,langue,code,attribut_1,attribut_2,...

== Import depuis un annuaire LDAP ==

[[File:token-Ldap-import.png]]
* Les requêtes sont définies manuellement par administrateur du système dans le fichier config-ldap.php
* Les doublons sont identifiés par le prénom, le nom et l'adresse de courriel. Si un doublon est trouvé, lors de l'importation la ligne concernée est omise, sauf si vous avez décoché la case de filtre des doublons.

== Un truc pour générer un nombre important de fausses adresses de courriels==

Quelquefois, vous pouvez avoir besoin d'un grand nombre d'adresses de courriel et d'invitations. Vous pouvez utiliser les fonctions de votre tableur ( par exemple OpenOffice Calc) pour les fabriquer. Supposons que vous souhaitiez des milliers d'adresses de courriel de la forme : 1@test.com, 2@test.com,3@test.com,... Vous aller entrer une liste consécutive de nombres dans la colonne A en indiquant à partir de la ligne 2 : =A1+1, ensuite copier/coller A2 autant de fois que vous le souhaitez. Dans la colonne B, en entête, vous indiquez email et à partir de B2: =A2&"@example.org". Vous pouvez ensuite enregistrer ce fichier au format CSV et l'importer dans votre table d'invitation.

Depuis la version 1.91, vous pouvez directement utiliser la génération automatique de code factices.

== Une astuce pour générer un grand nombre de liens individuels incluant l'invitation ==

La structure du lien pour un sondage est la suivante :

Limesurvey 1.x: http://url-vers-votre-installation-limesurvey/index.php?sid=XXXX&lang=fr&token={TOKEN}

Limesurvey 2.x: http://url-vers-votre-installation-limesurvey/index.php/survey/index/sid/xxxx/newtest/Y/lang/FR/token/{TOKEN}

So you proceed similar to the example above for generating email adresses.
*First column: http://url-to-your-limesurvey-installation/index.php?sid=XXXX&lang=en&token= (for version 1.x) OR http://url-to-your-limesurvey-installation/index.php/survey/index/sid/xxxx/newtest/Y/lang/EN/token/ (for version 2.x) (same URL for all, as long as the language is the same!)
*Second column: {TOKEN} (put your tokens here, of course they must be individual)
*Third column: use the CONCATENATE function to join the first column with the second column.

= L'envoi des courriels=

== Les champs réservés des courriels==

Les textes suivants sont autorisés dans des modèles des courriels d'invitation ou de rappel et sont saisi dans les propriétés du sondage. Lors de l'envoi des courriels ces champ seront déjà remplacé dans l'aperçu de votre invitation ou de votre courriel de rappel.

{|
|{ADMINEMAIL}||courriel de l'adminsitrateur
|-
|{ADMINNAME}||Nom de l'administrateur
|-
|{SURVEYNAME}||Titre du questionnaire
|-
|{SURVEYDESCRIPTION}||Description du questionnaire
|}

Les champs suivants sont aussi permis dans les courriels d'invitation ou de rappel et seraont remplacé lors de l'envoi du courriel

{|
|{EMAIL}||Adresse de courriel de l'invité
|-
|{FIRSTNAME}||Prénom
|-
|{LASTNAME}||Nom
|-
|{SURVEYURL}||L'adresse URL pour démarrer le questionnaire - en cas d'envoi au format HTML, ce sera un lien HTML complet
|-
|@@SURVEYURL@@||L'adresse URL pour démarrer le questionnaire au format texte - c'est l'adresse brute. Utilisable dans le corps HTML par exemple (disponible à partie de la version 1.90)
|-
|{TOKEN}||Le code pour accéder au questionnaire
|-
|{ATTRIBUTE_1}||Attribut 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...continuant pour chaque attributs)
|}

If your survey is NOT anonymous, the following field names are available to insert token data in survey text and javascript. You can use these fields in confirmation and notification email template, too.

{|
|{TOKEN:EMAIL}||Adresse de courriel de l'invité
|-
|{TOKEN:FIRSTNAME}||Prénom
|-
|{TOKEN:LASTNAME}||Nom
|-
|{TOKEN}||Le code pour accéder au questionnaire
|-
|{TOKEN:ATTRIBUTE_1}||Attribut 1
|-
|{TOKEN:ATTRIBUTE_2}||Attribut 2 (...continuant pour chaque attributs)
|}

===Additional hints===
*If your survey is using anonymized responses then token-related placeholders will not work in notification email templates.
*You can use [[Expression Manager|Expression Manager]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[Expression Manager HowTos|Expression Manager HowTos]] for an example.
Also have a look at the examples on using [[Adding a question#Information from tokens table|information from tokens table]].

==Paramètres des courriels==
#'''Objet du courriel d'invitation :''': La ligne du sujet de votre courriel d'invitation en cas de table d'invitation.
#'''Courriel d'invitation :''': C'est le texte du courriel d'invitation qui sera envoyé. Il est par défaut rempli par un message d'invitation par défaut ( provenant du fichier de langue). Vous pouvez utiliser les champs suivants pour insérer des informations personnalisées dans chaque courriel.
**'''{FIRSTNAME}''' - sera remplacé par le prénom
**'''{LASTNAME}''' - sera remplacé par le nom
**'''{SURVEYNAME}''' - sera remplacé par le titre du questionnaire
**'''{SURVEYDESCRIPTION}''' - sera remplacé par la description du questionnaire
**'''{ATTRIBUTE_1}''' - sera remplacé par la valeur de l'attribut 1
**'''{ATTRIBUTE_2}''' - sera remplacé par la valeur de l'attribut 2, etc ...
**'''{SURVEYURL}''' - sera remplacé par l'adresse d'accès au sondage en HTML
**'''@@SURVEYURL@@''' - sera remplacé par l'adresse brute d'accès au sondage (à partir de la v1.90)
**'''{OPTOUTURL}''' - sera remplacé par l'adresse peremattant au répondant de se désinscrire (opt-out) du questionnaire

Noter que ses champs reservés sont possible dans les champs des courriels suivant.
#'''Objet du courriel de rappel''': Le sujet du courriel de rappel
#'''Courriel de rappel''': Texte du contenu du courriel de rappel, éventuellement en HTML
#'''Objet du courriel de confirmation''' Quand les invitations sont utilisée, un courriel de confirmation est envoyé au participant à la validation du questionnaire. C'est ici le sujet de ce courriel.
#'''Courriel de confirmation''': Le texte du courriel de confirmation. Effacer ce texte permet de ne pas envoyer de confirmation.
#'''Objet du courriel d'enregistrement public''': C'est le sujet envoyé suite à une inscription sur un questionnaire.
#'''Courriel d'enregistrement public''': C'est le texte du courrier de confirmation envoyé suite à une inscription, il contient le nécessaire pour accède r directement au questionnaire.

==Envoi des courriels==

=== Envoyer les invitations===

{IMG(attId="88",imalign="center")}

Vous pouvez ignorer les invitations pour lesquelles le statut du courriel est différent de "OK", en choisissant "Sauter les invitations avec une adresse de courriel invalide"

==== Renvoyez une invitation====

Quelquefois vous voulez renvoyer des courriels d'invitation à certaines personnes. Quand vous utilisez '''Envoyer les courriels d'invitation''' seules les personnes auxquelles vous n'avez pas encore envoyé d'invitation vont recevoir un courriel.

Vous pouvez donc renvoyer aussi des invitations à des utilisateurs en particulier en éditant leur invitation et en indiquant '''N''' dans la case '''Invitation envoyée?''', en remplaçant la date existante.

==== Désinscription d'un participant (opt-out)====

Lorsque vous utilisez le tag { OPTOUTURL} dans votre courriel d'invitation ou de rappel , vos participants ont la possibilité de se retirer de cette enquête en particulier en cliquant simplement sur cette adresse URL. Cela permet de ne pas harceler les utilisateurs avec des courriels de rappel. Un participant qui a opté de votre enquête aura 'Opt Out' l'état électronique indiquée dans le jeton.

=== Envoi des rapppels===

{IMG(attId="92",imalign="center")}

Quand vous envoyez des rappels, vous pouvez:
*Passer les invitations avec une adresse invalide
*Passer les invitations pour laquelle un courriel a été 'récemment' envoyé.
*Passer les invitations pour lequel un nombre donné de courriels ont déjà été envoyés.

Note: A reminder will only be send to tokens where the "completed" field is not "N" (this means the respondent has either not taken or has not completed the survey).

=== Envoi groupé de courriel===

Quand vous avez un grand nombre de courriel à envoyer en même temps, LimeSurvey va limiter les envois par groupe de N courriel ( ceci est paramétrable dans les options générales, par défaut à 50)

Vous devez cliquer sur suivant jusque ce que l'ensemble des courriels soient envoyés.

=== Courriel de confirmations===

Quand vous utiliser les invitations, un courriel de confirmation lui est envoyé à la validation du questionnaire.

If you don't want this message to be sent, just deactivate this in the General survey settings.

=== Spam problems===

Often users complain not having received an invitation/reminder email because the user’s spam filter treated the email as spam.

If an email is treated as spam mostly depends on the spam filter being used and its settings. A spam filter usually checks the sender address and the email subject and content, so there are ways and means to influence how they treat your LimeSurvey invitation and reminder emails.

At [http://www.limesurvey-consulting.com/how-to-prevent-limesurvey-email-invitations-or-reminders-being-treated-as-spam/ this blog post] on limesurvey-consulting.com a lot of possible issues and solutions are listed.

===Wrong domain in invitation/reminder email link===

LimeSurvey automatically tries to determine the URL for the invitation link by looking at the URL by which you logged in to the LimeSurvey administration. However with some server (mis-)configurations this might not work properly and you will have to set this manually.

You can edit application/config/config.php to change the default base URL value. Add hostInfo property like this to the existing 'components' array.

<syntaxhighlight lang="php" enclose="div"> 'components' => array(
...
'request' => array(
'hostInfo' => 'http://www.example.com',
),
)
</syntaxhighlight>

Regarding the source of the problem: LimeSurvey tried to determine the domain from the server PHP variable $_SERVER<nowiki>[</nowiki>'HTTP_HOST'] or $_SERVER<nowiki>[</nowiki>'SERVER_NAME'].

Some web server software do not properly seem to provide this information or are mis-configured.

= Enregistrement public=

==Permettre l'enregistrement public==

Vous pouvez vouloir ouvrir votre questionnaire à tous mais avoir le système de contrôle utilisable avec les invitations. Ceci est possible : si vous initialiser la table des invitations et que vous choisissez OUI à Permettre l'enregistrement public? dans les paramètres du questionnaire alors les répondants vont pouvoir s'inscrire avant de répondre à votre questionnaire. Aprèsn s'éêtre inscrit, il recevront une adresse URL pour remplir le questionnaire.

Tous les codes d'invitations provenant d'un enregistrement public commence par la lettre R.

==Les 'captchas' dans l'enregistrement public==

Pour protéger votre sondage d'inscription par des robits, il y a une fonction de 'captcha' pour l'enregistrement, la sauvegardez et le chargelent des questionnaires (à partir de la version 1.48). Cette fonctionnalité n'est disponible que si vous avez le support GD d'activé dans votre configuration de PHP (voir [[Installation|Prérequis d'Installation]] ).

Translations:Survey participants/18/fr

2014-04-06T21:42:07Z

Courtm:

Le système des codes factices a été ajouté à partir de la version 1.91.

Upgrading from a previous version/fr

2014-03-26T21:47:39Z

Courtm: Created page with "<div class="simplebox">'''Vérifications après une mise à jour''': *'''depuis n'importe quelle version précédent la 2.xx''': Les '''gabarits''' ont subit de nombreux chang..."

<languages /> <div class="simplebox">La traduction de cette page n'est pas terminée.</div>

=Avant de commencer...=

<span style='color:#FF0000'>... lisez ceci car c'est très important: '''Ne jamais oublier de faire une sauvegarde des fichiers et de la base de données de votre installation actuelle!!'''</span>

Vous pouvez le faire en utilisant les outils d'administration de la base de données comme [http://www.phpmyadmin.net phpMyAdmin] etc. et un gestionnaire de fichiers! Si vous ne savez pas comment procéder pour faire les sauvegardes des fichiers et de la base, alors vous devez demander à quelqu'un de le faire pour vous ou de vous l'apprendre ou alors utilisez la méthode [[ComfortUpdate]] qui est censée tout faire pour vous.

=Méthode rapide (pour les changements mineurs de version)=

You can use these instructions if you are doing a minor upgrade (for example from 2.00 to 2.01)
*Backup your files and database (did we already mention that?)
*Delete all the old files/directory except for
**/application/config/config.php
**/upload directory
*Copy the new files from the new LimeSurvey package to the existing location.
*'''After the upgrade: Clear your browser cache and cookies!'''

=La méthode complète (pour les grands sauts de version)=

Malheureusement il y a quelques petites choses à faire, par conséquent veuillez suivre attentivement les instructions suivantes

==Mettre à jour depuis une version 1.50 ou plus vers n'importe quelle version supérieure à 2.xx ==

<div class="simplebox">'''Vérifications après une mise à jour''':
*'''depuis n'importe quelle version précédent la 2.xx''': Les '''gabarits''' ont subit de nombreux changements. Veuillez vérifier que vos gabarits personnels continuent à vous convenir. Sinon vous devez les ré-éditer (vérifier par rapport aux gabarits originaux ce qui a changé). Le processus de mise à jour tente de remplacer l'inclusion de template.js par l'espace réservé {TEMPLATEJS}. Si vous avez des problèmes javascript avec vos gabarits personnels, vérifier si votre gabarit a l'espace réservé {TEMPLATEJS} dans startpage.pstpl.
*'''depuis une version précédent la v1.53''': Lors de la mise à jour depuis une version antérieure à la 1.53 vers la dernière version, vérifier les '''droit globaux de l'utilisateur''' de chaque utilisateur. Il y a un nouveau droit '''superadmin''' introduit dans la version 1.53 qui peut donner à un utilisateur les mêmes droits que le compte d'administrateur créé pendant l'installation. Le script de mise à jour devine à qui donner ces droits dans l'ancienne version. Comme il n'est pas parfait, le résultat doit être soigneusement vérifié.

==Upgrading from version 1.50 or later to any later 1.xx version==
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.
# Prepare and backup the old installation
## Backup your installation directory files and SQL-based database just in case.
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory
### Using phpMyAdmin or similar to export all tables; or using the '''LimeSurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.
# Replace all the installation directory files
## Delete all old files in the existing installation directory
## Upload and unpack the new code version into the same installation directory
## Edit or replace the '''config.php''' file:
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.
## Copy your /upload directory back to the old location
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [[Installation#Set Directory permissions|Installation]]
# Finishing the installation
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script
## Check if any special, manual checks apply as listed below
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!

<div class="simplebox">'''Special checks after an upgrade''':
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div>

==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==

Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.

=Upgrade FAQ=

==What is the most actual LimeSurvey version that still supports PHP4?==

The last release offering PHP4 support was version 1.82+.

==Can I upgrade even if I have active surveys?==

Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.

==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==

Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.

Translations:Upgrading from a previous version/10/fr

2014-03-26T21:47:38Z

<div class="simplebox">'''Vérifications après une mise à jour''':
*'''depuis n'importe quelle version précédent la 2.xx''': Les '''gabarits''' ont subit de nombreux changements. Veuillez vérifier que vos gabarits personnels continuent à vous convenir. Sinon vous devez les ré-éditer (vérifier par rapport aux gabarits originaux ce qui a changé). Le processus de mise à jour tente de remplacer l'inclusion de template.js par l'espace réservé {TEMPLATEJS}. Si vous avez des problèmes javascript avec vos gabarits personnels, vérifier si votre gabarit a l'espace réservé {TEMPLATEJS} dans startpage.pstpl.
*'''depuis une version précédent la v1.53''': Lors de la mise à jour depuis une version antérieure à la 1.53 vers la dernière version, vérifier les '''droit globaux de l'utilisateur''' de chaque utilisateur. Il y a un nouveau droit '''superadmin''' introduit dans la version 1.53 qui peut donner à un utilisateur les mêmes droits que le compte d'administrateur créé pendant l'installation. Le script de mise à jour devine à qui donner ces droits dans l'ancienne version. Comme il n'est pas parfait, le résultat doit être soigneusement vérifié.

Upgrading from a previous version/fr

2014-03-26T21:31:31Z

Courtm: Created page with "==Mettre à jour depuis une version 1.50 ou plus vers n'importe quelle version supérieure à 2.xx =="

<languages /> <div class="simplebox">La traduction de cette page n'est pas terminée.</div>

=Avant de commencer...=

<span style='color:#FF0000'>... lisez ceci car c'est très important: '''Ne jamais oublier de faire une sauvegarde des fichiers et de la base de données de votre installation actuelle!!'''</span>

Vous pouvez le faire en utilisant les outils d'administration de la base de données comme [http://www.phpmyadmin.net phpMyAdmin] etc. et un gestionnaire de fichiers! Si vous ne savez pas comment procéder pour faire les sauvegardes des fichiers et de la base, alors vous devez demander à quelqu'un de le faire pour vous ou de vous l'apprendre ou alors utilisez la méthode [[ComfortUpdate]] qui est censée tout faire pour vous.

=Méthode rapide (pour les changements mineurs de version)=

You can use these instructions if you are doing a minor upgrade (for example from 2.00 to 2.01)
*Backup your files and database (did we already mention that?)
*Delete all the old files/directory except for
**/application/config/config.php
**/upload directory
*Copy the new files from the new LimeSurvey package to the existing location.
*'''After the upgrade: Clear your browser cache and cookies!'''

=La méthode complète (pour les grands sauts de version)=

Malheureusement il y a quelques petites choses à faire, par conséquent veuillez suivre attentivement les instructions suivantes

==Mettre à jour depuis une version 1.50 ou plus vers n'importe quelle version supérieure à 2.xx ==

<div class="simplebox">'''Special checks after an upgrade''':
*'''from any earlier version to 2.xx''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed). The upgrade process tries to replace the template.js inclusion by the placeholder {TEMPLATEJS}. If you have javascript issue with your custom template, verify if your template have the placeholder {TEMPLATEJS} in startpage.pstpl.
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div>

==Upgrading from version 1.50 or later to any later 1.xx version==
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.
# Prepare and backup the old installation
## Backup your installation directory files and SQL-based database just in case.
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory
### Using phpMyAdmin or similar to export all tables; or using the '''LimeSurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.
# Replace all the installation directory files
## Delete all old files in the existing installation directory
## Upload and unpack the new code version into the same installation directory
## Edit or replace the '''config.php''' file:
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.
## Copy your /upload directory back to the old location
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [[Installation#Set Directory permissions|Installation]]
# Finishing the installation
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script
## Check if any special, manual checks apply as listed below
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!

<div class="simplebox">'''Special checks after an upgrade''':
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div>

==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==

Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.

=Upgrade FAQ=

==What is the most actual LimeSurvey version that still supports PHP4?==

The last release offering PHP4 support was version 1.82+.

==Can I upgrade even if I have active surveys?==

Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.

==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==

Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.

Translations:Upgrading from a previous version/9/fr

2014-03-26T21:31:30Z

Courtm: Created page with "==Mettre à jour depuis une version 1.50 ou plus vers n'importe quelle version supérieure à 2.xx =="

==Mettre à jour depuis une version 1.50 ou plus vers n'importe quelle version supérieure à 2.xx ==

Upgrading from a previous version/fr

2014-03-26T21:29:52Z

Courtm: Created page with "Malheureusement il y a quelques petites choses à faire, par conséquent veuillez suivre attentivement les instructions suivantes"

<languages /> <div class="simplebox">La traduction de cette page n'est pas terminée.</div>

=Avant de commencer...=

<span style='color:#FF0000'>... lisez ceci car c'est très important: '''Ne jamais oublier de faire une sauvegarde des fichiers et de la base de données de votre installation actuelle!!'''</span>

Vous pouvez le faire en utilisant les outils d'administration de la base de données comme [http://www.phpmyadmin.net phpMyAdmin] etc. et un gestionnaire de fichiers! Si vous ne savez pas comment procéder pour faire les sauvegardes des fichiers et de la base, alors vous devez demander à quelqu'un de le faire pour vous ou de vous l'apprendre ou alors utilisez la méthode [[ComfortUpdate]] qui est censée tout faire pour vous.

=Méthode rapide (pour les changements mineurs de version)=

You can use these instructions if you are doing a minor upgrade (for example from 2.00 to 2.01)
*Backup your files and database (did we already mention that?)
*Delete all the old files/directory except for
**/application/config/config.php
**/upload directory
*Copy the new files from the new LimeSurvey package to the existing location.
*'''After the upgrade: Clear your browser cache and cookies!'''

=La méthode complète (pour les grands sauts de version)=

Malheureusement il y a quelques petites choses à faire, par conséquent veuillez suivre attentivement les instructions suivantes

==Upgrading from version 1.50 or later to any later 2.xx version==
#[http://www.limesurvey.org/download Download] the latest version of LimeSurvey.
# Prepare and backup the old installation
## Backup your installation directory files and SQL-based database just in case.
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. For example in Linux tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory.
### Using phpMyAdmin or similar to export all tables; or use the according '''LimeSurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database
## Copy your '''config.php''' file, modified '''template''' directories and the /upload directory separately for quick access later.
# Replace all the installation directory files
## Delete all old files in the existing installation directory
## Upload and unpack the new code version into the same installation directory
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.
## Copy your /upload directory back to the old location
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [[Installation#Set_Directory_permissions|Installation]]
## Open http://<yourdomain>/<yourlimesurveydir>/admin in your browser and follow the instructions (you can use the old config.php as reference). The existing database will be automatically detected and , if necessary, upgraded after confirmation.
# Check if any special manual checks apply as listed below
# '''Now clear your browser cache and cookies!'''
# You are done (:biggrin:).

<div class="simplebox">'''Special checks after an upgrade''':
*'''from any earlier version to 2.xx''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed). The upgrade process tries to replace the template.js inclusion by the placeholder {TEMPLATEJS}. If you have javascript issue with your custom template, verify if your template have the placeholder {TEMPLATEJS} in startpage.pstpl.
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div>

==Upgrading from version 1.50 or later to any later 1.xx version==
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.
# Prepare and backup the old installation
## Backup your installation directory files and SQL-based database just in case.
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory
### Using phpMyAdmin or similar to export all tables; or using the '''LimeSurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.
# Replace all the installation directory files
## Delete all old files in the existing installation directory
## Upload and unpack the new code version into the same installation directory
## Edit or replace the '''config.php''' file:
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.
## Copy your /upload directory back to the old location
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [[Installation#Set Directory permissions|Installation]]
# Finishing the installation
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script
## Check if any special, manual checks apply as listed below
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!

<div class="simplebox">'''Special checks after an upgrade''':
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div>

==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==

Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.

=Upgrade FAQ=

==What is the most actual LimeSurvey version that still supports PHP4?==

The last release offering PHP4 support was version 1.82+.

==Can I upgrade even if I have active surveys?==

Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.

==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==

Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.

Translations:Upgrading from a previous version/8/fr

2014-03-26T21:29:52Z

Courtm: Created page with "Malheureusement il y a quelques petites choses à faire, par conséquent veuillez suivre attentivement les instructions suivantes"

Malheureusement il y a quelques petites choses à faire, par conséquent veuillez suivre attentivement les instructions suivantes

Global settings/fr

2014-03-26T21:22:27Z

Courtm:

<languages />
__TOC__

=Description générale=

Si vous cliquez sur l'icône [[File:global.png]] dans la barre d'outils principale vous arriverez sur les paramètres généraux. L'accès aux paramètres généraux est réservé aux utilisateurs avec des droits de "Super administrateur". Ceux-ci peuvent permettre d'ajuster certains réglages de LimeSurvey d'une manière globale. Dans les versions antérieures à 1.87, ces [[réglages optionnels]] n'étaient disponibles qu'en modifiant le fichier config.php ou config-default.php. Depuis la version 1.87, les valeurs dans ces fichiers sont simplement les valeurs utilisées par défaut. Une fois que vous serez entré dans l'écran des paramètres généraux et que vous aurez fait une première sauvegarde, ces valeurs seront remplacées par celles dans les paramètres généraux

=Paramètres et leurs explications=

==Overview & Update==
*'''System overview''': This is pretty much self explaining. Here you can get a short insight on the number of surveys and other statistics in your LimeSurvey installation. For debug purposes you can also find a button to show your PHP Info.
*'''Updates''':
:[[File:Update_check_settings.jpg]]

:{{Arrow|1}} Vous pouvez paramétrer si, et à quelle fréquence, Limesurvey vérifie la disponibilité de mises à jour. Si une mise à jour est trouvée vous pouvez, soit effectuer la mise à jour manuellement (en téléchargeant le nouveau package de Limesurvey et en suivant les [[Actualiser à partir d'une version précédente|Instructions de mise à jour]]) ou utiliser la fonctionnalité [[ComfortUpdate]]

==General==
*'''Site name''': Donnez un nom à votre questionnaire. Ce nom apparaîtra dans la liste des questionnaires et dans l'en-tête de l'administration.
*'''Default language''': La langue qui sera utilisée par défaut aussi bien pour votre administration de l'enquête que pour le public qui va y répondre si aucune autre langue n'est choisie.
*'''Default template''': Le choix de cette préférence indiquera quel gabarit("template") sera utilisé par les répondants de votre enquête ou questionnaire ainsi que pour l'élaboration des nouveaux questionnaires si aucun autre gabarit n'est choisi.
*'''Default HTML editor mode:''' Spécifie le mode par défaut pour l'éditeur HTML intégré. Les choix possibles sont: éditeur HTML en ligne (default), éditeur HTML dans une popup et aucun:
** ''inline'': Inline replacement of fields by an HTML editor. Lent mais facile et pratique
** ''éditeur HTML dans une popup'': Ajoute une icône permettant d'ouvrir une fenêtre avec l'éditeur HTML. Plus rapide mais le code HTML est affiché on the form.
** ''aucun'': Pas d'éditeur HTML
*'''Time difference (in hours)''': If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia but use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "+14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses.
*'''PDF export available:''' This feature activates the PDF export for the 'Printable survey' feature and data export.
*'''Screen reader compatibility mode''': If this option is set to true, then LimeSurvey will add 'title' html element to all links used in menus. This will help screen reader to analyze the menus. Only set this to true if you're using a screen reader because it overlaps with tool tips.
*'''Session lifetime''': Defines the time in seconds after which a survey session expires (provided there is no action from the participant). The maximum value on this is 65000 (seconds). Please use a reasonable value. Depending on your server configuration LimeSurvey may not be allowed to override the server setting - in that case you have to set the session timeout value in your PHP configuration.

==Paramètre de messagerie==
*'''Default site admin email''': C'est l'adresse par défaut de l'administrateur du site, utilisée pour les messages système et les options de contact.
*'''Administrator name''': Le nom "réel" de l'administrateur du site.
*'''Email method:''' Détermine comment les emails sont envoyés. Les options suivantes sont disponibles:
**'''PHP:''' utilise les fonctions PHP internes
**'''Sendmail:''' utilise sendmail
**'''SMTP:'''utilise un relai smtp. Il faut utiliser cette option si on fait tourner Limesurvey sur une machine qui n'est pas notre serveur de mail.
***Make sure that you are using your SMTP configured e-mail (Global settings -> E-mail settings) at the survey settings (At the moment you create a survey or after you create it Edit Survey Settings -> General) if you use SMTP, otherwise there might be a chance that the following error is displayed: SMTP -> ERROR: RCPT not accepted from server: 553 5.7.1 : Sender address rejected: not owned by user.
**'''Qmail:'''Set this if you are running the Qmail mailer
*'''SMTP host:''' If you use 'SMTP ' as email method then you have to put your SMTP-server here. If you are using a different part than port 25 (standard for SMPT) then you have to add the port number separated be a colon (example: 'smtp.gmail.com:465')
*'''SMTP username:''' If your SMTP-server needs authentication then set this to your user name, otherwise it must be blank.
*'''SMTP password:''' If your SMTP-server needs authentication then set this to your password, otherwise it must be blank.
*'''SMTP SSL/TLS:''' Set this to 'SSL' or 'TLS' to use SSL/TLS for your SMTP connection
*'''SMTP debug mode''': Si vous activer ceci alors au moment d'envoyer les invitations ou les rappels un log détaillé de connection et un message d'erreur (si une erreru se produit) vous sont fournis. Not for the faint of heart, but this can give valuable information why a SMTP relay does not work. Généralement ce switch reste à Off.
*'''Email batch size:''' When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities, and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a PHP script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting. Clicking the 'send email invitation' button on the token control toolbar, (not the button on the right of each token), sends the maxemails number of invitations, then displays a list of the addresses sent to and a warning that "There are more emails pending than could be sent in one batch. Continue sending emails by clicking below. There are ### emails still to be sent." and provides a "continue button" to proceed with the next batch. I.e., the user determines when to send the next batch after each batch gets emailed. It is not necessary to wait with this screen active. The admin could log off and come back at a later time to send the next batch of invites.

==Bounce settings==
*'''Default site bounce email''': This is the email address where bounced emails will be sent to.
*'''Server type''': If set to 'Off' no bounce processing functions will be available. Set this to POP or IMAP to check a related account for bounces.
*'''Server name & port''': Name of the server and (if needed) the port separated by a colon.
*'''User name''': The user name for the POP/IMAP account
*'''Password''': The password for the POP/IMAP account
*'''Encryption type''': If encrpytion is used please set the right one here (SSL or TLS)

==Security==
*'''Survey preview only for administration users''': By default, preview of inactive survey is restricted to authenticated users only. If you set this to 'No' any person can test your survey using the survey URL - without logging in to the administration and without having to activate the survey first.
*'''Filter HTML for XSS''': By default you survey manager will not be authorized to use dangerous HTML tags in their survey/group/question/labels texts (for instance JavaScript code). This is intended to prevent a survey operator to add malicious script in order to have a true admin raise his permissions on the system. '''If you want to use any script objects like Javascript scripts of Flash applets in your surveys you will need to switch this off.'''
*'''Group member can only see own group''': By default non-admin users defined in the LimeSurvey management interface will only be able to see other users if they belong to at least one group this user belongs to. If you set this to 'No' they can see all users (for example in [[Survey security settings]] )
*'''Force HTTPS''': By default this is set to "Don't force on or off". Switch the setting to "on" to force the connection to use HTTPS. '''''Note:''''' If your server doesn't support HTTPS properly, you can lock yourself from the system! Therefor test the "check if this link works" link first. If the link does not work and you turn on HTTPS, LimeSurvey will break and you won't be able to access it.

==Presentation==
*'''Show 'no answer' option for non-mandatory questions''': When a question of a radio button/select type that contains editable answers (i.e.: List & array questions) is not mandatory and this is set to 'Yes' (default), an additional entry 'No answer' is shown for each subquestion - so that participants may choose to not answer the question. Some people prefer this not to be available. Set this to 'No' to turn this off.
*'''Repeating headings in array questions every X subquestions''': With array type question, often you'll have a lot of subquestions, which - when displayed on screen - take up more than one page. The repeat-headers setting lets you decide how many answers should be displayed before repeating the header information for the question. A good setting for this is around 25. If you don't want the headings to repeat at all, set this to 0.
*'''Show "There are X questions in this survey"''':
*'''Show question group name and/or description''':
*'''Show question number and/or question code''':

==Language==
*'''Default site language''': This is the default language to be used in your administration , and also the default language for the public survey list if none is given.
*'''Available languages''': If you don't want all languages to be available in the administration language select boxes you can here define the language that should be available only.

==Interfaces==
*'''RPC interface enabled''': Using this feature you can activate/deactivate the LimeSurvey [[RemoteControl 2 API|RemoteControl2]] interface API, either using JSON-RPC (recommended) or XML-RPC.

Translations:Global settings/13/fr

2014-03-26T21:22:26Z

Courtm:

:{{Arrow|1}} Vous pouvez paramétrer si, et à quelle fréquence, Limesurvey vérifie la disponibilité de mises à jour. Si une mise à jour est trouvée vous pouvez, soit effectuer la mise à jour manuellement (en téléchargeant le nouveau package de Limesurvey et en suivant les [[Actualiser à partir d'une version précédente|Instructions de mise à jour]]) ou utiliser la fonctionnalité [[ComfortUpdate]]

Global settings/fr

2014-03-26T18:00:55Z

Courtm: Created page with "==Paramètre de messagerie== *'''Default site admin email''': C'est l'adresse par défaut de l'administrateur du site, utilisée pour les messages système et les options de c..."

<languages />
__TOC__

=Description générale=

Si vous cliquez sur l'icône [[File:global.png]] dans la barre d'outils principale vous arriverez sur les paramètres généraux. L'accès aux paramètres généraux est réservé aux utilisateurs avec des droits de "Super administrateur". Ceux-ci peuvent permettre d'ajuster certains réglages de LimeSurvey d'une manière globale. Dans les versions antérieures à 1.87, ces [[réglages optionnels]] n'étaient disponibles qu'en modifiant le fichier config.php ou config-default.php. Depuis la version 1.87, les valeurs dans ces fichiers sont simplement les valeurs utilisées par défaut. Une fois que vous serez entré dans l'écran des paramètres généraux et que vous aurez fait une première sauvegarde, ces valeurs seront remplacées par celles dans les paramètres généraux

=Paramètres et leurs explications=

==Overview & Update==
*'''System overview''': This is pretty much self explaining. Here you can get a short insight on the number of surveys and other statistics in your LimeSurvey installation. For debug purposes you can also find a button to show your PHP Info.
*'''Updates''':
:[[File:Update_check_settings.jpg]]

:{{Arrow|1}} Vous pouvez paramétrer si, et à quelle fréquence, Limesurvey vérifie la disponibilité de mises à jour. Si une mise à jour est trouvée vous pouvez, soit effectuer la mise à jour manuellement (en téléchargeant le nouveau package de Limesurvey et en suivant les [[Upgrading from a previous version|Update instructions]]) ou utiliser la fonctionnalité [[ComfortUpdate]]

==General==
*'''Site name''': Donnez un nom à votre questionnaire. Ce nom apparaîtra dans la liste des questionnaires et dans l'en-tête de l'administration.
*'''Default language''': La langue qui sera utilisée par défaut aussi bien pour votre administration de l'enquête que pour le public qui va y répondre si aucune autre langue n'est choisie.
*'''Default template''': Le choix de cette préférence indiquera quel gabarit("template") sera utilisé par les répondants de votre enquête ou questionnaire ainsi que pour l'élaboration des nouveaux questionnaires si aucun autre gabarit n'est choisi.
*'''Default HTML editor mode:''' Spécifie le mode par défaut pour l'éditeur HTML intégré. Les choix possibles sont: éditeur HTML en ligne (default), éditeur HTML dans une popup et aucun:
** ''inline'': Inline replacement of fields by an HTML editor. Lent mais facile et pratique
** ''éditeur HTML dans une popup'': Ajoute une icône permettant d'ouvrir une fenêtre avec l'éditeur HTML. Plus rapide mais le code HTML est affiché on the form.
** ''aucun'': Pas d'éditeur HTML
*'''Time difference (in hours)''': If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia but use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "+14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses.
*'''PDF export available:''' This feature activates the PDF export for the 'Printable survey' feature and data export.
*'''Screen reader compatibility mode''': If this option is set to true, then LimeSurvey will add 'title' html element to all links used in menus. This will help screen reader to analyze the menus. Only set this to true if you're using a screen reader because it overlaps with tool tips.
*'''Session lifetime''': Defines the time in seconds after which a survey session expires (provided there is no action from the participant). The maximum value on this is 65000 (seconds). Please use a reasonable value. Depending on your server configuration LimeSurvey may not be allowed to override the server setting - in that case you have to set the session timeout value in your PHP configuration.

==Paramètre de messagerie==
*'''Default site admin email''': C'est l'adresse par défaut de l'administrateur du site, utilisée pour les messages système et les options de contact.
*'''Administrator name''': Le nom "réel" de l'administrateur du site.
*'''Email method:''' Détermine comment les emails sont envoyés. Les options suivantes sont disponibles:
**'''PHP:''' utilise les fonctions PHP internes
**'''Sendmail:''' utilise sendmail
**'''SMTP:'''utilise un relai smtp. Il faut utiliser cette option si on fait tourner Limesurvey sur une machine qui n'est pas notre serveur de mail.
***Make sure that you are using your SMTP configured e-mail (Global settings -> E-mail settings) at the survey settings (At the moment you create a survey or after you create it Edit Survey Settings -> General) if you use SMTP, otherwise there might be a chance that the following error is displayed: SMTP -> ERROR: RCPT not accepted from server: 553 5.7.1 : Sender address rejected: not owned by user.
**'''Qmail:'''Set this if you are running the Qmail mailer
*'''SMTP host:''' If you use 'SMTP ' as email method then you have to put your SMTP-server here. If you are using a different part than port 25 (standard for SMPT) then you have to add the port number separated be a colon (example: 'smtp.gmail.com:465')
*'''SMTP username:''' If your SMTP-server needs authentication then set this to your user name, otherwise it must be blank.
*'''SMTP password:''' If your SMTP-server needs authentication then set this to your password, otherwise it must be blank.
*'''SMTP SSL/TLS:''' Set this to 'SSL' or 'TLS' to use SSL/TLS for your SMTP connection
*'''SMTP debug mode''': Si vous activer ceci alors au moment d'envoyer les invitations ou les rappels un log détaillé de connection et un message d'erreur (si une erreru se produit) vous sont fournis. Not for the faint of heart, but this can give valuable information why a SMTP relay does not work. Généralement ce switch reste à Off.
*'''Email batch size:''' When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities, and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a PHP script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting. Clicking the 'send email invitation' button on the token control toolbar, (not the button on the right of each token), sends the maxemails number of invitations, then displays a list of the addresses sent to and a warning that "There are more emails pending than could be sent in one batch. Continue sending emails by clicking below. There are ### emails still to be sent." and provides a "continue button" to proceed with the next batch. I.e., the user determines when to send the next batch after each batch gets emailed. It is not necessary to wait with this screen active. The admin could log off and come back at a later time to send the next batch of invites.

==Bounce settings==
*'''Default site bounce email''': This is the email address where bounced emails will be sent to.
*'''Server type''': If set to 'Off' no bounce processing functions will be available. Set this to POP or IMAP to check a related account for bounces.
*'''Server name & port''': Name of the server and (if needed) the port separated by a colon.
*'''User name''': The user name for the POP/IMAP account
*'''Password''': The password for the POP/IMAP account
*'''Encryption type''': If encrpytion is used please set the right one here (SSL or TLS)

==Security==
*'''Survey preview only for administration users''': By default, preview of inactive survey is restricted to authenticated users only. If you set this to 'No' any person can test your survey using the survey URL - without logging in to the administration and without having to activate the survey first.
*'''Filter HTML for XSS''': By default you survey manager will not be authorized to use dangerous HTML tags in their survey/group/question/labels texts (for instance JavaScript code). This is intended to prevent a survey operator to add malicious script in order to have a true admin raise his permissions on the system. '''If you want to use any script objects like Javascript scripts of Flash applets in your surveys you will need to switch this off.'''
*'''Group member can only see own group''': By default non-admin users defined in the LimeSurvey management interface will only be able to see other users if they belong to at least one group this user belongs to. If you set this to 'No' they can see all users (for example in [[Survey security settings]] )
*'''Force HTTPS''': By default this is set to "Don't force on or off". Switch the setting to "on" to force the connection to use HTTPS. '''''Note:''''' If your server doesn't support HTTPS properly, you can lock yourself from the system! Therefor test the "check if this link works" link first. If the link does not work and you turn on HTTPS, LimeSurvey will break and you won't be able to access it.

==Presentation==
*'''Show 'no answer' option for non-mandatory questions''': When a question of a radio button/select type that contains editable answers (i.e.: List & array questions) is not mandatory and this is set to 'Yes' (default), an additional entry 'No answer' is shown for each subquestion - so that participants may choose to not answer the question. Some people prefer this not to be available. Set this to 'No' to turn this off.
*'''Repeating headings in array questions every X subquestions''': With array type question, often you'll have a lot of subquestions, which - when displayed on screen - take up more than one page. The repeat-headers setting lets you decide how many answers should be displayed before repeating the header information for the question. A good setting for this is around 25. If you don't want the headings to repeat at all, set this to 0.
*'''Show "There are X questions in this survey"''':
*'''Show question group name and/or description''':
*'''Show question number and/or question code''':

==Language==
*'''Default site language''': This is the default language to be used in your administration , and also the default language for the public survey list if none is given.
*'''Available languages''': If you don't want all languages to be available in the administration language select boxes you can here define the language that should be available only.

==Interfaces==
*'''RPC interface enabled''': Using this feature you can activate/deactivate the LimeSurvey [[RemoteControl 2 API|RemoteControl2]] interface API, either using JSON-RPC (recommended) or XML-RPC.

Translations:Global settings/7/fr

2014-03-26T18:00:55Z

==Paramètre de messagerie==
*'''Default site admin email''': C'est l'adresse par défaut de l'administrateur du site, utilisée pour les messages système et les options de contact.
*'''Administrator name''': Le nom "réel" de l'administrateur du site.
*'''Email method:''' Détermine comment les emails sont envoyés. Les options suivantes sont disponibles:
**'''PHP:''' utilise les fonctions PHP internes
**'''Sendmail:''' utilise sendmail
**'''SMTP:'''utilise un relai smtp. Il faut utiliser cette option si on fait tourner Limesurvey sur une machine qui n'est pas notre serveur de mail.
***Make sure that you are using your SMTP configured e-mail (Global settings -> E-mail settings) at the survey settings (At the moment you create a survey or after you create it Edit Survey Settings -> General) if you use SMTP, otherwise there might be a chance that the following error is displayed: SMTP -> ERROR: RCPT not accepted from server: 553 5.7.1 : Sender address rejected: not owned by user.
**'''Qmail:'''Set this if you are running the Qmail mailer
*'''SMTP host:''' If you use 'SMTP ' as email method then you have to put your SMTP-server here. If you are using a different part than port 25 (standard for SMPT) then you have to add the port number separated be a colon (example: 'smtp.gmail.com:465')
*'''SMTP username:''' If your SMTP-server needs authentication then set this to your user name, otherwise it must be blank.
*'''SMTP password:''' If your SMTP-server needs authentication then set this to your password, otherwise it must be blank.
*'''SMTP SSL/TLS:''' Set this to 'SSL' or 'TLS' to use SSL/TLS for your SMTP connection
*'''SMTP debug mode''': Si vous activer ceci alors au moment d'envoyer les invitations ou les rappels un log détaillé de connection et un message d'erreur (si une erreru se produit) vous sont fournis. Not for the faint of heart, but this can give valuable information why a SMTP relay does not work. Généralement ce switch reste à Off.
*'''Email batch size:''' When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities, and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a PHP script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting. Clicking the 'send email invitation' button on the token control toolbar, (not the button on the right of each token), sends the maxemails number of invitations, then displays a list of the addresses sent to and a warning that "There are more emails pending than could be sent in one batch. Continue sending emails by clicking below. There are ### emails still to be sent." and provides a "continue button" to proceed with the next batch. I.e., the user determines when to send the next batch after each batch gets emailed. It is not necessary to wait with this screen active. The admin could log off and come back at a later time to send the next batch of invites.

Global settings/fr

2014-03-26T16:26:34Z

Courtm:

<languages />
__TOC__

=Description générale=

Si vous cliquez sur l'icône [[File:global.png]] dans la barre d'outils principale vous arriverez sur les paramètres généraux. L'accès aux paramètres généraux est réservé aux utilisateurs avec des droits de "Super administrateur". Ceux-ci peuvent permettre d'ajuster certains réglages de LimeSurvey d'une manière globale. Dans les versions antérieures à 1.87, ces [[réglages optionnels]] n'étaient disponibles qu'en modifiant le fichier config.php ou config-default.php. Depuis la version 1.87, les valeurs dans ces fichiers sont simplement les valeurs utilisées par défaut. Une fois que vous serez entré dans l'écran des paramètres généraux et que vous aurez fait une première sauvegarde, ces valeurs seront remplacées par celles dans les paramètres généraux

=Paramètres et leurs explications=

==Overview & Update==
*'''System overview''': This is pretty much self explaining. Here you can get a short insight on the number of surveys and other statistics in your LimeSurvey installation. For debug purposes you can also find a button to show your PHP Info.
*'''Updates''':
:[[File:Update_check_settings.jpg]]

:{{Arrow|1}} Vous pouvez paramétrer si, et à quelle fréquence, Limesurvey vérifie la disponibilité de mises à jour. Si une mise à jour est trouvée vous pouvez, soit effectuer la mise à jour manuellement (en téléchargeant le nouveau package de Limesurvey et en suivant les [[Upgrading from a previous version|Update instructions]]) ou utiliser la fonctionnalité [[ComfortUpdate]]

==General==
*'''Site name''': Donnez un nom à votre questionnaire. Ce nom apparaîtra dans la liste des questionnaires et dans l'en-tête de l'administration.
*'''Default language''': La langue qui sera utilisée par défaut aussi bien pour votre administration de l'enquête que pour le public qui va y répondre si aucune autre langue n'est choisie.
*'''Default template''': Le choix de cette préférence indiquera quel gabarit("template") sera utilisé par les répondants de votre enquête ou questionnaire ainsi que pour l'élaboration des nouveaux questionnaires si aucun autre gabarit n'est choisi.
*'''Default HTML editor mode:''' Spécifie le mode par défaut pour l'éditeur HTML intégré. Les choix possibles sont: éditeur HTML en ligne (default), éditeur HTML dans une popup et aucun:
** ''inline'': Inline replacement of fields by an HTML editor. Lent mais facile et pratique
** ''éditeur HTML dans une popup'': Ajoute une icône permettant d'ouvrir une fenêtre avec l'éditeur HTML. Plus rapide mais le code HTML est affiché on the form.
** ''aucun'': Pas d'éditeur HTML
*'''Time difference (in hours)''': If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia but use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "+14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses.
*'''PDF export available:''' This feature activates the PDF export for the 'Printable survey' feature and data export.
*'''Screen reader compatibility mode''': If this option is set to true, then LimeSurvey will add 'title' html element to all links used in menus. This will help screen reader to analyze the menus. Only set this to true if you're using a screen reader because it overlaps with tool tips.
*'''Session lifetime''': Defines the time in seconds after which a survey session expires (provided there is no action from the participant). The maximum value on this is 65000 (seconds). Please use a reasonable value. Depending on your server configuration LimeSurvey may not be allowed to override the server setting - in that case you have to set the session timeout value in your PHP configuration.

==Email settings==
*'''Default site admin email''': This is the default email address of the site administrator and used for system messages and contact options.
*'''Administrator name''': The real name of the site administrator.
*'''Email method:''' This determines how e-mail messages are being sent. The following options are available:
**'''PHP:''' use internal PHP mailer
**'''Sendmail:''' use sendmail mailer
**'''SMTP:'''use SMTP relaying. Use this setting when you are running LimeSurvey on a host that is not your mail server.
***Make sure that you are using your SMTP configured e-mail (Global settings -> E-mail settings) at the survey settings (At the moment you create a survey or after you create it Edit Survey Settings -> General) if you use SMTP, otherwise there might be a chance that the following error is displayed: SMTP -> ERROR: RCPT not accepted from server: 553 5.7.1 : Sender address rejected: not owned by user.
**'''Qmail:'''Set this if you are running the Qmail mailer
*'''SMTP host:''' If you use 'SMTP ' as email method then you have to put your SMTP-server here. If you are using a different part than port 25 (standard for SMPT) then you have to add the port number separated be a colon (example: 'smtp.gmail.com:465')
*'''SMTP username:''' If your SMTP-server needs authentication then set this to your user name, otherwise it must be blank.
*'''SMTP password:''' If your SMTP-server needs authentication then set this to your password, otherwise it must be blank.
*'''SMTP SSL/TLS:''' Set this to 'SSL' or 'TLS' to use SSL/TLS for your SMTP connection
*'''SMTP debug mode''': If you switch this on then on sending invitations or reminders a detailed connection log and error message will be given (if an error occurs). Not for the faint of heart, but this can give valuable information why a SMTP relay does not work. Usually you want this to be off.
*'''Email batch size:''' When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities, and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a PHP script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting. Clicking the 'send email invitation' button on the token control toolbar, (not the button on the right of each token), sends the maxemails number of invitations, then displays a list of the addresses sent to and a warning that "There are more emails pending than could be sent in one batch. Continue sending emails by clicking below. There are ### emails still to be sent." and provides a "continue button" to proceed with the next batch. I.e., the user determines when to send the next batch after each batch gets emailed. It is not necessary to wait with this screen active. The admin could log off and come back at a later time to send the next batch of invites.

==Bounce settings==
*'''Default site bounce email''': This is the email address where bounced emails will be sent to.
*'''Server type''': If set to 'Off' no bounce processing functions will be available. Set this to POP or IMAP to check a related account for bounces.
*'''Server name & port''': Name of the server and (if needed) the port separated by a colon.
*'''User name''': The user name for the POP/IMAP account
*'''Password''': The password for the POP/IMAP account
*'''Encryption type''': If encrpytion is used please set the right one here (SSL or TLS)

==Security==
*'''Survey preview only for administration users''': By default, preview of inactive survey is restricted to authenticated users only. If you set this to 'No' any person can test your survey using the survey URL - without logging in to the administration and without having to activate the survey first.
*'''Filter HTML for XSS''': By default you survey manager will not be authorized to use dangerous HTML tags in their survey/group/question/labels texts (for instance JavaScript code). This is intended to prevent a survey operator to add malicious script in order to have a true admin raise his permissions on the system. '''If you want to use any script objects like Javascript scripts of Flash applets in your surveys you will need to switch this off.'''
*'''Group member can only see own group''': By default non-admin users defined in the LimeSurvey management interface will only be able to see other users if they belong to at least one group this user belongs to. If you set this to 'No' they can see all users (for example in [[Survey security settings]] )
*'''Force HTTPS''': By default this is set to "Don't force on or off". Switch the setting to "on" to force the connection to use HTTPS. '''''Note:''''' If your server doesn't support HTTPS properly, you can lock yourself from the system! Therefor test the "check if this link works" link first. If the link does not work and you turn on HTTPS, LimeSurvey will break and you won't be able to access it.

==Presentation==
*'''Show 'no answer' option for non-mandatory questions''': When a question of a radio button/select type that contains editable answers (i.e.: List & array questions) is not mandatory and this is set to 'Yes' (default), an additional entry 'No answer' is shown for each subquestion - so that participants may choose to not answer the question. Some people prefer this not to be available. Set this to 'No' to turn this off.
*'''Repeating headings in array questions every X subquestions''': With array type question, often you'll have a lot of subquestions, which - when displayed on screen - take up more than one page. The repeat-headers setting lets you decide how many answers should be displayed before repeating the header information for the question. A good setting for this is around 25. If you don't want the headings to repeat at all, set this to 0.
*'''Show "There are X questions in this survey"''':
*'''Show question group name and/or description''':
*'''Show question number and/or question code''':

==Language==
*'''Default site language''': This is the default language to be used in your administration , and also the default language for the public survey list if none is given.
*'''Available languages''': If you don't want all languages to be available in the administration language select boxes you can here define the language that should be available only.

==Interfaces==
*'''RPC interface enabled''': Using this feature you can activate/deactivate the LimeSurvey [[RemoteControl 2 API|RemoteControl2]] interface API, either using JSON-RPC (recommended) or XML-RPC.

Translations:Global settings/6/fr

2014-03-26T16:26:34Z

Courtm:

==General==
*'''Site name''': Donnez un nom à votre questionnaire. Ce nom apparaîtra dans la liste des questionnaires et dans l'en-tête de l'administration.
*'''Default language''': La langue qui sera utilisée par défaut aussi bien pour votre administration de l'enquête que pour le public qui va y répondre si aucune autre langue n'est choisie.
*'''Default template''': Le choix de cette préférence indiquera quel gabarit("template") sera utilisé par les répondants de votre enquête ou questionnaire ainsi que pour l'élaboration des nouveaux questionnaires si aucun autre gabarit n'est choisi.
*'''Default HTML editor mode:''' Spécifie le mode par défaut pour l'éditeur HTML intégré. Les choix possibles sont: éditeur HTML en ligne (default), éditeur HTML dans une popup et aucun:
** ''inline'': Inline replacement of fields by an HTML editor. Lent mais facile et pratique
** ''éditeur HTML dans une popup'': Ajoute une icône permettant d'ouvrir une fenêtre avec l'éditeur HTML. Plus rapide mais le code HTML est affiché on the form.
** ''aucun'': Pas d'éditeur HTML
*'''Time difference (in hours)''': If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia but use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "+14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses.
*'''PDF export available:''' This feature activates the PDF export for the 'Printable survey' feature and data export.
*'''Screen reader compatibility mode''': If this option is set to true, then LimeSurvey will add 'title' html element to all links used in menus. This will help screen reader to analyze the menus. Only set this to true if you're using a screen reader because it overlaps with tool tips.
*'''Session lifetime''': Defines the time in seconds after which a survey session expires (provided there is no action from the participant). The maximum value on this is 65000 (seconds). Please use a reasonable value. Depending on your server configuration LimeSurvey may not be allowed to override the server setting - in that case you have to set the session timeout value in your PHP configuration.

Global settings/fr

2014-03-26T14:53:28Z

Courtm:

<languages />
__TOC__

=Description générale=

Si vous cliquez sur l'icône [[File:global.png]] dans la barre d'outils principale vous arriverez sur les paramètres généraux. L'accès aux paramètres généraux est réservé aux utilisateurs avec des droits de "Super administrateur". Ceux-ci peuvent permettre d'ajuster certains réglages de LimeSurvey d'une manière globale. Dans les versions antérieures à 1.87, ces [[réglages optionnels]] n'étaient disponibles qu'en modifiant le fichier config.php ou config-default.php. Depuis la version 1.87, les valeurs dans ces fichiers sont simplement les valeurs utilisées par défaut. Une fois que vous serez entré dans l'écran des paramètres généraux et que vous aurez fait une première sauvegarde, ces valeurs seront remplacées par celles dans les paramètres généraux

=Paramètres et leurs explications=

==Overview & Update==
*'''System overview''': This is pretty much self explaining. Here you can get a short insight on the number of surveys and other statistics in your LimeSurvey installation. For debug purposes you can also find a button to show your PHP Info.
*'''Updates''':
:[[File:Update_check_settings.jpg]]

:{{Arrow|1}} Vous pouvez paramétrer si, et à quelle fréquence, Limesurvey vérifie la disponibilité de mises à jour. Si une mise à jour est trouvée vous pouvez, soit effectuer la mise à jour manuellement (en téléchargeant le nouveau package de Limesurvey et en suivant les [[Upgrading from a previous version|Update instructions]]) ou utiliser la fonctionnalité [[ComfortUpdate]]

==General==
*'''Site name''': Give your survey site a name. This name will appear in the survey list overview and in the administration header.
*'''Default template''': This setting specifies the default design template used for the 'public list' of surveys and for new surveys or surveys using a non-existing template.
*'''Administration template''': This setting specifies the default design template used for the LimeSurvey administration.
*'''Default HTML editor mode:''' Sets the default mode for integrated HTML editor. Valid settings are: inline (default), popup and none:
** ''inline'': Inline replacement of fields by an HTML editor. Slow but convenient and user friendly
** ''popup'': Adds an icon that opens a popup window with the HTML editor. Faster, but HTML code is displayed on the form.
** ''none'': No HTML editor
*'''Question type selector''': Choose 'Full selector' to get a question type selector with preview and 'Simple' to get a plain select box.
*'''Template editor:''': Choose 'Full template editor' to get a enhanced editor (with syntax-highlighting) when editing survey templates and 'Simple template editor' to get a plain editor field
*'''Time difference (in hours)''': If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia but use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "+14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses.
*'''Session lifetime''': Defines the time in seconds after which a survey session expires (provided there is no action from the participant). The maximum value on this is 65000 (seconds). Please use a reasonable value. This setting is only available when LimeSurvey is configured to store sessions in a database. When using regular, file-based sessions, it is up to the system administrator to define the right values for "session.gc_maxlifetime", "session.save_path", etc. in the PHP configuration. This only sets the lifetime of sessions in surveys, it doesn't affect the administration interface sessions, which have to be configured with PHP configuration in all cases.
*'''IP Info DB API Key''': Allows integration with the IP-Info-DB service that let's you determine the geographic location of survey takers based on their IP.
*'''Google Maps API Key''': Allows for integration with Google Maps.
*'''Google Analytics API Key''': Allows for integration with Google Analytics. Surveys can over-ride this site-level value. The API key can be inserted into templates using {GOOGLE_ANALYTICS_API_KEY}. The full JavaScript that Google Analytics expects (including the key) can be included in templates via {GOOGLE_ANALYTICS_JAVASCRIPT}.
*'''Google API howto''':
# Register/login on Google Analytics (GA): [http://www.google.com/analytics/ www.google.com/analytics/]
# Create a key (the site should not point to the survey, but to the part before 'index.php?') The key should be UA-xxxxx.
# Go to your survey's global settings in LimeSurvey.
# Put the key in appropriate field (Google Analytics API Key). It's probably the best to set GA to track all pages as you can have more info.
# You don't need to do anything in shipped templates, as the {GOOGLE_ANALYTICS_JAVASCRIPT} part is already there.
# Activate the survey.
# Do the survey.
# Go to GA panel mainsite. (select appropriate account in left-hand upper corner if you have more than one). You should see some graphs with the statistics. Beware of the dates in upper right corner.
*'''Google Translate API Key''': As of version 1.92, the Auto Translate feature is now using the new version 2 of Google Translate's API. Google now charges for this service. In order for the Auto Translate feature to work, you get an API key from [https://code.google.com/apis/console/?api=translate this site], and enter the key in this field. Please note that this is currently a global feature, so any installation that has an assigned Translate API key will all charge translations to the same account.
*'''Google Analytics Event Tracking Code''': Some LimeSurvey {KEYWORDS} can be used inside [http://code.google.com/intl/en-EN/apis/analytics/docs/tracking/eventTrackerGuide.html GG Analytics Event Tracking Code], e.g, '_trackEvent', 'MyEvent', '{SID}'

==Email settings==
*'''Default site admin email''': This is the default email address of the site administrator and used for system messages and contact options.
*'''Administrator name''': The real name of the site administrator.
*'''Email method:''' This determines how e-mail messages are being sent. The following options are available:
**'''PHP:''' use internal PHP mailer
**'''Sendmail:''' use sendmail mailer
**'''SMTP:'''use SMTP relaying. Use this setting when you are running LimeSurvey on a host that is not your mail server.
***Make sure that you are using your SMTP configured e-mail (Global settings -> E-mail settings) at the survey settings (At the moment you create a survey or after you create it Edit Survey Settings -> General) if you use SMTP, otherwise there might be a chance that the following error is displayed: SMTP -> ERROR: RCPT not accepted from server: 553 5.7.1 : Sender address rejected: not owned by user.
**'''Qmail:'''Set this if you are running the Qmail mailer
*'''SMTP host:''' If you use 'SMTP ' as email method then you have to put your SMTP-server here. If you are using a different part than port 25 (standard for SMPT) then you have to add the port number separated be a colon (example: 'smtp.gmail.com:465')
*'''SMTP username:''' If your SMTP-server needs authentication then set this to your user name, otherwise it must be blank.
*'''SMTP password:''' If your SMTP-server needs authentication then set this to your password, otherwise it must be blank.
*'''SMTP SSL/TLS:''' Set this to 'SSL' or 'TLS' to use SSL/TLS for your SMTP connection
*'''SMTP debug mode''': If you switch this on then on sending invitations or reminders a detailed connection log and error message will be given (if an error occurs). Not for the faint of heart, but this can give valuable information why a SMTP relay does not work. Usually you want this to be off.
*'''Email batch size:''' When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities, and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a PHP script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting. Clicking the 'send email invitation' button on the token control toolbar, (not the button on the right of each token), sends the maxemails number of invitations, then displays a list of the addresses sent to and a warning that "There are more emails pending than could be sent in one batch. Continue sending emails by clicking below. There are ### emails still to be sent." and provides a "continue button" to proceed with the next batch. I.e., the user determines when to send the next batch after each batch gets emailed. It is not necessary to wait with this screen active. The admin could log off and come back at a later time to send the next batch of invites.

==Bounce settings==
*'''Default site bounce email''': This is the email address where bounced emails will be sent to.
*'''Server type''': If set to 'Off' no bounce processing functions will be available. Set this to POP or IMAP to check a related account for bounces.
*'''Server name & port''': Name of the server and (if needed) the port separated by a colon.
*'''User name''': The user name for the POP/IMAP account
*'''Password''': The password for the POP/IMAP account
*'''Encryption type''': If encrpytion is used please set the right one here (SSL or TLS)

==Security==
*'''Survey preview only for administration users''': By default, preview of inactive survey is restricted to authenticated users only. If you set this to 'No' any person can test your survey using the survey URL - without logging in to the administration and without having to activate the survey first.
*'''Filter HTML for XSS''': By default you survey manager will not be authorized to use dangerous HTML tags in their survey/group/question/labels texts (for instance JavaScript code). This is intended to prevent a survey operator to add malicious script in order to have a true admin raise his permissions on the system. '''If you want to use any script objects like Javascript scripts of Flash applets in your surveys you will need to switch this off.'''
*'''Group member can only see own group''': By default non-admin users defined in the LimeSurvey management interface will only be able to see other users if they belong to at least one group this user belongs to. If you set this to 'No' they can see all users (for example in [[Survey security settings]] )
*'''Force HTTPS''': By default this is set to "Don't force on or off". Switch the setting to "on" to force the connection to use HTTPS. '''''Note:''''' If your server doesn't support HTTPS properly, you can lock yourself from the system! Therefor test the "check if this link works" link first. If the link does not work and you turn on HTTPS, LimeSurvey will break and you won't be able to access it.

==Presentation==
*'''Show 'no answer' option for non-mandatory questions''': When a question of a radio button/select type that contains editable answers (i.e.: List & array questions) is not mandatory and this is set to 'Yes' (default), an additional entry 'No answer' is shown for each subquestion - so that participants may choose to not answer the question. Some people prefer this not to be available. Set this to 'No' to turn this off.
*'''Repeating headings in array questions every X subquestions''': With array type question, often you'll have a lot of subquestions, which - when displayed on screen - take up more than one page. The repeat-headers setting lets you decide how many answers should be displayed before repeating the header information for the question. A good setting for this is around 25. If you don't want the headings to repeat at all, set this to 0.
*'''Show "There are X questions in this survey"''':
*'''Show question group name and/or description''':
*'''Show question number and/or question code''':

==Language==
*'''Default site language''': This is the default language to be used in your administration , and also the default language for the public survey list if none is given.
*'''Available languages''': If you don't want all languages to be available in the administration language select boxes you can here define the language that should be available only.

==Interfaces==
*'''RPC interface enabled''': Using this feature you can activate/deactivate the LimeSurvey [[RemoteControl 2 API|RemoteControl2]] interface API, either using JSON-RPC (recommended) or XML-RPC.

Translations:Global settings/13/fr

2014-03-26T14:53:27Z

Courtm:

:{{Arrow|1}} Vous pouvez paramétrer si, et à quelle fréquence, Limesurvey vérifie la disponibilité de mises à jour. Si une mise à jour est trouvée vous pouvez, soit effectuer la mise à jour manuellement (en téléchargeant le nouveau package de Limesurvey et en suivant les [[Upgrading from a previous version|Update instructions]]) ou utiliser la fonctionnalité [[ComfortUpdate]]

Global settings/fr

2014-03-26T14:52:53Z

Courtm: Created page with ":{{Arrow|1}} Vous pouvez paramétrer si et à quelle fréquence Limesurvey vérifie la disponibilité de mises à jour. Si une mise à jour est trouvée, vous pouvez, soit eff..."

<languages />
__TOC__

=Description générale=

Si vous cliquez sur l'icône [[File:global.png]] dans la barre d'outils principale vous arriverez sur les paramètres généraux. L'accès aux paramètres généraux est réservé aux utilisateurs avec des droits de "Super administrateur". Ceux-ci peuvent permettre d'ajuster certains réglages de LimeSurvey d'une manière globale. Dans les versions antérieures à 1.87, ces [[réglages optionnels]] n'étaient disponibles qu'en modifiant le fichier config.php ou config-default.php. Depuis la version 1.87, les valeurs dans ces fichiers sont simplement les valeurs utilisées par défaut. Une fois que vous serez entré dans l'écran des paramètres généraux et que vous aurez fait une première sauvegarde, ces valeurs seront remplacées par celles dans les paramètres généraux

=Paramètres et leurs explications=

==Overview & Update==
*'''System overview''': This is pretty much self explaining. Here you can get a short insight on the number of surveys and other statistics in your LimeSurvey installation. For debug purposes you can also find a button to show your PHP Info.
*'''Updates''':
:[[File:Update_check_settings.jpg]]

:{{Arrow|1}} Vous pouvez paramétrer si et à quelle fréquence Limesurvey vérifie la disponibilité de mises à jour. Si une mise à jour est trouvée, vous pouvez, soit effectuer la mise à jour manuellement (en téléchargeant le nouveau package de Limesurvey et en suivant les [[Upgrading from a previous version|Update instructions]]) ou utiliser la fonctionnalité [[ComfortUpdate]]

==General==
*'''Site name''': Give your survey site a name. This name will appear in the survey list overview and in the administration header.
*'''Default template''': This setting specifies the default design template used for the 'public list' of surveys and for new surveys or surveys using a non-existing template.
*'''Administration template''': This setting specifies the default design template used for the LimeSurvey administration.
*'''Default HTML editor mode:''' Sets the default mode for integrated HTML editor. Valid settings are: inline (default), popup and none:
** ''inline'': Inline replacement of fields by an HTML editor. Slow but convenient and user friendly
** ''popup'': Adds an icon that opens a popup window with the HTML editor. Faster, but HTML code is displayed on the form.
** ''none'': No HTML editor
*'''Question type selector''': Choose 'Full selector' to get a question type selector with preview and 'Simple' to get a plain select box.
*'''Template editor:''': Choose 'Full template editor' to get a enhanced editor (with syntax-highlighting) when editing survey templates and 'Simple template editor' to get a plain editor field
*'''Time difference (in hours)''': If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia but use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "+14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses.
*'''Session lifetime''': Defines the time in seconds after which a survey session expires (provided there is no action from the participant). The maximum value on this is 65000 (seconds). Please use a reasonable value. This setting is only available when LimeSurvey is configured to store sessions in a database. When using regular, file-based sessions, it is up to the system administrator to define the right values for "session.gc_maxlifetime", "session.save_path", etc. in the PHP configuration. This only sets the lifetime of sessions in surveys, it doesn't affect the administration interface sessions, which have to be configured with PHP configuration in all cases.
*'''IP Info DB API Key''': Allows integration with the IP-Info-DB service that let's you determine the geographic location of survey takers based on their IP.
*'''Google Maps API Key''': Allows for integration with Google Maps.
*'''Google Analytics API Key''': Allows for integration with Google Analytics. Surveys can over-ride this site-level value. The API key can be inserted into templates using {GOOGLE_ANALYTICS_API_KEY}. The full JavaScript that Google Analytics expects (including the key) can be included in templates via {GOOGLE_ANALYTICS_JAVASCRIPT}.
*'''Google API howto''':
# Register/login on Google Analytics (GA): [http://www.google.com/analytics/ www.google.com/analytics/]
# Create a key (the site should not point to the survey, but to the part before 'index.php?') The key should be UA-xxxxx.
# Go to your survey's global settings in LimeSurvey.
# Put the key in appropriate field (Google Analytics API Key). It's probably the best to set GA to track all pages as you can have more info.
# You don't need to do anything in shipped templates, as the {GOOGLE_ANALYTICS_JAVASCRIPT} part is already there.
# Activate the survey.
# Do the survey.
# Go to GA panel mainsite. (select appropriate account in left-hand upper corner if you have more than one). You should see some graphs with the statistics. Beware of the dates in upper right corner.
*'''Google Translate API Key''': As of version 1.92, the Auto Translate feature is now using the new version 2 of Google Translate's API. Google now charges for this service. In order for the Auto Translate feature to work, you get an API key from [https://code.google.com/apis/console/?api=translate this site], and enter the key in this field. Please note that this is currently a global feature, so any installation that has an assigned Translate API key will all charge translations to the same account.
*'''Google Analytics Event Tracking Code''': Some LimeSurvey {KEYWORDS} can be used inside [http://code.google.com/intl/en-EN/apis/analytics/docs/tracking/eventTrackerGuide.html GG Analytics Event Tracking Code], e.g, '_trackEvent', 'MyEvent', '{SID}'

==Email settings==
*'''Default site admin email''': This is the default email address of the site administrator and used for system messages and contact options.
*'''Administrator name''': The real name of the site administrator.
*'''Email method:''' This determines how e-mail messages are being sent. The following options are available:
**'''PHP:''' use internal PHP mailer
**'''Sendmail:''' use sendmail mailer
**'''SMTP:'''use SMTP relaying. Use this setting when you are running LimeSurvey on a host that is not your mail server.
***Make sure that you are using your SMTP configured e-mail (Global settings -> E-mail settings) at the survey settings (At the moment you create a survey or after you create it Edit Survey Settings -> General) if you use SMTP, otherwise there might be a chance that the following error is displayed: SMTP -> ERROR: RCPT not accepted from server: 553 5.7.1 : Sender address rejected: not owned by user.
**'''Qmail:'''Set this if you are running the Qmail mailer
*'''SMTP host:''' If you use 'SMTP ' as email method then you have to put your SMTP-server here. If you are using a different part than port 25 (standard for SMPT) then you have to add the port number separated be a colon (example: 'smtp.gmail.com:465')
*'''SMTP username:''' If your SMTP-server needs authentication then set this to your user name, otherwise it must be blank.
*'''SMTP password:''' If your SMTP-server needs authentication then set this to your password, otherwise it must be blank.
*'''SMTP SSL/TLS:''' Set this to 'SSL' or 'TLS' to use SSL/TLS for your SMTP connection
*'''SMTP debug mode''': If you switch this on then on sending invitations or reminders a detailed connection log and error message will be given (if an error occurs). Not for the faint of heart, but this can give valuable information why a SMTP relay does not work. Usually you want this to be off.
*'''Email batch size:''' When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities, and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a PHP script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting. Clicking the 'send email invitation' button on the token control toolbar, (not the button on the right of each token), sends the maxemails number of invitations, then displays a list of the addresses sent to and a warning that "There are more emails pending than could be sent in one batch. Continue sending emails by clicking below. There are ### emails still to be sent." and provides a "continue button" to proceed with the next batch. I.e., the user determines when to send the next batch after each batch gets emailed. It is not necessary to wait with this screen active. The admin could log off and come back at a later time to send the next batch of invites.

==Bounce settings==
*'''Default site bounce email''': This is the email address where bounced emails will be sent to.
*'''Server type''': If set to 'Off' no bounce processing functions will be available. Set this to POP or IMAP to check a related account for bounces.
*'''Server name & port''': Name of the server and (if needed) the port separated by a colon.
*'''User name''': The user name for the POP/IMAP account
*'''Password''': The password for the POP/IMAP account
*'''Encryption type''': If encrpytion is used please set the right one here (SSL or TLS)

==Security==
*'''Survey preview only for administration users''': By default, preview of inactive survey is restricted to authenticated users only. If you set this to 'No' any person can test your survey using the survey URL - without logging in to the administration and without having to activate the survey first.
*'''Filter HTML for XSS''': By default you survey manager will not be authorized to use dangerous HTML tags in their survey/group/question/labels texts (for instance JavaScript code). This is intended to prevent a survey operator to add malicious script in order to have a true admin raise his permissions on the system. '''If you want to use any script objects like Javascript scripts of Flash applets in your surveys you will need to switch this off.'''
*'''Group member can only see own group''': By default non-admin users defined in the LimeSurvey management interface will only be able to see other users if they belong to at least one group this user belongs to. If you set this to 'No' they can see all users (for example in [[Survey security settings]] )
*'''Force HTTPS''': By default this is set to "Don't force on or off". Switch the setting to "on" to force the connection to use HTTPS. '''''Note:''''' If your server doesn't support HTTPS properly, you can lock yourself from the system! Therefor test the "check if this link works" link first. If the link does not work and you turn on HTTPS, LimeSurvey will break and you won't be able to access it.

==Presentation==
*'''Show 'no answer' option for non-mandatory questions''': When a question of a radio button/select type that contains editable answers (i.e.: List & array questions) is not mandatory and this is set to 'Yes' (default), an additional entry 'No answer' is shown for each subquestion - so that participants may choose to not answer the question. Some people prefer this not to be available. Set this to 'No' to turn this off.
*'''Repeating headings in array questions every X subquestions''': With array type question, often you'll have a lot of subquestions, which - when displayed on screen - take up more than one page. The repeat-headers setting lets you decide how many answers should be displayed before repeating the header information for the question. A good setting for this is around 25. If you don't want the headings to repeat at all, set this to 0.
*'''Show "There are X questions in this survey"''':
*'''Show question group name and/or description''':
*'''Show question number and/or question code''':

==Language==
*'''Default site language''': This is the default language to be used in your administration , and also the default language for the public survey list if none is given.
*'''Available languages''': If you don't want all languages to be available in the administration language select boxes you can here define the language that should be available only.

==Interfaces==
*'''RPC interface enabled''': Using this feature you can activate/deactivate the LimeSurvey [[RemoteControl 2 API|RemoteControl2]] interface API, either using JSON-RPC (recommended) or XML-RPC.

Translations:Global settings/13/fr

2014-03-26T14:52:53Z

:{{Arrow|1}} Vous pouvez paramétrer si et à quelle fréquence Limesurvey vérifie la disponibilité de mises à jour. Si une mise à jour est trouvée, vous pouvez, soit effectuer la mise à jour manuellement (en téléchargeant le nouveau package de Limesurvey et en suivant les [[Upgrading from a previous version|Update instructions]]) ou utiliser la fonctionnalité [[ComfortUpdate]]

SGQA identifier/fr

2014-02-27T17:59:25Z

Courtm:

<languages /> __TOC__

<div class="simplebox">Depuis la version 1.92, vous n'avez plus besoin d'utiliser les identifiants SGQA. A la place vous pouvez utiliser des codes de questions compatible avec [[Expression Manager|Expression Manager]]. Vous trouverez ici les informations concernant leur [[Expression Manager#Access to Variables|syntaxe]]</div>

<div class="simplebox">'''Hint:''' This page describes how you can find out an SGQA identifier. For information how to use it please refer to the page [[Adding a question]]. </div>

===Description générale===

L'identifiant SGQA (pour Survey/Group/Question/Answer en français, Questionnaire/Groupe/Question/Réponse mais seule la notation anglaise est interprétée par LimeSurvey) est un raccourci vers une réponse à une question. Chaque questionnaire, chaque groupe et chaque question que vous créez se voit attribuer un code unique dans la base de données. Vous pouvez retrouver ces nombres (appelés aussi xID) dans l'écran d'administration dans les barres de titres de questionnaire, de groupe et de question.

<center>[[File:SGQA.png]]</center>

Pour déterminer l'identifiant SGQA vous devez rassembler ces nombres en les séparant par la lettre "X".

<div class="simplebox">'''Note:''' Always use capital letters ("X" instead of "x")!</div>

=Use editor to add placeholder=

The integrated editor has a feature to select the placeholder for a certain question. The icon is called "LimeSurvey replacement fields properties". This feature always lists questions of previous survey pages only, so it depends on the survey mode.

[[File:lime_replacement_editor.png]]

===Identifiant pour une question à choix unique :===

Par exemple, le questionnaire a l'ID 1, le groupe a l'ID 6 et la question a l'ID 12. L'identifiant pour ce genre de question à choix unique doit ressembler à quelque chose comme ceci :

'''1X6X12'''

===Identifiant pour une question à choix unique utilisant un jeu d'étiquettes===

Puisque cela reste une question à choix unique qui utilise des étiquettes pour les réponses, cette réponse particulière doit elle-aussi être identifiée. Pour cela, ajoutez simplement le code de cette étiquette sans le "X". Par exemple, questionnaire d'ID 1, groupe d'ID 6, question d'ID 12. La réponse qui nous intéresse possède le code "lab1".

L'identifiant ressemblera donc à ça~hs~:

'''1X6X12lab1'''

===Identifiant pour une question à choix multiples===

Comme il s'agit d'une question à choix multiples, la réponse recherchée doit aussi être identifiée. Ajoutez simplement le code de cette réponse sans le "X".

Par exemple, questionnaire d'ID 1, groupe dD 6, question d'ID 12. La réponse recherchée possède le code "ber1".

L'identifiant ressemblera donc à ça~hs~:

'''1X6X12ber1'''

=Identifier for Array (Text) or Array (Number) Questions=

Since it is a combined array question the particular answer within the cell must be identified too. Add the subquestion code of the row without an X, then append the underscore char and finally add the subquestion code that indentifies the column. For example: Survey has ID 1, Group has ID 6, Question has ID 12. The particular subquestion has code 'ber1', and the column is identified by the subquestion with code 'lab1'

Your identifier for this "Array (Text)" question answer would look like this:

1X6X12ber1_lab1

=Uses of the SGQA identifier=

The SGQA identifier can be used to load the answers to previously saved questions into the question text of later questions. (See [[Adding a question#Information from previous answers|Information from previous answers]])

It can also be used in the query URL of a survey to "prefill" answers to a survey. eg: for SGQA 1X6X121ab1, your query URL could include "&1X6X121ab1=Y" to prefill that answer with a "Y". (See [[Workarounds: Survey behaviour#Prefilling_survey_answers_using_the_survey_URL|Prefilling survey answers using the survey URL]])

The SGQA identifier is also the field name where the data for each question is stored in the database survey responses table.

=Dynamically reference the SGQ identifier=

Some people may find a need to reference a question dynamically. For instance, if you would like to [[Workarounds: Manipulating a survey at runtime using Javascript#General|hide the input text field]] of a short text answer. You can now do this (as of SVN build 9755) by using the {SGQ} identifier. LimeSurvey will replace the {SGQ} with the full Id of that question, ex: 3583X84X249

Translations:SGQA identifier/2/fr

2014-02-27T17:59:25Z

Courtm:

<div class="simplebox">Depuis la version 1.92, vous n'avez plus besoin d'utiliser les identifiants SGQA. A la place vous pouvez utiliser des codes de questions compatible avec [[Expression Manager|Expression Manager]]. Vous trouverez ici les informations concernant leur [[Expression Manager#Access to Variables|syntaxe]]</div>

Translations:SGQA identifier/1/fr

2014-02-27T17:58:36Z

Courtm: Created page with "__TOC__"

__TOC__

SGQA identifier/fr

2014-02-27T17:57:33Z

Courtm: Created page with "<div class="simplebox">Depuis la version 1.92, vous n'avez plus besoin d'utiliser les identifiants SGQA. A la place vous pouvez utiliser des codes de questions compatible avec..."

<languages /> __TOC__

<div class="simplebox">Depuis la version 1.92, vous n'avez plus besoin d'utiliser les identifiants SGQA. A la place vous pouvez utiliser des codes de questions compatible avec [[Expression Manager|Expression Manager]]. Vous trouverez ici </div>

<div class="simplebox">'''Hint:''' This page describes how you can find out an SGQA identifier. For information how to use it please refer to the page [[Adding a question]]. </div>

===Description générale===

L'identifiant SGQA (pour Survey/Group/Question/Answer en français, Questionnaire/Groupe/Question/Réponse mais seule la notation anglaise est interprétée par LimeSurvey) est un raccourci vers une réponse à une question. Chaque questionnaire, chaque groupe et chaque question que vous créez se voit attribuer un code unique dans la base de données. Vous pouvez retrouver ces nombres (appelés aussi xID) dans l'écran d'administration dans les barres de titres de questionnaire, de groupe et de question.

<center>[[File:SGQA.png]]</center>

Pour déterminer l'identifiant SGQA vous devez rassembler ces nombres en les séparant par la lettre "X".

<div class="simplebox">'''Note:''' Always use capital letters ("X" instead of "x")!</div>

=Use editor to add placeholder=

The integrated editor has a feature to select the placeholder for a certain question. The icon is called "LimeSurvey replacement fields properties". This feature always lists questions of previous survey pages only, so it depends on the survey mode.

[[File:lime_replacement_editor.png]]

===Identifiant pour une question à choix unique :===

Par exemple, le questionnaire a l'ID 1, le groupe a l'ID 6 et la question a l'ID 12. L'identifiant pour ce genre de question à choix unique doit ressembler à quelque chose comme ceci :

'''1X6X12'''

===Identifiant pour une question à choix unique utilisant un jeu d'étiquettes===

Puisque cela reste une question à choix unique qui utilise des étiquettes pour les réponses, cette réponse particulière doit elle-aussi être identifiée. Pour cela, ajoutez simplement le code de cette étiquette sans le "X". Par exemple, questionnaire d'ID 1, groupe d'ID 6, question d'ID 12. La réponse qui nous intéresse possède le code "lab1".

L'identifiant ressemblera donc à ça~hs~:

'''1X6X12lab1'''

===Identifiant pour une question à choix multiples===

Comme il s'agit d'une question à choix multiples, la réponse recherchée doit aussi être identifiée. Ajoutez simplement le code de cette réponse sans le "X".

Par exemple, questionnaire d'ID 1, groupe dD 6, question d'ID 12. La réponse recherchée possède le code "ber1".

L'identifiant ressemblera donc à ça~hs~:

'''1X6X12ber1'''

=Identifier for Array (Text) or Array (Number) Questions=

Since it is a combined array question the particular answer within the cell must be identified too. Add the subquestion code of the row without an X, then append the underscore char and finally add the subquestion code that indentifies the column. For example: Survey has ID 1, Group has ID 6, Question has ID 12. The particular subquestion has code 'ber1', and the column is identified by the subquestion with code 'lab1'

Your identifier for this "Array (Text)" question answer would look like this:

1X6X12ber1_lab1

=Uses of the SGQA identifier=

The SGQA identifier can be used to load the answers to previously saved questions into the question text of later questions. (See [[Adding a question#Information from previous answers|Information from previous answers]])

It can also be used in the query URL of a survey to "prefill" answers to a survey. eg: for SGQA 1X6X121ab1, your query URL could include "&1X6X121ab1=Y" to prefill that answer with a "Y". (See [[Workarounds: Survey behaviour#Prefilling_survey_answers_using_the_survey_URL|Prefilling survey answers using the survey URL]])

The SGQA identifier is also the field name where the data for each question is stored in the database survey responses table.

=Dynamically reference the SGQ identifier=

Some people may find a need to reference a question dynamically. For instance, if you would like to [[Workarounds: Manipulating a survey at runtime using Javascript#General|hide the input text field]] of a short text answer. You can now do this (as of SVN build 9755) by using the {SGQ} identifier. LimeSurvey will replace the {SGQ} with the full Id of that question, ex: 3583X84X249

Translations:SGQA identifier/2/fr

2014-02-27T17:57:33Z

Expression Manager/fr

2014-02-27T17:52:31Z

Courtm: Created page with "IMC calcule la formule du poids comme {weight_kg / (height_m * height_m)}."

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

[[File:tutorial4.jpg]]

Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez répondu à la question précédente (e.g.{!is_empty(p1_sex)}). EM combine pour vous les équations de pertinence du niveau Groupe et Question pour vous. Les questions dans un groupe sont posées uniquement si le groupe dans son ensemble est pertinent. Ensuite , seulement le sous-ensemble de questions du groupe qui sont pertinentes sont effectivement posées.

Voici l'écran pour éditer la pertinence de niveau groupe pour cette question.

[[File:tutorial5.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

==Tailoring/Piping==

EM vous permet facilement de réaliser des conditions simples et complexes de vos questions. Parfois vous avez juste besoin d'une simple substitution, comme quand vous dites , "Vous nous avez dit que vous aviez acheté [Produit]. Qu'avez vous particulièrement apprécié en lui ?".
Parfois vous avez besoin d'une substitution conditionnelle comme "[M/Mme] [Nom], seriez vous prêt à remplir notre sondage ?. Dans ce cas vous voulez utiliser M ou Mme en fonction du sexe de la personne. D'autres fois vous avez besoin de substitutions encore plus complexes (basées par exemple sur un calcul mathématique). Em supporte tous ces types de customisations.

===Equations Conditionnelles===

L'exemple de l'Indice de Masse Corporel montre la capacité à calculer l'IMC d'une personne même en la laissant entrer sa taille et son poids dans des unités métriques ou non métriques.

[[File:tailoring7.jpg]]

Ici weight_kg est {if(weight_units == 'kg', weight, weight * .453592)}. La fonction if() signifie que si le sujet a entré son poids en utilisant les kilogrammes alors utilise cette valeur, sinon multiplie la valeur entrée (donc en livres) par 0.453592 pour la convertir en kilogrammes. La variable height_m utilise une approche similaire pour calculer la taille de la personne en mètres, même si elle l'a entré en pouces.

IMC calcule la formule du poids comme {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/32/fr

2014-02-27T17:52:30Z

Courtm: Created page with "IMC calcule la formule du poids comme {weight_kg / (height_m * height_m)}."

IMC calcule la formule du poids comme {weight_kg / (height_m * height_m)}.

Expression Manager/fr

2014-02-27T17:51:51Z

Courtm: Created page with "Ici weight_kg est {if(weight_units == 'kg', weight, weight * .453592)}. La fonction if() signifie que si le sujet a entré son poids en utilisant les kilogrammes alors utilise..."

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

[[File:tutorial4.jpg]]

Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez répondu à la question précédente (e.g.{!is_empty(p1_sex)}). EM combine pour vous les équations de pertinence du niveau Groupe et Question pour vous. Les questions dans un groupe sont posées uniquement si le groupe dans son ensemble est pertinent. Ensuite , seulement le sous-ensemble de questions du groupe qui sont pertinentes sont effectivement posées.

Voici l'écran pour éditer la pertinence de niveau groupe pour cette question.

[[File:tutorial5.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

==Tailoring/Piping==

EM vous permet facilement de réaliser des conditions simples et complexes de vos questions. Parfois vous avez juste besoin d'une simple substitution, comme quand vous dites , "Vous nous avez dit que vous aviez acheté [Produit]. Qu'avez vous particulièrement apprécié en lui ?".
Parfois vous avez besoin d'une substitution conditionnelle comme "[M/Mme] [Nom], seriez vous prêt à remplir notre sondage ?. Dans ce cas vous voulez utiliser M ou Mme en fonction du sexe de la personne. D'autres fois vous avez besoin de substitutions encore plus complexes (basées par exemple sur un calcul mathématique). Em supporte tous ces types de customisations.

===Equations Conditionnelles===

L'exemple de l'Indice de Masse Corporel montre la capacité à calculer l'IMC d'une personne même en la laissant entrer sa taille et son poids dans des unités métriques ou non métriques.

[[File:tailoring7.jpg]]

Ici weight_kg est {if(weight_units == 'kg', weight, weight * .453592)}. La fonction if() signifie que si le sujet a entré son poids en utilisant les kilogrammes alors utilise cette valeur, sinon multiplie la valeur entrée (donc en livres) par 0.453592 pour la convertir en kilogrammes. La variable height_m utilise une approche similaire pour calculer la taille de la personne en mètres, même si elle l'a entré en pouces.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/31/fr

2014-02-27T17:51:51Z

Ici weight_kg est {if(weight_units == 'kg', weight, weight * .453592)}. La fonction if() signifie que si le sujet a entré son poids en utilisant les kilogrammes alors utilise cette valeur, sinon multiplie la valeur entrée (donc en livres) par 0.453592 pour la convertir en kilogrammes. La variable height_m utilise une approche similaire pour calculer la taille de la personne en mètres, même si elle l'a entré en pouces.

Expression Manager/fr

2014-02-27T17:47:32Z

Courtm: Created page with "L'exemple de l'Indice de Masse Corporel montre la capacité à calculer l'IMC d'une personne même en la laissant entrer sa taille et son poids dans des unités métriques ou ..."

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

[[File:tutorial4.jpg]]

Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez répondu à la question précédente (e.g.{!is_empty(p1_sex)}). EM combine pour vous les équations de pertinence du niveau Groupe et Question pour vous. Les questions dans un groupe sont posées uniquement si le groupe dans son ensemble est pertinent. Ensuite , seulement le sous-ensemble de questions du groupe qui sont pertinentes sont effectivement posées.

Voici l'écran pour éditer la pertinence de niveau groupe pour cette question.

[[File:tutorial5.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

==Tailoring/Piping==

EM vous permet facilement de réaliser des conditions simples et complexes de vos questions. Parfois vous avez juste besoin d'une simple substitution, comme quand vous dites , "Vous nous avez dit que vous aviez acheté [Produit]. Qu'avez vous particulièrement apprécié en lui ?".
Parfois vous avez besoin d'une substitution conditionnelle comme "[M/Mme] [Nom], seriez vous prêt à remplir notre sondage ?. Dans ce cas vous voulez utiliser M ou Mme en fonction du sexe de la personne. D'autres fois vous avez besoin de substitutions encore plus complexes (basées par exemple sur un calcul mathématique). Em supporte tous ces types de customisations.

===Equations Conditionnelles===

L'exemple de l'Indice de Masse Corporel montre la capacité à calculer l'IMC d'une personne même en la laissant entrer sa taille et son poids dans des unités métriques ou non métriques.

[[File:tailoring7.jpg]]

Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/29/fr

2014-02-27T17:47:31Z

L'exemple de l'Indice de Masse Corporel montre la capacité à calculer l'IMC d'une personne même en la laissant entrer sa taille et son poids dans des unités métriques ou non métriques.

Expression Manager/fr

2014-02-27T17:45:29Z

Courtm: Created page with "===Equations Conditionnelles==="

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

[[File:tutorial4.jpg]]

Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez répondu à la question précédente (e.g.{!is_empty(p1_sex)}). EM combine pour vous les équations de pertinence du niveau Groupe et Question pour vous. Les questions dans un groupe sont posées uniquement si le groupe dans son ensemble est pertinent. Ensuite , seulement le sous-ensemble de questions du groupe qui sont pertinentes sont effectivement posées.

Voici l'écran pour éditer la pertinence de niveau groupe pour cette question.

[[File:tutorial5.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

==Tailoring/Piping==

EM vous permet facilement de réaliser des conditions simples et complexes de vos questions. Parfois vous avez juste besoin d'une simple substitution, comme quand vous dites , "Vous nous avez dit que vous aviez acheté [Produit]. Qu'avez vous particulièrement apprécié en lui ?".
Parfois vous avez besoin d'une substitution conditionnelle comme "[M/Mme] [Nom], seriez vous prêt à remplir notre sondage ?. Dans ce cas vous voulez utiliser M ou Mme en fonction du sexe de la personne. D'autres fois vous avez besoin de substitutions encore plus complexes (basées par exemple sur un calcul mathématique). Em supporte tous ces types de customisations.

===Equations Conditionnelles===

The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height in weight in metric or non-metric units.

[[File:tailoring7.jpg]]

Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/28/fr

2014-02-27T17:45:28Z

Courtm: Created page with "===Equations Conditionnelles==="

===Equations Conditionnelles===

Expression Manager/fr

2014-02-27T17:45:05Z

Courtm: Created page with "EM vous permet facilement de réaliser des conditions simples et complexes de vos questions. Parfois vous avez juste besoin d'une simple substitution, comme quand vous dites ,..."

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

[[File:tutorial4.jpg]]

Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez répondu à la question précédente (e.g.{!is_empty(p1_sex)}). EM combine pour vous les équations de pertinence du niveau Groupe et Question pour vous. Les questions dans un groupe sont posées uniquement si le groupe dans son ensemble est pertinent. Ensuite , seulement le sous-ensemble de questions du groupe qui sont pertinentes sont effectivement posées.

Voici l'écran pour éditer la pertinence de niveau groupe pour cette question.

[[File:tutorial5.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

==Tailoring/Piping==

EM vous permet facilement de réaliser des conditions simples et complexes de vos questions. Parfois vous avez juste besoin d'une simple substitution, comme quand vous dites , "Vous nous avez dit que vous aviez acheté [Produit]. Qu'avez vous particulièrement apprécié en lui ?".
Parfois vous avez besoin d'une substitution conditionnelle comme "[M/Mme] [Nom], seriez vous prêt à remplir notre sondage ?. Dans ce cas vous voulez utiliser M ou Mme en fonction du sexe de la personne. D'autres fois vous avez besoin de substitutions encore plus complexes (basées par exemple sur un calcul mathématique). Em supporte tous ces types de customisations.

===Conditional Equations===

The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height in weight in metric or non-metric units.

[[File:tailoring7.jpg]]

Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/27/fr

2014-02-27T17:45:04Z

EM vous permet facilement de réaliser des conditions simples et complexes de vos questions. Parfois vous avez juste besoin d'une simple substitution, comme quand vous dites , "Vous nous avez dit que vous aviez acheté [Produit]. Qu'avez vous particulièrement apprécié en lui ?".
Parfois vous avez besoin d'une substitution conditionnelle comme "[M/Mme] [Nom], seriez vous prêt à remplir notre sondage ?. Dans ce cas vous voulez utiliser M ou Mme en fonction du sexe de la personne. D'autres fois vous avez besoin de substitutions encore plus complexes (basées par exemple sur un calcul mathématique). Em supporte tous ces types de customisations.

Expression Manager/fr

2014-02-27T17:35:05Z

Courtm: Created page with "Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence"

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

[[File:tutorial4.jpg]]

Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez répondu à la question précédente (e.g.{!is_empty(p1_sex)}). EM combine pour vous les équations de pertinence du niveau Groupe et Question pour vous. Les questions dans un groupe sont posées uniquement si le groupe dans son ensemble est pertinent. Ensuite , seulement le sous-ensemble de questions du groupe qui sont pertinentes sont effectivement posées.

Voici l'écran pour éditer la pertinence de niveau groupe pour cette question.

[[File:tutorial5.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

==Tailoring/Piping==

EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need simple substitution, like saying, "You said you purchased <nowiki>[</nowiki>Product]. What did you like best about it?". Sometimes you need conditional substitution like "<nowiki>[</nowiki>Mr./Mrs.] <nowiki>[</nowiki>LastName], would you be willing to complete our survey?". In this case, you want to use Mr. or Mrs. based upon the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation). EM supports each of these types of tailoring/piping.

===Conditional Equations===

The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height in weight in metric or non-metric units.

[[File:tailoring7.jpg]]

Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/25/fr

2014-02-27T17:35:04Z

Courtm: Created page with "Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence"

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

Expression Manager/fr

2014-02-27T17:34:00Z

Courtm: Created page with "Voici l'écran pour éditer la pertinence de niveau groupe pour cette question."

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

[[File:tutorial4.jpg]]

Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez répondu à la question précédente (e.g.{!is_empty(p1_sex)}). EM combine pour vous les équations de pertinence du niveau Groupe et Question pour vous. Les questions dans un groupe sont posées uniquement si le groupe dans son ensemble est pertinent. Ensuite , seulement le sous-ensemble de questions du groupe qui sont pertinentes sont effectivement posées.

Voici l'écran pour éditer la pertinence de niveau groupe pour cette question.

[[File:tutorial5.jpg]]

Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping==

EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need simple substitution, like saying, "You said you purchased <nowiki>[</nowiki>Product]. What did you like best about it?". Sometimes you need conditional substitution like "<nowiki>[</nowiki>Mr./Mrs.] <nowiki>[</nowiki>LastName], would you be willing to complete our survey?". In this case, you want to use Mr. or Mrs. based upon the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation). EM supports each of these types of tailoring/piping.

===Conditional Equations===

The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height in weight in metric or non-metric units.

[[File:tailoring7.jpg]]

Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/23/fr

2014-02-27T17:33:57Z

Courtm: Created page with "Voici l'écran pour éditer la pertinence de niveau groupe pour cette question."

Voici l'écran pour éditer la pertinence de niveau groupe pour cette question.

Expression Manager/fr

2014-02-27T17:33:21Z

Courtm: Created page with "Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez ré..."

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

[[File:tutorial4.jpg]]

Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez répondu à la question précédente (e.g.{!is_empty(p1_sex)}). EM combine pour vous les équations de pertinence du niveau Groupe et Question pour vous. Les questions dans un groupe sont posées uniquement si le groupe dans son ensemble est pertinent. Ensuite , seulement le sous-ensemble de questions du groupe qui sont pertinentes sont effectivement posées.

Here is the screen for editing the group-level relevance for that question:

[[File:tutorial5.jpg]]

Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping==

EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need simple substitution, like saying, "You said you purchased <nowiki>[</nowiki>Product]. What did you like best about it?". Sometimes you need conditional substitution like "<nowiki>[</nowiki>Mr./Mrs.] <nowiki>[</nowiki>LastName], would you be willing to complete our survey?". In this case, you want to use Mr. or Mrs. based upon the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation). EM supports each of these types of tailoring/piping.

===Conditional Equations===

The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height in weight in metric or non-metric units.

[[File:tailoring7.jpg]]

Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/22/fr

2014-02-27T17:33:20Z

Comme vous pouvez le voir, le groupe aussi possède des critères de pertinence du niveau question, de telle façon que chaque question n’apparaît que lorsque vous avez répondu à la question précédente (e.g.{!is_empty(p1_sex)}). EM combine pour vous les équations de pertinence du niveau Groupe et Question pour vous. Les questions dans un groupe sont posées uniquement si le groupe dans son ensemble est pertinent. Ensuite , seulement le sous-ensemble de questions du groupe qui sont pertinentes sont effectivement posées.

Expression Manager/fr

2014-02-27T17:00:38Z

Courtm: Created page with "Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affic..."

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

[[File:tutorial4.jpg]]

As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). EM combines the Group and Question-level relevance for you. Questions in a group are only asked if the group as a whole is relevant. Then, only the subset of questions within the group that are relevant are asked.

Here is the screen for editing the group-level relevance for that question:

[[File:tutorial5.jpg]]

Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping==

EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need simple substitution, like saying, "You said you purchased <nowiki>[</nowiki>Product]. What did you like best about it?". Sometimes you need conditional substitution like "<nowiki>[</nowiki>Mr./Mrs.] <nowiki>[</nowiki>LastName], would you be willing to complete our survey?". In this case, you want to use Mr. or Mrs. based upon the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation). EM supports each of these types of tailoring/piping.

===Conditional Equations===

The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height in weight in metric or non-metric units.

[[File:tailoring7.jpg]]

Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/20/fr

2014-02-27T17:00:37Z

Ceci est une exemple de sondage de recensement; La première page demande combien de personnes vivent avec vous et l'enregistre dans la variable "cohabs". Cette page est affiché seulement si vous avez plus d'un co-habitant (elle est donc affichée pour la deuxième personne qui co-habite avec vous), et également seulement affiché si vous avez spécifié quelle est votre relation avec Person One (p1_rel).

Expression Manager/fr

2014-02-27T16:56:47Z

Courtm: Created page with "=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ==="

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

This is a sample census survey. The first page asks how many people live with you and stores that in the "cohabs" variable. This page is only shown if you have more than one cohabitant (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).

[[File:tutorial4.jpg]]

As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). EM combines the Group and Question-level relevance for you. Questions in a group are only asked if the group as a whole is relevant. Then, only the subset of questions within the group that are relevant are asked.

Here is the screen for editing the group-level relevance for that question:

[[File:tutorial5.jpg]]

Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping==

EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need simple substitution, like saying, "You said you purchased <nowiki>[</nowiki>Product]. What did you like best about it?". Sometimes you need conditional substitution like "<nowiki>[</nowiki>Mr./Mrs.] <nowiki>[</nowiki>LastName], would you be willing to complete our survey?". In this case, you want to use Mr. or Mrs. based upon the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation). EM supports each of these types of tailoring/piping.

===Conditional Equations===

The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height in weight in metric or non-metric units.

[[File:tailoring7.jpg]]

Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==

Translations:Expression Manager/19/fr

2014-02-27T16:56:46Z

Courtm: Created page with "=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ==="

=== Voir / Modifier l'équation de filtre conditionnel au niveau du groupe ===

Expression Manager/fr

2014-02-27T16:56:24Z

Courtm: Created page with "Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence"

<languages />
__TOC__

<div class="simplebox"> Remarque: Cette fonction est uniquement disponible dans LimeSurvey 1.92 ou plus tard. </div>

=Démarrage rapide=

=Vue d'ensemble=

Quand vous paramétrez vos enquêtes, vous avez souvent besoin de pouvoir spécifier:
#'''Navigation/branchement''' - permet de modifier l'ordre dans lequel sont posées les questions en fonction de la réponse du sondé
#'''Peaufiner''' - comment poser la question (en se référant aux réponses précédentes, ou en conjuguant les phrases de votre question en fonction du nombre ou du genre de votre sondé), ou comment générer des rapports personnalisés (comme des évaluations ou des conseils sur mesure).
#'''Validation''' - être sur que la question valide certains critères, comme des valeurs min et max, ou corresponde à un motif précis.

L'Expression Manager (EM) procure une façon intuitive de spécifier la logique de toutes ces fonctionnalités. Presque tout ce que vous pouvez écrire comme équation mathématique standard est une expression valide, même en appelant des fonctions. EM procure l'accès à 70 fonctions et peut facilement être étendu pour en supporter d'avantage. Il vous permet également d’accéder à vos variables avec des noms de variables lisibles (plutôt qu'avec la notation SGQA).

Les sections suivantes montrent quelles sont les principales circonstances où l'Expression Manager (EM) est utilisé

==Filtre conditionnel (Contrôle De Navigation/Branchement)==

Certaines enquêtes utilisent une logique "aller à ("Goto Logic"), par exemple si vous répondez à la Question1 avec la réponse C, alors sautez à la Question5. Cette approche est très limitée, car il est très difficile de valider et de maintenir la cohérence si vous avez à ré-ordonner les questions. EM utilise une équation booléenne pour spécifier toutes les conditions sous lesquelles une question peut être valide. Si la question est pertinente, alors la question est posée, sinon elle n'est pas applicable et la valeur NULL est stockée dans la base. C'est similaire à ce qui peut être fait par l'intermédiaire de l'éditeur de conditions, mais EM vous permet de spécifier facilement des critères bien plus complexes et puissants (et vous permet d'utiliser des noms de variables plutôt que la notation SGQA)

Cette image montre une façon d'appréhender la logique de la pertinence pour un questionnaire. Il calcule l'Indice de Masse Corporelle. L'équation de la pertinence est indiquée dans les crochets juste après le nom de la variable (qui est en vert). Donc, la pertinence du poids (weight), des unités de poids (weight_units), de la taille (height) et des unités de taille (height_units) sont toutes à 1, cela signifie que ces questions sont toujours posées. Cependant, la pertinence pour l'IMC est {!is_empty(height) and !is_empty(weight)}, ce qui veut dire que l'IMC sera calculé seulement si le sujet entre une valeur à la fois pour la taille et le poids (évitant ainsi le risque de division par 0). De même la question de rapport est montré seulement si le sujet répond aux quatre questions (taille, unité de taille, poids, unités de poids).

[[File:tutorial1.jpg]]

La pertinence est affichée et modifiables aux endroits suivants :

=== Voir / Modifier l'équation de filtre conditionnel au niveau de la question ===

Cette équation calcule l'Indice de Masse Corporelle (IMC). Elle est posée uniquement si la personne entre d'abord sa taille et son poid

[[File:tutorial2.jpg]]

Ceci est l'écran d'édition pour la question sur l'IMC

[[File:tutorial3.jpg]]

Notez que vous n'avez pas à utiliser les accolades quand vous entrez une équation de pertinence

===Viewing / Editing Group-Level Relevance===

This is a sample census survey. The first page asks how many people live with you and stores that in the "cohabs" variable. This page is only shown if you have more than one cohabitant (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).

[[File:tutorial4.jpg]]

As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). EM combines the Group and Question-level relevance for you. Questions in a group are only asked if the group as a whole is relevant. Then, only the subset of questions within the group that are relevant are asked.

Here is the screen for editing the group-level relevance for that question:

[[File:tutorial5.jpg]]

Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping==

EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need simple substitution, like saying, "You said you purchased <nowiki>[</nowiki>Product]. What did you like best about it?". Sometimes you need conditional substitution like "<nowiki>[</nowiki>Mr./Mrs.] <nowiki>[</nowiki>LastName], would you be willing to complete our survey?". In this case, you want to use Mr. or Mrs. based upon the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation). EM supports each of these types of tailoring/piping.

===Conditional Equations===

The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height in weight in metric or non-metric units.

[[File:tailoring7.jpg]]

Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.

BMI computes the weight formula as {weight_kg / (height_m * height_m)}.

Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")

Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View

[[File:tailoring8.jpg]]

From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports===

<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>

This example shows the BMI report.

[[File:tailoring10.jpg]]

Here is the edit window for the same question.

[[File:tailoring11.jpg]]

As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.

[[File:tailoring12.jpg]]

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation==

EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.

The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction=

LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).

This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions==
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?==

The short answer is No (but also yes).

EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.

However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.

This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?==

Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.

Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?==

Here is a list of pros and cons of each style:

{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}

The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?==

Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?==

Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?==

LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.

One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started=

The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=

==Conditions => Relevance==

Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring==

Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring==

Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation==

Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations==

Equations were not supported without fancy JavaScript.

==Equation Question Type==

Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?=

The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)==

EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance===

Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.

Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.

Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:

{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}

The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.

As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance===

Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping===

Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).

Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations===

There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.

This solves a common request for storing Assessment scores within the database

==Syntax==

Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).

Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>

Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

EM syntax follows normal operator precedence:

{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)===

Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.

To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables==

Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question

In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.

Furthermore, Expression Manager lets you access many properties of the Question:

{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue===

For security issues, text entered by user are filtered. Some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming==

Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

QuestionCode . '_' . SubQuestionID . '_' . ScaleId

For comment and other, question code are QuestionCode_comment and QuestionCode_other

{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables==

Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).

The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''

''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)

''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}

You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}

The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''

''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''

Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}

The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.

The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions==

Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions===

The following functions are currently available:

{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered===

Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.

{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local==

In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions==

If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant

{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions===

Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.

To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).

So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?==

Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):

{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}

All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.

Expression Manager provides this functionality by surrounding each expression with a named <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==

{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting=

To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting==

{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading=

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==

==[[Expression Manager HowTos|Use Cases and HowTos]]==

==[[Expression Manager Examples|Step-by-Step Examples]].==

==[[Expression Manager for developers|Reference for Developers]]==

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==