SetVariableExpressionEnd

 Hint: This features is available starting in version 4.0.0

Usage

This event happen when ExpressionScript is constructed. It allow to update know variables array by expression.

Input

• surveyId : the related survey id
• language : the related language
• newExpressionSuffixes : and empty array by default. To be added as expression suffix (like .question, .NAOK etc …)
• knownVars : the current known Variables by expression.
• questionSeq2relevance ^{(New in 4.2.0 )} : array index by question order. This array contains all information to display the question.

Possible output

• knownVars : can be updated by plugins
• questionSeq2relevance ^{(New in 4.2.0 )} : can be updated by plugins

Some detail of knowVars

knowVars are array of variables know by expression manager. Key are the variables.

  Update knowVars in your plugins can break LimeSurvey core functionnality. Updating directly knowVars in plugin must be done with care and can broke without API version update.

LimeSurvey core have 2 types of variables for knowVars :

• Value fixed by template or survey or current view : SID, SURVEYURL, QID …
• Value from response of the user.

Fixed variables are stored as

$knownVars[$variable] = array(
    'code' => // the static value for the variable
    'type' => // ''
    'jsName_on' => // ''
    'jsName' => // ''
    'readWrite' => // 'N' - since these are always read-only variables
);

Dynamic variables are stored as

$knownVars[$sgqa] = array(
    'jsName_on' => // the name of the javascript variable if it is defined on the current page - often 'answerSGQA'
    'jsName' => // the name of the javascript variable when referenced  on different pages - usually 'javaSGQA'
    'readWrite' => // 'Y' for yes, 'N' for no - currently not used
    'hidden' => // 1 if the question attribute 'hidden' is true, otherwise 0
    'question' => // the text of the question (or subquestion)
    'qid' => // the numeric question id - e.g. the Q part of the SGQA name
    'gid' => // the numeric group id - e.g. the G part of the SGQA name
    'grelevance' =>  // the group level relevance string
    'relevance' => // the question level relevance string
    'qcode' => // the qcode-style variable name for this question  (or subquestion)
    'qseq' => // the 0-based index of the question within the survey
    'gseq' => // the 0-based index of the group within the survey
    'type' => // the single character type code for the question
    'sgqa' => // the SGQA name for the variable
    'ansList' => // ansArray converted to a JavaScript fragment - e.g. ",'answers':{ 'M':'Male','F':'Female'}"
    'ansArray' => // PHP array of answer strings, keyed on the answer code = e.g. array['M']='Male';
    'scale_id' => // '0' for most answers.  '1' for second scale within dual-scale questions
    'rootVarName' => // the root code / name / title for the question, without any subquestion or answer-level suffix.  This is from the title column in the questions table
    'subqtext' => // the subquestion text
    'rowdivid' => // the JavaScript ID of the row identifier for a question.  This is used to show/hide entire question rows
    'onlynum' => // 1 if only numbers are allowed for this variable.  If so, then extra processing is needed to ensure that can use comma as a decimal separator
);

Some detail of questionSeq2relevance

  Update questionSeq2relevance in your plugins can break LimeSurvey core functionnality. Updating directly questionSeq2relevance in plugin must be done with care and can broke without API version update.

This array give information of each the question by order of visibility during survey process. You can use it to reorder question on your way or set some specific state (relevance, hidden).

$questionSeq2relevance[$seq] = array(
        * 'relevance' => // the question-level relevance equation
        * 'grelevance' =>  // the group-level relevance equation
        * 'qid' => // the question id
        * 'qseq' => // the 0-index question sequence, same as key
        * 'gseq' => // the 0-index group sequence
        * 'jsResultVar_on' => // the javascript variable holding the input value
        * 'jsResultVar' =>  // the javascript variable (often hidden) holding the value to be submitted
        * 'type' => // the one character question type
        * 'hidden' => // 1 if it should be always_hidden
        * 'gid' => // group id
        * 'mandatory' =>  // 'Y' if mandatory, 'N' if not
        * 'eqn' => // To be documented
        * 'help' => // the help text
        * 'qtext' => // the question text
        * 'code' => // the full variable name
        * 'other' => // whether the question supports the 'other' option - 'Y' if true
        * 'rowdivid' => // the javascript id for the row - in this case, the 5th subquestion
        * 'aid' => // the answer id
        * 'sqid' => // the subquestion's qid (only populated for some question types)
);

Please note that all this data are not used in LimeSurvey core and Expression script must be improved.

Possible (tested) usage

• reorder question on plugin way
• set hidden attribute inside plugin (with the related knowVar hidden value)
• set relevance inside plugin (with the related knowVar relevance value)

About Expression Suffixes

When ExpressionScript get a variables, if there are no suffix, default one is code. If you want to add new suffixes : you can add it in newExpressionSuffixes. Currently only «Fixed» suffix is allowed. Value of the suffix is same in PHP and javascript.

Sample plugins

• expressionFixedDbVar
• expressionQuestionForAll
• expressionQuestionHelp
• organizeSurvey