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 are 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 are escaped. This happens mostly in the ImageLocation parameter. The image cache typically contains a simple & character which outputs as &. If the location is to be used in a script, you will need to convert all occurrences of & to &.
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
To obtain a question’s input, use 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 examples of how to write custom controls, see 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>
See also