Custom controls
Custom controls are controls that you define and then place on the page using a sub-template. The UNICOM Intelligence Developer Documentation Library contains examples of slider and calendar custom controls that you can use as they come or customize to suit your company’s requirements.
The general procedure for writing and using a custom control is as follows.
▪Write the control in HTML and Javascript and save it in a file in the project folder. The control logic should be implemented in a separate .js file.
Note Because survey authors are able to enter arbitrary HTML and JavaScript content, they are considered privileged users.
▪Create any images that are required by the template and save them in the project folder.
▪Create a question sub-template and add the extra tags that name the
.js file and place the control on the page. For more information, see
Sub-templates for custom controls.
▪Define the questions in the metadata section of the script and use the
templates parameter to name the sub-template to be used. For more information, see
Using a custom control.
Sub-templates for custom controls
A sub-template for a custom control contains all the things that an ordinary sub-template contains, plus the following items that are specific to the custom control:
1 An <mrRef> tag that names the Javascript file containing the specification for the custom control:
<mrRef RefType="script" RefPosition="head" type="text/javascript" src="filename">Text</mrRef>
where:
▪RefPosition="head" or RefPosition="bottom" says to place the reference to this file in the <head> section or the closing body tag of the HTML document that the Player creates for the page. This allows you to use the same custom control more than once on a page without having to repeat the reference for each use.
▪filename is the name of the Javascript file that contains the code for the control.
▪Text is any text of your choice. A brief description of what the control does is useful.
Place this statement at the start of the template file, after the <mrSubTemplate> tag.
2 A <script> section that places the custom control in the page’s HTML document using <mrData QuestionElement="Parameter"> tags to reference the question:
<mrData QuestionElement="Parameter" Type="PType"/>
where PType is the type of information you want to set or request, and is one of:
|
PType
|
Description
|
|
FullQuestionName
|
The full question name including the _Q prefix used in the HTML document to identify questions.
|
|
ImageLocation
|
The image location that is inserted before image tags, mrRef tags, and so on.
A backslash is output as \\ which makes it easier to use ImageLocation as a string. Ampersand is output as &
|
|
Label
|
The question text without any style formatting. (Normally, the question text is output in a <span>, preceded by a <div> tag.) Using the Label parameter type returns just the question text. If the text contains HTML tags, these will be passed as they are defined provided that they are well formed.
|
|
Max
|
The maximum value defined on the validation node.
|
|
Min
|
The minimum value defined on the validation node.
|
|
PFormatType
|
Indicates the Player XML will be inserted into the HTML page as a static string of JSON or XML format. [JSON|XML]
|
|
QuestionName
|
The question name.
|
|
Id
|
The full question ID including the _Q prefix used in the HTML document to identify questions.
|
|
Value
|
The question’s response value.
|
All parameters are inserted as text so they must be well formed XML. This means that any reserved characters will be escaped. This happens mostly in the ImageLocation parameter. The image cache will typically contain a simple & character which will output as &. If the location is to be used in a script, you will need to convert all occurrences of & to &.
Note For DateTime questions, the HTML Player replaces the <mrData/> tag, converts the date in the Player XML to a VT_DATE based on the Player XML locale, and converts the date back to text using a neutral locale.
Placing the control using the question input ID
You can obtain a question’s input using the FullQuestionName setting as follows:
var QuestionInput = document.getElementById("<mrData QuestionElement="Parameter" Type="FullQuestionName"/>)
You must do this in order to set the question’s response.
Placing the control using a tag with a known ID
If you know the ID of the control, you can access the control using its ID. In the following example, the custom control consists of a slide bar image that has the ID "RailImg". It is displayed on the page by the <mrRef> tag. When you need to refer to the image in the <script> section, use this ID. The image is located using getElementById and is renamed using the FullQuestionName parameter in order to ensure a unique identifier.
<mrRef RefType="img" id="RailImg" src="SliderRail.jpg" style="width: 500px; height: 50px"/>
<script type="text/javascript">
var Rail<mrData QuestionElement="Parameter" Type="FullQuestionName"/> =
document.getElementById("RailImg")
Rail<mrData QuestionElement="Parameter" Type="FullQuestionName"/>.id =
"Slider<mrData QuestionElement="Parameter" Type="FullQuestionName"/>RailImg"
...
</script>
For more detailed examples of how to write custom controls, refer to the Calendar.htm and Slider.htm files in the subfolders of Scripts\Interview\HTML Controls in the UNICOM Intelligence Developer Documentation Library. You can see these custom controls in action by running the NewFeatures script in the Scripts\Interview\Projects\NewFeatures folder in the UNICOM Intelligence Developer Documentation Library.
Working with JSON and XML
When working with JSON and XML, the <mrData> tag is replaced by an appropriate <script> tag that contains the unrendered question representation. The tag will have an id attribute that is identical to the question id, except it is appended with XML or JSON (as appropriate). This allows the script tag to be associated with the question when there are multiple questions on the page.
For example, <mrData QuestionElement=” Parameter” Type=”XML”> would be replaced with something similar to:
<script id=”_Q0_XML” language="text/xml">
<Question QuestionName="Name">
<Response>
<Value>Jonathan</Value>
</Response>
<Properties>
<property name="DIV" value="&lt;div&gt;My Div&lt;/div&gt" type="8"/>
</Properties>
</Question>
</script>
<mrData QuestionElement=” Parameter” Type=”JSON”> would be replaced with something similar to:
<script id="_Q0_JSON" type="application/json">
{
"Question": {
"QuestionName": "Name",
"Response": { "Value": "Jonathan" }
},
"Properties": {
"Property": [
{
"name": "prop1",
"value": "2"
},
{
"name": "prop2",
"value": "3"
}
]
}
}
</script>
Using a custom control
To use a custom control, define the question in the usual way and then add the templates parameter to name the sub-template that contains the control. For example:
AttendDate "When did you visit the exhibition?" templates(Question="calendar.htm") date;
Custom controls in grid and loop questions
Custom controls are appropriately rendered when used within a grid or loop. The HTMLOption ApplySubTemplatesInGrids is used to enable or disable the effects of custom controls in sub-templates for grid and loop questions.
Using the following metadata script as an example:
HDATA -
[
HtmlOptions = "ApplySubTemplatesInGrids"
];
dtelp1 "Loop_Text_Goes_Here" loop
{
red "red",
blue "blue",
green "green"
} fields -
(
AttendDate1 "When did you visit the exhibition?"
templates(
Question = "calendar.htm"
)
date;
) expand;
UNICOM Intelligence will render the results as:
For <mrData QuestionElement="Parameter" Type="PType"/>, the returned result will be:
PType | Result |
|---|
FullQuestionName | _Qdtelp1_Qred_QAttendDate1 |
QuestionName | AttendDate1 |
See also
