Programmatically inserting text into labels
You can use named inserts to insert any text into a label which you can then display during the interview or write to a file.
Variable response texts shows one example of using named inserts to present a respondent’s Other answer in the response list for a later question, but you can use named inserts in other situations too. For example, if you are writing an error handler that logs an error report to a file, you can define the fixed text of the message as an
info item in the metadata section (which makes it available for translation) and use named inserts to mark the points at which interview-specific information should be inserted when the message is written out.
When defining the fixed text in the metadata section, mark the place at which the variable text goes by typing:
{<marker>}
where <marker> is a word of your choice. Make the marker’s name similar to the text that will be substituted in its place, but if you are trying to write portable or reusable code this might not always be possible. If you need to make more than one substitution, choose a different marker for each one.
Next, add statements to the routing section that insert the appropriate values in the markers you have defined.
<item_name>.Label.Inserts["<marker>"].Text = <value>
where:
▪<item_name> is the name of the item in which the marker is used.
▪<marker> is the name of the marker whose value you are defining.
▪<value> is the value you want the marker to have.
Example
Going back to the error handler example, here is the error message text from the metadata section. It has been split over several lines for readability. If you want to use this example, type the entire <a> tag on a single line, as line breaks will cause it to be treated as plain text:
ErrorDisplay "A processing error has occurred. If you have a
moment to spare, please help us to resolve the error by clicking
<a "mailto:_helpdesk@unicomsi.com?subject=Error in survey
{ProjectName}
&body=Please enter any details about what happened here:%0A%0A
Technical details:%0ATime of error (UTC) = {TimeStamp}%0A
Project = {ProjectName}%0ARecord identifiers = {Serial},
{RespId}%0A
{ErrorDetails}"">here</a> to send an email description of the
problem.
<br/><br/>Please return later to try again. Thank you for
your help."
info;
The marker names are in curly braces; they represent information that is specific to each interview. The markers are defined in the error handler code in the routing section. Some values (for example, the project name and the respondent ID) come from properties that are maintained by the interview scripting language; other values (for example, the time), come from external functions.
ErrorHandler2:
Dim err_msg
' Write message to log file
err_msg = "Error executing script (line " + _
CText(Err.LineNumber) + "): " + Err.Description + " (" + _
CText(Hex(Err.Number)) + ")"
Debug.Log(err_msg, logLevels.LOGLEVEL_ERROR)
' Populate inserts for user message
ErrorDisplay.Label.Inserts["TimeStamp"].Text = Now("UTC")
ErrorDisplay.Label.Inserts["ProjectName"].Text = IOM.ProjectName
ErrorDisplay.Label.Inserts["Serial"].Text = CText(IOM.Info.Serial)
If (IOM.Info.RespondentID = "") Then
ErrorDisplay.Label.Inserts["RespId"].Text = "Unavailable"
Else
ErrorDisplay.Label.Inserts["RespId"].Text =
IOM.Info.RespondentID
End If
ErrorDisplay.Label.Inserts["ErrorDetails"].Text = err_msg
' Display message
IOM.Texts.InterviewStopped = ErrorDisplay.Label
' Terminate interview and flag as failed due to script error
IOM.Terminate(Signals.sigError)
If an error occurs, the respondent sees an error page with an explanation and a click here link. Clicking the link opens the respondent’s mail program with the template message displayed:
See also
