INI file parameters

Search:

Introduction

The project.ini file is used to set parameters that define or control some aspects of the questionnaire or survey process. Examples include defining the mode of access to the questionnaire or listing the style sheet(s) to be used. A value is associated with each parameter using syntax of the form

%PARAMETER_NAME%=numeric_value %PARAMETER_NAME%="alpha_string"

  • PARAMETER_NAME - Identifier that must start with a letter and contain only letters, numbers or the character "_".
  • value - the values associated with each key may be numbers or character strings: character strings start and end with quotation marks (").

Alphabetic list of ini file parameters: A B C D E F G H I J K L M N O P Q R S T U V W

ACCESSMODE: mode of access to the questionnaire

There are 3 types of access :

  • Free (no control on who can answer the questionnaire) - code 1 or code 6 (for creation of unique encrypted GKIDs)
  • Login (needs an identifier to connect to the survey) - code 2 or code 5 (more secure, ids included as hidden field)
  • Login (needs an identifier and a password) - code 3

    Note: In %ACCESSMODE% = 3, when the page is validated, the passwords entered are saved in lowercase. If they are passwords in capital letters, they should be saved in lowercase in the login.csv, so that they are recognised.

Free access

%ACCESSMODE%=1 %ACCESSMODE%=6

Access with identifier

%ACCESSMODE%=2 %ACCESSMODE%=5

Access with identifier and password

%ACCESSMODE%=3

The login identifiers are put in a login.csv file in the project .rsc directory.

CATI: Uses URL of the survey without ID with entry of the identifier by the interviewer on the survey access page (%ACCESSMODE%=2). (Internal GIDE example: https://khaki.gide.net/surveys/svn/gide/p1705mds009_gazette_palais/dsc_cati/)

GENERAL REMARK: Several URLs can be used to access the same survey:

Free access:

  • Long URL: https://server_name.com/cgi-bin/cawi/Q/surveyname/surveyname.pl

  • Long URL without access through the login.blk page: https://server_name.com/cgi-bin/cawi/Q/surveyname/surveyname.pl?CW_start=-1 or: https://server_name.com/cgi-bin/cawi/Q/surveyname/surveyname.pl by adding %SKIPHOME%=1 to the .ini file).

  • Short URL: https://server_name.com/cawi-surveyname/

  • Short URL without access through the login.blk page: https://server_name.com/cawi-surveyname/go/ or: https://server_name.com/cawi-surveyname by adding %SKIPHOME%=1 to the .ini file).

Access With identifier:

  • Long URL: https://server_name.com/cgi-bin/cawi/Q/surveyname/surveyname.pl?login=gide0001

  • Long URL without access through the login.blk page: https://server_name.com/cgi-bin/cawi/Q/surveyname/surveyname?CW_start=gide0001

  • Short URL: https://server_name.com/cawi-surveyname/gide0001

  • Short URL without access through the login.blk page: https://server_name.com/cawi-surveyname/go/gide0001

AUTOFOCUS: to be documented

Back to start

BACKHOME: return to the questionnaire home page

Use BACKHOME to allow or disallow return to the the start page of the questionnaire with the [previous page] button of the navigation bar (nav.blk).

Return allowed

%BACKHOME%=1 Return not allowed

%BACKHOME%=0 (Set the parameter %NOBACK%=1)

BGROWS: background colour for questions

Define the style background-color for the question (qbody)

%BGROWS%="#CEE5EF:#B4D9ED" The different colours are separated by :

Back to start

CACHE: to be documented

CLICKCELL: cells "clickable"

In grid questions (items in lines and responses in columns), the parameter CLICKCELL can be used to indicate that the respondent will be able to click in the cell containing the check box to select that box, rather than having to click precisely on the check box:

%CLICKCELL%=1

CMPRE: identifying complete questionnaires

CMPRE contains a regular expression used to identify complete questionnaires: the system scans all the .dat files and identifies as complete all those for which the specified regular expression is true.

In the example below the questionnaire is defined as finished if the variable qstatus is equal to 2 :

%CMPRE%="^qstatus=2$"

CSS: style sheet(s)

CSS specify the style sheets used for the questionnaire style:

%CSS%="client.css:cawi.css"

If more than one .css file is declared, they are separated by :

CUSTOMER: client name

This information not displayed in the survey (to be verified).

%CUSTOMER%="GIDE"

Back to start

DEBUGCANVAS: help for CANVAS manipulation

No help (mode "live") :

%DEBUGCANVAS%=0

Makes the framework of the cells visible. If the mouse is moved over a cell the coordinates are displayed:

%DEBUGCANVAS%=1

DESCRIPTION: page description

To change the description of the HTML page (metadata description).

%DESCRIPTION%="GIDE Survey"

DROPDOWNMSG: heading for dropdown lists

Specify the text to appear at the head of a drop down list :

%DROPDOWNMSG%="Please select your answer -->"

DSC: specify the main questionnaire file

Optional

%DSC%="myquestionnaire.dsc"

DSCENC: encoding of the dsc

%DSCENC%="utf-8" Modify to be able to deal with certain alphabets.

Back to start

ERRFINISHED: questionnaire finished

ERRFINISHED specifies the page which is displayed if a person who has already completed a questionnaire tries to open it again:

  • questionnaire complete (finished)
  • respondant screened out (screenout)
  • quota full (quotafull)

In the example below, the finished.blk page is displayed. This file should be in the .rsc directory for the project:

%ERRFINISHED%="finished"

ERRMSG: error message

ERRMSG specify the error message to appear on top of the page when at least one error is detected in the page. Set to 0 to suppress display of the message.

%ERRMSG%=" One or more of the questions requires a response or more information. Please check your responses on this page."

EXCID: identifiers to be excluded from the results

EXCID contains a regular expression that is used to exclude questionnaire data with IDs matching the expression.

In the example below, the identifiers starting with gide, demo and test are excluded.

%EXCID%="^(test|gide|demo)"

Back to start

FIXALL: CAWI bug fix

This parameter enables internal bug fixing in the CAWI system: it should always be set to "2". It replaces all the other parameters starting with FIX, excluding the FIXPAGES parameter. (The %FIXFINISHED% is not replaced if %FIXALL%=1 and not 2)

%FIXALL%=2

FIXPAGES: improves the fluidity of the questionnaire.

Optional. To use for large questionnaires.

%FIXPAGES%=1

FREEACCESS: access with an identifier not in login.csv

Allows access to the questionnaire with a free/arbitrary identifier (i.e. an identifier not defined in login.csv in advance): access to the questionnaire must be authenticated (%ACCESSMODE%=2).

%ACCESSMODE%=2 %FREEACCESS%=1

Comments:

  • This above settings to be used when a client wishes to do the emailing without giving GIDE the identifiers. The login.csv file will be empty. The URL of the survey will then be of the type:

http://srv4.cawi.fr/cgi-bin/cawi/Q/namesurvey/namesurvey.pl?CW_start=XXX or http://srv4.cawi.fr/cgi-bin/cawi/Q/namesurvey/namesurvey.pl?loginXXX

      where XXX is to be generated (by the client) with the contact ID.

  • If someone starts to answer from an email link (access identified) then resume the survey after modifying their identifier in the URL, then they will not see their previous answers (a new .dat will be created).

NB!: With FREEACCESS=1 mode the login.csv file is not read so variables cannot be imported from login.csv into the .dat file. (even though setting is ACCESSMODE=2).

Back to start

HANDHELD: Adds mobile compatibility settings:

<meta name="robots" content="noindex, nofollow"> <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"> <meta name="HandheldFriendly" content="true"> <meta name="apple-mobile-web-app-capable" content="yes"> <meta name="mobile-web-app-capable" content="yes">

%HANDHELD%=1

HIDE_QID_ON_ERROR: do not display the identifiers of the questions generating error messages

The identifiers of the questions with errors are normally displayed

You have not answered all the questions, or some answers are wrong. The following questions have errors: q1, q2, q3.

To prevent this display use:

%HIDE_QID_ON_ERROR%=0

The question identifiers are not displayed:

You have not answered all the questions, or some answers are wrong. Thank you for checking your answers.

HOMECSS: to be documented

HOME_PARMS: to be documented

HTML5: html version

Forces the CAWI to generate HTML5 and not HTML4.

%HTML5%=1

HTML_DIR: For the monitor. Change the direction of the writing

Mainly for Arabic kanguages. For right to left display:

%HTML_DIR%="rtl"

Back to start

ICLOGIN: to be documented

IMAGETOOLBAR: hide the IE image toolbar

Change the meta-tag on the page. This meta tag tells Internet Explorer not to display the toolbar in the picture at mouseover.

%IMAGETOOLBAR%="no"

Back to start

JAVASCRIPT: Javascript files

Declare the list of .js files used in the questionnaire :

%JAVASCRIPT%="cawi.js:rank.js"

If more than one .js files is used, the files are separated by a ":".

JQMOBILE: to be documented

JQMTHEME: to be documented

JQUERY: activate the Jquery libraries

%JQUERY%=1

Back to start

KEYLEN: length of GKID

KEYLEN specifies the number of characters of the GKID variable for exporting data. Specify the largest number of characters present in the file login.csv.

%KEYLEN%=12

Note: It is good practice for the ids in the login.csv file to be unique to each survey. So, tor example, include the project ID in GKIDs.

Back to start

LANG: language to be used for CAWI non response messages

LANG specifies the language to be used in the questionnaire for the default error messages :

English

%LANG%="en"

Comments: For English, use en (and not gb or uk). Otherwise the export of data to SPSS format will not work.

Dutch

%LANG%="nl" Portuguese

%LANG%="pt"

LOGINBLK: file to be used to define the opening page

%LOGINBLK%="login_A.blk" By default the file login.blk is used.

Back to start

NAVBLK: file used to define the navigation bar

%NAVBLK%="nav_nxt.blk" By default the file nav.blk is used

NOBACK: prevent return to the previous question using the browser [BACK] button:

allow return

%NOBACK%=0 diable return

%NOBACK%=1

NOCACHE: to be documented

NOIP: suppress collection of IP address - GDPR requirement

Prevents the IP address from being collected in the .dat file (IP address replaced by 0.0.0.0).

%NOIP%=1

NOMARGIN: hide the question margins

Margin hidden :

%NOMARGIN%=1 Margin visible :

%NOMARGIN%=0

The margin text is defined with the MARGIN marker:

q1 "@MARGIN$Sex @$Are you?"

Back to start

ONACCESS: to be documented

ONBYE: to be documented

ONCGIPARSE: return to the last validated page if user re-connects to the questionnaire

This option must be completed with the function resume in the usrdef.pl

This option is to be used on a non-standard case, otherwise use %RESUME%=1 (see below).

%ONCGIPARSE%="resume"

ONDISPLAY: to be documented

Back to start

PARMS_mypage: to be documented

PASSWORD: password for the monitor

Specifies the passwords needed to access the questionnaire monitoring and results interface. If several passwords are allocated, they must be separated by ":" :

%PASSWORD%="client_password:internal_password"

PBALIGN: alignment of the progress bar

Specify the alignment of the progress bar.

%PBALIGN%="right"

PBBGCOLOR: background colour of the progress bar

Specify the background colour of the progress bar (not to be confused with the colour of the progress which is determined by an image - named by default, "bar.png").

%PBBGCOLOR%="#e5eaec"

PBCOLOR: colour of the progress bar borders

%PBCOLOR%="#000000"

PBHEIGHT: height of the progress bar

%PBHEIGHT%=14

Fixed by default to 12

PBWIDTH: width of the progress bar

%PBWIDTH%=180

PLAINPWD: Integrate password

Allows the addition of passwords to the login.csv file for the survey when using ACCESSMODE=3

%PLAINPWD%=1

PREPLOG: integrate login information

Makes it possible to retrieve information from the login.csv file.

%PREPLOG%=1

PRINTING: export the questionnaire

Option to activate export of the questionnaire.

%PRINTING%=1

PROGBARIMG: file used for the progress bar

%PROGBARIMG%="bar_new.png"

By default, the file used is "bar.png".

Back to start

RESUME: return respondent to the last page validated.

If the respondent reconnects to an uncompleted questionnaire, return them to the last page validated.

This option is used on a standard case, otherwise use %ONCGIPARSE%="resume" (see above).

%RESUME%=1

Back to start

SKIPHOME: do not show the homepage

Directly display the first page of the questionnaire without going through the homepage for open access questionnaires (ACCESSMODE =1 or 6).

%SKIPHOME%=1

SPLITLOGIN: splitting the login.csv file.

Splitting the file makes it easier to connect to the survey.

%SPLITLOGIN%=3

STATS_EXCLUDES_Q: For the monitor: questions to exclude from summary counts.

Provide list of questions not to be included in the summary counts.

%STATS_EXCLUDES_Q%="quotaReport,q11"

STATS_INCLUDES_Q: For the monitor: questions to include in summary counts.

Provide list of questions to be included in the summary counts.

%STATS_INCLUDES_Q%="q1,q2"

STATS_FILTERS: For the monitor: questions used in filters

Provide list of questions that can be used to filter summary counts.

%STATS_FILTERS%="qstatus,q1"

STOP: close the survey

Survey open:

%STOP%=0 Survey closed: access to the questionnaire is blocked, the stop.blk page is displayed.

%STOP%=1

TITLE: page title

Changes the title of the HTML page (title tag). It will be visible as a title on the page tab. Do not enter special characters (of type ' « etc…).

%TITLE%="GIDE Survey"

TOOLTIP: display tooltips

Allow the display of tooltips

%TOOLTIP%=1

TOPBLK: file to use at the top of each HTML page

%TOPBLK%="top_uk.blk"

By default the file top.blk is used.

WARNMSG: warning message

Specifies the warning message displayed at the top of the page when at least one error is detected on the page, but can be ignored by clicking Next Page. Set to 0 to suppress display of the error message.

%WARNMSG%="Warning: Please check your responses on this page.<br />Click [Next] to ignore this warning."

The display of this message is linked to the instruction warn=yes in the ROUTE section of the dsc.

CHECK:{ IF NOANSWER(Q2) THEN WARNING(Q2,"Are you sure you do not want to answer?","warn=yes") }

Back to start