Table of contents
Quick start
This page provides brief instructions on how to set up your first CallWeb project. It is assumed that you have access to a Web server equipped with CallWeb and to an FTP program to transfer files to the server.
General introduction
CallWeb is a computer system which facilitates the creation of intelligent forms and questionnaires and the management of the collection of data using these forms and questionnaires.
This document reviews the operations of CallWeb in the following sequence:
Much of the CallWeb action is centered around scripts which are text files comprising the definitions of each question in the questionnaire — and then some. There are two ways to create and modify scripts:
The choice of the questionnaire creation and modification is yours; however, this documentation is focussed on the text editor approach (rather than the cwedit module) because it is faster and because it requires more handholding in the beginning.
Questionnaire design
Introduction
A CallWeb questionnaire is contained in a strict ANSI file (only ANSI characters, no word processing commands) where each question is presented in the sequence in which it will be used in the questionnaire. The questionnaire file uses the following naming convention: the extension must be .scw (stands for "script for CallWeb") and the file name (without extension) becomes the project name as far as CallWeb goes. Caution: the case of the letters counts in the name of the file and in the project name.
The structure of a question definition is as follows:
So a real-life example of a question definition would be as follows.
Each segment of the questionnaire definition will now be reviewed.
Question name line
The question name line uses the following syntax (all information must be supplied on a single line):
The question name:
The MIN= parameter is the minimum number of responses expected. Set at zero, it allows nonresponse to a question. The default is 1.
The MAX= parameter is the maximum number of responses expected. Set at a value greater than 1, it forces the use of check boxes rather than radio buttons. The default is 1.
Setting both MIN and MAX at zero creates a question without answer categories. CallWeb displays the question text and note, if applicable.
The NCOLS= parameter determines over how many columns the response categories will span. The overall system default is a single column list. This system default can be overridden by a questionnaire-wide default using the # N COLONNES PAR DEFAUT instruction. Finally, the question-level NCOLS parameter can override all of the defaults on a question by question basis.
The SUBSET=question parameter names the open-end part to use to reduce the list of answer categories using a substring in the code labels (see a full description).
The CODESIN=question parameter names the open-end part to use to reduce the list of answer categories using any criteria from a related data base (see a full description).
The CATEGORIES=question parameter names the open-end part to use as input to create the list of answer categories (see a full description).
The MUST=(condition) parameter specifies a logical condition under which an answer MUST be supplied to the question.
The CORNER=(text) parameter changes the text displayed in the left corner of a table header, for this question only. It can contain one segment for each questionnaire language, specified using square brackets and two-letter language codes (e.g., [EN]).
The KEYWORDS can be any of the following values (logically, some can be used concurrently, others not):
Question text
The question text may flow over several lines. CallWeb concatenates all lines prior to processing the text. Remember that the final appearance for the survey participant, including line wrapping, is controlled by the browser.
Example of a question text segment:
The question text may contain HTML codes. Such codes are interpreted directly by the browser.
Recall of previous answers can be done in the question text. See the Response recall section for the syntax of the recalls.
If more than one language is defined in the questionnaire, language segments of the question must be preceded by the international ISO language code within brackets (e.g., [EN]). A lonely equal sign (=) in a text field can be used to copy text from the default language to any non-default language.
The text of the question can be borrowed from another question by putting the equal sign (=) left of the name of the question from which to copy. However, the copy by equal sign is deactivated if the question text starts with a tilde (~) to allow for UTF-8 encoded email titles — the tilde is silently deleted.
Question note
Notes are displayed after the question text, using a different look; they also specify the text of the line in matrix presentations (see Tables section).
Example of a note segment:
The note text may contain HTML codes. Such codes are interpreted directly by the browser.
Recall of previous answers can be done in the note text. See the Response recall section for the syntax of the recall.
If more than one language is defined in the questionnaire, language segments of the note must be preceded by the international ISO language code within brackets (e.g., [EN]). A lonely equal sign (=) in a text field can be used to copy text from the default language to any non-default language.
The text of the note can be borrowed from another question by putting the equal sign "=" left of the name of the question from which to copy.
Question cloning
When a series of questions that are exactly the same except for the Note field (and possibly the display condition) must be created (e.g., to create a battery of questions presented in a table format), it is possible to use a succinct cloning syntax. This is more easily explained with an example:
This code creates three questions (Q1_A, Q1_B and Q1_C) which share all characteristics except for the content of the Note. These questions may or may not be then placed into pages and/or tables. If different languages are used, each suffixed entry must contain the proper language segments.
The container question (Q1 in the example above) does not exist as far as CallWeb is concerned; only the suffixed questions do. Therefore, while it is possible to copy from and to the suffixed questions (Q1_A and following in the example), it is not possible to copy from and to the container question (Q1 above). This means that, following the same example, this code is legitimate:
and this code as well:
but that this one is not:
We highly discourage building a script containing a regular question (e.g., Q1) AND a container question (e.g., Q1 + various suffixes), or two container questions, with the same name. The compiler is able to deal with such situations but the cwedit module cannot.
Display conditions can also be applied to particular suffixes. Such a display condition is inserted between brackets immediately after the SUFFIX bracket set and immediately before the text of the note. SUFFIX display conditions supersede any display condition that could be attached to the container question. Thus, in the following example:
the display condition on the first statement is [Q1.EQ.1] while the other statements have a display condition of [Q1.EQ.2-4].
The same logic applies to CORNER=(text) parameters which can be added on the SUFFIX line as follows:
The CORNER=(text) parameter changes the text displayed in the left corner of a table header, for this question only. It can contain one segment for each questionnaire language, specified using square brackets and two-letter language codes.
SUFFIX questions are not limited to building tables but they are a very quick way to create a series of questions that share a response set and that can be displayed in table format. It is sometimes useful to insert a title row in such a table, as shown in the image to the right where the PRODUCT and FINANCIAL lines act as titles (no data is collected about them). One simple way to create such titles is to add the letter "T" to the keyword "SUFFIX" (making it "SUFFIXT"). A SUFFIX-title question is imposed a minimum of zero answers (so that it can be left unanswered) and all of its response codes are given a behaviour code of "N" (in addition to any other behaviour code the answer categories may have) so that no response object (a radio button or a check box) is shown in the cells of the title line.
Answer categories
Each answer category must be laid out on a single line. Remember that the final appearance for the survey participant, including line wrapping, is controlled by the browser. The syntax of the answer category line may be either of the following three:
A simple label is automatically assigned a numeric code one unit larger than the previous code, starting from 1. If a number is provided between asterisks, that number becomes the category code. Answer categories need not be ordered according to this number and numbers need not form a sequence.
Answer categories are always given numeric codes. By default, CallWeb reserves four digits to store all answers to regular questions (exclusive of open end parts, see Open end part section) but more can be used. If more are used, the "# Extraction width" pound instruction will be requested by the compiler.
One or more behaviour codes may be added between asterisks following the number code (a number code is required in order to use a behaviour code). Behaviour codes are selected from the following list:
Language segments in answer categories are treated in the same manner as within the question text. A lonely equal sign (=) in a text field can be used to copy text from the default language to any non-default language.
Example of an answer category:
An unlimited number of categories may be defined for each question. Questionnaire compilation is obviously longer as the number of categories increases.
Copying of answer categories
It is possible to borrow integrally the answer categories from another question by inserting a single line in the answer category section. This line contains the symbol "=" and the name of the question from which to borrow such as in the following:
Borrowing questions and questions borrowed from need not be in any particular order in the questionnaire.
Response aliases
Response aliases are elements of text which are different from the main label of an answer and which can be recalled instead of the main label. The syntax of aliases is as follows:
Language codes and behaviour codes can be used along with aliases as in the following example:
In a given set of answer codes, some codes may bear aliases while others don't. A give code can possess an indefinite number of aliases. Aliases must be placed at the end of the response. Aliases are used in recalls using the syntax &QUESTION#alias_label (e.g., &Q1#PW).
"Title" attribute
Special tags can be added to each response category to improve accessibility for the visually impaired. These special tags are placed in the "title" attribute of HTML form objects to better identify them. These labels are defined in a pair of tags <title></title> in the definition of a response category like this:
The "title" attribute can be defined for all categories, some or none, in one language or several, as needed. The default is the response label itself.
Special cases: permutations and inversions
CallWeb features special tools to implement answer category permutation and inversion.
If the keyword "ROTATION" is present on the question name instruction, the answer categories are displayed in random order, suject to the categories with a B behaviour code.
If the keyword "INVERSION" is present on the question name instruction, the answer categories are displayed in the original order or the reversed order, randomly, suject to the categories with a B behaviour code.
Example:
Special case: display conditions on response categories
By default, all response categories are displayed. However, their display can be made conditional to previous answers by inserting an additional line containing a display condition within square brackets. Such a condition line affects the category that is defined on the line following immediately.
In this example, the second category is displayed and available only if the value of Q1 is 1. Answer category display conditions are enforced even when questions are presented as tables.
Simple skips
The definition of a simple skip is... simple: list the answer category code(s) left of an equal sign (=), separated by commas, and the question to skip to to the right of the equal sign. There can be any number of such definitions in a question; each must be on its own line.
Example of a simple skip:
Note that, by default, when questions are skipped, all of the data that they contained are erased. This behaviour can be changed for the whole questionnaire by setting the # Cleaning skips parameter to "no" or for a specific skip by prefixing the destination question with a "~" sign as in
Hyperlink skips with JUMP
It is possible to create a hyperlink to a particular question in the current questionnaire. The syntax is as follows:
This syntax creates a link on "text" (which can part of any of the question elements) that jumps immediately to question "QUESTION" without processing any input from the current page. This type of hyperlink skip does not clean intervening questions.
It is also possible to JUMP to another project using the following syntax: {JUMP:QUESTION,project}.
Finally, it is also possible to JUMP to a specific case of another project using the following syntax: {JUMP:QUESTION,project,telkey}.
These various flavours of {JUMP:} can all produce encrypted links if they are called as {JUMPC:}. (See the cover function.)
Display condition
A display condition is a logical expression which determines whether a question is displayed. It is a way to implement skip logic which is much more robust than simple skips or calculated skips because it is directly associated with the destination question.
The logical expression must use the xBase logical expression format (for experts: the expression can also follow Perl syntax and use any variable in the Perl environment if the condition is presented between "{" and "}" signs). It may use any of the variables defined in the questionnaire, including prepopulated data. Basics of the xBase logical expression format are as follows:
CallWeb takes care of applying the xBase logic on multiple-answer questions.
Remember that all answer categories are numeric. This simplifies the construction of logical expressions.
Example of a display condition segment:
When CallWeb encounters a display condition which evaluates to "false", it erases any data that the associated question may contain in its numeric and open-end portions — however, it does not erase the destination of a CALCUL variable. This is a logical behaviour since that question should not have been displayed to start with — although it may have been legitimately displayed before the user backtracked and changed previous answers. To create a non-displayed variable where data must be stored (such as prepopulated fields), consider using the open-end portion of a BLANK question or the NEVERUPDATE or STOCK question types, or the display condition must be prefixed with a tilde (~) to indicate a non-cleaning display condition (much like the tilde prefix makes a simple skip non-cleaning)..
It is possible to borrow the display condition from another question by inserting a single line in the display condition section. This line contains the symbol "=" and the name of the question from which to borrow such as in the following:
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).
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:
as in
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:
where
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).
Response recall
CallWeb allows for the recall of three types of information in the question text, question note and answer categories:
Recalls can be performed on data stored in any type of question, be that a regular "asked" question or a BLANK question, a CALCUL question, etc.
Example of recall of the answer category selection in question Q1:
Recall pound instruction
Special recall values can be created using the "# Recall" or "# Rappel" instruction. The syntax of the instruction is as follows:
These values are recalled using the following syntax: &#some_label. For example, all "New" icons used in this documentation appear using
To avoid clashes with HTML symbols, some_label must be in capital letters when recalled and it must start with a letter. It can contain letters, numbers and the underscore character.
# RECALL (or # RAPPEL) can use display conditions so that different substitutions are done under different circumstances. Display conditions come right before the recalled value itself as in:
In this example, &#WORD recalls "word" (singular) if AQ1 is less than or equal to 1 and "words" (plural) if AQ1 is greater than 1.
The display condition is expressed in xBase syntax unless it is within braces and it is expressed in Perl syntax. If the display condition contains a closed bracket symbol (as in a Perl regular expression including classes of characters), use double open and closed bracket symbols to delimit it (as in [[{condition}]]). The recalled text of the first matching display condition is used. The condition [ELSE] is always true; it is useful to conclude a series of conditions.
If the recall is followed by a tilde (e.g. &#WORD~), this character serves as a delimiter and is NOT transmitted to the questionnaire page thereby allowing the absence of spacing between the ercall and the text that follows it..
Advanced features
Recalled values are inserted within HTML <SPAN> markers to give them the SUBSTITUT style. This can interfere with the proper display of some recalled values — particularly if the recalled values are placed within hyperlink marks. To avoid the addition of the SUBSTITUT style, insert a tilde character (~) between the recall symbols and the variable name as in the following:
It is possible to recall any variable available in the Perl environment as part of the CallWeb script (see the context data, in particular). The recall syntax is then {$variable}. For example, the following page header would cite the current case access code:
Recalled values may contain recalls. For example, the following instruction is valid and will recall the _telkey value using &#TELKEY:
There is yet another type of recall (although it is more than a simple recall). Any Perl expression (not only variable names) can be displayed where substitutions are allowed using the following syntax:
Using this syntax, one can display the result of complex calculations without having to store them in a CallWeb question field.
Also, it is possible to calculate the result of a recall into a question or as part of an EXECUTE tag. See the "substitue" function on the computed questions page.
Finally, here is a specialized type of substitution: <crypt>text</crypt>. The text between these tags is encrypted using the cover function. There is a special application of this type of substitution. Options inserted in CallWeb questionnaire URLs can be obfuscated using syntax like the following:
which produces
Used in an e-mail invitation, for example, CallWeb encodes the value between <crypt></crypt> tags and associates it to the _crypt URL option. This option is decompressed by CallWeb to recover the initial options and values that the encrypted text contains. It is possible to encrypt only a portion of the URL options if there are advantages to doing so.
Computed questions
BLANK questions
If the keyword "BLANK" is present on the question name instruction, then
A BLANK question can be associated with a display condition to attribute a value to the question conditional on previous answers or to perform complex skips.
Complex skips
A simple skip associated with the first answer category of BLANK questions is honoured. Therefore, BLANK questions can be used to implement complex skips via the display condition, i.e., the complex skip logic is placed in the display condition and the destination of the skip is associated with the first category of the question.
Complex skips can also be implemented via CALCUL questions (see the next paragraph). In this case, a calculation is made, returning a value into the same question (for example; this is not a necessity, as long as there is a value in the CALCUL question to use for skips), and response categories are associated with simple skips. For example, using the contexte system variable, the following code checks whether the current time is before or after noon and redirects the questionnaire flow accordingly:
CALCUL questions
If the keyword "CALCUL" is present on the question name instruction, CallWeb expects the question text to use the following syntax:
This returns the result of the evaluation of "perl_expression" in "output_variable". The "perl_expression" must follow Perl syntax and question names must be prefixed with "$". Please refer to the questionnaire driving Circum Network Inc.'s EchantiCalc script for several examples of use of this feature.
Some special functions can be used in a CALCUL question to perform survey-specific actions. Among them are:
COMPUTE BUTTON feature
It is sometimes useful to perform a mathematical operation right on a page, such as summing a series of numerical answers and displaying the total. This can be accomplished by adding a button on the page; that button performs the operations programmed in a CALCUL question and then redisplays the same page where a recall of values can be performed.
Syntax of the COMPUTE BUTTON:
<COMPUTE BUTTON>CALCUL_QUESTION, text</COMPUTE BUTTON>or<BOUTON CALCULE>CALCUL_QUESTION, text</BOUTON CALCULE>
CALCUL_QUESTION is the name of the CALCUL question triggered by the button. The text which follows the CALCUL_QUESTION and a comma is displayed as part of the button. If this text happens to be the name of a (image) file, that image is used to display the button. In this case, a third portion, still delimited by a comma, can contain the ALT text of the image. A fourth portion, still delimited by a comma, can contain the keyword NOTEST to ensure that the button calculation is activated even if the data on the page do not conform to the normal validation tests.
For example, the following code:
displays this table:
Note: other Web survey packages perform such operations using JavaScript; in keeping with the CallWeb philosophy, no JavaScript is used in programming this feature. Also, the operations triggered by the COMPUTE BUTTON are totally up to the questionnaire designer (e.g., totalling, sum of products, extraction of data, string manipulation) since they are encapsulated in a CALCUL question which may perform any operation and modify any number of fields.
The display condition of the CALCUL question triggered by the button is enforced.
RANDOM questions
RANDT is now deprecated. Please use the random_integer function described above.
If the keyword "RANDOM" is present on the question name instruction, CallWeb expects the rest of the question to use one of the following syntaxes:
The RANDT function returns, in "output_variable", a random integer between 1 and either NUMBER or the value of the variable named "input_variable".
Commenting a script
It is often useful to add comments in CallWeb scripts to provide explanations of what the designer is trying to accomplish. The feat may not be so obvious to another questionnaire designer who may be called upon to modify one's script.
There are two classes of comments in a CallWeb script:
Here are the legitimate locations of printing comments:
Note that printing comments are not compabible with cwedit.cgi and with the copy syntax which uses the equal sign (=).
Questionnaire structure
The basic CallWeb questionnaire contains a series of instructions defining questions and variables. Another set of commands is available to affect questionnaire structure. All of these instructions are located within the questionnaire file and identified with a pound sign ("#") as the first character of the line. Each of these instructions must fit on a single line in the questionnaire file.
Pages
By default, CallWeb displays one question per browser screen. The # GROUP instruction changes this default behaviour. It uses the following syntax:
Limitations: note that skips cannot take place within a page and that simple skips are honoured only on the last question displayed on the page. Also, BLANK questions and CALCUL questions do not perform their feat within pages; these types of questions should be located between defined pages if necessary — in fact, their inclusion in a page is flagged as an error by the compiler.
Tables
By default, CallWeb displays each question sequentially. The # TABLE instruction changes this default behaviour. When a series of variables belong to a matrix:
The syntax of the "# TABLE" instruction is:
Important note: by definition, tables are displayed within pages; therefore, the questions making up the matrix must also be part of a (and the same) page defined with a # GROUP instruction.
The following statements show an example which incorporates all of the circumstances described in this section:
Permutation of questions
By default, CallWeb displays the questions in the order in which they are defined in the questionnaire. This default order can be affected by simple skips and complex skips. It can also be randomised via the permutation of questions.
CallWeb uses the # PERMUTATION instruction to define sets of consecutive questions which are to be displayed in random order. The syntax follows:
In the following example,
Q6 always comes right after Q5, as will Q8 after Q7 and Q10 after Q9. However, the three pairs are offered in random order to respondents as in:
Only two randomly selected questions in the series from Q5 to Q10 are displayed, in random order.
Only two randomly selected blocks of two questions in the series from Q5 to Q14 are displayed. They could be Q7-Q8 and Q11-Q12, for example.
Display conditions affect which variables are displayed throughout the questionnaire, including in permutations.
Parallel permutations
Sometimes, the order of a second set of questions must be the same as the random order of a first set of permutated questions. This is achieved by adding the LIKE= parameter to the second permutation definition followed by the name of the first permutation. For example:
Permutation P2 will always be presented in the same order as permutation P1. Note that the LIKE parameters do not supercede the STEP and LIMIT parameters. The number of items in the two permutations must be the same. Different display conditions may apply and modulate the number of items displayed in a given questionnaire but the order of those displayed will be the same.
Permutation within permutation: embedding permutations at any depth
All of the features described above can be implemented in permutations that are performed within permutated blocks. For example, in the following definitions:
The questions of a permutation cannot overlap between blocks of the exterior permutation. Also, a permutation cannot include questions that are part of an exterior permutation and other questions that are not.
Note: permutation imbedding works only if the names of the permutations are chosen such that, in each case, the exterior permutation comes before the interior permutation, in alphabetical order of permutation names.
Such imbedding of permutations can be done at any depth level (e.g., permutations within permutations within permutations within ...).
Hierarchical projects
Typically, all data for a project are maintained within a single CallWeb data base. There are times, however, when a more complex structure is more appropriate. Let's take the example of a study on family employment. Part of the questionnaire may deal with the household; another part may request information from each household member. Of course, it is possible to set up a large enough number of blocks of questions to accommodate the largest possible household, but this may not be the most efficient way to collect the information. That's where hierarchical projects come into play.
In hierarchical projects, a master CallWeb project acts as the parent data base (in our example, it would deal with the household). One or more "children" CallWeb projects link into the master project to allow as many children "relations" as is required. In our example, each household member would be a child of the master household project. Each such child relation requires a separate CallWeb project; there can be any number of such relationships within a project and children projects may have children projects of their own. For example, one household could have several household members and each household member could have several jobs.
Syntax
Hierarchical projects are defined using RELATION-type questions.
Useful pointers
Respondent user interface
When reaching the RELATION question, the respondent is shown an "Add" button and a "Refresh" button. Upon clicking the Add button, the system continues with a new child questionnaire; once that child questionnaire is completed, the system redisplays the parent questionnaire with a table describing the existing child or children. In this table, a link allows the respondent to correct one of the children or to delete it. The table also displays information from each child using the question text and the text of the answer categories from the child project. Alternative text for questions text and answer categories can be defined in the appropriate segments of the child questionnaire by putting this alternative text between <parent></parent> tags. For example,
*1*This is the text for category 1 <parent>Category 1</parent>
would display "This is the text for category 1" within the child questionnaire but "Category 1" in the summary table in the parent questionnaire.
Extracting data from child records
Child data are stored in a separate CallWeb project. Nonetheless, it is possible to extract information from the child data during the completion of the questionnaire and use it in the parent project.
The &apropos_relations function can be used in CALCUL questions to perform extractions. The general syntax of this function is as follows:
The following table details the existing data types that can be produced and their associated parameters.
Interruption
A button to offer respondents the ability to interrupt the questionnaire may be added on every page of the questionnaire by activating the # Bouton stop instruction. By default, # BOUTON STOP is deactivated as in:
To display the Interruption button, set the instruction to "oui" and add the question where the respondent will be directed upon interruption after a comma, as in:
This instruction will force the display of an Interruption button on each page of the questionnaire. If the respondent clicks that button, they will be directed to question Q99 but, upon coming back into the questionnaire later, they will resume from the page attained before requesting the interruption.
The STOP button can also be displayed conditionally based on a display condition placed in lieu of the Yes first argument, in square brackets. For example:
will display the STOP button only if QTYPE equals 1.
What happens on the page where the interruption is directed is up to the CallWeb script designer. It could be a page without buttons (BACKWALL, CULDESAC and NOSTOP) displaying some message or the URL needed to return into the questionnaire. It could be calculated questions that send an e-mail to the respondent with instructions. It could be anything CallWeb can do with its set of features and questions.
The text of the Interruption button is controlled by the # TEXTE STOP instruction. Each language of the questionnaire may have its own such instruction as in:
The interruption button can also be an image. See the # IMAGE STOP instruction.
Although a STOP block of questions is often used to allow stopping of a questionnaire at one point and resuming from where the interruption block was invoked, it can also be used to branch to a special set of questions from anywhere in the questionnaire and then to go back to the normal flow of questions afterwards. To perform this feat, add a # Stop button instruction, branch to an isolated part of the questionnaire and end this block of questions with a question qith a DESTOP type. The DESTOP question branches back to the question from which the STOP button was invoked.
Questionnaire appearance
The appearance of the questionnaire is controlled by three sources of information: a cascading style sheet, various pound sign instructions and some in-questionnaire parameters.
Page structure and templates
In its simplest form, the CallWeb page (see the example on this page) is a vertical construction that includes the following pieces:
This linear structure and the related pound instructions allow for the creation of a wide variety of questionnaire looks and for the creation of custom pages. While remaining simple, this structure is constraining: it can only be vertically oriented and the integration of visual elements from other sites like corporate Web sites is arduous and limited. The # Template instruction shatters these constraints imposed by the vertical construction of the questionnaire.
Template-controlled page structure
The # Template instruction offers a second page composition method. It identifies an HTML file from which the questionnaire page is built. For example, the HTML file could be a copy of a typical Web page from an organisation or templates of the Government of Canada Common Look and Feel Standards for the Internet standard. In that HTML page, the CallWeb designer places markers that CallWeb substitutes for portions of questionnaire pages. The existing markers are as follows:
These markers can be placed anywhere in the HTML template page. This could allow, for example, to have a Previous page button on the left side of the page and a Next page button on the right side. None of the markers is mandatory and all can be repeated (e.g., there can be several &*BUTTONSH:...)
Technical note: the template page must be built taking into account that the questionnaire is produced from the root directory of the CallWeb instance. Therefore, links to objects (e.g., images, styles, hyperlinks) must be relative to the root directory (which is most flexible) or must be absolute (which is simplest).
Text formatting
CallWeb expects to find a cascading style sheet (CSS) called "style.css" in the directory of the questionnaire file; otherwise, it looks for it in the resources directory (usually gr/) and finally in the current directory (the CallWeb root installation directory in the case of the callweb module or the source utility directory for utilities). The # Stylesheet instruction can also be used to name a stylesheet file for a particular project.
To obtain the official CallWeb look, place this stylesheet in the gr/ directory and the folloing instructions in the etc/usager.conf file:
The explanation of the syntax of CSS is beyond this manual; several good references exist, as well as several Web sites. (http://www.w3.org/TR/REC-CSS1 is a key reference.) The CSS must define some specific styles and it may contain additional ones.
CallWeb styles (note that capitalization of the style name counts in certain browsers and that CallWeb uses all-uppercase style names):
Styles which should be defined:
Other styles:
Colours and layout
A number of pound instructions control the formatting of several aspects of the questionnaire appearance. Another page of this documentation identifies which aspects of the page are controlled by CSS styles.
All tabular outputs (tables and MEMO questions within questionnaires but also parameter tables in utilities, record dumps in cwNav, two-way crosstabs in cwFreq, etc.) are produced by the same protocol. This protocol uses the pound instructions stored within the questionnaire to format tabular outputs. If the questionnaire script does not contain specific instructions for a particular aspect of the tabular output, CallWeb uses the specific installation defaults stored in the instance configuration directory. If instructions are not found there, defaults apply.
Advanced colours and layout
It is possible to control the formatting of question tables in a finer way by using a CSS style sheet. To access this advanced mode, first activate it with the following pound instruction:
# Styles for tables = yes
With this mode activated, the format of table cells is controlled by a collection of style sheets rather than by the pound instructions listed above. The following image documents which style controls which cell. The lines of style definition under the image indicate the statements used in the style.css file (note that all style names are in uppercase letters).
.ORDINARY_CELL_A, .ORDINARY_CELL_A0, .ORDINARY_CELL_A1 { background: #E4EDF9; } .ORDINARY_CELL_A2 { background: #F9FAFF; } .ORDINARY_CELL_B, .ORDINARY_CELL_B0, .ORDINARY_CELL_B1 { background: #FFFFFF; } .ORDINARY_CELL_B2 { background: #CCCCCC; } .SPECIAL_COLUMN0 { background: #FFFFFF; } .SPECIAL_COLUMN1 { background: #FFFF66; } .SPECIAL_COLUMN2 { background: #CCFF00; } .SPECIAL_LINE_A0 { background: #FFFFFF; } .SPECIAL_LINE_B0 { background: #CCCCCC; } .SPECIAL_CELL1 { background: #FFFFCC; } .SPECIAL_CELL2 { background: #CCFF99; }
Here is how this works:
Particular cases: in-questionnaire formatting
Open-end box size
It was earlier stated that the syntax to define an alphanumeric open-end part was
In fact, two other arguments may be used, as follows:
HTML coding
In the question text, the question note and in the text of answer categories, as well as other questionnaire pound instructions such as # ENTETE and # PIED, it is possible to include standard HTML code. This way, HTML tables can be drawn to line up parts of text, hyperlinks can be inserted, images can be displayed, etc.
Final products
Here are examples of appearences that CallWeb pages may take. Of course, this is by no means an exhaustive set.
Field management
The management of a CallWeb field project encompasses a series of operations which are depicted in the next exhibit, along with the tool which is reserved for each step. It is assumed that text editing (we really like TextPad) and FTP transfers are mastered by the project manager (even though the cwdocs module can now be used to transfert files).
The rest of this section describes the five stages of a field project: the initiation of the project, modifications during data collection, case management of data, real-time table production and data extraction.
Permission management
All administrative accesses to CallWeb are controlled by a set of permissions that are based on modules and projects. Access to questionnaires by respondents and access to CATI interviewer modules are NOT subject to this permission scheme.
If no permissions are defined (such as upon initial use of the system), the site manager must access the cwperm.cgi module in the utility directory and define a super-user (see definition below). This super-user can then define additional users according to site needs.
Key concepts
There are two kinds of users: super-users and regular users. Super-users have access to anything and are the only ones who can use cwperm.cgi to create users and set permissions. Regular users can only perform the tasks that they are allowed according to the permissions set for them by the super-user.
There are six types of permissions, as follows:
Users are temporarily locked out of the system if they accumulate three incorrect accesses within a two minute period.
Permission management functions
Once a super-user accesses cwperm.cgi (either directly or via the integrated module), they get a menu similar to the one depicted here. The following functions are available to them:
User management strategies
More to come.
Integrated module
A module called cw, located in the utilities directory, provides a front-end for every CallWeb module available in the said directory (as well as the callweb.cgi module located one level up in the directory structure.
It is highly advisable to use this module to access all of the other CallWeb programs as the required and optional parameters are displayed on screen (no typing, no risk of forgetting arguments).
Utilities located in the main utilities directory (defined in the installation file) have access to all CallWeb projects. To create an instance of a utility program that has access to a limited number of projects, follow the procedure explained in the CallWeb cookbook.
Initiation of a project
Required pound statements
In addition to the definition of questions, a CallWeb questionnaire script must include the following three pound statements:
Physical installation of the questionnaire script file
The physical installation of a CallWeb project requires that the questionnaire script file:
Each CallWeb project creates the following files:
Questionnaire compilation
Once a questionnaire is sufficiently complete (still subject to tests and modifications) and uploaded to the Web server, the cw script is used to activate various functions.
Compilation requires the script name. Six options are available:
The compilation produces a wealth of information which should be studied carefully. Compilation errors are highlighted using the .ERREUR style found in the style.css file and located at the top of the compilation report.
If compilation errors are found, no change is made to the compiled questionnaire or to the response data base.
Compilation may also produce "warnings". Warning messages are elements of information of particular interest that are not errors per se but that could potentially be considered problematic. They include:
Questionnaire comparison
cwCompare can be used to help identify the structural differences between two versions of the same questionnaire. Both versions must be compiled and reside on the same server. cwCompare does not compare the text of the questionnaire — only the structural components (skips, question types, etc.).
Data prepopulation
Once the questionnaire has compiled without error, data may be forced into the data base. This is called prepopulating the data base. This must be used to create access codes in fully controlled data collections. Prepopulation can also be used to insert information about people who will complete the questionnaire, in a controlled-access context; these data can then be used in the course of the data collection.
Prepopulation can be done on an empty CallWeb data base or cases may be added to an existing data base.
Prepopulation data are supplied in a file with the following characteristics:
This file must be uploaded to the Web server and located in the same directory as the questionnaire script file for the project.
To assure the preservation of prepopulated data in all circumstances (include case reinitialization), use the NEVERUPDATE keyword on the question name line of the questions in which data are imported.
In the cw integrated interface, cwprepop can be called by selecting the project name and the name of the tab-delimited data file from drop-down lists.
The cwprepop module can also be used to add data into existing cases (or replace existing data) if the "replace variables" button is selected instead of the "add cases" button in the cw interface. In this context, a value of "--" does not replace the pre-existing value.
Generation of random test data
Once the questionnaire has compiled without error, test data can be randomly generated to verify that the logical conditions of the script work as expected. The script cwgen performs this function. It can be used in two manners:
Each question in the questionnaire is scanned for each case and a random answer is selected for close-ended questions and for open-end parts. Skips, calculations, no-answer questions, etc. are honoured; matrix texts and Test pound instructions are not — and a list of these oversights is produced upon completing the random generation of data.
CallWeb aborts the random generation process if it reaches what appears to be an infinite loop.
File management
The CallWeb cwdocs module allows you to manage your project files on the server without the need for a separate FTP or SFTP program. Like all other CallWeb modules, cwdocs is entirely Web-based and requires no local installation.
With this module, users can create, delete, copy, rename and move directories. They can also upload, download, delete, copy, rename and move files. (To come: deleting to a trashcan.)
This module was written with security in mind. Users are jailed within the CallWeb instance; if cwdocs is called from a directory other than the master utility directory, users are jailed in that directory. They see only files that are reasonably managed in a Web application. They cannot change file or directory permissions.
cwdocs can only modify or delete directories and files that are accessible to the user under which the Web server runs. Therefore, it is possible that users of cwdocs will not be able, for example, to delete files or directories that were created by other Linux users. That's the cost of security.
When a user creates a directory off the root of the CallWeb instance, access to that directory is added to that user's permissions. However, that access permission is not deleted if the directory is erased. It would be deleted if a super-user re-saved the user's permissions in the permission module.
Access to cwdocs will be from a new icon placed in the upper right-hand side corner of the integrated module interface.
Quota management
CallWeb supports completion quotas based on single-character stratification (e.g., gender) and multiple-character stratification (e.g., gender within age groups) as well as compound stratification (e.g., a set of quotas on gender and a set on age groups). Membership to a stratum can be based on pre-populated data as well as on data collected in the questionnaire itself and on a combination of such. Quota targets can be modified at any time during the data collection period. Once a quota is filled, respondents from that stratum are redirected within the questionnaire, for total control over the handling of the situation.
Strata and quotas are defined in a special type of question: the QUOTA type. A question is a QUOTA question if the keyword "QUOTA" is present on the question name instruction. The syntax of the question text is as follows (in this syntax, quotas, commas and equal signs are significant):
The ingredients of the definition of quotas are as follows:
Stratum membership is determined by the value stored in the QUOTA variable. For example, if the QUOTA variable contains a 4 for a particular case, that case belong to quota number 4. Response categories may be defined (and labelled) for QUOTA questions but this is not mandatory. If they are defined, the labels are used by the report modules.
A particular quota is deemed complete when the number of cases with a value greater than zero in the "complete" variable is equal to or greater than the target stated in the QUOTA question for that stratum.
QUOTA questions are subject to display conditions: the quota criteria are activated only if the display condition is true.
Several QUOTA questions may be used in a questionnaire; they are used if and when the flow of the questionnaire reaches them. Therefore, a first set of quotas could be imposed on a first characteristic, early in the questionnaire or based on prepopulated data, and a second set of quotas could take effect later, maybe based on data collected as part of the interview or calculated data.
The following constraints apply to QUOTA questions:
E-mail notification
The cwemail module sends initial notification and reminders via e-mail. It uses a question as a template which may include recalls of values stored in the survey data base (probably via pre-population). It features tools to select subsets of cases according to any data in the data base as well as subsets defined by ranges of position numbers in the data set. Therefore, it is possible, for example, to send an initial invitation to all participants which includes their custom access code and which is delivered in their preferred language, and to follow-up with those who have initiated but not completed the questionnaire a week later with a motivational message which could be different from another follow-up to those who have not accessed the questionnaire at all.
E-mail notification is based on a special questionnaire variable which contains the title and text of the message to be broadcast. The following rules apply:
The following are required for the e-mail notification operation:
One option, offered interactively, allows for the simulation of the mailing: messages are displayed on screen but neither sent out not timestamped in the data file.
Managing bounced e-mail messages
Using the # Send bounces to instruction, bounced messages can be sent to any arbitrary destination, or to the cwbounces.pl script which logs bounced messages and attempts to signal them in the CallWeb data set. To activate this latter function, follow these instructions:
Automatic e-mail delivery
Using parameters set in # Auto email instructions, CallWeb can be asked to scan project data on a regular basis (say, every hour) to identify records which meet a certain condition, and to send them an e-mail message. The e-mail message itself follows the rules outlined above regarding formatting and recalling of record values. The generix syntax of this instruction is as follows (note: the equal signs and the commas are delimiters; use them as described in this example):
Here is a real life example:
One CallWeb project can contain any number of such automatic e-mail instructions (make sure they have different identifying strings) so that various circumstances (defined by the selection condition) can trigger different e-mail messages.
Limited substitution capabilities exist within the "selection" clause — essentially via the contexte list of data fields. For example, to trigger a message on January 1, 2009, the following condition could be used:
Questionnaire completion
Once the questionnaire is compiled — and data are prepopulated, if necessary — potential participants may be invited to complete the questionnaire. There is a variety of technical ways to open access to a questionnaire. Some are reviewed.
The most transparent way to access a CallWeb questionnaire is with the following Web instruction which applies to a fully open questionnaire or one where participants are provided with access codes on the fly:
If an access code (see the # Survey type pound instruction) must be supplied to open a questionnaire, the same instruction may be used (and the system will prompt for the access code) or the instruction may be completed as follows:
If the questionnaire must be initiated at a location other than the first question (for a blank questionnaire) or the last question displayed (for a return questionnaire), the URL may contain a specific entry point as follows:
An appendix to this documentation lists all available URL options available when calling a questionnaire.
The instruction to access CallWeb may be hidden on a static page using a form or a hyperlink or using Web redirection tools like go.97.ca or custom built Web scripts.
Extremely short URL syntax
CallWeb also supports an extremely short URL syntax which ensures that links are not cut off in invitation e-mail messages. The syntax is as follows:
or
if no access code is required or supplied within the link and the questionnaire starts at the beginning or at the last question displayed.
In fact, even the language parameter is optional; if it is not supplied, the default language defined in the questionnaire script is used. Note that CallWeb uses as the language parameter the first value that is made of two (and only two) letters (such that, if the project name, the _telkey or the _debute question are two-letter codes, the language parameter must be specified and must come before the other two-letter code). The other parameters must be in the order defined above.
Given the proper set up of the Web server, it is also possible to dispense with the explicit call to the callweb module (in Apache terms, by making callweb.cgi one of the DirectoryIndex entries). the link could then be shortened to something like:
Modifications during the course of a project
Any modification may be made to the questionnaire during the course of a project and without interrupting the collection of data. Of course, adding a question won't suddenly make data appear in completed questionnaires, but the system can regenerate itself to take modifications into consideration from there on and keep as much of the previously collected data as possible.
A simple compilation is sufficient to affect changes to a questionnaire:
The compilation procedure reports whether a structural data change is required. If so, it will be performed only if the "structural change" checkbox of the integrated module has been selected; otherwise, the compilation will terminate with an error and no change will be made either to the compiled questionnaire or to the data base.
Case management
Sometimes, data must be accessed on a case-by-case basis to look up responses, to correct them or to code open-ends. CallWeb offers cwNav to do just that. A call to cwNav (which stands for Navigate) is done via the integrated interface by providing the project name in the "Display data" section of the cw module.
The cwNav tool displays a menu to select cases and to select a subset of questions to display. Provided the right access codes are provided, the interface offers two ways to delete cases, three to view a case individually and three to open a case for editing.
Mass editing
Of particular significance is the mass editing mode that is activated by making the proper selection in the options menu. In mass editing mode, all displayed fields of all displayed cases are editable directly in a grid-like format. This could be particularly useful to display open-ended responses and a series of open-ended coding variables to perform a content analysis of the textual responses.
In mass edit mode, if _res (the most recent call result) is selected for editing, a new line appears in the menu. It offers the possibility of changing all existing _res values among selected cases to a new value. A dropdown list of possible _res codes is offered. If one of these codes is selected, all cases with _res values within the scope of the case selection are changed to that chosen value.
If a multiple-response question is edited in boxed mass edit mode, different values can be separated by commas or spaces. CallWeb edits the data upon Action! to delimit the values using "μ" characters. This is useful to code open-ended questions.
Reapplying CALCUL questions
cwNav also allows to reapply CALCUL questions (that is, to compute or recompute a calculation) on existing cases. After possibly identifying the cases to use in the operation using the case-selection portion of the menu, select a CALCUL question from the appropriate drop down list in the cwNAV interface (this feature is only available if the write-access password has already been supplied, if one is defined) and click Action!. Then key in the "UPDATE" keyword (upper case) and click Action! again.
Technical note: when reapplying CALCUL questions using cwnav.cgi, system variables (with names starting with an underscore) from the case data (such as _prepops and _h1) must be capitalized in the CALCULations (which is not the case in the CALCULations which take place during the performance of the questionnaire). One way around this issue for CALCUL questions which are intended to be used in cwnav.cgi as well as in the regular CallWeb context is to double up the name of the field and to put an "or" bar between the two as in $_prepops|$_PREPOPS. In Perl parlance, this means "use $_prepops if it exists, otherwise use $_PREPOPS".
Assigning values based on calculated expressions
This module also includes the ability to assign values to a variable based on a MySQL expression. Any field in the data base can be reassigned. Any type of assignment may be performed as long as the syntax of the expression is legitimate from MySQL's point of view and as long as the result of the expression conforms to the selected field data type. The following rules apply:
For example, it is possible to assign to AQ2 a value that is twice that of AQ1 with the following expression: AQ1*2. Also as an example, this operation could be performed only on cases where AQ2 is larger than 10 by making the proper selection in the options menu.
Use of this feature should be left to exceptional circumstances as the control of the assignment rests entirely with the user; none of the normal CallWeb data validation procedures are applied.
Real-time results
The cwFreq tool builds univariate frequency distributions, histograms, two-way tables and descriptive statistics in real time. It performs its duties equally well on numeric and on alphanumeric data. A call to cwFreq (which stands for Frequencies) is done via the integrated interface by providing the project name in the "Build tables" section of the cw module.
The cwFreq tool displays a menu to select cases and to select a subset of questions to display. Provided the right access codes are provided, the interface offers access to cases for editing.
Extraction of data
Data may be extracted at any time from the CallWeb data base and formatted for use with popular data analysis software. CallWeb can create:
The cwExtr (which stands for Extraction) tool is called from the integrated interface. cwExtr compresses the files it extracts into a zip archive. It either sends this zip file by e-mail to the address identified in # Send extractions to or it leaves the extraction on the server. The destination is selected in the cwExtr parameter interface.
In database-to-database mode (requested from the integrated interface, cwExtr can copy data from one CallWeb data base directly into another CallWeb data base. The source and destination data bases can reside in separate servers but they can also be in different instances of CallWeb on a single server or in the same CallWeb instance. In this mode, new data records can be added to the destination data base and existing data records can be updated with the data in the source data base. It is possible to select only a subset of fields to be transferred but system fields (the name of which starts with an underscore) are always transferred. All fields selected for transfer from the source data base must exist in the destination data base but the data base structure may differ between the two CallWeb projects otherwise.
Data base destruction
Once a project is completed and the data have been secured by an extraction, the cwdestruction module is used to get rid of the data base itself. The program requests that the keyword "DESTRUCTION" be typed in to confirm the intentions of the user. The write-access password must also be supplied if it is defined in the cwNav write password pound instruction.
This module is the only one (other than cwcompile, of course) which works even if the questionnaire file is not available. This allows for the destruction of data bases even if the questionnaire file was deleted (or otherwise rendered inaccessible) before the data base.
There is no further confirmation of the destruction command, so be extremely prudent in using this module.
Performing back-ups
CallWeb data reside in MySQL data bases which are not readily available to back-up software. The cwArchive modules perform timed back-ups of data files and place the zipped archives in the project directory.
The cwArchive back-up planning tool is available from the cw integrated module. It lists each CallWeb project based on the existence of MySQL data tables. For each project, hourly and daily back-ups can be planned. The number of hourly and daily back-up files to conserve on disk must also be set. It is also possible to provide an e-mail address where the back-ups will be sent.
By combining these tools, it is therefore possible, for example, to back-up the data file at 11AM, 2PM and 6PM while keeping 6 of these back-up files on disk (thereby providing two days of fail-safe back-ups) and to send a back-up set every night to an off-site e-mail address.
The first line of the back-up planning table defines the default behaviour that is applied to all project that don't possess their own planning strategy — this way, once the default strategy is defined, it is not necessary to worry about defining a back-up strategy for each new project.
cwArchive implements the following efficiency procedures:
The cwArchive.pl module must be referenced in the /etc/cron.hourly directory to that it is started up every hour. The text on the installation of CallWeb offers more information in this regard.
Appendix A
Pound instructions
Pound instructions define various elements of the behaviour of CallWeb. They start with a pound sign (#) which may be preceded by spaces or tabs for the sake of clarity. A given pound instruction may be split over several lines by starting the second and following lines with a pound followed by a greater-than sign (#>); this combination may be preceded or followed by spaces or tabs.
* This value is used internally by CallWeb.
Appendix B
Installation instructions
Server software requirements
CallWeb needs the following to be installed on the server:
Questionnaire designer client station
The following software has proven very valuable in editing CallWeb .scw files:
File locations
System configuration file
The system configuration file and the project configuration files may contain several parameters controlling the in-depth behaviour of CallWeb and its default appearance. Some parameters must be supplied in one file or the other. Mandatory parameters are (parameters are case-sensitive):
The following are mandatory in CATI mode:
The following are mandatory to connect an Asterisk server to CallWeb:
The following are mandatory in robot mode:
The following are mandatory in connecting CallWeb to a predictive dialer:
In a project-specific configuration file, if the MySQL host is redefined, the following entry is mandatory:
Any pound instruction can be inserted in the system configuration file. All such pound instructions found in the system configuration file are inserted at the beginning of all questionnaires upon compilation. This means two things:
In addition, optional configuration parameters include (parameters are case-sensitive):
Automated tasks
A number of tasks are performed automatically by various programs once they are scheduled in the cron feature of a Linux server. They are as follows.
One last script cwbounces.pl is a special case. Its purpose is to intercept bounced messages and to update the CallWeb data base with an indication of this bounce. It is not located in the cron system but rather, it is called by Sendmail upon receiving bounced messages for the "bounces" address. A single instance of this program services an entire server and all instances of CallWeb installed on it. Here are detailed installation instructions:
Note that, for cwbounces.pl to work with a given instance of CallWeb on a server, the following directories and files must be readable by the user or the group "mail" (under which Sendmail runs):
Daemon mode installation
The CallWeb daemon mode is three times as fast as the base mode. In daemon mode, CallWeb runs constantly in the server background, waiting for questionnaire page request files to be placed by cwx.cgi (which replaces callweb.cgi in daemon mode) in the spool directory. The CallWeb daemon processes these request files and places the HTML code of the next questionnaire page in the spool directory for cwx.cgi to display to the respondent.
To use the CallWeb daemon mode, follow the installation instructions and then call the questionnaires with the cwx.cgi module instead of the callweb.cgi module.
CallWeb daemon mode installation instructions:
The CallWeb daemon is started, stopped and restarted with the command service callwebd start|stop|restart. The daemon status can also be probed with service callwebd status. When the "restart" or the "stop" command is issued, the CallWeb daemon waits until the request queue is empty before proceeding with stopping the daemon.
The CallWeb daemon configuration file is /etc/callweb.conf. The CallWeb daemon must be restarted for changes to the configuration file to take effect. Its content is as follows.
Multi-server configuration (CallWeb cluster)
Using the configuration files, it is possible to develop various server implementations of CallWeb. First, CallWeb can run on the same computer as the data base server if the "hote" parameter of the main CallWeb configuration file points locally:
hote = localhost
Another CallWeb server could use the same MySQL server by specifying a distant address for the "hote" in its main configuration file:
hote = 99.99.99.99
If the two CallWeb servers use the same "client" parameters in their main configuration file, both servers will "see" projects from both origins; that would be the typical setup of a multi-site CATI system. If they use different "client" parameters, each CallWeb server will only see its own projects.
Each project used in a multi-server configuration (also called "CallWeb cluster") should possess a # Master compilation server pound instruction to protect the integrity of the questionnaire files. Parallelism of the questionnaire files across servers is ensured by the # Copy questionnaire into instruction which dispatches a copy of the questionnaire (and an empty .scw file) to distant servers (there should be one such instruction for each of the distant servers in the CallWeb cluster which will use the questionnaire). This dispatching of questionnaires requires that a direct SSH connection (with exchange of public keys) exists between the servers; see below for the procedure.
In a multi-server configuration, re-compilation of the .scw script involving changes in data structure should be performed on the computer running the MySQL server. Otherwise, while the compilation will be performed and the data base adjusted if required, no backup of the data will be kept before modifying the data structure.
Note that, for bi-mode projects, the CATI CallWeb server must be the Master for compilation so that the .ccw file is correctly processed.
Exchange of public keys between servers
This procedure must be carried out only once per server connection. In brief, here is the procedure for the exchange of public keys between Linux servers:
Appendix C
URL options
It is highly advisable to use the cw integrated module to access the various components of CallWeb (for simplicity and safety). Nonetheless, there may be circumstances where direct coding of URLs is necessary. The following tables provide the URL options which can facilitate the creation of specialized menus.
URL options for the callweb module
URL options are used when building the URL to call CallWeb. Such URL could look something like: <http://blabla.ca/callweb.cgi?_proj=test&_demo=1&_lq=1&_print=1&_debute=Q1>. CallWeb also offers a short syntax to call questionnaires.
Appendix D
Recent changes and additions
Appendix E
Formatted tabular output syntax
In CallWeb, virtually any character string to be displayed on screen can be formatted as a table using the colours defined for the questionnaire (see Colours and layout) using a standardized tool. This simplifies the creation of tabular layouts and ensures consistency of look throughout the questionnaire. Of course, existing recall protocols can be used within these formatted tables.
To insert a table into a string (the question text segment, for example), surround the table instructions with double braces, i.e. {{ and }}. Within these delimiters, insert the text to be displayed as a table and the special instructions described below (the following table was created using this feature).
The table above was created with the following instructions.
Annexe F
Security Features
CallWeb incorporates several layers of security features. They are reviewed in this section.
Appendix G
Context data
CallWeb stores the following context data in the %contexte hash, referenced as $contexte{key} in Perl expressions.
Appendix H
TEST pound instruction
The TEST pound instruction defines a logical test which triggers an error message. This generic statement comes in addition to CallWeb built-in tests such as tests on the minimum and maximum number of responses, on the coherence of the selection of answers, on MUST conditions, on table conditions, etc.
Syntax:
Where
Any given question may trigger more than one test.
Examples:
This will display the error message above the table to which AQ1 belongs if the 3 responses don't total 100.
This will display the error message above Q10 if Q5, Q6 and Q7 were answered while Q8 and Q9 were not. Note that questions Q5 to Q9 need not be on the same CallWeb page as Q10.
Appendix I
System messages
The "System message" pound instruction redefines a system message for a particular questionnaire.
At the time of this writing, there were 43 system messages, available in five languages: English, French, Spanish, German and Portuguese. Another language could be added by re-defining each of the system messages and using the proper ISO-language code between brackets. The table below lists the English and French versions of the messages and associates with each its numeric ID which is used in calling "# System message".
Some messages incorporate variable information such as the minimum or maximum number of responses, or the minimum or maximum allowable value, or the mark of a plural. These are indicated in the messages using a ranking number between brackets. Make sure to not omit them in re-designed messages and to place them in the correct place for the language of your choosing. Use the French of English versions below as indications of the type of information represented by these replacement marks.
Appendix J
System variables
In utility modules like cwfreq and cwnav, all lists of variables, questions and fields begin with a series of entries which start with an underscore (e.g., _telkey, _date); they are system variables which are available in every CallWeb project. The meaning of these system variables is explained in the following table.
Appendix K
Weights (deprecated)
A WEIGHT question calculates a weighting scheme based on the known marginal distribution of some variables, using the rim weighting algorithm initially proposed by Deming and Stephan (W. Edwards Deming and Frederick F. Stephan, "On a Least Squares Adjustment of a Sampled Frequency Table When the Expected Marginal Totals are Known", The Annals of Mathematical Statistics, volume 11, number 4, December 1940, pp. 427-444). This weighting scheme is stored in the open-end part of the WEIGHT variable; it can be extracted or used in cwfreq to create weighted frequency tables.
Weighting instructions are placed in the question text segment of the question. Each weighting question is listed followed by the weight for each value of the question separated by slashes and ordered according to the numerical list of categories. Questions are separated by commas. Here is an example of the syntax:
QWEIGHT WEIGHT%QSEX=0.5/0.5/0QLANGUAGE = 0.80 / 0.08 / 0.12 / 0 / 0
Weight calculation supports the following (cwnav) options:
The following rules are enforced:
Weights are calculated in cwnav by selecting from the WEIGHT variable list shown after the write-access password is entered.
Weights are used in cwfreq by selecting from the WEIGHT variable list offered.
Appendix L
Basic HTML tags
HTML colours
In HTML, colours are defined using RGB (red, green and blue) codes. RGB codes are made up of three pairs of hexadecimal (from 0 to F) characters, followed a pound sign (which is unrelated to CallWeb's pound instructions). Each pair of hexadecimal characters indicates the amount of each base colour (red, green and blue) in the specific colour combination. For example, #FFFFFF is white because it includes a maximum of each of red, green and blue colours; #000000 is black because there is none of any of the colours.
There are many useful on-line tools to help with colour selection. ColorPicker, the Febooti on-line colour chart and the Doughnut Color Picker return colour codes for millions of colours using a familiar interface. Other tools like ColorScheme Designer, Color Palette Creator and kuler help select colour schemes. Finally, pixie (Windows executable) and Colorzilla (Firefox extension) identify colours that the mouse points to on screen.
Basic HTML codes
Appendix M
Project initiation checklist
The following checklist is offered as a guide to control that all steps of the project installation process have been completed. A CATI-specific project initiation checklist is also available.
Appendix N
File types
A CallWeb project directory often contains a series of files that testify to the unfolding of the project. Here is a list of files that can be found in project directories.