BPC SurveyManager - Creating Surveys - The Page Script
Introduction - Purpose and Usage
Pages in BPC SurveyManager are not pre-stored the content of pages are dynamically selected and displayed according to the default question script or question level rules scripts. Questions to be displayed on a page are selected and loaded into an internal Question List using (in order):
- The rules stored with the question of the previous page submitted to the survey engine, if no questions selected (or no previous page)
- A QScript tag value passed to the survey in the initial survey call, if no tag value
- A QScript property held in the survey property list, if no property value
- A property for the current user named as SID + _SCRIPT, if no property value
- The "default page script" which is a field stored in the survey header, if no script defined
- An auto generated script that returns the default number of questions in a page as defined in the survey header, or if no default page value
- The next single question in the question list after the last one answered.
The QScript tagproperty if a property of the surveybody tag. It defines the script to be used to load the question list for a survey page. The QScript tagproperty (QScript="value") uses the same script syntax as the QSCript survey header field, and properties that store QScripts.
When you script the rules engine you define the list of questions using the QScript syntax explained here.
The QScript Engine
The survey engine works by loading an internal question list as it processes each page. The initial survey page is loaded by reading the question script (provided in either a QScript tagproperty or, if that is empty, question script field of the survey header, and if that is empty the default page size field of the header is used). The script is then executed and the result is a list of questions for the next page. That list is then passed to the page assembler which loads and preprocesses each question in the list. On subsequent pages the question list is first assembled from the rules attached to each question of the previously posted question list, and if empty, then the QScript tagproperty and if that is empty the question script field in the header, and if that is empty, the default page size defined in the survey header is used.
The QScript Syntax
A QScript is a list of display scripts, seperated by commas and is of the form:
command(ssss,ssss,...), command(ssss,ssss,...), ...
- where ... means 'repeat indefinately' (don't put it in your script - it is a grammar symbol for use here only)
- where command is @ (means ask), ask, show, showpage -- all of which mean ask the things in the brackets. @, ask, show are all the same and work for any QRL list, showpage assumes the QRL list is a list of question groups.
- where ssss might contain (one or more of):
- .[QuesGroupName] - List all questions with this question group id
- QRL1,QRL2,QRL3,...QRLn) - List of Question Resource Locators separated by commas
- .[*] - List the questions in the question group (alphabetically) after the last question. QuestionGroups are sorted alphabetically.
- .[. for num] - List the next 'num' number of questions from the current question (the last question served to the browser - questions are sorted numerically by the order field, then alphabetically by the QID field)
- [!P] - get the string from a property of the person called SID + '_SCRIPT'
- [!] - get the string from a property with the same name as the SID
- [!D] - get the string from the default script for the survey (WARNING: Do not use this in a surveyheader default script field)
Standard and Typical QScripts
As the only command currently supported is "@" (although ask and show are also supported but mean the same thing), allowed QScript formats are therefore :
- @(.[QuesGroupName]) - List all questions with this question group id
- @(QRL1,QRL2,QRL3,...QRLn) - List of Question Resource Locators separated by commas
- @(.[*]) - List the questions in the question group (alphabetically) after the last question. QuestionGroups are sorted alphabetically.
- @(.[. for num]) - List the next 'num' number of questions from the current question (the last question served to the browser - questions are sorted numerically by the order field, then alphabetically by the QID field)
- @([!P]) - get the string from a property of the person called SID + '_SCRIPT'
- @([!]) - get the string from a property with the same name as the SID. This is commonly uses with rule jumpfunctions PADD/PSET/PCLR existing in other surveys to define a list of questions to display for a specific user. See:BPC SurveyManager - Creating Surveys - Rules Scripting
- [!D] - get the string from the default QScript field of the survey (WARNING: Do not use this in a surveyheader default QScript field)
Note in somes circumstanses the following would work-
- @(SID.[*]) - List the questions in the question group after the last question for survey SID
In all cases the script is processed for [!P], [!D]. [!] is a special form used for annotation surveys in the default script field of the survey header. It allows a property of the user to contain a list of QRL's (usually questions/or info blocks) to be displayed (such as in a second survey embedded in a left hand column, representing the list of things selected by rules of the primary survey in the right hand column). See: BPC SurveyManager - Creating Surveys - Rules Scripting
Most of the BPC SurveyManager clients will automatically insert the default script "@(.[*])" to the default script field of the surveyheader when you create a survey. This is the best general script for a conventional survey as it essentially tells the survey engine to retrieve the next quesgroup and display all of its questions. This orients the survey to treating quesgroups as pages. Obviously you can override it.
About Question Resource Locators (QRL)
A QRL (Question Resource Locator) of the form:
SID.QID:RID which means SurveyID.QuestionID:RuleID
Where the RuleID MUST be a number.
In QScripts the RuleID portion does not make sense, so it should be omitted, thus:
QRL's are designed so that if a portion is omitted they are automatically expanded with the current value for the omitted value. So if the current survey is XYZ001, the QRL ".Q001" would be expanded to "XYZ001.Q001"