CallWeb - doc

Questionnaire design

Open-end part

An alphanumeric, numeric and other types of open-end component may be attached to any answer category. It is stored in a separate "question" which bears the same name as the originating variable to which the letter "A" is preappended. The definition of open-end parts follows this syntax: list the associated answer category code(s), separated by commas, left of an equal sign and add the open-end instructions right of the equal sign.

Example of an open-end segment:

The syntax of the open-end instruction line is as follows (according to the type of data expected).

Syntax	Use	Explanation
Cwidth	alphanumeric open-end	where WIDTH is the number of characters of the character field
Nwidth.decimals min max	numeric open-end	WIDTH is the number of characters of the numeric field; DECIMALS is the number of decimals; MIN is the minimum acceptable answer value; it may be a constant, the name of a variable in the questionnaire (e.g., Q1 or AQ1) or a Perl expression within braces; MAX is the maximum acceptable answer value; it may be a constant, the name of a variable in the questionnaire (e.g., Q1 or AQ1) or a Perl expression within braces
Mwidth	password data entry	where WIDTH is the maximum number of characters of the character field
Ewidth	e-mail	to open a 40-character text box validated as an e-mail address associated with response code 4, use: 4 = E40
Uwidth	URL	to open a 40-character text box validated as a URL associated with response code 4, use: 4 = U40. The string "http://" is added if absent and the following validation is performed: the string must contain at least one dot but no at-sign
Pwidth	Canadian postal	an example would be similar to the e-mail example above except for the key-letter P
Swidth	first three digits of a Canadian postal code	same as above except for the key-letter S
Twidth	Telephone number	requires 10-digit telephone numbers (non-numeric characters are deleted and the number is reformatted as (xxx)xxx-xxxx)
D min max	date	date fields are always displayed as 8-character text fields; the system expects the date formatted as YYYYMMDD and accepts dashes, spaces and slashes between the three segments; if the respondent browser accepts JavaScript code, clicking in the date box pops a calendar from which the respondent can pick a date. MIN is the minimum acceptable answer value; it may be the name of a variable in the questionnaire (e.g., Q1 or AQ1) or a Perl expression within braces; MAX is the maximum acceptable answer value; it may be the name of a variable in the questionnaire (e.g., Q1 or AQ1) or a Perl expression within braces
H min max	hour	hour fields are always displayed as 4-character text fields; the system expects the time formatted as HHMM and accepts a dash, a space, a colon and the letter h between the segments; MIN is the minimum acceptable answer value; it may be the name of a variable in the questionnaire (e.g., Q1 or AQ1); MAX is the maximum acceptable answer value; it may be the name of a variable in the questionnaire (e.g., Q1 or AQ1)
Iwidth	IP address	to open a 15-character text box validated as an IP address associated with response code 4, use: 4 = I15
Rwidth lines columns regular-expression	regular expression	to open a 7-character text box validated as a course ID which looks like XXX:XXX associated with response code 4, use: 4 = R15 1 15 [a-zA-Z0-9]{3}:[a-zA-Z0-9]{3} In the case of this open-end code, lines and columns MUST be specified. References to regular expressions: 1, 2
Lwidth [condition]	droplist open-end	where WIDTH is the number of characters of the character field; this displays a C-type open-end preceded by a droplist of entries already found in the data for this question. A condition expressed in MySQL syntax and using any data in the dataset can be added between brackets to limit the values shown in the dropdown list (for example [Q1=1] or [AQ1="ABC"]). In use, a selection made in the droplist always supersedes text typed in the open-end box
Fwidth	open-end to upload a file to the server	where WIDTH is the number of characters of the field. The # GENERAL UPLOAD PARMS pound instruction defines the location of the upload as well as the constraints imposed to the size and types of files that are allowed. Files are stored in a MySQL table and, optionally, in the upload directory, and they are named according to the project name, the _telkey, the name of the open-end question and the file extension of the file originally uploaded. There cannot be more than one question with an F open-end per page of the questionnaire.
W		this is a modifier of the C open-end which interprets the limit in terms of words rather than characters in a multi-line open end.

Controlling the size of the data entry box

Most open-end parts default to displaying a 4-line, 40-column box. The size of the box can be determined on a case-by-case basis using the following syntax:

open-end_parameter n_rows n_columns

as in

C30 1 20

which opens a 1-row, 20-column box to contain an alpha-numeric answer of a maximum of 30 characters.

Note: Unless "# Enforce response length" is set to YES, multi-line boxes do not implement the limit as to the acceptable number of characters; in this case, the limit is used only upon extracting a fixed-column file. Single-line boxes do constrain the input to the number of characters specified along with the open-end type. If "# Enforce response length" is set to YES and that the W modifier accompanies the C open-end (e.g., CW100 2 30), the value (here 100) is expressed in words rather than characters.

Numeric open-end parts always open a single-line data entry box; the width of this box is a function of the number of characters allowed by the open-end part definition.

Formatting numeric values

By default, numeric values supplied in open-end parts are not formatted; in fact, extraneous characters like dollar signs and percent signs are stripped from the value stored in the data base and French decimal commas are changed to English decimal points.

Using the following syntax, it is possible to display a formatted version of an open-end part in data entry boxes and in response recalls:

1 = N5 FORMAT=formatxx

where

"FORMAT=" is a keyword that must be supplied as such;
"format" is one of the following values:

NUM: for a simple numeric value using xx decimals
DOLLAR or DOLLARS: for a currency value expressed in dollars
POUND or POUNDS: for a currency value expressed in Sterling pounds
EURO or EUROS: for a currency value expressed in euro
PERCENT or POURCENT or %: for a percentage value
TELEPHONE: for a telephone number stored as a 10-digit number
ZERO: returns z zero-padded version of an integer value

"xx" is the number of decimals to display (except for TELEPHONE where no xx is expected and ZERO where xx is the total number of positions in the final zero-padded integer value).

Therefore, 1 = N6.2 0 100 FORMAT=DOLLAR2 would display the open-end part as a dollar value with 2 decimals.

Note that the field width (6 in the example above) determines the width of the data entry box for a numeric value; this width must be sufficient to allow for the display of the formatted value.

Also note that the "format" keyword can be replaced by a substituted value in Perl (between braces) format; this allows for conditional formatting (e.g., displaying currency amounts as a function of a previous question).