Desktop User Guides > Professional > Interview scripting > Writing interview scripts > Page layout facilities > Templates > Displaying response controls side by side with question text > Referring to external files
 
Referring to external files
External files are image files, stylesheets, or files containing Javascript that you want to use in the current template. When you write and test a script using UNICOM Intelligence Professional, you might have these files in a different location to where they will be for live interviews. This means that you have to remember to change the references to the files in the template before you activate. A better approach is to name these files in the template using an <mrRef> or <mrSharedRef> tag. The <mrRef> and <mrSharedRef> tags are similar except that the <mrRef> tag is typically used to reference project specific files while the <mrSharedRef> tag is used to reference files that might be shared across projects (like Javascript frameworks used to support custom controls or large media files).
When a template contains an <mrRef> tag and you test your script in UNICOM Intelligence Professional, the interviewing program looks for external files in folders relative to the location of the template. When you activate the project, the <mrRef> locations are prefixed with the image cache URL or, if you are manually copying the files to the web server, with the relative path to the images folder. The interviewing program for live interviews will find the external files without you needing to make any changes to the template.
<mrRef> tag
<mrRef RefType="type" RefPosition="position" attribute="value" ...> [Text] </mrRef>
type
The tag name that you would normally use to reference a file of the current type; for example, a for hyperlinks, img for images, link for stylesheets, and script for JavaScript files.
position
Either head or bottom and indicates that the reference to the file is put in either the <head> section or the closing body tag of the HTML document that the Player creates for the page. You can use the same custom control more than once on a page without having to repeat the reference for each use.
attribute
An attribute that you would normally specify on the type tag, as follows:
Tag
Attributes Required
<a>
src, alt
<imageCacheURL>
Defines the URL that is used to reference files in the rendered HTML that is sent to the respondent’s browser. For example, <mrRef RefType="imageCacheURL"/> results in the following URL address:
http://<ServerName>/SPSSMR/ImageCache/ImageCache.aspx?Project=<ProjectName>&File=
<img>
src, alt. id is also beneficial. Other attributes might be included as necessary.
<link>
rel, type, href
<script>
type, src
value
The value for that attribute.
The following keywords are case‑sensitive: mrRefTag, RefType, href, src.
Some HTML tags do not support the empty tag format: for example, <script> does not support the <script/> notation, and will not display anything if a tag of this form is read. To avoid this problem, always place some text between the opening and closing <mrRef> tags. If you reference a Javascript program, you can type a description of what the program does.
You can define any number of attributes and values by listing them one after the other, separated by spaces. When the interviewing program reads the <mrRef> tag, it builds an HTML tag by using the information given with <mrRef>. For example, if the <mrRef> tag is:
<mrRef RefType="img" src="logo.jpg" alt="SPSS logo" border="0">Dummy text</mrRef>
the instructions passed to the browser are:
<img src="logo.jpg" alt="SPSS logo" border="0"/>
Similarly:
<mrRef RefType="link" rel="stylesheet" type="text/css" Standard2.css">Dummy text</mrRef>
becomes:
<link Standard2.css" rel="stylesheet" type="text/css"></link>
<mrSharedRef> tag
The <mrSharedRef> tag provides similar functions as the <mrRef> tag, but locations used in <mrSharedRef> are based on a global location.
For Web/CATI Survey and UNICOM Intelligence Author Server Edition:
[FMRoot]\Shared\Content
For UNICOM Intelligence Interviewer - Offline for Windows, UNICOM Intelligence Author, and UNICOM Intelligence Professional:
[INSTALL_FOLDER]\IBM\SPSS\DataCollection\<version>\ SharedContent
Desktop products, such as UNICOM Intelligence Interviewer - Offline for Windows, UNICOM Intelligence Author, and UNICOM Intelligence Professional, use this location as a prefix when referencing files specified in <mrSharedRef>. For example,
<mrSharedRef RefPosition="head" RefType="script" type="text/javascript" src="Dojo//dojo/dojo.js" djConfig="parseOnLoad: true">
Dojo script</mrSharedRef>
is rendered in UNICOM Intelligence Professional as:
<script type="text/javascript" src="C:\Documents and Settings\All Users\Application Data\IBM\SPSS\DataCollection\7\
SharedContent/Dojo/dojo/dojo.js" djConfig="parseOnLoad: true">Dojo script</script>
For server products, such as UNICOM Intelligence Interviewer - Server and UNICOM Intelligence Author Server Edition, the same tag might be rendered and loaded from the shared content area using the ImageCache. For example:
<script type="text/javascript" src="Images/Dojo/dojo/dojo.js" djConfig="parseOnLoad: true">Dojo script</script>
In addition, when referring to JavaScript frameworks like Dojo, you can update the examples to use hard-coded links from a content delivery network. For example:
< script type="text/javascript"
src=" http://ajax.googleapis.com/ajax/libs/dojo/1.5/dojo/dojo.xd.js"
djConfig="parseOnLoad: true">
jQuery HTML control example
The jQuery HTML Control example demonstrates HTML controls built with the jQuery JavaScript library.
For information on installing jQuery, see Readme.htm file that is installed with the UNICOM Intelligence Developer Documentation Library at [INSTALL_FOLDER]\IBM\SPSS\DataCollection\7\DDL\Scripts\Interview\HTML Controls\jQuery.
See also
Writing templates
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.
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 &amp;
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 &amp. If the location is to be used in a script, you will need to convert all occurrences of &amp 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="&amp;lt;div&amp;gt;My Div&amp;lt;/div&amp;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:
This graphic is described in the surrounding text.
For <mrData QuestionElement="Parameter" Type="PType"/>, the returned result will be:
PType
Result
FullQuestionName
_Qdtelp1_Qred_QAttendDate1
QuestionName
AttendDate1
See also
Writing templates