homefeaturesexamplesDOCUMENTATIONblogpricingcontact us
technical documentationCATI documentationcookbookrobot

Questionnaire structure

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.

  • In a RELATION question, the minimum and maximum number of answers refer to the number of child records. Setting the minimum and maximum to 1 and 3 will ensure that the respondent enters at least 1 child and no more than 3. The default values are 0 and 9999 respectively.
  • The number of child records is stored in the RELATION question upon moving to the next page.
  • A RELATION question has no text of its own; therefore, it would normally be inserted in a multi-variable screen which would provide context and explanations. Note that a RELATION question cannot co-exist on the same page with other questions collecting answers; the reason for this is that the add and modify relation buttons open a new questionnaire without first saving the information in the current page of the parent questionnaire.
  • The question text segment of the question is used to pass along the RELATIONship parameters using the following syntax (where commas and slashes count!):
parameter value exemple explanation
child_project=children,name of the CallWeb project
parent_telkey_varname_in_child_project=parent_telkey,name of the child project variable that will contain the parent _telkey code
display_from_child_project=Q1/Q2/AQ3,the slash-separated list of child values displayed in table format within the parent project. Each question name listed can be preceded by a display condition within square brackets. If the display condition requires a comma, insert it as &#comma; (with the trailing semi-colon); if it needs a slash, inset it as &#slash; (with the trailing semi-colon).
copy_into_children=Q11/Q12/AQ13,the slash-separated list of values to be copied from the parent to the children (they must exist in both projects and be attributable in the child project [see # ATTRIBUTABLE QUESTIONS])
child_subset_in_sql=Q1=1,(optional) the expression must be a valid WHERE MySQL expression (without the keyword "WHERE"); if present, this parameter determines the list of child records displayed by the RELATION question; it supersedes the selection of child records containing the "parent_telkey_varname_in_child_project" value. The expression cannot contain a comma since commas act as separators.
erase_question=QCONFIRM,(optional) this is the name of a question in the parent questionnaire that is used to request confirmation of the deletion of a child record. In the absence of this parameter, deletions are done without confirmation. The "erase_question" must possess the ERASEREL question type. It is not shown in the normal flow of the questionnaire and it is automatically made BACKWALL.
erase_code=1,(optional) this is the numeric code of the "erase_question" question that indicates that the request for deletion was confirmed; it is mandatory if "erase_question" is defined. For example, if the question is "Do you really want to delete this record?" and if "Yes" bears code 1, then "erase_code=1" would be used in the RELATION question.
erase_calcul=QCALCUL,(optional) this is the name of a CALCUL question that is executed after deleting a child record when "erase_question" equals "erase_code".
read_also=Q99,(optional) a slash-separated list of child values read from the child record and that are necessary for some substitutions.
order_by=Q99,(optional) a slash-separated list of child values used to sort the child table.
crypt
=yes,(optional) yes or no, whether or not the links to the children are crypted.

Useful pointers

  • Use an open-end part (e.g., APARENTCODE) to store the many characters of parent_telkey_varname_in_child_project.
  • Variables copied from the parent to the child (parent_telkey_varname_in_child_project and copy_into_children) should probably bear a STOCK type so that they are not displayed.
  • In the child project, variables copied from the parent must be listed in a # Attributable questions instruction so that the child project accepts the values.
  • There are default text values for the buttons to add, modify or delete a child as well as to refresh the page displayed. These text values can be customized for a project using a series of pound instructions prefixed with # Text relation.
  • For technical reasons, the "refresh" button of RELATION questions is NOT compatible with the DEMO mode. The same can be accomplished in DEMO mode by backtracking to the question prior to the RELATION question and going forward again.
  • Recalling a RELATION question as &@QUESTION inserts the number of children in the recall location. Recalling as &QUESTION inserts a complete table of the children.
  • The child project must include a "# URL" instruction pointing back to the parent questionnaire. The URL link should use a syntax like this one:
    # URL = callweb.cgi?_proj=PARENT_NAME&_lang=EN&_telkey={$APARENT_TELKEY}&_debute=RELATION_QUESTION
    where PARENT_NAME is the name of the parent project, APARENT_TELKEY is the name of the child variable containing the parent telkey (parent_telkey_varname_in_child_project, above) and RELATION_QUESTION is the name of the RELATION question in the parent project.

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 children 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:

    DESTINATION = &apropos_relations("RELATION_QUESTION","DATA_TYPE","OPTIONAL_PARAMETER")

The following table details the existing data types that can be produced and their associated parameters.

Data typeParametersExample
N(none)&apropos_relations("REL","N")
TOTAL or SUMchild variable to sum up&apropos_relations("REL","TOTAL","AQ1")
MINchild variable from which to get the minimum&apropos_relations("REL","MIN","AQ1")
MAXchild variable from which to get the maximum&apropos_relations("REL","MAX","AQ1")
AVGchild variable from which to get the average&apropos_relations("REL","AVG","AQ1")
STDchild variable from which to get the standard deviation&apropos_relations("REL","STD","AQ1")

   

e-mail technical support!