gess q. · gess q. user manual gesellschaft für software in der sozialforschung mbh waterloohain 6...

GESS Q.

User Manual

Gesellschaft für Software

in der Sozialforschung mbH

Waterloohain 6 - 8

22769 Hamburg

Tel.: +49 40 - 853 753 - 0

Fax: +49 40 - 853 753 - 33

www.gessgroup.de

Contents

1 Fundamentals 11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Program Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2.1 GESS Q. Desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.2 GESS Q. Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.3 GESS Q. Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.4 Demo Versions, Full Versions and Updates . . . . . . . . . . . . . . . . 21.2.5 Example for a Setup and Project Management with GESS Q. Desktop 3

1.3 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Preprocessor Directives 62.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.2 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.4 Define . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.5 Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Question Definitions 93.1 Question Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3 SingleQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.3.1 Alternative Selection Options . . . . . . . . . . . . . . . . . . . . . . . . 133.4 MultiQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.5 OpenQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.6 PasswdQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.7 TextQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.8 NumQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.8.1 GNumQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.9 SingleGridQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.9.1 Standard-Grid-Question . . . . . . . . . . . . . . . . . . . . . . . . . . . 183.9.2 Transposed Grid Question . . . . . . . . . . . . . . . . . . . . . . . . . 193.9.3 Grid Question with Multiple Question Blocks (Label Groups) . . . . . . 193.9.4 Data Storage and Access . . . . . . . . . . . . . . . . . . . . . . . . . . 203.9.5 Directionals / Bipolar Scales . . . . . . . . . . . . . . . . . . . . . . . . 203.9.6 Further GridQ parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.10 MultiGridQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.11 Answer Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4 Definition of the Interview Process 324.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324.2 Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324.3 Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334.5 Whitelist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

5 Interview Settings 355.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

5.2 Script Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355.3 HTML Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

6 Text Replacement 486.1 Text Replacement with @insert . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

7 Screens 507.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507.2 HTML Specific Screen Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 52

7.2.1 HTML Code Integration . . . . . . . . . . . . . . . . . . . . . . . . . . 527.2.2 HTML Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

7.3 Dynamic Screen Content / JavaScript . . . . . . . . . . . . . . . . . . . . . . . 54

8 Special Types of Variables 568.1 Compute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568.2 Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568.3 DictFileVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598.4 DecisionVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598.5 IntRandom (Random Numbers) . . . . . . . . . . . . . . . . . . . . . . . . . . . 598.6 Block Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608.7 TextElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608.8 Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618.9 TextArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618.10 VarArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628.11 RestrictVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

9 Internal Variables 639.1 Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639.2 Further Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639.3 Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639.4 External URL Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649.5 Exit-Code (_finished) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649.6 Number of the Interviewee and Case Number (_respid und _caseid) . . . . . . 649.7 Cancel Code (_cancel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659.8 Resuming after Cancellation (_resume) . . . . . . . . . . . . . . . . . . . . . . 659.9 Export of Internal Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

10 Filtering and Plausibility Conditions 6710.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6710.2 Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

10.2.1 Examination by Arrays and Multivariable . . . . . . . . . . . . . . . . . 6810.2.2 Functions and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . 68

10.3 Filter Conditions (flt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7110.3.1 Filter General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7110.3.2 Filter on Questions, Block, Screens . . . . . . . . . . . . . . . . . . . . 7110.3.3 Filter in Label Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7210.3.4 Filter in Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7310.3.5 Specialties: Filter Texts, Noexport und Setfilter . . . . . . . . . . . . . 74

10.4 Plausibility Conditions (Assert) . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

11 Sorting 7611.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7611.2 Array Contents as Sorting Order . . . . . . . . . . . . . . . . . . . . . . . . . . 7911.3 Automatic Generation of the Sorting-ID . . . . . . . . . . . . . . . . . . . . . . 80

12 Quotas 8212.1 Quotas Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8212.2 Quota Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8312.3 Quotas and Access Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

13 Automatic Forwarding to the Interviewer 8613.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8613.2 Integrating in a panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

14 Action Commands and Action Blocks 8814.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8814.2 Action Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8914.3 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

15 Template, Layout, Graphic Elements 10015.1 Frame Layout - the "Template" . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

15.1.1 Structure of the Template . . . . . . . . . . . . . . . . . . . . . . . . . . 10015.1.2 template_error.html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10115.1.3 Placeholder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10115.1.4 Progress Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10315.1.5 The GESS JavaScript Library . . . . . . . . . . . . . . . . . . . . . . . 105

15.2 Graphical Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10515.2.1 Requirements for the Usage . . . . . . . . . . . . . . . . . . . . . . . . . 10615.2.2 GESS Q. Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10615.2.3 Adjustable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 10715.2.4 Example Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

15.3 Graphical Formatting and Layout . . . . . . . . . . . . . . . . . . . . . . . . . . 10915.3.1 CSS Classnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11015.3.2 Formatting of Individual Questions, Areas and Types of Questions . . . 11315.3.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11315.3.4 Adding CSS to the Question . . . . . . . . . . . . . . . . . . . . . . . . 11415.3.5 CSS, the not Recommended Version . . . . . . . . . . . . . . . . . . . . 11515.3.6 Responsive Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

15.4 Self-built Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11615.5 Graphical Navigation Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11815.6 Making of Custom Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

16 Keyboard Input 12116.1 Keyboard Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12116.2 Function Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12116.3 The control fields ki_mode, ki_input and ki_check . . . . . . . . . . . . . . . . 12216.4 Adjustable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

17 SliderQ: Slider Bar 12417.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12417.2 Requirements to the Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

17.3 GESS Q. Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12417.4 Adjustable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

17.4.1 Graphical parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12517.4.2 Functional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

17.5 Example code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12717.6 Graphical Formatting and Layout . . . . . . . . . . . . . . . . . . . . . . . . . . 128

18 QSortable: The NumQ as Drag & Drop List 12918.1 Script Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

18.1.1 HTML Lists Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 12918.2 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

19 PackagingQ: Packaging Configurator 13319.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13319.2 Requirements for the Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13319.3 PackagingQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13319.4 Adjustable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

19.4.1 Image area / Corpus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13419.4.2 Grouping options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13419.4.3 Adjustments of the visibility menu . . . . . . . . . . . . . . . . . . . . . 13519.4.4 Correspondence label - Graphic . . . . . . . . . . . . . . . . . . . . . . 13519.4.5 Randomization and filter . . . . . . . . . . . . . . . . . . . . . . . . . . 13519.4.6 Optical design with CSS . . . . . . . . . . . . . . . . . . . . . . . . . . 135

19.5 Example Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

20 Additional Graphical Components 13820.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13820.2 Image Preview with Thumbnails . . . . . . . . . . . . . . . . . . . . . . . . . . 138

20.2.1 Requirements for the Use . . . . . . . . . . . . . . . . . . . . . . . . . . 13820.2.2 Example Code: Thumbnail . . . . . . . . . . . . . . . . . . . . . . . . . 138

20.3 Integration of Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13920.3.1 Formats and Scripts Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 13920.3.2 Configuration of the Player . . . . . . . . . . . . . . . . . . . . . . . . . 140

20.4 Integration of Audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14120.4.1 Formats and Scripts Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 14120.4.2 Configuration of the Player . . . . . . . . . . . . . . . . . . . . . . . . . 141

20.5 Dynamically show / hide Questions in Screens . . . . . . . . . . . . . . . . . . . 14220.5.1 Requirements for the Usage . . . . . . . . . . . . . . . . . . . . . . . . . 14220.5.2 Example-Code: Show / Hide . . . . . . . . . . . . . . . . . . . . . . . . 142

20.6 Tachistoscopic Question Options . . . . . . . . . . . . . . . . . . . . . . . . . . 14320.6.1 Requirements for Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 14420.6.2 Tachistoscope Option 1 (Timer) . . . . . . . . . . . . . . . . . . . . . . 14420.6.3 Tachistoscope Option 2 (classical) . . . . . . . . . . . . . . . . . . . . . 145

20.7 Heat Plotter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14620.8 Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14920.9 Integration of ImageMaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14920.10 3D Rotation Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

21 Invitation Links, Participant IDs and Panel Connection 15421.1 Participant-IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15421.2 Survey Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

21.3 Invitation Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15521.4 Panel Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

21.4.1 Using the Panelists ID as GESS Q. Participant ID . . . . . . . . . . . . 15921.4.2 Redirect to Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

22 The Local Installation - GESS Q. Desktop 16122.1 Installation and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

22.1.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16122.1.2 Folder Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

22.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16222.2.1 Configuration File qonline.cfg . . . . . . . . . . . . . . . . . . . . . . . . 16222.2.2 User Accounts and Access Rights: users.lst . . . . . . . . . . . . . . . . 16522.2.3 User Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16522.2.4 access.lst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16622.2.5 Blacklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16622.2.6 server.lst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

22.3 Starting and Ending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16622.4 Licensing and Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

22.4.1 Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16722.4.2 Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

22.5 Requirements for GESS Q. Desktop . . . . . . . . . . . . . . . . . . . . . . . . . 168

23 The Productive Operation - GESS Q. Server 17023.1 Recommendation for GESS Q. Webserver . . . . . . . . . . . . . . . . . . . . . 170

24 The Android App - GESS Q. Android 17124.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17124.2 Menu Navigation and Language . . . . . . . . . . . . . . . . . . . . . . . . . . . 17124.3 Installation und Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17224.4 Licensing and Case Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17324.5 Data Exchange via USB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17324.6 Services App-Block and Net-Block . . . . . . . . . . . . . . . . . . . . . . . . . 17524.7 Features and JavaScript Functions . . . . . . . . . . . . . . . . . . . . . . . . . 175

24.7.1 Startdefines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17524.7.2 Cancel / Resume of interviews . . . . . . . . . . . . . . . . . . . . . . . 17524.7.3 writerescuedata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17624.7.4 Record Audio (MP3) in the Background . . . . . . . . . . . . . . . . . . 17624.7.5 Record Audio (MP3) Selectively via Recorder . . . . . . . . . . . . . . 17624.7.6 Take Fotos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17724.7.7 Net-Block start/stopp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17824.7.8 System Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17824.7.9 Play Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17824.7.10 Web Browsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17824.7.11 Number Keypad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

24.8 Short Passage: GESS Q. Android on the Tablet . . . . . . . . . . . . . . . . . . 17924.9 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

25 The User Interface 18425.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18425.2 Start of interviews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

25.2.1 Robot: Autofill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

25.3 Configuration of the Study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18625.3.1 Enable / Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18625.3.2 Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18625.3.3 Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18625.3.4 Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18725.3.5 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18725.3.6 Check Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18725.3.7 ID Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18825.3.8 Reporting Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18925.3.9 Quotas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19025.3.10 File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19025.3.11 User Assignment - User Accounts . . . . . . . . . . . . . . . . . . . . . 19125.3.12 Print - Print Questionnaire . . . . . . . . . . . . . . . . . . . . . . . . . 19125.3.13 Language Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 19225.3.14 Translations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19425.3.15 Expanded Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19425.3.16 Logfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

25.4 Upload of Studies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19525.4.1 Server Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19525.4.2 Android Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

25.5 Data and Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19625.5.1 Edit Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19725.5.2 Column Mapping (colmap.lst) . . . . . . . . . . . . . . . . . . . . . . . 19925.5.3 Variable Definition (var.inc) . . . . . . . . . . . . . . . . . . . . . . . . 20125.5.4 ASCII, OPN and SPSS Files . . . . . . . . . . . . . . . . . . . . . . . . 202

25.6 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20325.7 Android Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20325.8 Survey Manager - Creating New Studies . . . . . . . . . . . . . . . . . . . . . . 205

25.8.1 Configuration Files in the Questionnaire Folder . . . . . . . . . . . . . . 20525.8.2 File Templates in the Questionnaire Folder in text . . . . . . . . . . . . 206

25.9 Users - User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20625.10 Help - References to Other Sources of Information . . . . . . . . . . . . . . . . . 20625.11 Server Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20725.12 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

25.12.1 Setting up GESStabs on the Survey Server . . . . . . . . . . . . . . . . 20725.12.2 Definition of the Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 20725.12.3 Customer Specific Tables . . . . . . . . . . . . . . . . . . . . . . . . . . 208

26 Other Features and Help 20926.1 HTTP Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

27 Bug Hunting 21027.1 Script Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21027.2 Variables value check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21027.3 HTML-output check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Index 212

List of Figures

1.1 GESS Q. Software-Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 GESS Q. Setup Examples in the Working Environment . . . . . . . . . . . . . . 31.3 Advantages and Disadvantages of the Setup Variations . . . . . . . . . . . . . . 3

3.1 SingleQ Alternatives: List, List with Search, Scrollable List . . . . . . . . . . . 143.2 Data Storage of a MultiGridQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

7.1 A Screen of Four Questions in Two Columns and Two Rows . . . . . . . . . . . 517.2 A Screen of Eleven Nested Components . . . . . . . . . . . . . . . . . . . . . . . 527.3 An Unexciting Example forhtmllabels . . . . . . . . . . . . . . . . . . . . . . . 54

15.1 Questionnaire Layout for a GESS Project . . . . . . . . . . . . . . . . . . . . . . 10015.2 The Same Questionnaire in Standard Layout for Android Devices . . . . . . . . 10015.3 The progress bar skips a screen: changepbar(1) . . . . . . . . . . . . . . . . . . 10315.4 Various paths with the same question number . . . . . . . . . . . . . . . . . . . 10415.5 Graphical Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10515.6 Image Preview by Graphical Buttons . . . . . . . . . . . . . . . . . . . . . . . . 10715.7 CSS Classes for SingleQ and MultiQ . . . . . . . . . . . . . . . . . . . . . . . . 11115.8 CSS Classes for GNumQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11115.9 CSS Classes for SingleGridQ and MultiGridQ . . . . . . . . . . . . . . . . . . . 11215.10 Graphical Navigation Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

16.1 Control Fields of the Keyboard Input . . . . . . . . . . . . . . . . . . . . . . . . 122

17.1 Slider Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12417.2 CSS Classes SliderQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

18.1 Example: NumQs as QSortable . . . . . . . . . . . . . . . . . . . . . . . . . . . 12918.2 QSortable Minimal Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13118.3 QSortable CSS Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

19.1 Packaging Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

20.1 Image Preview with Thumbnails . . . . . . . . . . . . . . . . . . . . . . . . . . . 13820.2 Dynamically show / hide Questions . . . . . . . . . . . . . . . . . . . . . . . . . 14220.3 Tachistoscopice Option 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14420.4 Tachistoscope Option 2 (classical) . . . . . . . . . . . . . . . . . . . . . . . . . . 14520.5 Heat plotter: Select Image Points . . . . . . . . . . . . . . . . . . . . . . . . . . 14720.6 ImageMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14920.7 3D Rotation Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

21.1 Scheme Panel Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

22.1 Folder - Integration of the License Key . . . . . . . . . . . . . . . . . . . . . . . 16722.2 Interface - Opening and Integration of the License Key . . . . . . . . . . . . . . 168

24.1 GESS Q. Android Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17124.2 The User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17224.3 The Android USB Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17424.4 GESS Q. Android: Audio Record . . . . . . . . . . . . . . . . . . . . . . . . . . 177

24.5 GESS Q. Android: Home Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . 17924.6 GESS Q. Android: Login as an Interviewer . . . . . . . . . . . . . . . . . . . . . 18024.7 GESS Q. Android: Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 18024.8 GESS Q. Android: Questionnaire . . . . . . . . . . . . . . . . . . . . . . . . . . 18124.9 GESS Q. Android: Login to the Server . . . . . . . . . . . . . . . . . . . . . . . 18124.10 GESS Q. Android: Reporting as Overview . . . . . . . . . . . . . . . . . . . . . 18124.11 GESS Q. Android: Reporting in Tables . . . . . . . . . . . . . . . . . . . . . . . 18224.12 GESS Q. Android: Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18224.13 GESS Q. Android: Additional Functions . . . . . . . . . . . . . . . . . . . . . . 183

25.1 GESS Q. Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18425.2 Start of an Interview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18525.3 Start of the Robot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18525.4 Configuration of the Study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18625.5 Configuring the Study: IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18825.6 Managing of IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18825.7 Configuration of a Study: Reporting . . . . . . . . . . . . . . . . . . . . . . . . 18925.8 Configuring a Study: Quotas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19025.9 Configuring the Study: Character Encoding . . . . . . . . . . . . . . . . . . . . 19125.10 Language Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19225.11 The Translation Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19325.12 Confirmation: Translate All Occurrences . . . . . . . . . . . . . . . . . . . . . . 19425.13 Uploading Studies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19525.14 Data and Export Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19625.15 Interface for the Data Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19725.16 Edit data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19725.17 Access to All Variables in the Data Record . . . . . . . . . . . . . . . . . . . . . 19825.18 available data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19825.19 edit dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19925.20 First Step of the Data Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19925.21 Data Export: Generate colmap.lst . . . . . . . . . . . . . . . . . . . . . . . . . 20025.22 Content of colmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20025.23 Generated Colmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20025.24 Editing Options for the var.inc file . . . . . . . . . . . . . . . . . . . . . . . . . 20125.25 Options by Saving the var.inc file . . . . . . . . . . . . . . . . . . . . . . . . . 20125.26 Translation Options when Saving the var.inc file . . . . . . . . . . . . . . . . . 20225.27 Save ASCII Data Record or SPSS Data Record . . . . . . . . . . . . . . . . . . 20225.28 Save Open Answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20325.29 Android Manager: Connected Device . . . . . . . . . . . . . . . . . . . . . . . . 20425.30 Android Manager: Blocker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20425.31 Android Manager: Surveys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20425.32 Server status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Chapter 1. Fundamentals

1 Fundamentals

1.1 Introduction

GESS Q. is a software suite for programming questionnaires, conducting surveys and processingdata. The questionnaire, written in the language GESS Q. script, can be used browser based foran online survey or in interviewing by phone, but can also run similar to the classic surveys inan app on a tablet or a reading device. Depending on the needs, the results can be collectedcentralized over the network on a server or offline locally on a computer. The data is availablefor further processing and presentation over open, documented interfaces. An integrated solutionfor data processing in tables is available with GESStabs. This solution alone can display thedata graphically and allows the output in various formats (PDF, HTML, Excel, PowerPoint).

Figure 1.1: GESS Q. Software-Suite

The first section of the manual addresses the programming of questionnaires and presents thespecially developed language GESS Q. script. The second part explains how to use the softwaredeals with adjustments based on HTML and CSS and explains various extensions by JavaScript.

Before we give a general idea for the GESS Q. scripting language, the current chapter must firstrepresent what versions of the software are available, which are the technical conditions andrequirements and how the typical application fields look like.

1.2 Program Versions

The three main forms of GESS Q. are designed to run on:

• Desktop PCs or laptops (GESS Q. Desktop),

• Web servers (GESS Q. Server),

• Android phone or tablet (GESS Q. Android).

The various applications can be harmoniously used simultaneously. So various scenarios for fieldwork are possible:

• GESS Q. server is used to administrate studies and conduct surveys online, using a browser.Both interviewer with GESS Q. Android on tablet (mobile) and interviewer with GESS Q.

GESS Q. (release: june 2016) 1


Desktop (offline) are able to upload their collected data to GESS Q. Server by a press of abutton (only when the Internet connection is available). So GESS Q. Server serves as acollection point of data from any location, which can be followed login protected onlinewith a browser, with flexible reporting in general or login specific.

• The interviewers or participants can fill surveys completely offline, for example, in CarClinicswith GESS Q. Android and transmit the data via USB connection (or local WiFi) to GESSQ. Desktop. GESS Q. Desktop acts in this scenario as the server described above, with alladministration and reporting functions.

The following is a brief look at the logistical characteristics. All three versions can also be founddescribed in more detail at the end of the manual.

1.2.1 GESS Q. Desktop

GESS Q. can be installed on any desktop or laptop computer. All program data and studies areaccessible on file level, so an interface can also be launched from the browser, which enables theuse of essential functions of the program. With this, studies can be created, copied and managedand the scripting takes place at file level. Furthermore, studies and data sets can be exchangedwith other GESS Q. installations by a press of a button. Desktop and server installations arereferenced with a URL, while Android devices download studies or can be operated via USB.Finally, the collected data can be exported in the form of a flexible definable ASCII or SPSSfiles. Chapter 22 is especially dedicated to GESS Q. Desktop, its installation, setup and furtheradjustment options.

1.2.2 GESS Q. Server

The web server installation basically has the same functions as the desktop installation. Over theserver address the user interface can be reached with every PC with Internet access. Potentialparticipants may be invited for interviews using certain links. It works on any server operatingsystems, in practice installing on Linux should be the easiest. Chapter 23 is especially dedicatedto the particularities and requirements of running GESS Q. Web servers productively.

1.2.3 GESS Q. Android

The Android app as a special software for mobile surveys has a specifically compiled functionalrange. The app can request data from servers (both desktop and web), transfer records back tothe server and can be controlled via USB from desktop installations. Chapter 24 is especiallydedicated to the app with native functions and their characteristics.

1.2.4 Demo Versions, Full Versions and Updates

All versions of GESS Q. are available as a demo version which provide a full functionality, butproduce no records. If a GESS Q. version is not licensed, the interviews are automatically startedwith #define demoversion . Upgradeable demo versions of GESS Q. Desktop and GESS Q.Android can be downloaded for free under http://www.gessgroup.de. An online activation of therespective full version is possible at any time by entering a time-limited license codes. It mustbe noted that at one workstation only one installation of GESS Q. Desktop can be unlocked.GESS Q. Desktop and GESS Q. Android also have integrated update mechanisms that allow acomfortable updating to the latest version.


http://www.gessgroup.de


1.2.5 Example for a Setup and Project Management with GESS Q. Desktop

For individual working environments GESS Q. can be adjusted flexibly using the diverse con-figuration options. Figure 1.2 shows three possible varieties of the local project administration,where in all cases each workstation has its own installation of GESS Q. Desktop. We recommendto script the questionnaires completely offline within GESS Q. Desktop and test in the firstinstance. GESS Q. server can then get the project by a simple upload, so that the customer cantest or survey can eventually start.

Figure 1.2: GESS Q. Setup Examples in the Working Environment

The first and simplest variation can be best described as pure single workstation solution.All workstations are completely independent and only have their own studies. On the other hand,the second variation is centralized project storage where, for example, there is a companynetwork drive to which all workplaces can access. A third thinkable possibility is the usage of aversion control system like SVN, CVS or Git. In this case, the entire installation of GESS Q.Desktop incl. projects is part of a central, versioned storage and each workstation can alwayssynchronize to the latest state and then operate independently with a full copy. The followinglisting summarizes the advantages and disadvantages of different solutions.

Figure 1.3: Advantages and Disadvantages of the Setup Variations

1.3 Setup

A questionnaire in GESS Q. script consists of questions that are grouped into blocks. It isimperative that every script contains the block main. The interview process doesn’t determinethe order of questions in the script but these are determined in the block (so here 1 3 2).

Question1;



Question2;

Question3;

block main = (Question1 Question3 Question2);

We can nest blocks in each other:

Question1;

Question2;

Question3;

Question4;

block b1 = (Question2 Question3);

flt = (Question1 eq 1);

block main = (Question1 b1 Question4);

We can also link filters and conditions to the blocks such as questions, to control the flow of theinterview. In the example here, the questions 2 and 3 can be asked, only if the question 1 gotanswer code 1.

Questions in the GESS Q. script must at least contain the definition of the question type, the IDof the question and the corresponding text:

textq Question1;

text="What's the question?";

The question type (here TextQ) already defines the possible answers. So a TextQ provides noanswer options, because it only serves to output a text on the screen. On the other hand aNumQ expects a numerical input, a singleq check on an answer option, etc ..

In the ID of the question (here Question1 ) is more than just the possibility to position it in ablock using the ID. At the same time the program addresses the ID as a variable in which theresponse to the question is stored.

singleq Question1;

text="What is the question of all questions?";

labels=

1 "How many roads must a man walk down?"

2 "How much 6*7?"

;

Here Question1 can only take the values 1 or 2, depending on the selection of the interviewees.Whether GESS Q. script stores the values in the variables as a single value or as an array, dependson the question type.

As said, GESS Q. considers the IDs of the questions as variables. Other variables can be createdwith compute (please also refer to section 8.1) or TextElement (please also refer to section 8.7).In any case, all the variable names must start with a letter (a-z A-Z).

By the keywords, in contrast to the question names and variable names, the uppercase andlowercase letters don’t matter.

SINGLEQ gender; is equivalent to singleq gender;

SingleQ gender; is not equivalent to SingleQ GENDER;



1.4 Requirements

You need an editor for the programming. On the page of GESS Q. you can find adjustments forNotepad++ and Emacs. These provide highlighting of the syntax and insertion of code snippeton a click.

For adjustments of HTML and CSS a browser is advisable. It would allow examining of individualelements in an HTML page (for example Firefox with the Add-on Firebug).

At the level of the file system GESS Q. script expects at least one project directory, because theprogram is searching for the questionnaire in the directory text.

Two recommendations:

• A questionnaire can be completely contained in a single file. In practice, that isn’trecommended for extensive questionnaires. It is better to use the include mechanism touse various files together and so to keep things clear.

• All instructions in GESS Q. script must always end with a semicolon.


Chapter 2. Preprocessor Directives

2 Preprocessor Directives

2.1 General

The processing of a GESS Q. script in the interview takes place in two steps. Before the contentof the script is evaluated in the second step, a pure resolution of so-called preprocessor directivestakes place. With this it is possible to integrate script components from external files, to createtemplates, to compress similar script sections or to consider parts of the script only conditionally.

For this purpose are available the functionally designated commands #Include, #Macro und#Define. What they all have in common is that in the script they start with a hash sign in thefirst column of a line. It is also possible to highlight areas in GESS Q. script as a comment:

2.2 Comments

Comments in GESS Q. give the scriptwriters the opportunity to enter notes or instructions thatare excluded from the processing of the script. These can also be used in order to disable areasof the script when developing or testing.

• A double slash // comments out the rest of the line.

• Block-comments over multiple lines start with /* and are closed with */

// this line is a comment line

SingleQ dummy; // and it also works within the line

/*

and this area with multiple lines is commented out,

where also the following SingleQ dummy2 will not be read

SingleQ dummy2;

*/

2.3 Include

#include "demography.q"

With the include directive, a content of a located in the text-file directory can also be included.The included line is replaced by the contents of the referenced file. In this way, long questionnairescan be structured and distributed in multiple files. It also allows multiple people to worksimultaneously on the same questionnaire. In addition, parts of the script, which can be used inmultiple projects, can be encapsulated and connected if needed. Like in the example, there couldbe a standardized demography part, which once scripted could be used multiple times.

2.4 Define

#define testmode

// ...



#ifdef testmode

HTML{ backbutton = yes; };

#endif

With the Define-directives, script lines may be taken into account conditionally. #define X

activates a parameter X which can later be used as a condition. The activating of a parametercan also be controlled via the start URL of the interview.

https://...&define=testmode&define=ANOTHERPARAMETER

With #ifdef X ("when activated") and #endif respectively #ifndef X ("when not activated")and #endif an area of the script can be included. The area will be included by the scriptprocessing, when the parameter X is activated respectively not activated.

With this, a script can be written, where different variations of a questionnaire are provided.These can be controlled via the URL parameter in the Start link. Through that mechanism thequestionnaire can be optionally started with certain settings (back button, keyboard input...),with certain parts of the questions or in test mode (without data storage, quota count).

GESS Q. doesn’t recognize other junction options, known from other programming languages,like #elseif or #elsif.

2.5 Macro

With #macro NAME and #endmacro a script area can be limited. This area remains with nofunction of its own. This is a template which can be used (instantiated) with &NAME; as manytimes as desired. Such a macro can be understood as a simple text replacement.

// EXAMPLE 1

#macro labellist

labels=

1 "very good"

2 "good"

3 "medium"

4 "bad"

5 "very bad"

;

#endmacro

SingleQ spot1;

text="How did you like the first commercial?";

&labellist;

Example 1 contains a #macro labellist with a label list, which may often appear in thequestionnaire course. Formulating a macro here saves a lot of programming work and also givesthe ability to store the content centralized, in one place. If the scale is to be changed, it must berewritten only in this one place.

// EXAMPLE 2

#macro car_template

SingleQ car$number;

text="Do you like the $model better than your current car?";

labels=



1 "Yes"

2 "No"

;

flt=($number in model selection);

#endmacro

&car_template;$number="1";$model="VW Passat";

&car_template;$number="2";$model="Skoda Octavia";

&car_template;$number="3";$model="Audi A4";

&car_template;$number="4";$model="Ford Mondeo";

We can formulate a macro with placeholders that will be replaced by the actual values:

&X;REPLACEMENT1="NEWLINE1";REPLACEMENT2="NEWLINE2";...;

GESS Q. replaces the placeholders with the values during expansion of macros.

In example 2 the #macro car_template is used to create several similar questions. The $model

ensures that a particular vehicle is inserted into the question text, while the placeholder $number

ensures that the questions get unique names on the one hand and that these are asked filteredon the other. The used filters postulate that there is a question model_selection, which givesa car selection with correspondingly numbered labels

Strictly speaking, any text can be used as a placeholder. The placeholder $model, used in theexample, would be changed in the text of the SingleQ car1 with »VW Passat«. It is muchrecommended to make placeholders recognizable in any, standardized form. Like here, one couldalways write the placeholders starting with the dollar sign - as »$REPLACEMENT1« instead of»REPLACEMENT1«.

Through macros scripts can often be created clearer, easier and faster. However, macros can alsoquickly appear cryptic and confusing, when it comes to nesting macros in macros with similaror linked placeholders. We therefore advise you to provide macros with meaningfulnames and to provide these with enough comments.

Please note: When resolving a macro GESS Q. reads placeholders character for character. Thiscan lead to errors in numbered placeholders (for example $1). If it is not taken into account,that by placeholder $10, not 10 will be considered, but p1 will be recognized again and a 0 willbe attached.

In addition, Unix accustomed users should keep in mind that the "$"-sign is just a sign for GESSQ., and has no special significance like in the Shell.


Chapter 3. Question Definitions

3 Question Definitions

3.1 Question Types

Questions in GESS Q. script are simply linded. Here the order of the questions is irrelevant,because the sequence given in the questionnaire is determined by screens and blocks. Thefollowing standard question types are available in GESS Q.:

TextQ Display a text

SingleQ A closed question with one reply option

MultiQ A closed question with several answer options

OpenQ Open question with free text entry

PasswdQ Open question with free text entry (hidden by points)

NumQ Numeric entry with one or more input options

SingleGridQ Several SingleQs combined in table view

MultiGridQ Several MultiQs combined in table view

3.2 General Properties

The properties or attributes of a question differ from question type to question type. However,there are several that are common for all the questions. The following listing describes thecontent somewhat in advance, but gives a brief summary, which attributes in principle, can beapplied for every question definition.

Question type NAME;

Text = "TEXT";

Title = "TITLE";

LABELLIST

JavaScript = "JAVASCRIPT";

Css = "CSS";

SortId = "SORTID";

HtmlPreText = "HTMLPRETEXT";

HtmlPostText = "HTMLPOSTTEXT";

PreHelptext = "PREHELPTEXT";

PostHelptext = "POSTHELPTEXT";

PreInterviewerHelptext = "PREINTERVIEWERHELPTEXT";

PostInterviewerHelptext = "POSTINTERVIEWERHELPTEXT";

InitActionBlock = { ... };

ContinueActionBlock = { ... };

ShowMaxLabels = NUMBER;

Nomissing = YES/NO;

Flt = CONDITION;

Assert CONDITION "Error text by violation.";

NAME The name of a question must begin with a letter (a-z or A-Z). In addition, the name of thequestion, the block (section 4.2) or the screen (chapter 7) may be assigned in a survey onlyonce. Duplicated names lead to errors in the Script check. Dots in names are generally not



allowed. Additionally there is a blacklist with reserved names that should not be used. TheScript check reports an error if a name of the blacklist was used.

SingleQ f1;

Text is commonly used for the question text. Each question can be provided with a text, whereon one screen (composed of several questions) always only one text is visible. The Screen itselfhas the text attribute but if it is not used, the screen uses the text of its first contained question.At which point the question text appears depends on the positioning of @qtext in the template

of the survey (section 15.1.3).

text = "How old are you?";

Title This is commonly used for additional notes and always appears directly above the answeroptions.

title = "Multiple selection";

LABELLIST Please refer to section 3.11.

JavaScript places JavaScript code directly behind the possible answers to the questions. Thatis not taken into account when generating a language source.

javascript = "alert ('I live!');";

Css places CSS information directly behind the possible answers to the questions, which is nottaken into account when generating a language source (also refer to section 15.3.4).

css = ".qtable{ border: 2px solid red; }";

SortId adds a Sort-ID to the question, through which it can be sorted within a block.

SortId = "F1";

HtmlPreText adds an additional text before the title. This requires the HTML parameterwritePreText to be set. Please refer to section 5.3.

HtmlPreText = "One more text before the text attribute.";

HtmlPostText adds an additional text behind the possible answers to the question. This requiresthe HTML parameter writePostText to be set. Please refer to section 5.3.

HtmlPreText = "A text behind the text attribute.";

PreHelptext adds a help text before text. This requires the script parameter showHelptext tobe set. Please refer to section 5.2.



PreHelptext = "Assistance to fill in the question.";

PostHelptext adds a help text behind text. This requires the script parameter showHelptext

to be set. Please refer to section 5.2.

PostHelptext = "More assistance for completing the question.";

PreInterviewerHelptext adds a text before text, that is intended as instruction for theinterviewer. This requires the script parameter showInterviewerHelptext to be set. Pleaserefer to section 5.2.

PreInterviewerHelptext = "Instructions for reading the question aloud.";

PostInterviewerHelptext adds a text behind text, that is intended as instruction for theinterviewer. This requires the script parameter showInterviewerHelptext to be set. Pleaserefer to section 5.2.

PostInterviewerHelptext = "More instructions for reading the question aloud.";

InitActionBlock For executing of application logic before presentation of the question. Pleaserefer to chapter 14.

ContinueActionBlock For executing of application logic after presentation of the question.Please refer to chapter 14.

Flt Filter condition that states if the question is to be displayed or skipped when the participantarrives at it. A detailed descriptions of filters is found in chapter 10.

flt = (f1 eq 1); // display if question contains f1 answer 1

ShowMaxLabels Possibility of limiting the maximum number of displayed labels in a question.For example this can be useful, if a list of N labels is to be display randomly, but it shouldalways only randomly select the first K items. ShowMaxLabels functions with Single(Grid)Qs,Multi(Grid)Qs as well as NumQs.

ShowMaxLabels = K;

SingleQ f1;

Text="TEXT";

labels=

1 "Label 1" random

2 "Label 2" random

3 "Label 3" random

4 "Label 4" random

5 "Label 5" random

6 "Label 6" random

;

ShowMaxLabels = 3;



With the rotation linked to the ShowMaxLabels command three random labels are displayed.

NoMissing The obligation for input for a single question can be turned on or off with thiscommand and has a higher priority than DefaultNoMissing (Please refer to section 5.1).

NoMissing = Yes/No;

Assert Examination of a (plausibility) condition after answering the question, which may lead toeither the question is presented again with an error message or the entire interview is terminated(ScreenOut). There are detailed descriptions of plausibility conditions in chapter 10.

assert (f1 eq 1) "Question f1 was not answered with 1" exit 2;

3.3 SingleQ

A SingleQ allows 1-of-N selection. As with all other questions, question text and title areoptional. Answer labels, however, are absolutely necessary. The label definition can become verycomplex. Full explanations of the labels are available in section 3.11.

There are different arrangements for the SingleQ (and also the MultiQ), which can be switchedwith the HTML script parameters singleQFormat:

standard - labels in row, buttons left

table - labels next to each other, buttons at the bottom

select - labels as a dropdown list (only SingleQ)

// HTML{ singleQFormat = standard; };

// HTML{ singleQFormat = table; };

HTML{ singleQFormat = select; };

SingleQ favorite_brand;

Text = "Which of these brands is your favorite brand??";

labels=

1 "Brand A"

2 "Brand B"

3 "Brand C"

4 "None of them"

;

To save the answer code, GESS Q. uses the name of the question as the variable name. In thisexample, when selecting »Brand C«, the value 3 is saved in the variable favorite_brand .

"favorite_brand" "3"

Furthermore, with @insert(selectQUESTIONNAME) SingleQs can be embedded as a selectionlist at any point in the text fields. These need to be positioned within the respective screen,without being displayed as a question. Example:



HTML { input=no; };

singleq other;

labels=

1 "other option A"

2 "other option B"

;

HTML { input=yes; };

multiq mainquestion;

text="Which option do you prefer?";

labels=

1 "option a"

2 "option b"

3 "option c"

9 "other, please select: @insert(select others)"

;

Screen scr = column(many question others);

Details on the HTML parameter input can be found in section 5.3.

3.3.1 Alternative Selection Options

The SingleQ can also offer a combination of input field and list and shortens the list by anincremental search for the already entered characters.


SingleQ streets;

text="Please select a street ...";

labels=

9999 ""

1 "Dorset Street"

2 "Carnaby Street"

3 "Brick Lane"

4 "Keats Grove"

5 "Marylebone Road"

;

assert (streets 9999) "Please choose.";

javascript="$('.streets .qselect').combobox();";

Additionally ingleQClass="GSingleQ";HTMLs;must be set, which usually takes place in the file gbuttons.q in the foldertext.

A further possibility is to scroll through the possible values. The name of the JavaScript functionthat provides this mechanism relates to the mouse wheel, but it works just as well with fingerson the tablet.


singleq hour;

labels =

99 "hour"

1 "1"

// ...

23 "23"



24 "24"

;

javascript="

createWheelSelector($('.hour .qselect'), 60, './media/@insert(_surveyname)/

scrollerimages/');

";

assert (hour ne 99) "Please select the hour.";

// createWheelSelector(SELECTBOX, WIDTH-IN-PX, PATH-TO-LAYOUT-IMAGES);

The function call createWheelSelector is supplied with several parameters. First, the questionname or variable name must be given as a CSS class name (here: ».hour«). Second, in thefunction call stands the width in pixels (here: 60) and lastly, the function receives the path tothe graphic elements. The templates for the graphic elements can be found in the directoryroot/media/demo_singleq_select/scrollerimages . The graphic elements are necessary,because they highlight the value that was selected.

Figure 3.1: SingleQ Alternatives: List, List with Search, Scrollable List

3.4 MultiQ

Besides the SingleQ, the MultiQ is a syntactically identical counterpart that allows an N-of-Mselection. The HTML script parameter singleQFormat switches also the arrangement of aMultiQ, apart from the option select. Please also refer to section 3.3.

MultiQ favorite_brands;

Text = "Which of these brands do you know?"

labels=

1 "Brand A"

2 "Brand B"

3 "Brand C"

4 "None of these" single

;

GESS Q. saves the entry in an array with the codes of the selection (in the order in which theselection has been made) and enters the missing value for the labels, that were not selected.When clicking on "Brand C" before clicking on "Brand B", GESS Q. stores (by a missing value of99):

"favorite_brands" "3 2 99 99"

It doesn’t matter how often the selection was made and was withdrawn, GESS Q. stores the lastselection made.



There is a substantial difference to SingleQ, when querying the variables. Since the variableof a SingleQ only stores one value, conditions for filters or plausibility checks can work withassert with the equality operator eq. On the other hand MultiQ questions store multiple values,so examination formulated with eq has limited usage. In the example above, the values »3 2 9999« for the variable favorite_brand

flt=( favorite_brand eq 2 ) changepbar(1);

would run empty, also when »2« is part of the results area (the filter would function only ifthe area consists only of »2« and missing-value). Therefore an in should be used by a MultiQ

examination:

flt=( 2 in favorite_brand ) changepbar(1);

3.5 OpenQ

In an open question, a field for input of free text appears in place of answer labels. Width andheight of the area is defined by the HTML script parameter textAreaRows (number of rows)and textAreaCols (columns). If only one line is desired, a single line is automatically generatedfrom the area. Additionally and primarily the input range can be formatted with CSS. Moreinformation in section 15.3.

HTML{ textAreaRows = 4; };

HTML{ textAreaCols = 80; };

OpenQ likes;

text = "What do you like particularly well in this brand?";

GESS Q. saves the entered text of the OpenQ in the string:

"likes" "design processing"

3.6 PasswdQ

The syntax corresponds to the syntax of an OpenQ, however, a password field (with points as aplaceholder for the letters) is used for the representation.

3.7 TextQ

A TextQ is strictly speaking not a question but only a text screen. The syntax is the same asby the OpenQ, but no text box is displayed. A TextQ may have a question text, a title, and theactual text So this is not necessarily specified in the question text. The keyword for this isscreentext. Example:

TextQ interviewer_instructions;

Text = "Instructions for the interviewer ";

screenText="Dear interviewer, please do this and that now!";



3.8 NumQ

A NumQ offers the possibility to make an open question about one or more numeric values (forexample age, zip code and so on). Each label corresponds to an input field. The expectedentry of the respondents can be accurately controlled. The definition is carried out via theOpenNumFormat.

The format by a NumQ limits the input options of the interviewees.

OpenNumFormat NAME = VMIN VMAX NMIN NMAX WMIN WMAX [EXCL] "ERR";

With NAME the OpenNumformat is bound with format to individual labels. It specifies thenumber of predecimal signs VMIN to VMAX, number of the significant decimal signs NMINto NMAX and the total value range WMIN to WMAX. Optionally, a value for an abstentionoption EXCL can be determined outside of the actual value range. If the entry of an intervieweeis in violation to these specifications, the error message ERR is displayed. Negative values canalso be used. Sign (- / +) don’t count for the * MIN / * MAX values. The same applies todecimal separator. Here both the point and that the comma are valid and equivalent. Thousandsseparators are not supported.

OpenNumFormat rating = 1 2 0 0 -10 10 "Please only integers between -10 and

10.";

NumQ nq;

Text="Please evaluate all brands between -10 and 10.";

labels=

1 "Brand A" format rating

2 "Brand B" format rating

3 "Brand C" format rating

;

The actual input field of NumQ can be placed within the label text as desired with @input,just in the middle of the text flow. In the further course of the script a value, entered withQUESTIONNAME.LABELCODE can be used. The direct reference to QUESTIONNAME returns the sumof all inputs.

NumQ nq;


labels=

1 "For brand A I award @input points" format rating

2 "For brand B I award @input points" format rating

3 "For brand C I award @input points" format rating

;

assert(nq gt 0) "Please award more positive than

negative points";

assert(nq.1 lt 0 or nq.2 lt 0 or nq.3 lt 0) "At least once award a negative

value.";

Like with other questions, an open input field can be offered as a label in a NumQ. This can bedone with the key word open. With @open can also be specified where the input field shouldappear.

NumQ nq;


labels=



1 "For brand A @input points" format rating

2 "For brand B I award @input points" format rating

3 "For @open I award @input points" open format rating

;

GESS Q. always saves the entry of a NumQ in an array. Even if only one value is requested witha NumQ, a warning appears in the script check, if the variable is used only as a sum via thename of the question in check or condition, rather than the exact variable name.

Opennumformat onf_sterne = 1 6 0 0 0 999999 "Miscount!";

NumQ stars;

Text="Do you know how many stars are there?";

labels=

1 "@input stars" format onf_stars

;

GESS Q. saves the entry »367485«

"stars.1" "367485"

Although a comparison like stars gt 1000 works, it causes the addressed warning in the

script check. A check with stars.1 gt 1000 would be better. By the entries »3, -4, 7« inthe previous example »Please evaluate all brands« GESS Q. put the values in this form:

"nq.1" "3"

"nq.2" "-4"

"nq.3" "7"

3.8.1 GNumQ

A variation of NumQ exists with the GNumQ. This allows allows the abstention of the above-mentioned option. For this, however, a graphic element is required, which can only be used ifthe JavaScript library gesstmpl.js is integrated.

A GNumQ offers all the features of NumQ and extends these by an additional function. If the classGNumQ is used, an abstention entry can be added to GNumQ by using the OpenNumFormat withdefined EXCL field. The abstention entry is indicated by a graphical button behind the labelswhich have been defined with the corresponding OpenNumFormat.

In order to create a GNumQ the class NumQ is set to GNumQ over the script parameternumQClass. The OpenNumFormat rating_EXCEL contains a value for the optional EXCL field. If

the rating_EXCL format is used for a label, the graphical representation of a question containsan abstention button for the label. The abstention text is placed via the script parameternoAnswerLabel. So with different OpenNumFormats an abstention option can be deliberatelyadded for individual labels.

HTML{ numQClass = "GNumQ"; };

noAnswerLabel= "No entry";

OpenNumFormat rating_EXCL = 1 2 0 0 -10 10 99 "Please only integers between -10

and 10.";

OpenNumFormat rating = 1 2 0 0 -10 10 "Please only integers between -10 and

10.";

NumQ nq;




labels=

1 "Brand A" format rating_EXCL

2 "Brand B" format rating_EXCL

3 "Brand C" format rating

;

The graphical element for the abstention is defined by the HTML properties unspecified_button_checked

andunspecified_button_unchecked by means of the instruction setProperty:

HTML{ setProperty( "unspecified_button_checked" "round_cl.png" ); };

HTML{ setProperty( "unspecified_button_unchecked" "round_ac.png" ); };

3.9 SingleGridQ

With a SingleGridQ a grid of scales can be represented, for example, a list of items in a row.Both the gridItems and the answer categories gridLabels are stated in the form of label lists.For each item only one answer can be selected. Also multiple groups of answer labels can standnext to each other. The line with the answer labels can be repeated in all n items (useful foritem lists).

The general syntax is:

SingleGridQ name;

Text="question text";

gridItems=

value text

...;

gridLabels=

value text

...

;

There are different variations of the SingleGridQ.

3.9.1 Standard-Grid-Question

Multiple items are displayed in a row on the side of the grid. Right of the items appear the answerchoices, the answer labels in the head of the grid. Above the answer label gridLabelHeader

(headings) can be added to the table, as well as an anchorText top left in the otherwise emptycell. Normally GESS Q. reports only one error for an incompletely filled grid question. WithshowAllErros; can be also set that for each incorrect row in the grid a message will be output.

Example:

SingleGridQ standardgrid;

text="How do you agree with the following statements?";

gridItems=

1 "item 1"

2 "item 2"



3 "item 3"

4 "item 4"

5 "item 5"

;

gridLabels=

1 "completely agree"

2 "rather agree"

3 "partially agree"

4 "rather disagree"

5 "completely disagree"

;

3.9.2 Transposed Grid Question

In the transposed grid question, the items in the head and the label are on the side of the grid.For each item still only one answer is possible. It differs from a simple swapping of item labelsand header labels, because the questions / scales are not positioned horizontally (next to eachother) but are vertical to each other.

The only difference to normal grid question consists of the ending of the transposed version withthe keyword transpose.

Example:

SingleGridQ transposed;

text="How likely is for you to visit these cities?";

gridItems=

1 "Rom"

2 "Berlin"

3 "London"

;

gridLabels=

1 "certain not to visit"

2 "probably will not visit"

3 "don't know"

4 "probably will visit"

5 "sure to visit"

;

transpose;

showAllErrors;

3.9.3 Grid Question with Multiple Question Blocks (Label Groups)

If multiple questions that relate to the same items are to be displayed side by side, a second gridlabel definition is added. In GESS Q. we speak of an additional Labelgroup. The items (alsothe lines) are defined with the statement gridItems, the labels for the first question - with thelabel statement gridLabels, the labels for the second question (to the right of the first) - alsowith gridLabels and so on.

Separate headings for both question blocks are created using the command gridLabelHeader.These appear in the top row of the grid and extend across the width of the answer options to



the question. Furthermore, an additional text can be inserted into the upper left corner of thegrid with the command anchorText.

Example:

SingleGridQ twoquestions;

text="Please evaluate the mentioned cities.";

gridItems=

1 "Rom"

2 "Berlin"

3 "London"

;

gridLabels=

1 "good"

2 "middle"

3 "bad"

;

gridLabels=

1 "yes"

2 "no"

;

gridLabelHeader=("How do you like the city overall?"

"Have you visited the city before?");

anchorText="Please evaluate!";

3.9.4 Data Storage and Access

Both the SingleGridQ and the MultiGridQ consist of multiple individual SingleQs respectivelyMultiQs, which are stored separately with systematically generated names in the data sets. Withthese name the values of the variables in the script can be retrieved. The names of the variablesare build as follows:

GRIDNAME.ITEMCODE.LABELGROUP

LABELGROUP is increased with each additional defined label group, starting at 1. In the lastexample, SingleGridQ twoquestions , the label group with the answer options good, middleand bad corresponds to 1 and the group with answer options yes and no corresponds to 2. Ifthere is only one question definition in the label group, it automatically receives 1.

Example:

Has the interviewee already visited London? (twoquestions.3.2 eq 1)

Has the interviewee not visited London? (twoquestions.3.2 eq 2)

Did the interviewee find Rome bad? (twoquestions.1.1 eq 3)

Did the interviewee find Rome good or medium? ([1 2] in twoquestions.1.1)

A more detailed example follows in the section on MultiGridQ (please refer to section 3.10).

3.9.5 Directionals / Bipolar Scales

A SingleGridQ can be displayed in such a manner, that the gridItems appear on both sidesof the label. The texts in the gridItems are separated by a | and the question definition iscompleted with bipolar.



Example:

SingleGridQ bipolar;

text="Directionals";

gridItems=

1 "too sweet | too sour"

2 "too soft | too hard"

3 "too cheap | to expensive"

4 "too big | too small"

;

gridLabels=

1 "(1)"

2 "(2)"

3 "(3)"

4 "(4)"

5 "(5)"

;

bipolar;

3.9.6 Further GridQ parameter

labelRepeat With longer item lists the line with the answer options can slip out of the visiblescreen area when scrolling. With the question attribute labelRepeat = K; it is possible torepeat all K rows in the matrix.

labelRepeat = NUMBER;

repeatGridAnchor It is also possible to repeat AnchorText with the repeatGridAnchor,matching the question attribute labelRepeat. This command works only in connection withlabelRepeat and requires a defined AnchorText.

repeatGridAnchor;

gridLabelFooter analogous to GridLabelHeader a gridLabelFooter that will appear underthe label list, can also be inserted. Since GridQs can also have multiple label lists, a label listcan be assigned per footer.

gridLabelFooter = ("FOOTER1" "FOOTER2" "...");

gridLabelRestrict filters a label list, so that only the labels (with the codes) are displayed,which are included in the set of values of a given variable (for example, a previously answeredquestion). In this case the brackets are absolutely necessary. For multiple label groups, multiplespace-separated variables can be stated.

gridLabelRestrict = (VARIABLE);

MultiQ m1;

Text="TEXT";

Labels=



1 "Label 1"

2 "Label 2"

3 "Label 3"

4 "Label 4"

;

SingleGridQ sq1;

Text="TEXT";

gridlabels=

1 "Label 1"

2 "Label 2"

3 "Label 3"

4 "Label 4"

;

griditems=

1 "Item 1"

2 "Item 2"

3 "Item 3"

4 "Item 4"

5 "Item 5"

;

gridLabelRestrict = (mq1);

gridItemRestrict works similar to the simple Restrict (please refer to section 3.11.)

gridItemRestrict = VARIABLE;

3.10 MultiGridQ

The MultiGridQ functions according to the SingleGridQ. The difference is, that here it ispossible to give multiple potential answers for each item.

All of the above explained functionalities and question attributes of the SingleGridQ can beanalogously applied to the MultiGridQ as well.

The properties of the answer label, possible in the MultiQ: single and always, are also applicableby the MultiGridQ.

Since the data storage is getting complicated parallel to the SingleGridQs, here follows a slightlymore detailed example. A MultiGrid question with the following code:

multigridq s1;

text="Gadgets";

gridlabels=

2 "television"

4 "newspaper"

6 "cinema"

8 "don't know" single

;

griditems=

1 "telephone"



2 "camera"

3 "tablet"

4 "phablet"

95 "others" open

;

is presented by GESS Q. as follows. The GESS Q. uses, as discussed above, systematic variablenames for the gridItems and assigns the values predetermined by the label.

Figure 3.2: Data Storage of a MultiGridQ

And as the graphic already indicates, the MutliGrid question stores the entries in this form( _missing = -1 ):

"s1.1.1" "2 4 6 -1"

"s1.2.1" "4 6 -1 -1"

"s1.3.1" "8 -1 -1 -1"

"s1.4.1" "6 -1 -1 -1"

"s1.95.1" "4 -1 -1 -1"

"s1.95.open" "glasses"

To make sure that only the people, who will not say »don’t know« to phablets, are beinginterviewed, the assert formulation would look as follows:

assert( not( 8 in s1.4.1 )) "Sorry" exit 2;

Furthermore, it should be ensured that the entry field is filled, as long as »don’t know« isn’tchecked to open question:

if( [2 4 6] in s1.95.1 ) assert( num(s1.95.open) gt 0 ) "Please enter gadgets;

As already explained in the context of (section 3.4), checks of MultiQ variables using the equalityoperator eq have limited use, because MultiQ questions save the result sets. Since MultiGridQ

questions are composed of individual MultiQ questions, the same applies.



3.11 Answer Label

Many questions have a list of possible answers (labels), from which the interviewee selects oneor more. GESS Q. offers various possibilities to design this list. This chapter begins with thedescription of the possibilities of label lists and then illustrates these with actual examples.

A list of labels is defined in the context of the question definition within the statementlabels = ...; . Hereby any sequence of individual labels or label groups can be defined.Generally expressed:

labels=

[LABEL | LABELGROUP | splitcolumn]+

;

splitcolumn A new column begins in the graphical representation with this keyword. In thisway, long label lists can be distributed across multiple columns.

LABELGROUP is a structuring element. The LABELGROUP can contain LABEL and furtherLABELGROUPS. From the technical point the label list itself is also a label group.

group(

[LABEL | LABELGROUP | splitcolumn]+

)

LABEL may be either a pure TEXTLABEL or a ANSWERLABEL. Label can be provided with parameters.

LABEL = [ TEXTLABEL | ANSWERLABEL ]

TEXTLABEL is used for the structuring of the answer options. Text labels can serve as headingsfor groups or, if necessary, simply add blank lines (without content). Optionally, they canbe provided with a restrict attribute, whose CODES works as a filter. The text label is onlydisplayed if one of the mentioned codes still exists in the finally shown label list, after executionof all the label filters. This type of filtering for text label is adopted by the general restricts.

text "LABELTEXT" [restrict(CODES)]

MultiQ known;

text="Which brands do you know?";

labels=

text "Audi" restrict([1:3])

1 "A3"

2 "A6"

3 "A8"

text "BMW" restrict([4:6])

4 "3"

5 "5"

6 "7"

;

MultiQ bought;

text="Which have you bought already?";

labels copy known;

restrict=known;



ANSWERLABEL is selectable answer option, which simultaneously assigns a code to the respectivename. The code is stored in the data and must not be assigned more than once to each questionvariable.

LABELCODE "LABELTEXT"

The following example shows how the possibilities, discussed so far, can be used:

multiq meals;

text="Please select all the meal that you like to eat.";

labels=

text "meals with meat"

11 "rump steak"

12 "pork cutlet"

13 "goulash"

14 "gyros"

splitcolumn

text "meals with fish"

21 "fish sticks"

22 "fish soup"

23 "pan fish"

splitcolumn

text "vegetarian meals"

31 "vegetable risotto"

32 "bruschetta"

33 "Greek farmers salad"

;

// Graphical output scheme:

//

// meals with meat meals with fish vegetarian meals

// -----------------------------------------------------------------------

// [] rump steak [] fish sticks [] vegetable risotto

// [] pork cutlet [] fish soup []

bruschetta

// [] goulash [] pan fish [] Greek farmers salad

// [] gyros

LABEL can optionally be provided with one or more parameters:

LABELCODE "LABELTEXT" [always] [flt] [open] [random] [single]

always A label with this attribute is always displayed even if the restriction condition is notsatisfied.

flt provides a label or an entire label group with a condition. The label respectively the groupis only displayed if the condition is met.

open combines the label with a single-line input field for free text which, for example, can beused for "Other information". The input field can be referenced in the script and can be found inthe data with the variable name QUESTIONNAME.LABELCODE.open.



random All the labels and label groups that have this attribute within a group, are presented inrandom order. The order is determined once at the start of the interview.

single The keyword is relevant if more than one answer can be given. Labels with theattribute single are exclusive answers, such as "none of them" or "unspecified". Using thejavascriptSingleMode (please refer to section 5.3) two options can be defined, how the questionreacts to a single selection: Either a click on a single answer disables all others, so that theyare no longer selectable or it automatically deselects all answers that were previously selected.

In order to represent all concretely, a few examples:

Let’s assume a list of car brands must be queried:

MultiQ brands;

labels=

1 "Audi"

2 "BMW"

3 "Mercedes-Benz"

;

These have to appear in random order (that means, different from interview to interview). Forthis we use random behind each label:

MultiQ brands;

labels=

1 "Audi" random

2 "BMW" random

3 "Mercedes-Benz" random

;

In a further question should be asked if three models of each brand are known to the interviewee.Here is the simple version of the label definition:

MultiQ models;

labels=

1 "Audi A4"

2 "Audi A6"

3 "Audi A8"

4 "BMW 3 series"

5 "BMW 5 series"

6 "BMW 7 series"

7 "Mercedes-Benz C-class"

8 "Mercedes-Benz E-class"

9 "Mercedes-Benz S-class"

;

To make it look a bit nicer, the brands should stand as a simple text line over the label:

MultiQ brands;

labels=

text " "

text "Audi"

1 "A4"

2 "A6"

3 "A8"



text ""

text "BMW"

4 "3"

5 "5"

6 "7"

text ""

text "Mercedes-Benz"

7 "C-class"

8 "E-class"

9 "S-class"

;

Like in the question about the brand recognition, the brand must now be displayed in a randomorder, including their headlines, inserted with text. For this purpose we combine them intogroups and give the groups the attribute random:

MultiQ models;

labels=

group (

text ""

text "Audi"

1 "A4"

2 "A6"

3 "A8"

) random

group (

text ""

text "BMW"

4 "3"

5 "5"

6 "7"

) random

group (

text ""


7 "C-class"

8 "E-class"

9 "S-class"

) random

;

The individual models must now also be distributed randomly within the brands:

MultiQ models;

labels=

group (

text " "

text "Audi"

1 "A4" random

2 "A6" random

3 "A8" random

) random

group (



text " "

text "BMW"

4 "3" random

5 "5" random

6 "7" random

) random

group (

text " "


7 "C-class" random

8 "E-class" random

9 "S-class" random

) random

;

Furthermore, the models of a brand should only be queried if the brand was already indicated asknown. To make this work each label group is provided with a filter. In addition, there is anexclusive answer option available - none of the above. There the attribute single is used. Soit looks like this:

MultiQ models;

labels=

group (

text " "

text "Audi"

1 "A4" random

2 "A6" random

3 "A8" random ) random flt (brands eq 1)

group (

text " "

text "BMW"

4 "3" random

5 "5" random

6 "7" random ) random flt (brands eq 2)

group (

text " "


7 "C-class" random

8 "E-class" random

9 "S-class" random ) random flt (brands eq 3)

text " "

10 "none of the above" single

;

The potential complexity of label definitions becomes evident here. It doesn’t matter howaccurately the line breaks are set, as theoretically everything could also be written in one line.

Furthermore the placeholder @input can be added by the NumQ in the place of the label text, onwhich the input field should appear. Please refer to section 3.8.

NumQ points;

Text="Please distribute 10 points to these brands";

labels=1 "brand A: @input points" format f1



2 "brand B: @input points" format f1

3 "brand C: @input points" format f1

4 "brand D: @input points" format f1

5 "other brand (please specify) @open : @input points" format f1;

labels copy, griditems copy, gridlabels copy With this instructions labels, respectivelygriditem, from previous question can be used again. The instruction labels copy belongs tothe non grid questions, while griditems/gridlabels copy is available for grid question.

SingleQ s1;

text="Text Text";

labels=

1 "1"

3 "3"

;

MultiQ s2;

text="Text Text";

labels copy s1

;

from grid question to grid question:

SingleGridQ s1;

text="Text Text";

gridlabels=

1 "gl 1"

2 "gl 2"

;

griditems=

3 "3"

4 "4"

;

MultiGridQ s2;

text="Text Text";

gridlabels copy s1

;

griditems copy s1;

;

and from non grid question to grid question and respectively the other way around

// non grid to grid

SingleQ s1;

text="Text Text";

labels=

1 "1"

2 "2"

;

MultiGridQ s2;

text="Text Text";

gridlabels



1 "gl 1"

2 "gl 2"

;

griditems copy s1;

;

// grid to non grid

SingleGridQ s1;

text="Text Text";

gridlabels=

1 "gl 1"

2 "gl 2"

;

griditems=

3 "3"

4 "4"

;

SingleQ s2;

text="Text Text";

labels copy s1

;

insertLabels adds more labels APPENDLABELS to the current label list. The new labels aresorted behind the label with the label code LCODE.

insertLabels = LCODE( APPENDLABELS );

SingleQ s1;

labels=

1 "1"

3 "3"

;

SingleQ s2; // s2 receives the following label list

labels copy s1; // labels=

insertLabels= // 1 "1"

1( // 2 "newly added"

2 "newly added" // 3 "3"

); // ;

shareLabels Unlike labels copy the shareLabels doesn’t function with a copy of the list.Changes to the label list, such as with insertLabels will affect both questions.

SingleQ s1;

labels=

1 "1"

3 "3"

;

SingleQ s2;

shareLabels = s1;



restrict filters a label list, so that only the labels (with the code) which are included in the setof values of a previously answered question are displayed. This allows working very easily withpreviously given answers. Instead of the set of values, a RestrictVar can also be specified. Formore information please refer to section 8.11.

MultiQ known;

text="Which of these products are known to you?";

labels=

1 "product 1"

2 "product 2"

3 "product 3"

4 "product 4"

5 "product 5"

6 "product 6"

;

MultiQ bought;

text="Which of the products have you purchased already?";

labels copy known;

restrict=known;

flt=(num(known) gt 0);

If it must be operated with a negative list, the restrict with the not must be put in parentheses.

restrict=(not(known));


Chapter 4. Definition of the Interview Process

4 Definition of the Interview Process

4.1 General

The interview consists of a tree-structure. The smallest unit is the question. The questions canbe combined into a screen (actually it would be more accurate: a website; we call it a screen)and the screens turn into blocks, which can be inserted into each other.

4.2 Blocks

Each block has a name. With main there is a block which must always be present and whichis also the entry point of the interview. During an interview, the content of the block main

is sequentially executed. The sequence can consist of a simple, linear order of questions, but itcan also have any degree of complexity due to multiple insertions, filter managing or randomarrangements (randomization).

Each block can contain more blocks as well as screens. The screens on the other hand containthe questions. If a screen contains only one question, it is not necessary to define explicitly ascreen for this question, rather a standard-screen, having the same name as the question, willbe generated. On the user end it will look like as if a question is directly added to a block, butactually a screen will be automatically generated.

The management of questions/screens in blocks enables to encapsulate parts of the interview.In this manner it is possible to provide a block of questions only if certain conditions are fulfilled.Also the questions within a block can be delivered in a random order for an interview or for aninterviewed group.

4.3 Screens

Screens contain the real questions that can be arranged in a recursive structure of columns androws. The following will serve as keywords for the arrangement of questions in columns androws: column and row. A screen has thereby exactly one question text, but every question inthe screen can have its own headline (displayed directly over the question), which title thequestion. One could define his own question text for a screen; unless this is done, the questiontext of the first question of the screen will be used automatically. (Detailed explanations ofscreens are offered in chapter 7.)

It is also possible to design screens completely with HTML independent of the question, butmore on that later (refer to section 15.4).



4.4 Examples

Let’s assume that the entire interview consisted only of a, b and c questions, displayed behindeach other in a linear sequence. The main block would look as follows:

block main=(a b c);

But if all the three questions must be displayed in a screen one below the other and the interviewmust consist solely of this screen, the syntax is:

Screen screen1=column(a b c);

block main=(screen1);

In order to achieve the desired sequence one must add at first the questions to the screen andthen the screen to the main block.

Let’s assume that, there are two TextQs text1 and text2 , and each TextQ is a SingleQ witha scale linked to it - so what is being described in the text can be evaluated ( scale1 andscale2 ). The texts must be next to each other and each scale must be under the text to whichit belongs, and the screen must get its own question text:

Screen pictures=row(

column(text1 skala1)

column(text2 skala2)

);

text="Please evaluate the two pictures!";

The nested structure of columns and rows can be achieved by the instructions column and row.The structure can also be designed with any degree of complexity by column and row.

Once again let’s assume that, there is a question asking about the gender of the interviewee.If the questions a, b, c, d must be addressed only to men, and the questions e, f, g, h only towomen, this can be done with two blocks, where the answer of the question about the genderwill be used as a filter (For more on the syntax of filters and conditions refer to chapter 10):

block block_m = (a b c d); flt=gender eq 1;

block block_w = (e f g h); flt=gender eq 2;

block any_block = (block_m block_w);

block main = (gender ... any_block ...);

Filters are added to a block with the keyword flt

A random sequence of five questions (q1, q2, q3, q4 and q5) can be easily achieved:

block fortuity = (q1 q2 q3 q4 q5); random;

block main = (fortuity);

Randomization is done by the keyword random.

It is possible to have a flexible control over the interview process with the hierarchical insertionof questions into screens and screens into blocks. There are also other possibilities to controlthe process except those mentioned so far. Such are, for example the plausibility conditions orsorting elements by sequence, recovered from the recent interview. (Refer to chapter 10)



4.5 Whitelist

Furthermore GESS Q. can use the mechanism of a whitelist to control the process of aninterview. The whitelist is a JSON-file with listings of questions, screens and blocks (includingthe labels and items). The elements, contained in the script but not contained in the whitelist,will be omitted in the interview. In order to use the whitelist, it must be in the text folder ofthe study and be linked via URL parameters. (For URL-parameters also refer to section 21.3):

&whitelist=fila name

In general, the whitelist mechanism could make it possibe to link different sequences to differentIDs.


Chapter 5. Interview Settings

5 Interview Settings

5.1 General

In this chapter, all available script parameters are listed and explained in alphabetical order, bycategory. Besides script parameters there are HTML parameters. Differentiation exists only forhistorical reasons. In the early stages of development, there were very different graphic outputsfor possible GESS Q. devices which brought all its peculiarities with it. At that time HTMLwas the graphics system for online surveys in Internet browsers. Meanwhile, the technology is sofar advanced that devices are increasingly connected to the World Wide Web and also supportHTML output by providing full browsers. The current versions of GESS Q. are all based onHTML, which leads to the fact, that now on one hand we have script parameters that wereoriginally valid for all output media and on the other hand »just« HTML parameters, whichparticularly deal with the HTML layout.

An example for clarification: The script parameter defaultnomissing specifies, whether an inputmandatory for the following questions should be provided or not. This is a script parameter, as thissetting is independent of the screen produced by the question. The BrowserNavigationMessage

however, is an error text which can occur only in connection with the use of the browser andthus is an HTML parameter.

The management of the two varieties of parameters remained so far only for compatibility reasons,but it is planned in the long run. However, at this point it is important the awareness, that thereare distinctions which affect the writing of the script:

// Script parameter

defaultnomissing = yes;

// HTML parameter

HTML{

BrowserNavigationMessage = "Please don't use the back button of your browser

.";

};

5.2 Script Parameters

There are two different behaviors of script parameters. Some apply to the entire questionnaireand are global where the last definition in the script wins. The other parameters can be changedfrom question to question and so affect the behavior of each question differently locally. Thefollowing sample script illustrates the behavior of the global DataWriteCondition and the localDefaultNoMissing:

DataWriteCondition = true; // (1) always write records

DefaultNoMissing = yes; // (2) mandatory input on

SingleQ S1;

// ...

DataWriteCondition = false; // (3) never write records

DefaultNoMissing = no; // (4) mandatory input - override (2)



SingleQ S2;

// ...

In the example above SingleQ S1 receives a mandatory input (2), which is turned off after

the question definition (4). Thus, the thereafter defined SingleQ S2 has no more mandatoryinput. On the other hand, the global parameter DataWriteCondition behaves differently.The illustrated usage is not intended like that. The setting is valid only once for the entirequestionnaire, regardless of where in the script the definition was made. Entry (4) overridesentry (2) and makes it non effective. So to the entire interview applies that records are neverwritten. Several definitions of global parameters are therefore not useful. In the following [G]indicates a global parameter and [L] indicates a local parameter.

ArrayInitMode [G] defines, if the fields in the created array are initialized in ascending orderor using the missing value.Options: missing|position

Default: missing

ArrayInitMode = position;

Array arr[5]; // {1, 2, 3, 4, 5}

autoChangePBar [G] automatically moves forward the progress bar of filtered questions / screens/ blocks respective number of screens. It is global alternative to ChangepBar, however, it can beused additively (section 10.3.2)Options: yes|no

Default: no

autoChangePBar = yes;

ClearScreenOnBack [G] defines whether the Back Button causes the deletion of the answers tothe currently displayed question.

It is a matter of a somewhat problematic setting. Most studies use the Back Button only in thetesting phase, because it is easier to check the filters with it. The default is not to delete bygoing back, which does no harm here, because any produced records don’t flow into the study.

If the interviewees should be given the opportunity to follow their own way, the given answersshould also be preserved. Problems arise, however, when by going back the interviewee decidesto change the answer to a question at earlier point, thus possibly fall into a filter, which providesa different path through the interview. In this case, the answers to the first variant are retainedand the responses of the second are then added.

The dilemma cannot be resolved, it can only be switched off with ClearScreenOnBack = yes; .

Options: yes|no

Default: no

ClearScreenOnBack = yes;

CompletedExitCode [G] defines the finish code, assigned to regularly finished surveys. Regularmeans that the interview is completely made, no premature end of the survey is enforced usingassert and no manual modification of finish codes was made in the script.Options: NUMBERDefault: 1

CompletedExitCode = 100;



ComputeMissingAsZero [G] By activation this setting effects the unoccupied variable respec-tively variables with the value _missing. By calculation these take the value 0 instead ofMissingValue. Here comparisons with eq etc. are not understood as a calculation.Options: yes|no

Default: yes

ComputeMissingAsZero = no;

CreateDefaultSortId [L] When activated, this setting ensures that all possible answers withlabel code are provided as sortID automatically with their code. Detailed descriptions of thesorting mechanisms of GESS Q. are found in chapter 11.Options: yes|no

Default: no

CreateDefaultSortId = yes;

CreateLabelOpenValidation [L] If this setting is activated, a validation of open text fields inlabel lists is generated automatically. If there is a check on a corresponding label, the associatedtext field must also be filled. If the text box filled, the label must be checked. If this automaticvalidation is violated, the error message LabelOpenErrorMessage is displayed.Options: yes|no

Default: no

CreateLabelOpenValidation = yes;

DataWriteCondition [G] defines the condition under which at the end of an interview datashould be written. If the condition is not met, the GESS Q. still generates records as safetyagainst accidental data loss. These are sent to the backup folder nodata and are listed in theuser interface on the page of the data export separately as »ignored data«.Options: CONDITIONDefault: false

DataWriteCondition = _finished eq 1;

#ifdef testmode

DataWriteCondition = false;

#endif

DefaultNoMissing [L] activates and deactivates the mandatory input for the following questions,defined in the script.Options: yes|no

Default: yes (mandatory input activated)

DefaultNoMissing = no;

DisableExitOnAssert [G] When enabled, interview terminations are suppressed through plau-sibility conditions (or more precisely: asserts with EXIT). Such assert behaves then as if ithas no EXIT. In the error message is displayed an additional indication incl. termination code,that at this point an interview termination actually happened. Linked with #ifdef testmode ,this parameter makes easier the testing of the studies.(Please refer to section 2.4).Options: yes|no

Default: no

DisableExitOnAssert = yes;



EnableTextReplace [G] activates and deactivates the text replacement, please refer to chapter 6.Options: yes|no

Default: yes

EnableTextReplace = no;

GridOpenNoMissing [L] For open items in grid questions a mandatory input can be tuned on(then the open field has to be filled in).Options: yes|no

Default: no

GridOpenNoMissing = yes;

ignoreFilter [G] If the variable is set to yes the interview can be done, as if there were nofilters. Please refer to theme Robot in section 25.2.1.Options: yes|no

Default: no

ignoreFilter = yes;

ignoreAssert [G] If the variable is set to yes the interview can be done, as if there were noplausibility conditions. Please refer to theme Robot in section 25.2.1.Options: yes|no

Default: no

ignoreAssert = yes;

ignoreNoMissing [G] If the variable is set to yes the interview can be done, as if there wereno mandatory inputs. Please refer to theme Robot in section 25.2.1.Options: yes|no

Default: no

ignoreNoMissing = yes;

InvalidIdMsg [G] defines the text of the message, which the interviewee gets, if he tries to makea second interview with an individual invitation link or if the link is invalid or his participantsID is not defined in the study.Options: TEXTDefault: Invalid respondent ID. This ID has an invalid syntax (only A-Z, a-z and 0-9 are allowed),is not registered to participate or has already been used.

InvalidIdMsg = "No further interviews are possible with your link.";

InvalidSingleMsg [G] By multiple responses with exclusive answers (single) is performed acheck weather only one, if only an exclusive response or only non-exclusive answers are given.If this is not the case, this error message is displayed. The current representations of Multi

(Grid)Qs make sure that only correct answers are accepted. Thus, it can only come to thiserror message when respondents distort the HTML source of the questionnaire manually in thebrowser (_singlemsg).Options: TEXTDefault: "Labels inconsistent."

InvalidSingleMsg = "The statements are contradictory. Please correct.";



ItemMissingText [L] This error message appears, if there is no answer to an item of a gridquestion (so mostly lines) and the mandatory input is turned on. By default, only one errormessage appears even if multiple answers are missing. In grid questions this behavior can beinfluenced by using the optional attributes showMultipleErrors.Options: TEXTDefault: "Please give an answer to all categories."

ItemMissingText = "Please fill out all the lines.";

LabelOpenErrorMessage [G] defines an error code, which appears when the automatic validationof open input fields in the label lists is violated. Please refer to CreateLabelOpenValidation.The uncompleted answers can be directly addressed in the error message using @label.Options: TEXTDefault: "Please respond fully, including text entries."

LabelOpenErrorMessage = "Missing answer for: @label.";

MissingText [L] This error message is displayed when mandatory input is activated and anquestion an the screen is not answered.Options: TEXTDefault: "Please answer the question."

MissingText = "Please answer the question.";

MissingValue [G] defines the value, which the unanswered questions should have at the startof the interview. It is recommended to select a value that otherwise does not play a role in thesurvey. Attention should be paid for the tests and calculations that unanswered questions alsocontain a value that is to be queried separately with the internal script variable _missing.Options: NUMBERDefault: 0

MissingValue = 999999;

flt = S1 ne _missing; // OK: is S1 answered to?

flt = S1 gt 0; // !!! Attention...

MultiExportLimit [L] limits the maximum number of answers for multi questions duringexport. For example, if there is a label list with 500 products and after filtering the intervieweecan only chose 10. It can be set, that GESS Q. only reserves 10 places instead of 500 in theASCII data set. In the raw data all entries are always saved. If there are excess entries comparedto with the MultiExportLimit, these are left out in the export.Options: NUMBERDefault: INFINITE

MultiExportLimit = 10;

NoAnswerLabel [L] specifies the text for abstentions. This concerns concretely sliders andgraphical NumQs optional offering abstention options.Optionen: TEXTDefault: "Unspecified"

NoAnswerLabel = "Abstention";

QuotaWriteCondition [G] With this setting, at the end of the interview will be evaluated anddefined, whether each case should even be included in the quota count. It should be noted that



a QuotaVar itself also defines when it should be counted. Please refer to chapter 12.Optionen: CONDITIONDefault: false

QuotaWriteCondition = _finished eq 1;

#ifdef testmode

QuotaWriteCondition = false;

#endif

PBarMax [G] the number of screens in the interview, which must be taken into account by theprogress bar and uses the number instead of the value that GESS Q. itself has calculated. Moreabout the topic progress bar can be found in section 15.1.4.Options: NUMBERDefault: <calculated value>

PBarMax = 42;

showHelptext [G] defines whether the additional interviewer instructions preHelptext andpostHelptext must be included in the question definition or not.Options: yes|no

Default: yes

showHelptext = no;

showInterviewerHelptext [G] defines whether the additional interviewer instructionspreInterviewerHelptext and postInterviewerHelptext must be included in the questiondefinition or not.Options: yes|no

Default: yes

showInterviewerHelptext = no;

SurveyClosedMsg [G] defines the text of the message that is presented to the participants whenthey try to start an interview, while the study is set to »inactive«.Options: TEXTDefault: The survey is currently inactive. Please try again in a few minutes. If this message stillappears, the survey might already have been closed.

SurveyClosedMsg = "We are sorry, the survey has been completed.";

WriteRescueData [G] determines whether a backup of the dataset must be made after eachcompleted screen. Normally, an active interview is in the memory of the computer that executesGESS Q. Physical data storage takes place only after completion, explicit termination or in caseof a web server by a timeout due to inactivity of the respondent. An unexpected failure of thecomputer would lead to the loss of all active interviews to the last storage point.

The continuous saving of data is very resources consuming and is only recommended on onlymarginally busy web servers. However this feature is completely acceptable and stronglyrecommended with the GESS Q. Android App because only one interview per device can takeplace at the same time.Options: yes|no

Default: no

#ifdef android

WriteRescueData = yes;

#endif



WriteViewingTime [G] sets whether viewing time of the individual screens is to be recorded.Since it is possible in the interviews, that the interviewee can see a screen multiple times - viathe Back Button, but also in the normal linear flow, there are different modes. The optionfirst stores the time that the participant spends at his first time on the screen, last - theduration of the last view and all is the sum of all times. none turns the funciton off. The timeis measured in milliseconds and corresponds to the time from the moment at which the serverhas just delivered the screen, to the time at which the respondent has sent back his response tothe server. Probable time-outs are not taken into account. It should be noted that this featurerefers to viewing times of screens. Although every question is implicit in a screen, GESS Q.builds the screens only when the blocks are created. So in order to measure the time spent on asingle question X, the question must be explicitly placed alone in a screen (or implicitly by usinga block). Please see the example.Options: none|first|last|all

Default: none

TextQ X; text="Please look at the picture...";

WriteViewingTime = first;

block bX = (X); // or: screen sX = column(X);

WriteViewingTime = none;

5.3 HTML Parameter

As previously described, HTML parameters refer to specific circumstances and capabilities ofthe HTML output. Since meanwhile all derivatives of GESS Q. are based on the HTML output,the special script syntax is no longer counterintuitive at first glance. However, as historicallygrown construct it is preserved for compatibility, whereby the strict separation between scriptand HTML parameter is not always entirely clear. If in doubt, one can rely on the syntaxexamination of the script checks in the user interface, which eliminates a possible improper use.HTML parameters can be noted individually or grouped within HTML ; .

HTML{ BackButton = yes; };

HTML{

BackButton = yes;

ContinueButton = yes;

};

As opposed to script-parameters all HTML parameters are local, which means they can bearbitrarily switched between question definitions and can take many different states, over thewhole questionnaire.

BackButton sets whether the Back button should be visible on the screens. This requires that itis also provided with @back in the template of the survey. Please refer to section 15.1.Options: yes|no

Default: no

HTML{ BackButton = yes; };

AddProperty adds a property name and value to the script which can be changed again withChangeProperty. Such properties cannot be queried directly, but are used as settings by some



types of questions (for example, slider or packaging configurator).deprecated: This command is obsolete and will not be supported in the long term. Please useSetProperty.

HTML{ AddProperty( "sl_showValues" "yes" ); };

BackButtonCnd Provided that the Back Button is enabled with the BackButton = yes; , addi-tional condition can be set, when it should actually be visible. Thus, the display of the BackButton can depend dynamically on the answers given by the interviewee.Options: CONDITIONDefault: true

f1 eq 1

BackButtonSrc Instead of the standard buttons of the respective browser, custom buttons fornavigation can also be integrated. This is done based on image files. It is possible to defineeffects when hovering the mouse, as well as differences in appearance depending on whether thebutton is currently inactive or not. Depending on the desired design, the integration can be a bitmore complicated, which is why the procedure is described in detail in section 15.5.

BackButtonText Labeling the Back Button. Only when using the default browser buttons(without BackButtonSrc).Options: TEXTDefault: "back"

HTML{ BackButtonText = "To Previous Page"; };

BrowserNavigationMessage is an error message that is issued by online surveys and by theuse of the browser’s own Back button. During the interview the browser saves the history ofvisited pages. In GESS Q. every screen corresponds to a new web page. Now, if the intervieweejumps a few screens back using the browsers history, this is done from the browser cache withoutcommunication to GESS Q. server. If now the respondent changes his answers to a previousscreen and sends it, GESS Q. actually expects these answers at a completely different point inthe interview and therefore rejects the re-entry, displays this error message and moves to theactual current question. This is displayed in the translation table as _browsermsg.Options: TEXTDefault: "Please do not use the browser buttons to navigate."

HTML{ BrowserNavigationMessage = "This interview, moves only forward."; };

CancelButton sets whether the Cancel Button should be visible on the screens. The prerequisitefor this is, that it is also intended in the template of the survey with @cancel. Please refer tosection 15.1.Options: yes|no

Default: no

HTML{ CancelButton = yes; };

CancelButtonCnd Refer to BackButtonCnd.

CancelButtonSrc Refer to BackButtonSrc.

CancelButtonText labeling the Cancel Button. Only when using the default browser buttons(without CancelButtonSrc).Options: TEXTDefault: "cancel"



HTML{ CancelButtonText = "Interrupt the Survey"; };

ChangeProperty Properties that have been already added to the script using AddProperty, canbe changed with this command.deprecated: This command is obsolete and is not supported in the long term. Please useSetProperty.

HTML{ ChangeProperty( "sl_showValues" "slider" ); };

ContinueButton sets whether the Next Button should be visible on the screens. This requiresthat it is also provided with @submit in the template of the survey. Refer to section 15.1.Options: yes|no

Default: no

HTML{ ContinueButton = yes; };

ContinueButtonCnd Refer to BackButtonCnd.

ContinueButtonSrc Refer to BackButtonSrc.

ContinueButtonText Labeling the Next Button. Only when using the default browser buttons(without ContinueButtonSrc).Options: TEXTDefault: "next"

HTML{ ContinueButtonText = "To the Next Page"; };

CssLayout provides questions with an additional CSS classification and specifies how manyalternate line layouts are provided in the presentation. A detailed description can be found insection 15.3.2.Options: TEXT, NUMBERDefault: "", 2

HTML{ CssLayout = "TeilA", 1; };

ErrorPostText Provided that ShowIndividualErrors = yes; is set, in case of error, this textis displayed after the faulty respectively incomplete or incorrectly filled question.Options: TEXTDefault: ""

HTML{ ErrorPostText = "... is an error"; };

ErrorPreText Provided ShowIndividualErrors = yes; is set, in case of error, this text isdisplayed before the faulty respectively incomplete or incorrectly filled question.Options: TEXTDefault: ""

HTML{ ErrorPreText = "In the following question..."; };

Input determines whether the GESS Q. internal rendering classes take over the representation ofthe questions completely or only background information and JavaScript should be provided inthe HTML output. For dismissed question layouts or special arrangements of the input fields andbuttons, the normal output can hereby be suppressed in order to design individual questions orentire screens only with HTML. Detailed examples on how to proceed can be found in section 15.4Options: yes|no Default: yes



HTML{ Input = no; };

JavascriptSingleMode controls the click behavior in exclusive answers in label lists. Withdeselect the click on an exclusive response automatically deselects all other previously selectedresponse options. deactivate doesn’t allow any choice to an exclusive answer as long otheranswers are available, and vice versa.Options: deselect|deactivate

Default: deactivate

HTML{ JavascriptSingleMode = "deselect"; };

MaxLabelsPerCol specifies the maximum number of lines allowed for a SingleQ or a MultiQ,or in other words, what is the maximal number of answer possibilities in a column. Once thepredetermined number is exceeded, GESS Q. automatically adds a new column and continuesthe label list with it. By the way, manual column breaks can also be forced within label listswith the attribute splitcolumn.Options: NUMBERDefault: INFINITE

HTML{ MaxLabelsPerCol = 10; };

MultiGridQClass selects alternative rendering classes for the MultiGridQ. Currently, nowadaysthe somewhat nostalgic standard version or the graphical MultiGridQ are selectable. Unknowninputs lead to the default behavior.Options: MultiGridQ|GMultiGridQ

Default: MultiGridQ

HTML{ MultiGridQClass = "GMultiGridQ"; };

MultiQClass selects alternative rendering classes for the MultiQ. Currently, nowadays thesomewhat nostalgic standard version, the graphical MultiQ or the packaging configurator areselectable. Unknown inputs lead to the default behavior.Options: MultiQ|GMultiQ|PackagingQ

Default: MultiQ

HTML{ MultiQClass = "PackagingQ"; };

NumQClass selects alternative rendering classes for the MultiQ. Currently, nowadays the somewhatnostalgic standard version, the graphical NumQ or the slider are selectable. Unknown inputslead to the default behavior.Options: NumQ|GNumQ|SliderQ

Default: NumQ

HTML{ NumQClass = "GNumQ"; };

NumQInputType determines whether the input field of the NumQ should be of type text or of thetype HTML5 type number. In particular with the Android App, the last means that the numerickeypad is automatically opened for numerical entries. Between different browser manufacturersthere is still disagreement by the new HTML5 about the further processing. The problemhere is that some partially already implemented validations are performed in the browser andwell-intentioned corrections of the entries are made, before the final value gets forwarded toGESS Q. The thousands separators and the decimal mark suddenly depend on the settings ofthe used browser and the values entered by the interviewee are twisted. At this point, caution is



imperative.Options: text|number

Default: text

HTML{ NumQInputType = "number"; };

PBarWidth Width of the progress bar used in the template of the survey in pixels. GESS Q.doesn’t obtain this value automatically from the template. To calculate the correct increment,the maximum width must be matched at this point. Further information about the progress barcan be found in section 15.1.4.Options: NUMBERDefault: 200

HTML{ PBarWidth = 250; };

setProperty adds a property with name and value to the script, which can also be changedagain with the same instruction. Such properties cannot be queried directly, but are used assettings by some types of questions (for example, slider or packaging configurator).

HTML{ setProperty( "minNumAnswers" "3" ); };

ShowQuestionName When activated, the (script) name of the particular question is shown beforethe question title. This is especially useful when testing or for keyboard entries.Options: yes|no

Default: no

#ifdef testmode

HTML{ ShowQuestionName = yes; };

#endif

ShowIndividualErrors When activated, this parameter ensures that in error cases ErrorPreText

and ErrorPostText are displayed.Options: yes|no

Default: no

HTML{ ShowIndividualErrors = yes; };

ShowSingleQValues When activated the label codes are displayed with the answer options. Herethe name of the setting is deceptive, because this applies to all types of questions and not justthe SingleQ.Options: yes|no

Default: no

HTML{ ShowSingleQValues = yes; };

SingleGridQClass chooses alternative rendering classes for the SingleGridQ. Currently, thesomewhat nostalgic standard version or the graphical SingleGridQ are selectable. Unknowninputs lead to the default behavior.Options: SingleGridQ|GSingleGridQ

Default: SingleGridQ

HTML{ SingleGridQClass = "GSingleGridQ"; };



SingleQAutoSubmit When activated, SingleQs automatically jump to the next question, assoon as these have been answered.Options: yes|no

Default: no

HTML{ SingleQAutoSubmit = yes; };

SingleQClass chooses alternative rendering classes for the SingleQ. Currently, the somewhatnostalgic standard version or the graphical SingleQ are selectable. Unknown inputs lead to thedefault behavior.Options: SingleQ|GSingleQ

Default: SingleQ

HTML{ SingleQClass = "GSingleQ"; };

SingleQFormat selects alternative layouts for SingleQ and MultiQ. By standard the labels arearranged below each other and at the left are placed the clickable buttons. table changes theview so that the labels are next to each other and the buttons are placed over these. The settingselect refers only to the SingleQ which provides a dropdown list where the first label of thelabel list is preselected.Options: standard|table|select

Default: standard

HTML{ SingleQFormat = select; };

SingleQTableLabelsFirst In display format table of the SingleQs und MultiQs, this parameterdetermines whether the answer options are over or under the checkboxes.Options: yes|no

Default: yes

HTML{ SingleQTableLabelsFirst = no; };

WritePostText determines whether the script attribute htmlposttext should actually be dis-played on questions in the questionnaire.Options: yes|no

Default: yes

HTML{ WritePostText = no; };

WritePreText determines whether the script attribute htmlpretext should actually be displayedon questions in the questionnaire.Options: yes|no

Default: yes

HTML{ WritePreText = no; };

WriteQText determines whether the script attribute text should actually be displayed onquestions in the questionnaire.Options: yes|no

Default: yes

HTML{ WriteQText = no; };



WriteTitle determines whether the script attribute title should actually be displayed onquestions in the questionnaire.

Options: yes|no

Default: yes

HTML{ WriteTitle = no; };


Chapter 6. Text Replacement

6 Text Replacement

6.1 Text Replacement with @insert

It is often necessary that the text of questions or label contains the answers of previous questions,or in some way depends on them. There is a possibility, to integrate the labels of other questionsin any text areas to a survey. Very useful here is the function Group (section 8.2). To be able touse the text replacement at all, the script parameter enableTextReplace must be set on yes,also refer to section 5.2.

The actual text replacement is performed with the command @insert.

@insert If text replacement is turned on with enableTextReplace = yes; the contents of avariable VAR can be pasted anywhere into the text fields via @insert.

@insert(VAR) // also @insert[VAR] or @insert{VAR}

SingleQ gender;

text="Are you... ?";

labels=

1 "male"

2 "female"

;

TextQ text_test;

text="You are @insert(gender).";

By the text replacement all variables in GESS Q. are represented in a specific manner. While 1-of-N variable shows its associated label texts, if possible; N-of-M variables list the values that theycontain. To address multiple answers and to show them as desired, there is MultiQTextInsert.

MultiQTextInsert makes a new text variable NAME. It takes the values of an N-of-M variablesVAR and replaces them with their associated label texts. It must also be defined, by whichcharacter the label text starts (BEF = before) and by which character the label text is completed(AFT = after). Finally, by which character the label texts must be separated. (DEL = delimiter).

MultiQTextInsert NAME = (VAR, BEF, AFT, DEL);

MultiQTextInsert ti_q9=(q9, "[", "]", ", ");

multiq q9;

text = "question text...";

labels=

1 "A"

2 "B"

3 "C"

4 "D"

;

// display with @insert(ti_q9) e.g.:

// [A], [B], [D]


Chapter 6. Text Replacement

// If the label text must not be surrounded by characters,

// the first two quotation marks could be left empty:

// MultiQTextInsert ti_q9=(q9, " ", " ", ", ");

The text replacement with @insert can also be used for dynamic content and representations. Incombination with group can represent different content, depending on the previous information.The following example illustrates how an image, which is subject to a prior selection, could beincluded.

single selection;

text="Please choose:";

labels=

1 "selection A"

2 "selection B"

;

group img_selection;

labels=

1 "bild_A.jpg" (selection eq 1)

2 "bild_B.jpg" (selection eq 2)

;

textq image;

text="Please look at the picture:

title="<img src=./media/@insert(_surveyname)/@insert(img_auswahl)>";

DecimalFormat All values in GESS Q. are floats with decimal. To display formatted numbers,there is DecimalFormat, which creates a new variable NAME and stores the VAR variable inalternative format FORMAT 1

DecimalFormat NAME = (VAR, FORMAT);

// min. 1 pre-decimal position and fix 2 post-decimal position

DecimalFormat meinDF = (euro, "0.00");

1http://docs.oracle.com/javase/6/docs/api/java/text/DecimalFormat.html


http://docs.oracle.com/javase/6/docs/api/java/text/DecimalFormat.html

Chapter 7. Screens

7 Screens

7.1 General

Questions can also be displayed simultaneously on one display together with other questionsin so-called Screens. A screen has a NAME and CONTENT. The GESS Q. syntax of thenotation is:

screen NAME = CONTENT;

The name can be selected freely, but must not be in conflict with previously assigned names ofother elements (screens, blocks). The content consists of questions that can be arranged incolumns and rows. For example, there are three questions q1, q2 and q3.

In order to arrange these under each other, one writes:

screen myScreen = column(q1 q2 q3);

To arrange the issues: next to each other:

screen myScreen = row(q1 q2 q3);

A column respectively a row may include not only questions, but can also again column und row

can be nestet.

Example of a screen with more complex nestings:

Screen image =

column(

row(know_alfa image_alfa)

row(know_bmw image_bmw)

row(know_honda image_honda)

row(know_maserati image_maserati)

)

;

text = "Please indicate whether you know the cars.";

As contents of a screen, instead of a list of individual questions A to B can be done. In this caseall the questions from the script starting with question A are sequentially inserted in the screenup to question B. Example:

SingleQ f1;

SingleQ f2;

SingleQ f3;

SingleQ f4;

SingleQ f5;

screen myScreen = column(f2 to f5);

// screen myScreen = column(f2 f3 f4 f5); // equivalent to

Internally GESS Q. puts together a screen instruction to an HTML table The following code:

Textq f1;

text="GESS Q. puts together the screens to a table.";


Chapter 7. Screens

title="top left";

Textq f2;

title="top right";

Textq f3;

title="bottom left";

Textq f4;

title="bottom right";

screen scr_f14 = column( row( f1 f2 ) row( f3 f4 ) );

results in a two-column table with two rows:

Figure 7.1: A Screen of Four Questions in Two Columns and Two Rows

On one hand, the design of the table is referenced to the CSS elements, which make up thescreen: The first line is addressed as qscreenrow-1, the second - as qscreenrow-2. GESS Q.numbers the cells in the CSS layer simply with qscreencell-LINENUMBER-CELLNUMBER, so thatquestion 1 can be selected as the top left qscreencell-1-1 and question 4 can be selected asbottom right qscreencell-2-2.

On the other hand, in any case, the GESS Q. builds a rectangular table. Slightly modified coderesults in a table with three cells in the first row and one cell in the second row.

Textq f1;

text="GESS Q. puts together screens in a rectangular table.";

title="top left";

Textq f2;

title="top middle";

Textq f3;

title="top right";

Textq f4;

title="bottom right";

screen scr_f14 = column( row( f1 f2 f3 ) row( f4 ) );

Since question 4 in the example stands alone in a line and it is the last cell, GESS Q. fills thetable with the internal HTML parameter colspan (here:colspan="3"), in order to show question4 over three columns. Thus, the table is rectangular again.

The colspan respectively rowspan parameter can be specified in the screen instruction in squarebrackets. From this screen instruction

screen scr_f15 = column( row( f1 f2 f3 ) row( f4[2] f5[1]) );

GESS Q. builds a two-line table with three cells in the first and two cells in the second line. Sof4 lies under f1 and f2, while f5 lies under f3. In the row instruction GESS Q. addresses the valuein square brackets as colspan (one cell covers multiple columns in one line).


Chapter 7. Screens

Within a column instruction

screen scr_f15 = row( column( f1 f2 f3 ) column( f4[2] f5[1]) );

GESS Q. uses the value in the square brackets as rowspan instruction (one cell covers multiplelines in a single row). As the chart shows, screen instructions may also turn complex:

Figure 7.2: A Screen of Eleven Nested Components

If by a question in a screen a filter condition is not met, the question will not appear in thescreen. If all questions of a screen are filtered out, the screen is skipped in the interview process.

7.2 HTML Specific Screen Functions

In order to maintain a high degree of flexibility, GESS Q. provides screen related functions thatallow you to program the HTML of individual screens.

7.2.1 HTML Code Integration

It is possible to integrate own (HTML) content in the generated pages. For this purpose thereare four optional placeholders available: @src1 to @src4, in the file template.html. For moreinfomation about templates, please refer to section 15.1. The placeholders can be replaced withcustom HTML content, which, in each case, is stored in the study directory in a separate textfile (file type does not matter). In the definition of a screen in the script can be refered to one ofthese files as follows:

Screen myScreen = column(f2 to f5);

src1 = additionalcontent.html;

src2 = text1.txt;

With this function, among other things, it is possible to design the questions completely. Thisrequires the automatic generation of the question to be suppressed using input. Also refer tosection 5.3. GESS Q. then sets internally all the necessary variables and logics for the question,in the HTML representation remains however empty.


Chapter 7. Screens

If the presentation of the question is deactivated, these can be incorporated into a screen andwith the above-mentioned function embed with own code, that includes the question. It shouldbe noted here that the control elements (radio buttons, checkboxes or whatever) must have thesame name as the software would have generated in display of the question, so that the softwarecould get the data.

7.2.2 HTML Label

If we embed static HTML code the content cannot be dynamic (randomized, filtered, etc.). Herethe HTML labels are helpful. Labels can be assigned to a screen, whose label text containsHTML, which is then built into the screen. Advantage over a static code is that the HTMLlabels, just like the labels of questions, can also be filtered and randomized. So these representthe connection of »handmade« HTML code and dynamically generated content.

In addition, there are two more text elements, htmlPreLabels and htmlPostLabels, which, ifpresent, are incorporated in the screen directly above or below the text that results from theHTML labels. Hereby, for example, the content of the labels can be displayed in a table.

Where HTML expects quotation mark, single quotation mark may alternatively be used or itmust be preceded by the "\" (backslash) so GESS Q. ignores the quotation marks.

A bit more detailed example:

HTML{ input = no; };

NumQ f1;

labels=

1 "number of colors:" format onf_1_x

;

SingleQ f1_jn;

labels=

1 "Yes, how many?:"

text "or"

2 "No"

;

HTML{ input = yes; };

screen scr_f1 = column( f1 f1_jn );

text="Do you see colors?";

htmlprelabels="<table class='qtable'>";

htmllabels=

1 "

<tr>

<td name='id_f1_jn1' class='checkable f1_jn qbuttoncell'><img id='

id_f1_jn_bi1'></td>

<td style='height:30px; padding:0;' name='id_f1_jn1' class='checkable

qlabeltextcell'>Yes - how many? <input type='number' min='0' name='f1_1n' class

='numinput'></td>

</tr>

"

text "

<tr>

<td colspan='2' class='qtextlabelcell'>or</td>

</tr>


Chapter 7. Screens

"

2 "

<tr>

<td name='id_f1_jn2' class='checkable f1_jn qbuttoncell'><img id='

id_f1_jn_bi2'></td>

<td name='id_f1_jn2' class='checkable qlabeltextcell'>No</td>

</tr>

"

;

htmlpostlabels="</table>";

In the generated page appears the text determined by the HTML labels in a HTML code. Sothe question is »Yes - how many?« and not like f1 defines (»number of colors:«) or like f1_jn

predefines (»Yes, how many:«). Type defines for NumQ a numeric entry field and min ensures aminimal value of 0, so that only numbers and non-negative values are possible.

Figure 7.3: An Unexciting Example forhtmllabels

If question specific content is generated with this method, attention must be paid (like with thestatistically embedded code) that the form elements must have names that correspond to theautomatically generated, so that the software can read the data.

Please note: The template must provide the placeholder statement @htmllabels, so thatGESS Q. a code incorporates into the page, defined by the HTML label. Please also refer tosection 15.1.3.

7.3 Dynamic Screen Content / JavaScript

Screens, defined in a conventional manner in the script, are static. However, it may be desirablethat the screens respond to user input. A typical example:With a closed question is asked how well the interviewees liked a product. In case they declarethat they did not like it, only then a text box with the open question should appear, why theinterviewee didn’t like the product. With the previously presented means this could not beimplemented.

One possibility would be to make the entire screen »by hand« with HTML code, but this wouldrequire a considerable effort. Therefore, there is a command available, which can automaticallyinstall a JavaScript event handler function. This command can be used in the part of a question,where the event of the click is processed (for example, clicking on a radio button of a singlequestion). The command is:

jsHandler="<Javascript-Function>";

and must be added directly to the question.


Chapter 7. Screens

The code of the JavaScript function itself must be available in the screen; It can replace aplaceholder in the screen definition, using the above presented src command, or can be writtendirectly to the file template.html.

The JavaScript function should be designed so that it validates the screen and accordinglyproduces the right conditions, each time when a button of a question is clicked.

For a detailed example of using the command jsHandler please see the appropriate tutorial.


Chapter 8. Special Types of Variables

8 Special Types of Variables

8.1 Compute

Compute variables are created with the name NAME and contain either directly a numericalvalue or a calculation procedure CALCULATION with other variables, the result of which isdetermined at the moment of access. They can be used for many purposes and optionally, ifdesired, included in the data export with the attribute export. They can be created as follows:

compute VARNAME = CALCULATION;

[export;]

In the simplest case, the CALCULATION is a simple numerical value, which can be changedwith action command set(VARNAME = VALUE); . In the following example initialization logicshould only be executed when first entering a question:

compute initNotwendig = 1;

TextQ intro;

text = "Here we go!";

continueActionBlock="

if(initnecessary eq 1){

set(initnecessary = 0);

// do some init stuff

};

";

However, compute variables can also be used to add the values of the four numeric fields of aNumQ, called »points«. Although the following example is not necessary, because the sum canalso be addressed under the name of NumQ points , it illustrates the principle.

compute sum = points.1 + points.2 + points.3 + points.4;

The variable sum contains the current result of the calculation at any time of access.

The possible arithmetic operators are +, -, *, /, % (modulo) and parentheticalexpressions. Proper order of operations is respected (multiplication and divisionbefore addition and subtraction).

8.2 Group

A Group is defined with a NAME and a slightly modified label list. It defines a reference betweenLABELCODEs, TEXTs and CONDITIONs. At any time of an interview, the conditions definewhich label codes are present in the group. This behavior can be used at various points, forexample, for conditional transfer of texts in the question text or for restrictions that can’t beeasily made by reference label value to other questions. The optional attribute export controlswhether the group is to be taken into account when data must be exported.

group NAME;

labels=

LABELCODE "TEXT" (CONDITION)

LABELCODE "TEXT" (CONDITION)

...



;

[export;]

Example: The interviewee is asked about gender and age, depending on what the answer is,a specific text (which can’t be directly taken from the questions about age and gender) mustbe included in the text TextQ message . The Group displayed with @insert helps by therealization.

SingleQ gender;

labels=

1 "male"

2 "female"

;

SingleQ age;

labels=

1 "18-39 years"

2 "40-59 years"

;

group salutation;

labels=

1 "Mr., you are 18-39 years old." (gender eq 1 and age eq 1)

2 "Mr., you are 40-59 years old." (gender eq 1 and age eq 2)

3 "Mrs., you are 18-39 years old." (gender eq 2 and age eq 1)

4 "Mrs, you are 40-59 years old." (gender eq 2 and age eq 2)

;

TextQ message;

text="@insert(salutation)";

The element of the Group, whose condition is satisfied, is applied as text in the question text.

In the case of text replacement, all the applied labels are shown as comma separated list. Theseparator symbol and the last separator can be set freely:

insert="SEP","CON";

Group myGroup;

labels=

1 "1" (1 in abc)

2 "2" (2 in abc)

3 "3" (3 in abc)

;

insert=" | ", " and ";

// @insert(myGroup) can look like the following: "1 | 2 and 3"

In this example, the meaning of the label values is not yet visible. Groups can also serve as atemplate for restrictions. For example, questions about car models can only be asked, if thebrand is generally known. This could be also solved with label filtering, but it is also only anexample:



MultiQ brand;

text="Which of these car brands are known to you?";

labels=

1 "Audi"

2 "BMW"

3 "Mercedes"

;

group restr;

labels=

1 "Audi" (brand eq 1)



4 "BMW" (brand eq 2)



7 "Mercedes" (brand eq 3)



;

MultiQ models;

text="Which of these car brands are known to you?";

labels=

1 "Audi A4"

2 "Audi A6"

3 "Audi A8"

4 "BMW 3er"

5 "BMW 5er"

6 "BMW 7er"

7 "Mercedes C-class"

8 "Mercedes E-class"

9 "Mercedes S-class"

;

restrict=restr;

In addition to the conditions that their values determine, the groups can also get an else-label.In this way, could be defined a default setting for a group, which will be repealed by certainconditions.

Group myGroup;

labels=

1 "1" (1 in abc)

2 "2" (2 in abc)

3 "3" (3 in abc)

9 "9" else

;

Although the group data can be clearly inferred from the other variables, they are stored in thedata record. The reason for that is that the data of a group can also be defined from variablesand their status afterwards is not always traceable. Examples of this are random numbers, timesand quota state.



8.3 DictFileVar

The DictFileVar implements a dictionary mechanism which assigns a value to a key. Forexample, a sub-division of Germany into regions (e.g. North, South, East and West) is possible.Interviewees are asked to enter their zip code and are assigned one of the four groups accordingly.The long list of all German postal codes, which will be divided into four groups, must be handled.This could be done with a group, but would be complicated and would use software resources.Here the DictFileVar shuold be the method of choice.

The syntax is:

DictFileVar name=("file", key variable);

The keys are listed in the file line by line and their associated values are next to them. The keyvariable contains the key value (in our example, the zip code). In the following example the file»plz.txt« contains only three lines two zip codes from Hamburg and one from Berlin:

10247 3

20257 1

22359 1

The zip code is requested in a NumQ with the name »plz«, therefore the key variable has the name»plz.1«. So the DictFileVar would look like this:

DictFileVar region=("plz.txt", plz.1);

Now, when the interviewee enters a zip code »10247«, this key value will be searched in the fileand the DictFileVar gets the assigned value 3 (for »east«). The DictFileVar can now againbe used for filter, quotas etc.

Both the key and the assigned value can also be a text (instead of numbers). The assigned valuecan be directly used for text replacement.

It should be noted: In order to avoid constant file access, the content of DictFileVar isdetermined only once, indeed at the time of the first access to the file. Therefore, there is arequirement for the usage of the DictFileVar: the matching must not change during the timeof the interview. After the value has been determined, changes to the key variables have noinfluence (for example, by going back and making changes during the interview).

8.4 DecisionVar

With the DecisionVar is possible to include the factor, whether a condition is met or not, inthe calculations.

Syntax:

DecisionVar name = (condition);

If the condition is met, the DecisionVar has the value 1, else 0.

8.5 IntRandom (Random Numbers)

With IntRandom random integers can be generated. The Syntax is:



IntRandom name=from to;

For example, a random number between 1 and 10 would be

IntRandomVar myRandomNumber = 1 10;

Please note, that the random number will be calculated once at the beginning of the interviewand then remains constant throughout the interview (the same as all other random elements likefor example randomized blocks).

8.6 Block Counter

When a block of questions is being run through, it may be necessary to determine the currentposition of the interview in this block. For example, questions can be in a randomized block anddepending on whether a question has the first or any other position in this block, the text of thequestion can be different. For this purpose, there is a variable per each block, which provides thisinformation. The variable is automatically generated and is named count_+Blockname. In casethe block has also the name »block1«, the block count variable would be called count_block1.By going through the block, the variable contains, as an value, the position of the block, wherethe interview stands at the moment.

Example:

Let’s assume, there are two questions, q1 and q2. These appear randomly in the block »block1«:

block block1=(q1 q2); random;

The question text must be different depending on whether a question comes as the first or thesecond. For example, for q1: The question text is generated by text replacement and a group.

group qtext_q1;

labels=

1 "questionText q1 firstSubmission" (count_block1 eq 1)

2 "questionText q2 secondSubmission" (count_block1 eq 2)

;

SingleQ q1;

text="@insert(qtext_q1)";

...

8.7 TextElement

TextElement represents a simple text variable. It can only be created with one name and newlyset in ActionBlocks using setText(TEXTVAR, "TEXT") and appendText(TEXTVAR, "TEXT")

or can be extended by an additional text.

TextElement myTextElement;

ActionBlock ab = {

setText(myTextElement, "That is an");

appendText(meinTextElement, "example.");

};



With the instruction saved a variable can be maintained also via canceling and readopting,

TextElement te = "a text" saved; // applied + saved (cancel / resume)

8.8 Array

The Array is a special type of variable. An array stores a number #VALUES of floating pointnumbers, which can be addressed via index. It can be accessed externally as a single, atomicvariable. The value of the array corresponds to the sum of its individual elements. Whenexporting data the array is taken into account with the optional attribute export.

Array VARNAME[#VALUES];

// Example:

Array tenFields[10];

[export;]

A newly created array is initialized according to the setting ArrayInitMode, please refer tosection 5.2. The array tenFields has therefore 10 fields with corresponding values which canbe accessed with square brackets. The index starts with 1.

tenFields[1]

...

tenFields[10]

For example, the arrays can be assigned values using for-loops, in order to transfer the valuesof a group (selection here) to an array (only useful if the array is initialized using _missing

values):

compute max = 10;

array arr[max];

for(counter=1 to max ) {

if( counter in selection ) {

set( arr[counter] = counter );

};

};

Alternatively, the array can also be filled with the action command set, please refer to section 14.2.

8.9 TextArray

Analog to Array there is also a variable type TextArray, containing multiple texts instead ofmultiple values. There are two ways to initialize a TextArray:

// Direct initialization with texts

TextArray brands = {"Audi" "BMW" "Mercedes"};

// Indirect initialization with the labels of a question

MultiQ q_brands;

labels=

1 "Audi"

2 "BMW"



3 "Mercedes"

;

TextArray brands = q_brands;

Like by regular arrays, the individual texts can be addressed using square brackets and theindex starts with 1.

8.10 VarArray

A third type of array, next to the Array for numbers and TextArray for texts, is available anarray for variables: VarArray. We can directly transfer the variables into the VarArray, usingtheir names and then access the values using the Index.

vararray NAME = (VAR1 VAR2 ...);

8.11 RestrictVar

The RestrictVar can be used as a template for the restrict command, to filter automaticallythe label lists. The following example shows the use with SingleQs, in order to distributesequentially the places on the labels from 1 to 3.

RestrictVar NAME = TEMPLATE;

singleq msq1;

text="1. place";

labels=

1 "a"

2 "b"

3 "c"

4 "d"

5 "e"

;

RestrictVar rsv = (not(msq1));

singleq msq2;

text="2. place";

labels copy msq1;

restrict=(not(msq1));

// restrict=rsv; // alternative spelling with the RestrictVar

singleq msq3;

text="3. place";

labels copy msq1;

restrict=(not(msq1 or msq2));


Chapter 9. Internal Variables

9 Internal Variables

9.1 Date and Time

There are several variables available, making it possible to work with time (HHMMSS), date(YYYYMMDD) and other time formats:

_currentdate actual date

_currentmillis current server time in milliseconds since the start of the Unix Time at January1, 1970 00:00 UTC (the Epoch)

_currenttime actual time

_duration duration of the interview in ms (incl. interruption intervals)

_finishdate date of interview end

_finishtime time of interview end

_startdate date of interview start

_startdayofweek weekday of the interview start(1=So - 7=Sa)

_starttime time of the interview start

9.2 Further Variables

Along with the times, there are a number of additional internal variables.

_revision current revision of GESS Q.

_surveyname name of the study

template1 TextElement for output in the template with @tt1. It is preserved by interruption/re-sumption.template2 ... @tt2

up totemplate8 ... @tt8

_breakcount number of interruptions of the interview

_currentScreen the variable name of the screen currently in process

_idmode [ t | s | m ], depending on whether the interview is performed in test mode, insingle mode (one ID per respondent) or multi mode (an ID for a number of respondents)

_missing the value that has been set for _missing.

_randomid a random character string with which the interview is clearly marked.

9.3 Runtime Environment

The variables provide information about in what environment, such as operating system andbrowser, the interview is done. This can be helpful in troubleshooting, if it comes e.g. to deviantrepresentations in different browsers.

_useragent saves the useragent input of the browser, via which the program identifies itself to aserver, e.g.



"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:31.0) Gecko/20100101 Firefox/31.0"

_browser Numeric code with which the browser is identified. The information is obtained fromthe _useragent-input, which unfortunately falls out highly unsystematic.

_os Numeric code with which the operating system is identified. The information is obtainedfrom the _useragent-input, which unfortunately falls out highly unsystematic.

9.4 External URL Parameter

The parameters in an online questionnaire can be handed over with the URL line. Especiallyfor this purpose the GESS Q. holds ready a series of so-called external variables. They arenamed ext1 to ext20 and can contain both numbers and text.

In order to assign the value 9 to the variable ext1 and the value 5 to the variable ext2 atthe beginning of the interview, the URL bar or the referral would look like this: http://

www.meinserver.de/SurveyServlet?action=startsurvey\&survey=meineStudie\&respid=

RESPID;\&ext1=9\&ext2=5

9.5 Exit-Code (_finished)

The variable _finished contains the status code after the end of the interview with which theinterview was terminated. When fully completed interviews the default value would be 1, butthe code can also be configured differently, for example, by termination after plausibility checkwith exit.

It may be desirable to explicitly assign a value to _finished, either to set a URL forwarding atthe end of the interview (refer to chapter 13) or for statistical analyzes.

The variable can be manually assigned to the action command set, for example in acmplActionBlock.

9.6 Number of the Interviewee and Case Number (_respid und

_caseid)

Each respondent has both an ID number and a case number. The case number is alwaysperson specific and unambiguous, which is not required for the ID number (for example, in testinterviews or nonspecific onsite pop-up surveys). The case number is generated from the IDnumber, combined with a counter. The ID number is saved in the variable _respid and the casenumber - in the variable _caseid. Only alphanumeric characters may be used for _respid (a-zA-Z 0-9)

GESS Q. keeps a record of the different cases with _caseid and increments the counter witheach started interview. The starting point is the entry in the file lfdcount.lst. GESS Q. readsthe status of the file and writes it back updated.

In order to provide a link to a special interview (for example, for download for the interviewees),GESS Q. additionally sets the encoded _caseid as _encryptedcaseid in the record. With thisvariable it is possible to generate a link at the end of the interview, which can be used by a robot

to export of the completed questionnaire. An example of that is provided in section 25.2.1.



9.7 Cancel Code (_cancel)

It is possible to include a Cancel Button in order to cancel the interview. In addition to thisbutton, a drop-down menu (ListBox) can be displayed. A reason for the cancellation (or anaction to follow the cancellation) can be chosen from this menu. The Cancel Button can beactivated with:

HTML { cancelButton=yes };

This menu is displayed automatically if it is defined. The menu items can be configured in thisform:

HTML { cancelMenu=("entry" "entry" "entry" ...) };

In addition, there is a default entry which represents »no choice«. This is specified with:

HTML { cancelMenuDefault = "--- please choose---"; };

If after clicking on a Cancel Button no menu selection is done, an error message is displayed.This is defined with:

HTML { cancelMenuErrorMsg = "Please select!" };

If an interview is ended by clicking on the Cancel Button, the variable _cancel obtains the indexof the chosen menu item as value, starting with 1.

9.8 Resuming after Cancellation (_resume)

Normally an interview, ended with an explicit action (fully completed, assert...exit, click onCancel Button), is considered finished. In contrast an interview which is terminated by atimeout (due to inactivity) is considered as cancelled. In contrast to a completed interview acancelled interview can be continued. It can be continued even if the study has already beendeactivated and new interviews can no longer be accepted.

Under certain circumstances it would be desirable also to continue a finished interview. Forexample, in the case of a telephone survey, the Cancel Button can be used to stop the interviewand a date for continuing can be agreed. With the internal variable _resume can be controlled,what type of record is created (with the possibility of resuming or without). If _resume has thevalue 0, the interview is considered finished and can’t be continued. If _resume has the value 1,the interview is considered cancelled and can be continued.

This variable is automatically set by the corresponding actions with the correct value, but it canalso be set manually.

9.9 Export of Internal Variables

GESS Q. automatically takes over a number of internal variables all the way to the tables andwrites them in the SPSS file. For the export GESS Q. adds the prefix sys to the variable name:

• sys_browser

• sys_caseid

• sys_currentScreen

• sys_duration



• sys_finishdate

• sys_finished

• sys_finishtime

• sys_os

• sys_respid

• sys_startdate

• sys_starttime


Chapter 10. Filtering and Plausibility Conditions

10 Filtering and Plausibility Conditions

10.1 General

Filtering and plausibility conditions are central mechanisms in GESS Q., which are used tocontrol the survey process and to formulate termination criteria. Filters manage, whether theparticipants are presented or not, individual labels, questions, screens or even entire blocks.Plausibility conditions (asserts) can be linked to individual screens to check whether certainconditions are satisfied at this point. Depending on that, the respective screen can be presentedagain to the interviewee or the interview can be terminated. Since both filtering and plausibilityconditions work on the basis of conditions, the first thing that should be formulated are theconditions.

10.2 Conditions

Logical conditions in GESS Q. are based on Boolean algebra. Their evaluation always results atthe end in true or false. For both logical values are available the expressions: true and false.The most basic conditions are:

(true) // always true

(false) // never true

In Boolean algebra two (sub) conditions with the logical AND (and) and the logical OR (or)can be combined. In order for the entire condition to be satisfied or true, in case of AND

both sub-conditions must be true, while by OR at least one of the sub-conditions must be met.Additionally, there is EITHER OR (xor), where exactly one of the sub conditions must bemet.

As opposed to and, or and xor a negation is also (not(X)) possible which reverses the logicalvalue of X. As a rule a chain of several of these operators is processed from left to right. Withthe use of brackets, as in the mathematics, the priorities can also be set differently. The followingmatrices summarize the behavior of the operators:

AND | T | F OR | T | F XOR | T | F NOT | T | F

---- --- --- ---- --- --- ---- --- --- ---- --- ---

T | T | F T | T | T T | F | T | F | T

---- --- --- ---- --- --- ---- --- ---

F | F | F F | T | F F | T | F

Individual conditions mainly result from comparisons of variable values with numbers or othervariable values. The following operators exist about it:

eq (equal)

ne (not equal)

gt (greater than)

ge (greater or equal)

lt (less than)

le (less or equal)



in check whether a value is contained in a set of values (Array)

Examples:

(1 eq 1) // true (= true)

(1 ne 1) // false (= false)

(1 eq 2) // false (= false)

(s eq 1) // true, when s = 1

(s gt 1) // true, when s > 1

(1 in m) // true, when 1 is contained in m

([1 2 3] in m) // true, when (1 in m) or (2 in m) or (3 in m)

([1:3] in m) // = ([1 2 3] in m)

([1:3 8] in m) // = ([1 2 3] in m) or (8 in m)

10.2.1 Examination by Arrays and Multivariable

There is a fundamental difference between the comparison operators (greater / less / equal) onthe one hand and to determine whether an array contains a certain value. This refers to all typesof questions, that store their values in arrays (NumQ, MultiQ, SingleGridQ, MultiGridQ, pleasealso refer to section 3.1).

The examination of a value with in results true in this example, when 1 is contained in f2, forexample f2 contains the values "1 2 3":

flt=(1 in f2); // true because 1 is contained in "1 2 3"

On the other hand, with other comparison operators (greater than / less than / equal to) GESSQ. forms the sum of the values in the array respectively the question (without the _missing

values).

flt=(f2 eq 6); // true because 1 + 2 + 3 = 6

The sums mechanism may prove useful in case the sum of the inputs of a NumQ plays a role.

10.2.2 Functions and Conditions

GESS Q. provides a number of functions, specifically aimed at conditions and can be combinedwith logical operators and simple comparisons:

containsText checks if the TEXT is contained in the TextArray TARRAY . Returns 1 if this isthe case, otherwise 0.

containsText(TARRAY, TEXT);

if(containsText(arr, ""is in?") ){

// ... "is in?" is in

}

count counts how many times the value VAL is contained in the ARRAY and returns the result.

count(ARRAY, VAL)



if(count(arr, 7) gt 2){

// ... the 7 is contained at least 3 times in arr

}

exists checks whether the specified variable VAR exists in the script.

exists(VAR)

// Checks if question f1 exists and if a label with code 7 is defined

flt=(exists(f1) and hasLabel(f1, 7));

hasDuplicateValues tests whether a value in ARRAY is repeatedly contained. If this is thecase, it returns 1, otherwise, 0.

hasDuplicateValues(ARRAY)

if(hasDuplicateValues(arr) eq 1){

// ... there are duplicates

};

hasLabel check whether a label with code CODE is defined for question GESS Q.

hasLabel(Q, CODE)

// Checks if question f1 exists and defines a label with Code 7

flt=(exists(f1) and hasLabel(f1, 7));

num returns the number of values in ARRAY, which are unequal _missing

num(ARRAY)

// Content of ten fields:

{_missing, 6, 3, _missing, _missing, _missing, 8, 1, 1, 2}

num(ten fields) // provides 6

if(num(arr) ge 1){

// ... contains arr at least one value unequal _missing?

}

regexp searches for a pattern (regular expression, hence »regex«) in a character string. If thepattern appears in the character string, regex returns the value 1.

regexp( MUSTER, TEXT )

The following example will check an entered email address and depending on the result willdeliver different text:



group grp_check;

labels=

1 "Address seems correct" (regexp ("^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0

-9-.]+$", adr) eq 1)

2 "Please correct address" (regexp ("^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0

-9-.]+$", adr) ne 1)

;

E-mail addresses should not be checked in this way, because they can also wrong in a differentway, but the expression is good for illustrating:Accordingly, the e-mail address consists of three fields. The first extends from the beginningof the string (labeled with ^) to the @ and consists of the combination of [a-zA-Z0-9_.+-]

lowercase letters from a to z and uppercase letters A to Z and also numbers from 0 to 9 and thecharacters underscore, point, plus, minus.

The second field behind the @ consists again of the letters and numbers combination but as anadditional sign only has a minus. Then a period follows. Since the point in regular expressionscan be used as a placeholder for any characters, an escape-sequence must be used, in order toaddress the point as a point. (\\)1

The last field to the end of the string (indicated by $) can now again be a letters and numberscombination and additionally considers minus sign and point (within the brackets it needs noescape sequence for the point).

The plus sign in front of the @, the . and the $, specifies that the preceding expression mustoccur in the string at least once and can occur repeatedly.

The example already suggests it, but it might be useful to mention some relatively simpleapplication possibilities: The regular expression ^123 examines regexp, if the string starts with123. On the other hand regexp provides with the pattern com$ always a 1, if the string endswith com.

Regular expressions are a powerful tool and can not be explained exhaustively here. Detailedexplanations and examples are provided in the Web. Wikipedia provides a starting point:https://de.wikipedia.org/wiki/Regulärer_Ausdruck.

strcmp compares TEXT 1 and TEXT2 character by character. As soon as strcmp finds adifferent symbol in TEXT1 and TEXT2, it returns the difference of their ASCII codes. Therefore,two identical texts provide the value 0, different text provide a value unequal 0.

strcmp(TEXT1, TEXT2)

if(strcmp("f12", _currentScreen) eq 0){

// ... is f12 the current screen?

}

timesSent returns how often the answer to a question has already been sent to the server with»Next«. The function can be used to intercept the behavior, where questions are simply skipped:When an unanswered question is once sent, the filter engages and in a second screen is askedmore precise question. In this way, labels can be filtered so that they appear only when thecondition is met.

timesSent(QUESTION)

1The standard for regular expressions provides only a backslash. However, Java requires two backslashes for this.


https://de.wikipedia.org/wiki/Regul�rer_Ausdruck


flt(timessent(f7.1) ge 1 and f7 le 0);

10.3 Filter Conditions (flt)

10.3.1 Filter General

Filters ensure that an item is displayed only when a condition is met. The syntax depends onthe context in which is filtered: question / screen / block or label / group.

GESS Q. skips the screens or blocks which are empty, because all its questions were filtered out.The same applies to blank questions, as such in which all the labels have been filtered out.

Important for the data storage: When skipping the filtered questions they are explicitly set to_missing-Value.

10.3.2 Filter on Questions, Block, Screens

The general formulation of a filter that applies to a question is:

flt = CONDITION;

This statement must be located directly behind the definition of the question, screen or blockto which it should belong. An element of this type can only have at most one filter. Multipleconditions can be linked with the different operators.

Examples:

flt=99 in brands;

// "brands" must contain a value 99

flt=[1 3 5 7 9] in abc;

// "abc" must contain at least one of the values 1, 3, 5, 7 or 9

flt=[1:7] in def;

// "def" must contain at least one of the values between 1 and 7

flt=99 in brands or [1:7] in def or f1 eq 2;

// "brands" must contain the value 99 ODER

// "def" must contain at least one of the values between 1 and 7 OR

// "f1" must have the value 2

To filter a single question, the filter condition must be simply added to the question definition:

SingleQ audi_known;

Text="Are you familiar with the brand Audi?";

labels=

1 "yes"

2 "no"

;

SingleQ audi_classification;

Text="And how do you like the brand Audi?";



labels=

1 "good"

2 "bad"

;

flt = audi_known eq 1;

It is also possible to filter a block, for example, a list of questions to a brand that is only to beasked if the brand is known:

Block audi_items = (audi_item_1 audi_item_2 audi_item_3 audi_item_4) random;

flt=audi_known eq 1;

Filter influence the course of an interview, which is often illustrated by a progress bar. Tosynchronize the bar with the process, the filters on questions, blocks or screens in addition shouldinvoke the function changepBar(NUM) and send the number of skipped questions.

flt = CONDITION changepBar(NUM);

Block bmw_items = (bmw_item_1 bmw_item_2 bmw_item_3 bmw_item_4) random;

flt=known eq 1 changepbar(4);

10.3.3 Filter in Label Lists

Also labels can be filtered. The syntax provides different variations, all of which are equivalent.

1 "label" (condition)

2 "label" flt(condition)

3 "label" flt=(condition)

singleq s1;

text="Which newspaper do you read most often?";

title="";

labels=

1 "SZ"

2 "taz"

3 "FAZ"

4 "WAZ"

5 "FR"

;

singleq s2;

text="And which newspaper do you read the second most?";

title="Title";

labels=

1 "SZ" (not (1 in s1))

2 "taz" flt(not (2 in s1))

3 "FAZ" flt=(not (3 in s1))

4 "WAZ" flt(not (4 in s1))

5 "FR" flt(not (5 in s1))

;

In s2 the answer from s1 is filtered out. By another construction, if all of the labels of a questionare filtered out, GESS Q. doesn’t show the question.



10.3.4 Filter in Groups

Like with the label filter, different options for defining of filters are available:

group grpname;

labels=

1 "L1" (condition1)

2 "L2" flt(condition2)

2 "L2" flt=(condition2)

;

Filtered groups are a good mechanism for the text replacement.

group newspaper1;

labels=

1 "SZ" (1 in s1)

2 "taz" flt(2 in s1)

3 "FAZ" flt=(3 in s1)

4 "WAZ" (4 in s1)

5 "FR" (5 in s1)

;

singleq s1;

text="Which newspaper do you read most frequently?";

title="";

labels=

1 "SZ"

2 "taz"

3 "FAZ"

4 "WAZ"

5 "FR"

;

singleq s2;

text="Which newspaper do you read most frequently after @insert(newspaper1)?";

title="Title";

labels=

1 "SZ" (not (1 in s1))

2 "taz" flt(not (2 in s1))

3 "FAZ" flt=(not (3 in s1))

4 "WAZ" flt(not (4 in s1))

5 "FR" flt(not (5 in s1))

;

In this example, the group is only utilized to use the answer of s1 into question s2. The samewould have been also possible with the standard text replacement @insert(s1) . But the maindifference from the normal text replacement is the ability to formulate conditions that may turnout complex.



10.3.5 Specialties: Filter Texts, Noexport und Setfilter

GESStabs knows filters that are provided with text. If the data is processed further with GESStabs,GESStabs can take filter together with the text from the questionnaire. For GESStabs the textis exported in the file var.inc (please also refer to section 25.5.3).

flt = ( condition ) "Filter Text";

In various situations, it may be desirable not to take filters in var.inc. Let’s say the syntaxof the script is not compatible with GESStabs, or a question shows up in different blocks andtherefore considered as two different variables. In such a cases, the export can be prevented bythe keyword noexport.

flt = ( condition ) "Filter Text" noexport;

As an alternative to the conventional flt on questions, screens and blocks, a setfilter

-endfilter construct can also be used. This command is identical to that in GESStabs.In this case the filter is written around the script part. The command is open withsetfilter = CONDITION; and closed with endfilter. A definition of the name and atransfer of the text is optional.

setfilter [NAME] [text "TEXT"] = CONDITION;

// Questions, Screens, Blocks

endfilter [NAME];

10.4 Plausibility Conditions (Assert)

Plausibility conditions (assertions) specify under which conditions a question (or a screen / block)can be left aside. If the condition is not met, the interview remains on the current screen withan error message. In addition, it is also possible to define plausibility conditions in such a way,so that if they are not met, the interview would be terminated. (For example if the intervieweesdo not fit in the quota scheme). Unlike the filters, an unlimited number of assert statementscan be listed to questions / screens / blocks.

The syntax for plausibility conditions is:

assert CONDITION "ERROR MESSAGE" [exit FINISHCODE] [attempts TRIES];

With CONDITION is a thesis stated that has to be fulfilled. If this is not the case, an ERRORMESSAGE is shown on the same screen, so that the interviewee can correct his information.The optional parameter exit goes one step further and terminates the interview completely.FINISHCODE is an integer, which is taken as a value in the variable _finished during interviewcancelation. So it is possible to differentiate reasons for cancelation (for example cancelation dueto gender-screenout or full quota).

In addition, it is possible with the parameter attempts to induce the consequences of a violationof the plausibility check not immediately. It is possible to allow the participants a limited numberof attempts to make corrections. How many attempts give TRIES is inputted also as an integer.Specifically, by the assert with exit, the participant’s entries can be corrected TRIES times,before the interview is permanently aborted. Until that, the assert behaves like there is no exit.



Let’s say a participant, for example distributes points and the sum of the points doesn’t matchafter the defined number of TRIES. When assert without exit is used, the participant is stillallowed to continue with the interview. With complex tasks it can be balanced, whether youprefer to get some inconsistent information or risk that the participant may give up in frustrationand you lose the interview entirely.

Examples:

SingleQ gender;

text="Gender of the interviewee";

labels=

1 "male"

2 "female"

;

assert (gender eq 1) "Women do not belong to the target group" exit 2;

SingleQ Age;

text="Age of the interviewee";

labels=

1 "under 18"

2 "18-29"

3 "30-49"

4 "50-64"

5 "65 and older"

;

assert ([2 3 4] at the age) "Respondent must be 18-64 years old." exit 3;

NumQ points;

Text="Please distribute 10 points to these brands.";

labels=

1 "Brand A" format f1

2 "Brand B" format f1

3 "Brand C" format f1

4 "Brand D" format f1

;

assert (points.1 gt 0) "Screenout. Brand A dind't receive points." exit 108;

assert (points eq 10) "Please distribute exactly 10 points." attempts 3;

In the context of plausibility conditions, the script parameter disableExitOnAssert is mentioned.It can suppress the entirely exit parameter and thus be very useful for testing the screenouts.Please also refer to section 5.2.


Chapter 11. Sorting

11 Sorting

11.1 General

One side of the sorting is bringing labels, questions, screens and blocks in an order or israndomizing them. On the other side, generally is to maintain the once-fixed sequence within aninterview.

Example can illustrate this: Three questions must be asked about three car brands. The brandsare Audi, BMW and Mercedes (standing in this alphabetical order in the script), and thequestions are assessments of the appearance, equipment and price. The three questions shouldbe carried out in a fixed order for all three brands. The order of the marks should be randomper interview.

If the random order of the Mercedes, Audi and BMW would be, it would result in this sequenceof questions:

1. Appearance Mercedes

2. Appearance Audi

3. Appearance BMW

4. Equipment Mercedes

5. Equipment Audi

6. Equipment BMW

7. Price Mercedes

8. Price Audi

9. Price BMW

So in the beginning of the interview is set the order (Mercedes, Audi, BMW). In order to maintainthis order in the various blocks, GESS Q. sets the specialized variable sortID, which saves theposition on an element. <id> must be a string:

sortID=<id>

In our example, all questions get Sorting-IDs:

SingleQ appearance_audi;

...;

sortID="audi";

SingleQ appearance_bmw;

...;

sortID="bmw";

SingleQ appearance_mercedes;

...;

sortID="mercedes";

SingleQ price_audi;

...;

sortID="audi";


Chapter 11. Sorting

SingleQ price_bmw;

...;

sortID="bmw";

SingleQ price_mercedes;

...;

sortID="mercedes";

SingleQ equipment_audi;

...;

sortID="audi";

SingleQ equipment_bmw;

...;

sortID="bmw";

SingleQ equipment_mercedes;

...;

sortID="mercedes";

All the questions about a brand get the same Sorting-ID, so that the brand will always appear atthe same position. In order to preserve the positions through different blocks, the blocks will beassigned to a specialized array - the sortOrder. The array holds the positions of the elements:A sortOrder-Array with »3 1 2« would ensure that the elements of the Sorting-ID 1 appear insecond position.

In our example, the order of the marks should be random and with random, we achieve a randomsequence in the block:

block appearance=(appearance_audi appearance_bmw appearance_mercedes); random;

GESS Q. enables here an implicit linking: The order of the block appearance can also be

linked to the other blocks using the sortOrder. By specifying the block appearance as a sortsource, the other two blocks get the same order.

block price=(price_audi price_bmw price_mercedes); sortOrder=appearance;

block equipment=(equipment_audi equipment_bmw equipment_mercedes); sortOrder=

appearance;

Thereby the order of the marks in the three blocks is retained.

Not only questions can be provided with a Sorting-ID. This also applies to answer labels as wellas for blocks which constitute the content of a block. Since the Sorting-ID and sortOrder arenumber respectively number sequences, a sorted order can be transfered as desired, for example,from labels to blocks.

In our example, a SingleQ can be inserted before the question blocks, where for example isasked, which of the three characteristic (price/appearance/features) is the most important for theinterviewees. The answer labels of the singleQ are randomized and the three blocks of questionsmust be asked in the same order as the answer labels:

SingleQ important;

text="Which of these characteristics is the most important for you?";


Chapter 11. Sorting

labels=

1 "Price" random sortID="price"

2 "appearance" random sortID="appearancen"

3 "Scope of the equipment" random sortID="equipment"

;

The question blocks are also given to the sort IDs from the SingleQ:

block appearance=(appearance_audi appearance_bmw appearance_mercedes); random;

sortID="appearance";

block price=(price_audi price_bmw price_mercedes); sortOrder=appearance; sortID

="price";

block equipment=(equipment_audi equipment_bmw equipment_mercedes); sortOrder=

equipment; sortID="equipment";

The sorting of the SingleQ important must be transferred to the question block:

block questions=(appearance price equipment); sortOrder=important;

Through sortOrder=important the question block gets the Single-Question important withits sequence of labels as sorting template.

This approach can be used even further. Since, ultimately the labels are a hierarchically nestedtree structure, the specification of the sortOrder may also refer to a specific group of labels. Inthe following example of a MultiQ, the queried models are grouped by brands and both thelabels and the groups get a Sorting-ID:

MultiQ car models;

text="Which of these car models you know?";

labels=

group (

text "Audi"

1 "A4" random sortID="a4"



) sortID="audi"

group (

text "BMW"

4 "3er" sortID="3er"



) sortID="bmw"

group (


7 "C-class" sortID="c"

8 "E-class" sortID="e"

9 "S-class" sortID="s"

) sortID="mb"

;

The next question should ask about the favorite model and the sequence of the models fromthe previous MultiQ is to be retained. With sortOrder=carmodels.audi the order of theMultiQ carmodels and the group audi is transferred to SingleQ.


Chapter 11. Sorting

SingleQ pref_audi;

text="Audi favoritemodel";

labels=

1 "A4" sortID="a4"

2 "A6" sortID="a6"

3 "A8" sortID="a8"

;

sortOrder=carmodels.audi;

The subgroup audi (identified by its Sorting-ID) is referenced with sortOrder=carmodels.audi .This can be nested to any depth (if the label groups are correspondingly complex), where thegroups are separated by a dot.

Similarly, it goes on with the BMW and Mercedes;

SingleQ pref_bmw;

text="BMW favoritemodel";

labels=

1 "3" sortID="3"

2 "5" sortID="5"

3 "7r" sortID="7"

;

sortOrder=carmodels.bmw;

SingleQ pref_mercedes;

text="Mercedes favoritemodel";

labels=

1 "C-class" sortID="c"

2 "E-class" sortID="e"

3 "S-class" sortID="s"

;

sortOrder=carmodels.mb;

11.2 Array Contents as Sorting Order

Under certain circumstances, an order must be calculated explicitly (for example, in order totake quota stands into account). Randomized numbers can be stored in an array and the arraycan then be used as a sorting template.

The command arraySortOrder allows the:

arraySortOrder NAME = ARRAY;

The elements, saved in the array, become in this way the SortingIDs. An array with the content:(2 3 1 4) results in the Sorting-IDs »2« »3« »1« »4«.

Array sort_template[4];

arraySortOrder also = sort_template;

StartActionBlock = {

set( sort_template[1] = 2 );



Chapter 11. Sorting



};

MultiGridQ s1;

text="Gadgets";

gridlabels=

group(

1 "Yes" sortid="1"

2 "No" sortid="2"

3 "Maybe" sortid="3"

4 "Yes and No" sortid="4"

) sortorder = aso

;

griditems=

1 "Phone"

2 "Camera"

3 "Tablet"

4 "Phablet"

;

GridLabels of a Grid-Question can be provided with a sortOrder with a group (the order ofthe labels here would also be »No«, »Maybe«, »Yes«, »Yes and No«). In order for the questionitself to get the sorting order, GridItems is sorted (with appropriate Sorting-ID).

11.3 Automatic Generation of the Sorting-ID

The manual preparation of the sort IDs is often time-consuming and redundant. In most casesit is sufficient to have a simple, short identifier. Therefore the ID for labels can be producedautomatically. The option can be activated or deactivated locally by a switch:

createDefaultSortId=[ yes | no ];

By value-labels, the value of the label is converted in a string and used as a Sorting-ID.

An example:

createDefaultSortId=yes;

MultiQ q4;

text="Which of the following vendors is known to you?";

labels=

1 "abc" random

2 "def" random

3 "ghi" random

4 "jkl" random

99 "None of the above" single

;

MultiQ q5;

text="The website of which vendors have you visited? ";


Chapter 11. Sorting

labels=

1 "abc"

2 "def"

3 "ghi"

4 "jkl"

99 "of none" single

;

sortorder=q4;

createDefaultSortId=no;


Chapter 12. Quotas

12 Quotas

12.1 Quotas Variables

The monitoring of the quota specifications is an important element in the conducting of thestudies.

The quota variables in GESS Q. are about interview-overarching counter with set points. Theyare counted up implicitly by fulfilling certain conditions at the end of each interview or arecounted up explicitly. It should be noted, that the quotaWriteCondition (refer to section 5.2)generally regulates whether an interview have any influence on the quotas count. In this manner,for example, the test mode or a used subscriber test ID can be excluded from the quotas count.

A quotas variable consists of several components:

• Name

• Condition, whether it is counted after the end of an interview

• Actual-counter status

• Desired-counter status

The syntax for defining a quotas variable in the script is:

quotaVar NAME=CONDITION;

quotaVar gender_m = gender eq 1;

quotaVar gender_w = gender eq 2;

The Actual-counter status and the Desired-counter status are not listed here yet. Since quotasstands are interview-overarched, they are stored in the file quotavars.lst, which must be locatedin the directory of the study. Quotas listet there must be defined in the script and vice versa.For the given example see e.g. the file as follows:

gender_m 0 100

gender_w 31 100

With this constellation, the women’s quota was counted already 31 times, while the male’s quotaremained untouched so far.

In order to be able to work with the information of the quotas variable in the script, there are 3different selectors:

QUOTAVAR Actual-status of the quota (without consideration of active interviews)

current(QUOTAVAR) Actual-status of the quota (with consideration of active interviews)

target(QUOTAVAR) Desired-status of the quota

The pure definition of the quota leads only to a counter behavior of the quota. It would alsocontinue to count beyond the set point. Crashes or other actions based on the quota standsmust be defined explicitly in the script. An example for a quotas conditioned termination of theinterview in the script could look as follows:

quotaVar gender_m = gender eq 1;

quotaVar gender_w = gender eq 2;


Chapter 12. Quotas

SingleQ gender;

text="gender";

labels=

1 "male"

2 "female"

;

if(gender eq 1) assert (gender_m lt target(gender_m)) "too many M" exit 2;

if(gender eq 2) assert (gender_w lt target(gender_w)) "too many F" exit 2;

For the significance of assert reference is made to section 10.4.

If one doesn’t want to use an implicit counting behavior of the quota, ratio variable with an,in any case, invalid condition can be defined and the counting can be done manually with theaction command incQuota(QUOTAVAR). Even if chapter 14 takes it a little ahead, it would beequivalent to the abovementioned example:

quotaVar gender_m = 1 eq 2;

quotaVar gender_w = 1 eq 2;

SingleQ gender;

text="gender";

labels=

1 "male"

2 "female"

;

if(gender eq 1) assert (gender_m lt target(gender_m)) "too many M" exit 2;

if(gender eq 2) assert (gender_w lt target(gender_w)) "too many W" exit 2;

cmplActionBlock = {

if(_finished eq 1){

if(gender eq 1){ incQuota(gender_m) };

if(gender eq 2){ incQuota(gender_w) };

};

};

12.2 Quota Groups

Several individual quotas variables often form logically connected units (as in the example withM/W). Therefore, it is useful (and in the future GESS Q. versions even necessary), to summarizethem in groups. In order to summarize several quotas variables into a group, the one must specifythe statement

QuotaGroup <name> begin;

before the definition of the variables and behind the

QuotaGroup end;

A Quotagroup can be directly used in a condition. It provides the value true, if the currentinterview »fits« to the quota groups. »Passing« means: all included QuotaVars, whose conditionsof current interview are true, have a lower actual-counter reading than target counter reading.


Chapter 12. Quotas

Example:

QuotaGroup qgr_gender begin;

quotaVar gender_m=gender eq 1;

quotaVar gender_w=gender eq 2;

QuotaGroup end;

SingleQ gendert;

text="gender";

labels=

1 "male"

2 "female"

;

assert qgr_gender "Already has enough interviews with this gender!" exit;

Alternatively, the individual variables can be specified directly at the QuotaGroup definition:

QuotaGroup qgr_gender=(gender_m gender_w);


Chapter 12. Quotas

12.3 Quotas and Access Rights

Via the web interface (refer to section 25.3.9) it is possible to control the quota stands and toadapt the specifications. In case the access to this entry menu is linked with the access rights,then each individual quota may be made visible or be hidden for a user’s account.

Currently, the access control can be achieved by two different mechanisms (changes are plannedin the near future). The younger mechanism allocates all quotas in a json-file of an user ID, onwhich this account is allowed to access. If GESS Q. should take into consideration the file, itmust be located in the study directory by the name quotafilter.json.

[

{

"userid": "user1",

"quotavars": [

"total",

"q2",

"q4"

]

},

{

"userid": "user2",

"quotavars": [

"total"

]

}

]

By an older mechanism GESS Q. evaluates a file called qsr.lst in the study directory. The fileassigns each quota line by line with a space-separated user IDs. Only the listed users can accessthe corresponding quota, no matter what user rights have been assigned to the accounts.

quote1 user1 user2 user3 user4


Chapter 13. Automatic Forwarding to the Interviewer

13 Automatic Forwarding to the Interviewer

13.1 General

It is often necessary that, at the end of the online interview, the interviewee is forwardedto another web page (e.g. one of a panel provider). Although the forwarding can be done»manually«, the GESS Q. provides a comfortable, automatic workflow. A list of redirectionscan be defined, each consisting of a URL, a text for the final screen of the survey, a conditionand a delay period. At the end of the interview, the conditions in the list are evaluated and theforwards, of which the conditions are met, are automatically integrated in the final screen. Theprerequisite for this, of course, is that only one of the conditions is met.

The syntax for this is:

finishForward={

("<URL 1>" "<text 1>" "<condition 1>" <delay>)




...

};

The URL here is incorporated into the header of the HTML page by meta tag, where »delay« isthe time of the delay. The text appears there, where the normal finished text stands virtuallyas an alternative text for URL (e.g. »If you are not redirected automatically, please click <ahref=...>hier</a>«).

13.2 Integrating in a panel

Special panels bring value to the forwarding at the end of the interview. Panels usually set three»end links« or »redirect-links« with which the interviewee should be forwarded, depending onthe completion code of the interview and (normally) are:

• one link for normally completed interviews

• one link to abortions from screening reasons (screen out)

• one link to abortions from quota reasons (quota out).

It is also necessary to document, in any way, what is the reason for ending the interview. Suitablefor that is the internal value _finished, containing a status code at end of interview, whichcan also be affected (please refer to assertions, section 10.4). The variable _finished must getcorresponding value in order to link a condition by FinishForward.

Lets assume, that there is an assert by a question, concerning screening criteria. Then there isan exit code »2« to be assigned.

assert ... "Unfortunately abort; exit 2;

The variable _finished obtains the value 2, if the abort occurred at this point. In case of quotawe assigned accordingly value 3:

assert ... "Unfortunately quota already full" exit 3;


Chapter 13. Automatic Forwarding to the Interviewer

The exit code for a normal fully implemented interviews is 1. By that we are now able to specifyappropriate conditions at FinishForward. In addition, the respondent ID must be incorporatedinto the link (which is a common requirement in the practice):

FinishForward={

("http://www.meinpanel.de/redirect_compl\&survey=meinestudie\&respid=@insert(

_respid)"

"<alternativ text>" "_finished eq 1")

("http://www.meinpanel.de/redirect_screenout\&survey=meinestudie\&respid=

@insert(_respid)"


("http://www.meinpanel.de/redirect_quotaout\&survey=meinestudie\&respid=@insert

(_respid)"


};

The <alternativ text> should be regarded here only as a symbolic placeholder. In the practicethe URL must be incorporated at this place as href, in case the automatic forwarding of thebrowser is deactivated.


Chapter 14. Action Commands and Action Blocks

14 Action Commands and Action Blocks

14.1 General

With the previously introduced means it is difficult to perform calculations that, for example,can be used to control the interview process. For example, if a variable is defined by compute

that constitutes of a calculation:

compute a = b+c;

Then with each access to the variable a (e.g. within calculation or conditions) the current valueof the addition b+c is determined and used as value of a. No counters are possible with that. Adefinition like:

compute count = count+1;

would lead to an endless recursion, because with the access to the value of count is made thecalculation count+1, which again makes an access to count, and so on.

Actionblocks provide a solution and allow, by the control, to take in consideration quotestands and random choices or to make calculation by start or resumption of an interview. Theactionblocks control structures are available for that, as they are known from conventionalprogramming languages: if-then, from-to, etc.

An action block contains any number of commands and is linked to a specific event. Theaction block is executed when the event occures. Available are both interview related events(start, cancel, finish) and question specific (before displaying, after clicking on »continue«, etc.).Specifically available are...

Interview specific:

startActionBlock executed at start, also at resumption. This also applies to cases, were thestudy is closed or deactivated, so that GESS Q. can output eventual messages in the correctlanguage

resumeActionBlock it is executed for a resumption after abort

timeoutActionBlock is carried out before an interview is cancelled due to inactivity

cmplActionBlock is executed if an interview is completed, no matter what is the status

Question or block specific:

initActionBlock is performed at initialization before displaying a question or block

preAssertionActionBlock is performed by clicking on the submit button, but before validatingthe asserts

continueActionblock is performed after successful validation of a question or a block beforeforwarding to the next screen

No variables can be defined within these command Blocks; that needs to be done in advancewith compute. An exception here are the counting variables of loops.

compute count=0;

SingleQ q1;

...



flt=count lt 3;

continueActionBlock={ inc(count); };

SingleQ q2;

...

flt=count lt 3;


SingleQ q3;

...

flt=count lt 3;


SingleQ q4;

...

flt=count lt 3;


SingleQ q5;

...

flt=count lt 3;


block random =(q1 q2 q3 q4 q5); random;

The command inc (for »increment«) is an action command. It increases the counter count byone after every question. In addition, each question is filtered, if the count has reached 3.

The commands in an ActionBlocks must be in curly brackets. They also serve to define furtherblock structures within an ActionBlock such as conditions and loops.

GESS Q. allows to write also action blocks on screens, however ActionBlocks only havefunction/meaning in questions or partially in blocks ([Init|Continue]ActionBlock).

The action commandscan can be split into two categories: »normal commands« and commandfor flow control (conditions, loops).

14.2 Action Commands

Action Commands make possible the use of counter, conditions and loops. The followingalphabetically sorted action commands can be used only within action blocks.

add replaces the first _missing location of an array ARRAY with VALUE. If the array iscompletely full, the instruction is not followed.

add(ARRAY, VALUE);

Array container[3];

actionblock set_container = {

set( container[1] = 1 );

set( container[3] = 3 );



};

actionblock add_container = {

add(container, 7);

};

continueActionblock = { print(container); };

// results in actionlog.txt:

// PrintAction: variable: container; value: 1 7 3

appendText attaches TEXT on TextElement TEXTVAR.

appendText(TEXTVAR, "TEXT");

appendText(textelem, "... being attached");

changePBar sets the progress bar with #QUESTIONS put further, as long as CONDITIONapplies. Alternatively (and more common) the progress bar can be defined, also within filters forquestions, screens and blocks, please refer to section 10.3.2.

changePBar((CONDITION) #QUESTIONS);

changePBar((var eq 1) 2);

clear depending on arrayInitMode each element of ARRAY gets assigned the missing value_missing or the corresponding locations Index.

clear(ARRAY);

[by arrayInitMode=missing]

ARRAY-content before clear(): { 1, 2, 3, 4, 5 }

ARRAY-content after clear(): { , , , , }

dec stands for decrement and decreases the value of VAR by one.

dec(VAR);

exit With exit the interview is terminated at the end of the current Action block withFINISHCODE and than is displayed the end page.

exit(FINISHCODE);

findMinValIndex, findMaxValIndex The functions search in an array (ARR) the lowest re-spectively the highest value and save the index of the location in the variable (VAR).

findMinValIndex(ARR, VAR)



compute min = 0;

compute max = 0;

set( arr = [1 3 5 -1 6:9 0 0] ); // {1, 3, 5, -1, 6, 7, 8, 9, 0, 0}

findMinValIndex(arr, min); // min obtained value 4

findMaxValIndex(arr, max); // max obtained value 8

getCountValue The Action command

getCountValue(VAR, "KEY")

calls of the counter, which searches in the file countvars.lst which is located in the study folder.First the counter KEY is incremented und then passed on to the variable VAR.

compute z1 = 0;

textq welcome;

text="

Welcome!<br />

You are the @insert(z1). participant in this survey!

";

initactionblock={

getCountValue(z1, "counter1");

};

With the displaying of the question, the count is increased. The messages are displayed insequence as follows:

You are the 1st participant in the survey!

You are the 2nd participant in the survey!

You are the 3th participant in the survey!

The file countvars.lst consists of Key-Value pairs:

counter1 0

counter2 0

counter3 0

inc stands for increment and increases the value of VAR by one.

inc(VAR);

incQuota increases the value of one QUOTAVAR explicitly by one.

incQuota(QUOTAVAR);

insertLabels attaches in the label list of question QUESTIONNAME behind the label withCode CODE a new label LABEL. Depending on the type of question, in this case, it must beensured that the originally created question also has enough space to save all possible answers.If the question in the given example is a MultiQ, than must be used oversizeArray(1); toensure that the original questions with 2 labels will have enough space to be able to save threeanswer codes.



insertLabels(QUESTIONNAME, CODE, [ LABEL ]);

multiq known;

labels=

1 "Lafite Rothschild"

3 "Haut-Brion"

;

initActionBlock={

insertLabels(known, 1, [ 2 "Mouton Rothschild" ]);

};

oversizeArray(1);

lalign moves each element of ARRAY, which is not equal to the Missing value _missing, left(to the smallest index), exchanging as many places as possible with missing values, please alsorefer to lalign.

lalign(ARRAY);

ARRAY-content before lalign(): { , 2, 3, , 5, 6, , , }

ARRAY-content after lalign(): { 2, 3, 5, 6, , , , , }

load copies the content of the value VAR2 in VAR1. The difference with set is, that not only avalue / number / Result is assigned, but the entire contents of a variable in a different variable.For example entire content of arrays can be copied.

load(VAR1 = VAR2);

performHttpRequest serves for the assignment of variables and questions in an interview. Thecommand sends an HTTP request to the web address URL and expects an answer with datain JSON format. The second parameter data="INFO" is optional and can transfer additionalinformation by the request. The given values are applied to the above mentioned variables, ifthey exist. The command works similarly to readJsonDataFile.

performHttpRequest( url="URL"; data="INFO"; );

performHttpRequest(

url="http://www.gessgroup.de/AntwortServlet";

data="optional information";

);

///////////////////////////////

// Server-Response:

///////////////////////////////

// {

// "variables": {

// "singleq": 4,

// "multiq": [2, 3, 5, 7, 9],

// "openq": "dies ist ein text",

// "numq": [14, 19, 5, 27],

// "sgq.1": [1,2,3,2],



// "mgq.1.1": [1,2,3],

// "mgq.1.2": [2,1]

// }

// }

pow from the stated numbers and with pow(BASE, EXPONENT) a degree is built and written inthe variable VAR.

set(var = pow(10, 3)); // 10^3

print writes the content of the variable VAR in a line of the file actionlog.lst in the foldertext of the study. In case there is no file with this name, a new file is created.

print(VAR);

printText writes the specified TEXT in a line of the file actionlog.lst in the folder text ofthe study. In case there is no file with this name, a new file is created.

printText("TEXT");

ralign moves every element from ARRAY, that is unequal the missing value _missing,to theright (to the biggest index), exchanging as many places as possible with missing values, also referto lalign.

ralign(ARRAY);

ARRAY-content before ralign(): { , 2, 3, , 5, 6, , , }

ARRAY-content after ralign(): { , , , , , 2, 3, 5, 6 }

readDataFile is used for the assignment of variables and questions for an interview. Thecommand searches in a structured data file FILE for a row with key value VAR, and assumesthe values indicated therein in the corresponding variables, in case they exist. The FILE mustbe found in the folder text in the respective study.

readDataFile(FILE, VAR);

// e.g. for ID 67

readDataFile("data1.txt", _respid);

///////////////////////////////

// data1.txt

///////////////////////////////

// ...

// 67 ( (p_intnr "thirty one") (s1 "6") )

// ...

Please note If VAR is a numerical information (created e.g. Compute or NumQ), must be used aDecimalFormat. Please refer to section 6.1. Otherwise it could happen that large numbers areconverted to exponential form or digits after the addition of the decimal sign. In such way thesearch might not deliver results.



readJsonDataFile JSON is used for the assignment of variables and questions of an interview.The commant reads a JSON formates data record FILE and assumes specified values in thementioned variables, in case they exist. FILE must be found in the folder Preset of the GESSQ. installation (please refer to section 22.2.1).

readJsonDataFile(FILE);

readJsonDataFile("data1.json");

///////////////////////////////

// data1.json

///////////////////////////////

// {

// "variables": {

// "singleq": 4,

// "multiq": [2, 3, 5, 7, 9],

// "openq": "this is some text",

// "numq": [14, 19, 5, 27],

// "sgq.1": [1,2,3,2],

// "mgq.1.1": [1,2,3],

// "mgq.1.2": [2,1]

// }

// }

readTextRessource reads a language resource file FILE from the folder text of the study andat this point changes all text information contained in the source.

readTextRessource(FILE);

if(lang eq 1) {

readTextRessource("englisch.lrs");

};

remove replace one or more values VAL in ARRAY with _missing.

remove(ARRAY, VAL, VAL, ...);

ARRAY-content before remove(): { 3, 2, 3, 5, 5, 6, 1, 6, 6 }

ARRAY-content after remove(ARRAY, 2, 6): { 3, , 3, 5, 5, , 1, , }

removeDuplicates removes values, which are contained more than ones in the ARRAY. Onlytheir respective first occurrence remains. All other values are replaced by the missing value_missing.

removeDuplicates(ARRAY);

ARRAY-content before removeDuplicates(): { 3, 2, 3, 5, 5, 6, 1, 6, 6 }

ARRAY-content after removeDuplicates(): { 3, 2, , 5, , 6, 1, , }

rotateLeft sets the values of an ARRAY by the specified number of digits to the left.



rotateLeft(ARRAY, ANZ-place);

ARRAY-content before rotateLeft(): {1 2 3 4 5}

ARRAY-content after rotateLeft(ARR, 2) : {3 4 5 1 2}

round rounds the value of the specified variable VAR to an integer

set(var = round(var));

script embeds JavaScript Syntax in Action block. Values from GESS Q. variables can beintegrated in JavaScript with @insert(). @save(VAR = VAL); defines which values are returnedin which Q variables at the end of the execution logic. This command requires Java 8 and is notyet available on Android.

script("JAVASCRIPT");

compute nhTestResult = 5;

compute x = 0;

compute y = 0;

compute z = 0;

Array nhTestArray[3];

OpenQ te;

vararray xyz = (x y z te nhTestArray);

// ...

Actionblock ab = {

script("

var x = 1;

var y = 2;

var z = @insert(nhTestResult);

var arr = new Array();

arr.push(x);

arr.push(y);

arr.push(z);

@save(xyz[1]) = x;

@save(xyz[2]) = y;

@save(xyz[3]) = z;

@save(nhTestResult) = x+y+z;

@save(xyz[5]) = arr;

@save(xyz[4]) = 'afterwards';

");

};

set assignes to the variable VAR the value VALUE. VALUE can also be a result of a calculation.

set(VAR = VALUE);



set(var = 0);

set(var = a * b + 1);

In use with array set can fill an array in one step. From array index 1 all locations, for whichvalues are specified, are thereby consecutively filled. Excess values are not taken into account.

array arr[10];

set( arr = [1 3 5 -1 6:9 0 0] ); // {1, 3, 5, -1, 6, 7, 8, 9, 0, 0}

(The syntaxis 6:9 shortens the indication 6 7 8 9)

setCurrentScreen resets the current screen and immediately accesses at the next participantinteraction. Discards entries in screens that outlast a timeout or when setCurrentScreen isused in an InitActionBlock.

setCurrentScreen(SCREEN);

// Syntactically can be written with or without the quotes.

// Without quotes the Screen existence is checked

TimeoutActionBlock = { setCurrentScreen(m4); };

// With quotes for example can be used @insert()

// setCurrentScreen("@insert(te_m4)");

// setCurrentScreen("m4");

setDecimalSeparator sets the decimal separator (default preset comma: ",")

setDecimalSeparator(".");

setGroupingSeparator sets the thousands separator (default preset point: ".")

setGroupingSeparator(",");

setNextScreen With the command setNextScreen a onetime defined jump is initiated withoutchanging the pre-defined path file. setNextScreen can be used at any desired location for anygiven screen. With the use, is to be noted, that the progress bar is not compatible with theskipping of questions or screens and so doesn’t progress parallel to the progress of the interviewand doesn’t finish parallel to it.

setNextScreen(SOURCE,TARGETSCREEN);

setNextScreen(a,c);

shuffle arranges the content of ARRAY randomly.

shuffle(ARRAY);

ARRAY-content before shuffle(): { 1, 2, 3, 4, 5 }

ARRAY-content after shuffle(): { 4, 3, 5, 1, 2 }



strCutLeft cuts the first NUMBER characters of the content of VAR and saves the result inTEXTELEMENT.

strCutLeft(TEXTELEMENT, VAR, NUMBER);

TextElement cutlery;

OpenQ q1;

text="Please enter something";

continueActionBlock={ strCutLeft(cutlery, q1, 2); };

strCutRight cuts the first ANZAHL characters of the content of VAR and saves the result inTEXTELEMENT.

strCutRight(TEXTELEMENT, VAR, ANZAHL);

syncsort sorts the contents of ARR1 ascending (ascending) or descending (descending).According to the scheme, how the elements change their position in ARR1, ARR2 is alsoreordered.

syncsort(ARR1, ARR2, ascending|descending);

syncsort(array1, array2, ascending);

// ARRAY-content before syncsort(): array1{ 3, 7, 1, 9, 4 } array2{ 1, 2, 3,

4, 5 }

// ARRAY-content after syncsort(): array1{ 1, 3, 4, 7, 9 } array2{ 3, 1, 5, 2,

4 }

writeJsonToSurvey writes a raw data set FILE in the folder of the study SURVEYNAME,which contains the variable VAR in JSON format.

writeJsonToSurvey(SURVEYNAME, FILE, (VAR, VAR, ...));

The example:

writeJsonToSurvey (example study, "case123.json", (sq1 sgq.1));

results in

///////////////////////////////

// case123.json

///////////////////////////////

{

"rvars": [

{

"name": "sq1",

"value": "3.0"

},

{

"name": "sgq.1",

"value": "4.0 4.0 5.0 5.0"

}

]

}



14.3 Control Structures

For the sequence control GESS Q. offers integrated control structures.

• if-else: if-then

• for: Loop (from-to)

• forEach: Loop (for-each)

• while: Loop (while)

if(<condition>)

{

...

};

The if can also be combined with an else:

if(<condition>)

{

...

}

else

{

...

};

Two types of loops are available: The for loop for and the while loop. By the for loop acounter variable is created, which is incremented in single steps from start to target value ateach iteration. As start and end value can be specified both numerical values and variables.

for(x=1 to 10)

{

...

};

The loop is executed 10 times, and x runs through the values 1 to 10

for(y=var1 to var2)

{

...

};

As start and end values here are specified variables. Of course, it should be noted that it ispossible to build endless loops, that never break, and especially when the variable are manipulatedwithin the loop, are possible very strange behaviors.

Note also that the counter variable is newly applied and therefore no variable with the samename must be present. This also means, that the counter variables for different for loops mustalso have diferent names.

Another type of the for-loop, is the forEach. Whit this loop can be processed a series of specificvalues.

forEach(y=1 3 5 7 9 50:55)

{

... runs through y with 1, 3, 5, 7, 9, 50, 51, 52, 53, 54, 55

};



There is no number variable with the while loop. The loop is repeated as long as the conditionis met:

while(<condition>)

{

...

};


Chapter 15. Template, Layout, Graphic Elements

15 Template, Layout, Graphic Elements

15.1 Frame Layout - the "Template"

15.1.1 Structure of the Template

The file template.html in the folder text builds the template for the layout of the questionnaire,or more precisely, for the design of the web page. With the means of HTML and CSS layout canbe adapted to your own concepts.

Figure 15.1: Questionnaire Layout for a GESS Project

Figure 15.2: The Same Questionnaire in Standard Layout for Android Devices

Here is not the place to explain HTML or CSS which are documented in many places on the web.1

Therefore, here are given only some summary remarks. The template file is divided by HTMLtags into two sections: head and body. In the head of the file between the tags <head> and</head> belongs the title of the survey (between <title> and </title>), which most browsersassume in its frame and use as a label for the tab.

<head>

<title>online questionnaire</title>

<meta name="Content-Type" content="text/html; charset=utf-8"/>

<link type="text/css" href="./css/default_gess.css" rel="stylesheet" />

<script type="text/javascript" src="./javascript/gesstmpl.js"></script>

<script type="text/javascript">

1For example: http://de.selfhtml.org/


http://de.selfhtml.org/


In the definition of the content type with Content-Type the character set must be defined asUTF-8, because GESS Q. uses this encoding for all the websites.

Various resources can be integrated with the link tag. Here, above all, it is all about the stylisticdefinitions in a CSS file. HTML structures one site only in headings, paragraphs, lists, etc. Howthe individual elements should look like, is determined by the rules in the CSS file (What fontmust be used in a title, how big should be the font of the title, what distance should be keptbetween the headline and the text, etc.) The file, embedded here, sets some basic layout decisionswhich are rarely changed (for example, font, font size, font color),

With the script tag JavaScript files can be included. These provide functions that are requiredat different points in the questionnaire. Already embedded is gesstmpl.js, because many of thegraphical functions are programmed there.

CCS style rules are used again in the integration of JavaScript in the template. These are usedwith the style-tag.

<style type="text/css">

In this section the template collects a number of CSS classes that are adjusted frequently inquestionnaires. This can also be expanded if necessary. In order to find the name of the desiredelement, most browsers now offer the option to select »Inspect Element« in the context menu -accessible with right-clicking on the item.

The head file ends with the style rules and then follows the section body with the HTML elements.These elements constitute the page. The appearance of the individual elements can be affectedfurther with style statements. Graphics from the media folder integrate the templates typicallywith the usage of variables $surveyname:

src="./media/$surveyname/redpbar.jpg"

Variable provides the folder name of the study.

15.1.2 template_error.html

If the interviewee starts a questionnaire and an error occurs, because the study has beencompleted or the respID is incorrect, an error message appears. This message follows thetemplate default layout of the study. If the error message should deviate from this style, theappropriate adjustments can be made in the file template_error.html.

15.1.3 Placeholder

GESS Q. fills the template in order to create the actual web page with the question. For thispurpose the various placeholders are used, which appear in the template with preset @ thebeginning of the line.

List of Placeholders in the Template

@tt1 – @tt8 Content of the internal TextElements »template1« – »template8« in the Script

@qtext – @end_qtext question text

@prehelptext – @end_prehelptext pre-help-text, pre-interviewer-help-text

@posthelptext – @end_posthelptext post-help-text, post-interviewer-help-text

@error – @end_error error messages



@input – @end_input content of questions

@javascript The JavaScripts, generated from GESS Q. must be inside the tag <script>

@forward forwarding at the end of the interview

@header The JavaScripts, generated from GESS Q. must be inside the tag <script>

@form HTML form for screen content (later a "</form>" must be manually noted

@body HTML screen content

@submit – @end_submit Next Button

@back – @end_back Back Button

@cancel – @end_cance Cancel Button

@pbar – @end_pbar progress as a number (depending on pBarWidth)

@src1 – @src4 Content from file (see Script Parameter src1 – src4)

@htmllabels HTML labels (refer to section 7.2.2)

@language – @end_language Language Selection

@surveyname name of the survay

$surveyname name of the survay (also within a line)

@dummy nothing

Thus GESS Q. replaces the placeholders with your content, these must always be at the beginningof the line. So for the web page the placeholder @input is replaced by the actual question.@submit, @back, @cancel provide the corresponding buttons (»Next«, »Back«, »Cancel«), ifthey are intended, etc. It also depends on the context whether the placeholders are considered.@pbar for example, is only considered within the questionnaire, on the other hand @forward

only adds a forwarding at the end of the interview.

The frequently appearing placeholder @dummy is always considered. It represents a mark forGESS Q. by which all read lines of the template since the last placeholder are written in theactual web page.

GESS Q. reads and buffers the layout line by line. Lines, which start with a placeholder, ensurethe evaluation of the buffer: If the placeholder is meaningful in the particular context, GESS Q.writes the contents of the buffer into the page. If the placeholder is meaningless, the bufferedlines are deleted.

The mechanism of the placeholder can also be used to display any necessary information from thecurrent interview. There are eight freely assignable variables with the names from template1

to template8 for this purpose. The placeholder, which must then be inserted in the template,must be named correspondingly from tt1 to tt8.

The ID of the interviewee can occupied the template1 by the use of the action command setText:

startActionBlock = { setText( template1, "@insert(_respid)" ); };

In order to display the ID the following should be inserted into the desired location in thetemplate

@dummy

@tt1

@dummy



The framing with @dummy placeholders is done for safety: First, the content since the lastplaceholder is written in the webpage and after that is made sure, that the content fromtemplate1 must be inserted.

The placeholder can also get an HTML snippet.

startActionBlock = {

setText( template1, "<div style=\"color:red;\"> @insert(_respid) </div>" );

};

With this, the ID of the interviewee would be displayed in red. In order to stop the displaying,the placeholder can be reset:

ContinueActionBlock = { setText( template1, "" ); };

15.1.4 Progress Bar

A progress bar shows the interviewees, how far they are in the survey or how long they still have.This feature is an advantage since the interviewee can see an end, but also holds the dangerof discouragement, because by long questionnaires the progress bar would move forward veryslowly. The progress bar is configured in the template with @pbar and respectively terminatedwith @end_pbar. Basically, the progress bar counts the number of screens in a questionnaire,NOT the number of questions. That means that there is not difference for the progress bar ifmultiple questions or only one question are shown on the screen. In both cases the progress barwould have the same speed.

If a screen is filtered (is therefore only displayed for a specific response and otherwise is skipped),the progress bar will not show correctly without the filter parameter changepBar(NUM). Theparameter ensures that the progress bar advances analog to the number on skipped screens.NUM stands for the number of skipped screens.

Figure 15.3: The progress bar skips a screen: changepbar(1)

singleq f0;

text = "where you are, is the sun shining today?";

labels=

1 "Yes"

2 "No"

;



openq f1;

title = "What you are doing in the fine weather today?";

flt = (1 in f0) changepbar(1);

singleq f2;

text = "Would you like to fly on a holiday?";

labels=

1 "Of course!"

2 "I prefer to work."

;

A further variant arises, if from a specific question forth a plurality of different paths can beentered, depending on which response is given. To illustrate there is a picture:

Figure 15.4: Various paths with the same question number

In the example shown, three different paths have been created of which only one is shown persurvey. In this example the progress bar would anticipate 17 questions (f1, 5 questions in path1, 5 questions in path 2, 5 questions in path 3 and f7). Since only one path with questions isselected and answered, at the end of the survey 10 questions will be missing and the progressbar will not complete. To eliminate this problem, the command pBarMax = NUM; is added tothe script. Thus, the maximum number of screens is determined and adjusted. In addition,the progress bar will move forward slowly, since it is provided with more questions that can beanswered in the survey. This suggests that the questionnaire is very long and the survey movessluggish. In the above example, the command must be pBarMax=7; . By the way in the scriptcheck can be seen, from how many screens the questionnaire is made.

More about this command can be found in section 5.2.

singleq f1;

text="Which of the statements is the most relevant to you?";

labels=

1 "I am a vegetarian."

2 "I do not eat vegetables."

3 "I do not care I-eat everything."

;

//Path 1

textq t1; text=" t1";







//Path 2





textq t10; text="t10";

//Path 3






//End of the paths

textq f7;

text="This is very interesting. Thanks for the honest answers."

pbarmax=7; //Adjusting the progress bar

block Pfad1 = (t1 t2 t3 t4 t5) ; flt= 1 in f1;



15.1.5 The GESS JavaScript Library

gesstmpl.js

...

15.2 Graphical Buttons

Figure 15.5: Graphical Buttons

As can be seen in figure 15.5, graphical buttons can appear in 3 versions:

• marked

• not marked

• disabled



Corresponding images for the buttons can be selected from any web-enabled formats (e.g.: .gif,.jpg, .png). It must be noted, that later in the questionnaire they are displayed in the originalsize.

Especially for multi-questions custom buttons can be defined, in order to make possible theoptical differentiation to single questions (similar to check boxes and radio buttons in HTMLstandard). There is also the option to specify a minimum required and a maximum permissiblenumber of marked answers. The graphical MultiQ (also MultiGridQ) always stores the answersgiven by interviewees in the click sequence, that means that the first clicked answer always comesfirst in the data record and the last clicked answer comes at the end.

15.2.1 Requirements for the Usage

The graphical buttons are available for the question types SingleQ, MultiQ, SingleGridQ andMultigridQ. In order to use these, the GESS JavaScript Library gesstmpl.js must be integratedin the template. Please refer to section 15.1.5. In addition, the images used for the buttons mustbe stored in the media path of the corresponding survey (./media/SURVEYNAME/) .

15.2.2 GESS Q. Script

Now it must be passed to the script that instead of the browser standards must be used thegraphical variants for each question type.

QUESTION TYPE VARIANT TO BE USED

HTML{ singleQClass = "GSingleQ"; };

HTML{ multiQClass = "GMultiQ"; };

HTML{ singleGridQClass = "GSingleGridQ"; };

HTML{ multiGridQClass = "GMultiGridQ"; };

The names of the graphical variants of the standard question types usually begin with the prefixG. The assignment of the actual image files for the buttons is performed using the HTML commandsetProperty() and can be changed from question to question:

HTML{ setProperty("button_checked" "bc.gif"); };

HTML{ setProperty("button_unchecked" "buc.gif"); };

HTML{ setProperty("button_inactive" "bia.gif"); };

SingleQ s1;

(...)

HTML{ setProperty("button_checked" "bc1.gif bc1.gif bc2.gif"); };

HTML{ setProperty("button_unchecked" "buc1.gif"); };

MultiGridQ mg1;

(...)

If the graphic types of questions are selected, but no information about the images is provided inGESS Q. script, the software assumes the default cases, which must be stored in the media pathof the survey.

button_checked A file name must be provided including an ending for a marked button. Multiplespace-separated file names can be specified in order to use different buttons within a question.The integration is done according to the label order written in GESS Q.Script. If there are more



labels than specified graphics, the latest file will be used.Default: button_checked.gif

button_unchecked A file name must be provided including an ending for an unmarked button.The use of different buttons within a question corresponds to button_unchecked.Default: button_unchecked.gif

button_inactive A file name of a graphic must be provided including an ending for a disabledbutton. The use of different buttons within a question corresponds to button_unchecked.Default: button_inactive.gif

multi_button_checked Analogously to button_checked. Especially for multi-questions.Default: Use of button_checked

multi_button_unchecked Analog to button_unchecked. Especially for multi-questions.Default: Use of button_unchecked

multi_button_inactive Analog to button_inactive. Especially for multi-questions.Default: Use of button_inactive

The graphical buttons are distinguished based on their file names. So no image can be used forfor example button_unchecked, or also for button_inactive.

15.2.3 Adjustable Parameters

Besides the aforementioned parameters for the image files, there are additional features that areused and adjusted via property parameters:

• Image preview by onMouseOver over the buttons

• minimum and maximum number of marked answers (only Multi(Grid)Q)

• mouse click behavior (mouseUp / mouseDown)

• Highlighting in lines or cells in grid questions

• Processing mode single answers (only Multi(Grid)Q)

Image Preview by onMouseOver over Buttons

Figure 15.6: Image Preview by Graphical Buttons



With button_preview it is possible to assign a preview to the buttons, in order to be shownwhen hovering mouse. Refer to figure 15.6.

button_preview A file name of a graphic must be provided including an ending or a markedbutton. In order to use different preview images for the different buttons within one question,multiple file names can be provided, separated by spaces. The integration is done according tothe label order written in GESS Q. script. If there are more labels than specified graphics, nopreview is added for the excess buttons.Default: ""

Minimum and Maximum Number of Marked Answers

The required maximum and minimum number of answers can be defined with minNumAnswers

and maxNumAnswers. If the number of given answers is lower than the minimum, the Next Buttonis disabled. If the number of answers reaches the maximum, the remaining answer buttons arealso disabled.

minNumAnswers An integer value must be provided.Default: 0

maxNumAnswers An integer value must be provided.Default: 10000

Mouse Click Behavior (mouseUp / mouseDown)

With mouseEvent can be set if answers are marked when the mouse button is press and release

mouseEvent are marked when pressed or released depending on the setting buttons.Options: onMouseUp | onMouseDown

Default: onMouseDown

Highlighting in Grid Questions - by Lines or by Cells

With gridHighlighting can be set if the answers in grid questions are highlighted by lines orby cells.

gridHighlighting Depending on the setting, when you move the mouse pointer in Grid questions,only cells or entire lines are highlighted.Options: row | cell

Default: cell

Processing Modes for Exclusive Answers

The behavior of the answer possibilities, which are provided with single, can be controlled (aswith other types of questions) with the parameter javascriptSingleMode. Since this scriptcommand is universally used in other places, the syntax differs from the previous parametersand can be reset at any time:

// Modus 'deselect'

HTML{ javascriptSingleMode=deselect; };

// Modus 'deactivate'

HTML{ javascriptSingleMode=deactivate; };

(...)



// from here again mode 'deselect'

HTML{ javascriptSingleMode=deselect; };

javascriptSingleMode sets the selection behavior in a single answer.Options: deselect | deactivate

Default: deactivate

In mode deselect a single answer button can be marked anytime. When it is marked, all otherpossibly existing marks are erased. Similarly, the selection of the single response button will bedeleted as soon as another button is selected.

In mode deactivate the single answer button can only be marked if no other button is marked(it would be inactive). If it is marked, all other possible answer buttons are disabled.

15.2.4 Example Code

Code for the example from figure 15.5:

HTML{

singleQClass="GSingleQ";

multiQClass="GMultiQ";

singleGridQClass="GSingleGridQ";

multiGridQClass="GMultiGridQ";

setProperty("button_checked" "smiley.gif");

setProperty("button_unchecked" "button_unchecked.gif");

setProperty("button_inactive" "button_inactive.gif");

setProperty("minNumAnswers" "1");

// setProperty("maxNumAnswers" "3");

// setProperty("mouseEvent" "onMouseUp");

// javascriptSingleMode=deselect;

};

MultiQ m1;

text="Question with Smiley-Buttons:";

labels=

1 "Multi 1a"

2 "Multi 1b"

3 "Multi 1c"

4 "All" single

;

15.3 Graphical Formatting and Layout

The graphical rendering classes are fully provided with CSS classes 2 and can be formatted withit. In this way, the layout of a questionnaire can be completely encapsulated of the contents.For essential layout specifications applying CSS files is recommended. In the following examplethe template of a questionnaire references the layout from the file default_gess.css which islocated in the folder css, next to the media folder. Based on this template questionnaire specificadaptations can be made, for example, directly in the template.

2http://de.selfhtml.org/css/


http://de.selfhtml.org/css/


<html>

<head>

...

<link type="text/css" href="./css/default_gess.css" rel="stylesheet"/>


// ... here survey specific CSS formatting

// Example: Question text in bold and underlined

.qtext{

font-weight:bold;

text-decoration:underline;

}

</style>

</head>

...

CSS formating is done according to the following workflow:

ELEMENT {1. CSS-FORMATTING; 2. CSS-FORMATTING; ...}

The (HTML) elements can be referenced by different attributes:

(1) .NAME{...} by the HTML class-attribut

(2) NAME{...} by the HTML name-attribut

(3) #NAME{...} by the HTML id-attribut

CSS allows different types of selection. The most important among them are briefly presentedhere:

.SEL1, .SEL2 {...} all elements with class SEL1 and all elements with class

SEL2

.SEL1.SEL2 {...} all elements which have class SEL1 and SEL2 at the same

time

.SEL1 .SEL2 {...} all elements SEL2, which are child of an element with SEL1

Several practical examples of CSS formatting are provided in section 15.3.3.

15.3.1 CSS Classnames

Figure 15.7 illustrates with which CSS class names the displayed elements are addressed of aSingleQ. MultiQ behaves identically. Analogously, figure 15.9 illustrates a SingleGridQ. Again,the MultiGridQ behaves the same.



Figure 15.7: CSS Classes for SingleQ and MultiQ

Figure 15.8: CSS Classes for GNumQ



Figure 15.9: CSS Classes for SingleGridQ and MultiGridQ

Every single question contained in the screen gets, in screen definitions, an own CSS selector inthe format qscreencell-x-y. »x-y« means the positioning of the question in the coordinatesystem of the screen. With qscreencell-1-2 can be selected the second question of the firs line.All the lines in the screen can be selected with the selector qscreencell.

Question texts and error messages are different from the other elements. Currently, thesecan be formatted only globally for the entire questionnaire. All other elements are located ina defined area (HTML <div>). These can be designed freely and independently from questionto question with its help. Details for the options are found in section 15.3.2.

In addition to the CSS class names contained in the graphics, there are a few other elementsthat can be formatted:

// Alternating, line by line highlighting

.qrowclass1{...}

.qrowclass2{...}

...

.qrowclassN{...}

// Incorrect (forgotten when filling out) grid cells

.qgriderrorcell{...}

// Highlighting when hovering the mouse

.qhighlight{...}

// Right item text cell in bipolar grids

.qrightitemtextcell{...}

// Spacing row in SingleQ/MultiQ with use of maxLabelsPerCol or splitcolumn

.qcolseparator{...}

Depending on the GESS Q. HTML parameter cssLayout the contents of a question are separatedin lines by .qrowclass.



cssLayout sets the name of a layout section and defines the number of the different highlightedlines. Both parameters must be set.Default: "",2

Example

--------

HTML{ cssLayout = "LayoutA",2; };

// for here the layout section s called "LayoutA" (until the name is changed

again)

// Questions contain alternating lines with the Classes .qrowclass1 and .

qrowclass2

The formatting of .qhighlight should be made in the last possible moment. Thus, it overwritesall previous, in case there were different inputs. For example, if .qrowclass calls for a light graybackground and .qhighlight defines a light green background, the browser chooses the newestentry (last standing in the source code).

15.3.2 Formatting of Individual Questions, Areas and Types of Questions

In addition to global definitions layout can also be defined at more refined levels. The followingformats are possible:

• Formatting of individual questions

• Formatting of sections

• Formatting of all questions of a particular type

The implementation is made over the QNAME, CSSLAYOUT and QTYPE, representativespecified in figure 15.7 and figure 15.9.

QNAME name of a question

CSSLAYOUT name of a layout area (see parameter cssLayout)

QTYPE question type {.singleq, .multiq, .singlegridq, .multigridq}

15.3.3 Examples

The following examples from the template of a survey illustrate the practical application of theformatting options that are described previously.

// Integration of a defined basic layout

<link type="text/css" href="./css/default_gess.css" rel="stylesheet"/>

// survey specific CSS formatting

// override any possibly existing details from the basic layout


// Fehlertexte (global)

.qerror{

color : white; // white text color

background-color: #990000; // background dark red

font-weight : bold; // bold font

}



// Table for the Title (global)

.qtable{

margin-top : 25px; // Margin above (for the title)

}

// label texts AND label codes (global)

.qlabeltextcell, qvlabelcell{

font-style : italic; // (1) italic font

padding-left : 20px; // left padding to the table cell

}

// label text (especially for question q1)

.q1 .qlabeltextcell{

font-style : normal; // normal font, overrides (1)

}

// Title (especially for layout area ABC)

.ABC .qtitle{

text-decoration : underline; // underlined text

}

// Highlighting (especially for MultiQs)

.multiq .qhighlight{

background-color: yellow; // (2) yellow background

}

// Highlight (especially for MultiQs in layout area ABC)

.multiq.ABC .qhighlight{

background-color: #dddddd; // light gray background, overrides (2)

}

</style>

15.3.4 Adding CSS to the Question

In addition to

• the applying of a CSS file

• the style statements in the template

• inserting style instructions in the survey with htmlPostText

there is a dedicated text area with css, which is inserted behind the question text. Css behavessimilar to htmlPostText but has a distinctive advantage: The CSS information is not exportedto the language files for translation.

css=".element{ property: defining; }";

Here, the question text appears in red:

openq start;

text="Which newspaper do you read?";

css=".qtext{ color: red; }";



15.3.5 CSS, the not Recommended Version

The variety of elements that GESS Q. provides, in order to give possibilities for the design -from PreHelpText over htmlPostText to css="..."; , have one primary objective: Questiontexts and answer options must be reached from the script, over the reporting and to the tables,without the necessity of reworking.

Texts and labels can also be given special formats, if the options are still not sufficient. For thatown classes can be provided in template.html:

.smallcaps

{

font-variant: small-caps;

}

.red

{

color: red;

}

.large

{

font-size: 150%;

}

The definitions in template.html can then be used as desired in the questions of the script:

singleq f0;

text="What question do you ask most frequently?"<div class=\"smallcaps\">

Small_caps </div>";

title="

<div class=\"red\">red </div>

";

labels=

1 "A"

2 "B <span class=\"large\">big </span>"

3 "C"

;

Whether the result makes sense is another matter, but "small caps" appear in small uppercaseletters, the title in red and the browser shows "big" 50% larger than the "B" next to it.

Such constructions normally don’t make it through the translation without errors, which arelikely to stay through to the creating tables - thus, ensure extra effort.

15.3.6 Responsive Design

Since around 2010 user access web pages increasingly on mobile devices, the desktop computer,which had previously been regarded as a measure of web development, slips in the second placeand it means: »mobile first«. The answers to the arising problems are summed under the heading»responsive design«: The web pages must be able to adapt to the respective screen. That’s thetheory, but the practice has proven to be obstinate.

CSS media queries must help to distinguish the devices under different criteria. The query mayfirst address a specific media type (all, screen, print, etc.) and then limit the CSS statements



using the detail, determined with the query. 3:

@media all and (property: value) { css selector { property: value;} }

When using the responsive design, it is recommended not to use fixed sizes. The first two linesare banned, if it is not clear what the size of the screen is:

width: 1024px;

font-size: 12px;

// instead:

max-width: 1024px;

font-size: 75%;

A browser can customize the display for the screen by specifying a maximum width. On theother hand, the fixed width will force the display out of a narrow screen of e.g. 800 pixel. Thefont size should be rather defined as a relation, since computer screens on the desk spread theirHD resolution at 20 inches and above, while phones accommodate the 1920x1080 pixels possiblyin 5 inches. (Desktop browsers usually set a 16 pixel wide font equal to 100%, so here is theconversion of 12 pixels to 75%.)

Typically certain representations are no longer meaningful below a certain pixel width, like forexample, a layout with two rows (the survey in the center, any explanations on the edge). Thiscan be intercepted with media queries.

@media all and (max-width: 800px) {

.rand{ display: block; }

}

Up to width of 800 pixels a member of the class ».rand« would be represented as a block elementand would therefore appear not next to the survey, but above or below, depending on thearrangement of the break, attached to the related block element.

A uniform presentation can be achieved with the zoom factors, taking into account the resolutionif it is known which displays will play a role in a survey (for example, the tablets in a Car Clinic),

@media only screen and (max-width: 1024px){ .maintab{ zoom: 80%; } }

@media only screen and (min-width: 1920px){ .maintab{ zoom: 150%; } }

By screens with a width up to 1024 pixels the display is reduced to 80%, by screens with a widthof 1920 pixels and more, the display is increased to 150%. The representation remains at 100%on the standard widths in between (1280, 1366, 1600), because nothing else has been specified.Zoom factors are not wisest choice, but it can save you work.

15.4 Self-built Screens

If a layout of a question or multiple questions combined can not be implemented within thegiven framework of GESS Q. question types, it is possible to create screens manually withHTML code. The generation of code for questions is suppressed by GESS Q. with the parameterinput = no; . The question definitions are imperative in any case, in order to be applied as a

variable in GESS Q.

3The list of types and properties are currently being coordinated in the standard W3C: http://www.w3.org/TR/css3-mediaqueries/#media1



HTML{ input = no; };

SingleQ sq;

labels=

1 'Answer A'

2 'Answer B'

3 'Answer C' single

;

HTML{ input = yes; };

Only the HTML representation of the eleventh input fields and texts must be addressed at thispoint. In order to use also randomizations and filters in the manually created screens, please referto section 7.2.2. A simple reproduction of the SingleQ sq with label code would look like this:

screen myscreen = column( sq );

text="

<div class='qtext'>selfmade Single Q Question</div>

<div class='qtitle'>Single Q Title</div>

<table class='qtable'>

<tr>

<td name='id_sq1' class='qvlabelcell'> (1) </td>

<td name='id_sq1' class='sq qbuttoncell'> <img id='id_sq_bi1'> </td>

<td name='id_sq1' class='qlabeltextcell'> Answer A </td>

</tr>

<tr>



<td name='id_sq2' class='qlabeltextcell'> Answer B </td>

</tr>

<tr>



<td name='id_sq3' class='qlabeltextcell'> Answer C </td>

</tr>

</table>

";

The statements for names, IDs and CSS Classes are imperative to ensure the correctfunctionality of the mouse behavior, highlightings and the design via CSS (refer to section 15.3).Name and ID are written as follows:

----- SingleQ and MultiQ -----

name : id_<QNAME>_<LABELCODE>

id (Button): id_<QNAME>_bi<LABELCODE>

--------- Grid Question ---------

name : drops off

id (Button): <QNAME>_bid<ITEMCODE>_<LABELGROUP>_<LABELCODE>

The highlighting in GESS Q. is done via the CSS class qhighlight. GESS Q. highlights alltable cells with the same name and adds a click / selection behavior. Single attributes in Multiquestions are taken into account automatically. If all the cells must be highlighted, but not all ofthem must become a click behavior, the CSS class checkable can also be selectively added.

...



// In this example, although the cell with the label code (2) is highlighted

// it is not provided with a mouse click functionality.

<tr>


<td name='id_sq2' class='checkable sq qbuttoncell'> <img id='id_sq_bi2'></td>

<td name='id_sq2' class='checkable qlabeltextcell'> Answer B </td>

</tr>

...

15.5 Graphical Navigation Buttons

The navigation buttons of an interview can also be designed freely, in addition to graphicalbuttons for answer labels, refer to figure 15.10.

• Next Button

• Back Button

• Cancel Button

Figure 15.10: Graphical Navigation Buttons

The JavaScript library gesstmpl.js must be integrated in the template in order use these. Referto section 15.1.5. Image files, used for the buttons, can be saved in the media path to thequestionnaire. Furthermore, two steps are necessary:

1. Extension of the template by <input> Fields and JavaScript

2. Selecting the navigation buttons on the GESS Q. Script side.

Image variables must be created for the buttons and initialized with the image files in JavaScriptsection of the template. The variable names in the following example must be strictly followed,while the name and format of the image files BUTTON.gif, MOUSEOVER.gif and INACTIVE.gifare freely selectable. Meaning of the abbreviations:

• cb: ContinueButton

• bb: BackButton

• cc: CancelButton

In addition, a supplement is required in the <body> field directly after @form - an <input>field per button.

<script type="text/javascript" src="./javascript/gesstmpl.js"></script>

@dummy

@header

<script type="text/javascript">

// graphical Next Button

var cbId = "img1";

cbImg = new Image(); cbImg.src = "./MEDIAPATH/BUTTON.gif";

cbOmoImg = new Image(); cbOmoImg.src = "./MEDIAPATH/MOUSEOVER.gif";

cbIaImg = new Image(); cbIaImg.src = "./MEDIAPATH/INACTIVE.gif";

// graphical Back Button



var bbId = "img2";

bbImg = new Image(); bbImg.src = "./MEDIAPATH/BUTTON.gif";

bbOmoImg = new Image(); bbOmoImg.src = "./MEDIAPATH/MOUSEOVER.gif";

bbIaImg = new Image(); bbIaImg.src = "./MEDIAPATH/INACTIVE.gif";

// // graphical Cancel Button (commented out for the example)

// var ccId = "img3";

// ccImg = new Image(); ccImg.src = "./MEDIAPATH/BUTTON.gif";

// ccOmoImg = new Image(); ccOmoImg.src = "./MEDIAPATH/MOUSEOVER.gif";

// ccIaImg = new Image(); ccIaImg.src = "./MEDIAPATH/INACTIVE.gif";

@dummy

@javascript

</script>

...

<body>

@dummy

@form

<div>

<input type="hidden" name="qcontinue" id="qcontinue" value="">

<input type="hidden" name="qback" id="qback" value="">

<input type="hidden" name="qcancel" id="qcancel" value="">

</div>

...

Now, the sources for the buttons at the GESS Q. side must also be specified. For this purposethere are the HTML parameter continueButtonSrc, backButtonSrc and cancelButtonSrc.

continueButtonSrc inserts an alternative (to the standard) HTML code-snippet, which replacesthe template placeholder @continue.Default:

backButtonSrc inserts a alternative (to the standard) HTML code-snippet, which replaces thetemplate placeholder @back.Default:

cancelButtonSrc inserts an alternative (to the standard) HTML code snippet, which replacesthe template placeholder @cancel.Default:

HTML{

continueButtonSrc="

<img id='img1'

src='./MEDIAPATH/CONTBUTTON.gif'

onclick='qcontinue_submit()'

onmouseover='mouseOverImage()'

onmouseout='mouseOutImage()'

style='cursor:pointer;'

/>

";



backButtonSrc="

<img id='img2'

src='./MEDIAPATH/BACKBUTTON.gif'

onclick='qback_submit()'

onmouseover='mouseOverBBImage()'

onmouseout='mouseOutBBImage()'

style='cursor:pointer;'

/>

";

// cancelButtonSrc="...";

};

15.6 Making of Custom Templates

To make own templates, which can later be selected from the Survey Manager , a few rules mustbe followed (refer to section 25.8). In the configuration file qonline.cfg in the folder config

the variable modelPath defines where GESS Q. should look for templates for a study. By default,the value is set to models and refers to a subdirectory in the config folder, so that path defaultis config/models.

The name of the directory in config/models/ serves, at the same time, as a name for theselection, that GESS Q. offers in the Survey Manager . With the name mytemplate the folder

structure must have two folders within config/models/mytemplate/ : media and mytemplate.The folder media, in turn, contains a folder mytemplate:

config/models/mytemplate

/media/mytemplate (1)

/mytemplate (2)

The folder mytemplate within media (1) has the graphical components of the template.Buttons, progress bars, logos, etc. can be stored here, as far that should be determined inadvance. These can be integrated via template.html. The folder mytemplate contains theframe of the study folder and can provide preconfigured files such as:

access.lst,active.cfg,idproperties.cfg,surveyconfig.cfg,title.txt

and already offers a base in a text folder with the files:finished.msg,formats.q,gbuttons.q,skript.q,summary.cfg,surveystats.cfg,template.html,template_error.html.


Chapter 16. Keyboard Input

16 Keyboard Input

16.1 Keyboard Input

With a few script commands also the numeric keypad can be used for data input in GESS Q.This feature is based on the functionality of the graphical buttons and enables easy and veryfast data acquisition of paper-based questionnaires over the Internet. The data is stored on theonline server of the survey.

Keyboard Layout - GENERAL

- send formular : ENTER

- move the focus forward : down arrow (adjustable)

- input symbols : all other available buttons

Keyboard Layout - ONLY SINGLE(GRID)Q and MULTI(GRID)Q

- input symbols : 0-9

- delete entry : left arrow (adjustable)

- evaluate input : right arrow (adjustable)

16.2 Function Description

The keyboard input in each GESS Q. online survey can be activated with a few lines in thescript. Please refer to section 16.4. The keyboard input is then automatically switched on inthe interview for all supported types of questions. These are available for the following types ofquestions (and their combinations in screens):

• TextQ, OpenQ, PasswdQ, NumQ

• SingleQ and SingleGridQ (only graphical variations)

• MultiQ and MultiGridQ (only graphical variations)

In order to use these, the following conditions must be met:

• Integration of GESS JavaScript Library gesstmpl.js in the template (please refer tosection 15.1.5)

• Integration of the 3 control fields ki_mode, ki_input and ki_check in the template.

The following is a short description of how the keyboard input works to each question type. Thequestion currently standing in focus is framed in red. Completed screens can always be confirmedwith the key Submit Form (ENTER KEY).

TextQ No input options

OpenQ The cursor is automatically placed in the entry field and waits for input.

PasswdQ refer to OpenQ

NumQ The cursor is automatically placed in the entry field of the first label and waits for numericalinput. To the next label leads the button move the focus forward. The entry field which iscurrently in focus is outlined in red.

SingleQ The cursor position doesn’t matter here. A numerical input is expected in order toselect labels. Open fields must be focused manually at first.



SingleGridQ The first row of the grid is automatically focused and outlined in red. The inputfor the line behaves like as by the SingleQ. The key move the focus forward leads to thenext grid line.

MultiQ refer to SingleQ.

MultiGridQ analog to SingleGridQ.

16.3 The control fields ki_mode, ki_input and ki_check

The control fields are HTML inputs which must be defined and positioned in the templatewhich must be defined and positioned in the template. These inform the user which inputs arecurrently expected, what is the current input and which is the input that has been processedlast. Please refer to figure 16.1.

Figure 16.1: Control Fields of the Keyboard Input

mode provides information on the expected input. TEXT stands for a text input(OpenQ, PasswdQ), NUM - for a numerical input (NumQ), X-digits expects the input of a labelcode with fixed number of digits (Single(Grid)Q and Multi(Grid)Q) and AUTO also expectsthe entry of a label code, in which the input is automatically completed, when a label code canbe clearly assigned.

input displays the current input. Since the inputs for the OpenQ, PasswdQ and NumQ are visibleanyway, this control field is used only for question types Single(Grid)Q and Multi(Grid)Q.

check displays the last processed entry. Since the inputs for the OpenQ, PasswdQ and NumQ arevisible anyway, this control filed is used only for the types of questions Single(Grid)Q andMulti(Grid)Q. Entries are highlighted differently depending on whether these are valid or not.

Exemplary HTML tags for the control fields Layout and text formatting have beenremoved for clarity.

<input id="ki_mode" type="text" size="8" readonly>

<input id="ki_input" type="text" size="6" readonly>

<input id="ki_check" type="text" size="6" readonly>

16.4 Adjustable Parameters

All settings for the keyboard input are made using the setProperty() mechanism. Please refertto section 15.2.2. The parameters begin with the acronym ki_:

ki_active enables / disables the keyboard input (must be indicated before the other properties).Options: yes | no

Default: no

ki_autoFocus If activated, when answering SingleQs or lines in SingleGridQs, the next questionin the screen respectively the next line in the grid is focused automatically (if available). Otherwise,



this must be performed manually with the key move the focus forward.Options: yes | no

Default: no

ki_autoCheck If activated, the input will be evaluated by the Single(Grid)Qs and Multi(Grid

)Qs, as long as the expected number of digits (control field ki_mode) is entered. Otherwise, thismust be done manually with the key evaluate inputOptions: yes | no

Default: no

ki_autoComplete If activated, the input will be checked by the Single(Grid)Qs andMulti(Grid)Qs, whether the input can be uniquely associated with a response label and possiblyextended automatically. For example, there are the answer labels 1 and 10 and the 1 should bemarked. This must be confirmed with the key evaluate input.

If activated, the answer label must always be entered with a fixed number of digits. The numberof digits depends on the largest label and is displayed in the control panel ki_mode.Options: yes | no

Default: no


Chapter 17. SliderQ: Slider Bar

17 SliderQ: Slider Bar

17.1 General

Figure 17.1: Slider Bar

A slider control bar respectively slider helps to playful specify and visualize the values in a certainranges of values. In figure 17.1 different functionalities are illustrated:

• Design of the regulator

• Design of the bars

• Display of the selected values

• Display of the sum of all values

• Remaining points for distribution

Further, the slider bar supports the mandatory entry over the script parameter defaultnomissing

and they provide an abstention mechanism via OpenNumFormat.

17.2 Requirements to the Usage

In order to use a slider bar, the GESS JavaScript library gesstmpl.js must be included in thetemplate, please refer to section 15.1.5. In addition, the library must be stored with the usedimages in the media path of the associated survey (./media/<Survey name>/)

17.3 GESS Q. Script

The slider bars are an alternative to NumQ and can replace it by the following script statement:

HTML{ numQClass = SliderQ; };

By this adjustment GESS Q. uses a slider bar with a preset appearance, instead of simple entryfields. The available range is defined analogously to the NumQ OpenNumFormat.

Excursus:

missingValue=999;

OpenNumFormat f1 = 1 2 0 1 0.0 10.0 997 "Invalid input!";

// | | | | error message

// | | | 997 value for abstention/nA (optional)

// | | 0.0-10.0 value range

// | 0-1 digits (after comma)

// 1-2 digits (before comma)



NumQ points;

Text="Please rate brand A (0-bad, 10-very good).";

labels=

1 "Mark A" format f1

;

If the OpenNumFormat contains the optional value for an abstention/nA (noAnswer) automat-ically appears a button for abstention. The corresponding labeling is done via the globallydefinable text constant noAnswerText. As with any OpenNumFormat the label code for abstention(and also for _missingValue) must be situated outside the permitted value range, otherwisethere will be an overlap in the code definitions.


All adjustments of the slider bars are made using the setProperty() mechanism (refer tosection 15.2.2). The parameters begin with the abbreviation sl_ and can be divided into 2categories:

• graphical parameters

• functional parameters

The graphic for the controller itself is an exception. Instead of the outdated parameters sl_image

it is possible to attach the graphics to each label.

labels=

1 "@slider(grafik.png) Text"

;

17.4.1 Graphical parameter

With the graphical parameters the rulers and the bars can be freely optically designed. Theycan be simply provided with colors from the RGB palette, but also with as graphics. Thecorresponding images are freely configurable in any Web formats. It must be noted that laterthey will be presented in their original size in the survey.

The usage of width adjusments, height adjustments and color adjustments is classified as»outdated« and in the medium-term will be no longer supported. The use of images for the barand the controller is explicitly recommended. In such a case, the image sizes are determinedautomatically.

sl_barWidth Width of the bar. Specified as an integer value in pixels. Applicable to all standardsliders within a question (without the use of sl_barImage).Default: 200

sl_barHeight Height of the bar. Specified as sl_barWidth

Default: 15

sl_barColor Color of the (entire) bar. Specified in HEX (6 digits) or transparent.Default: transparent

sl_barColorLeft Color of the left part of the bar from the regulating element position. Theyare specified by sl_barColor and are higher prioritised. The both entries are necessary for thedifferent colors left and right of the control elements. In case the images for the bar are also



defined, then they will be preferred over the color adjustment.Default: transparent

sl_barImage Graphics for the (entire) bar. They will be displayed centered and in original size.The file name of a graphics including the ending must be specified.Default:

sl_barImageLeft Graphics for the left part of the bar from the regulating element position.They are indicated as sl_barImage and are higher priorised. This means that thay are displayedas sl_barImage and must also have the same size.Default:

sl_imageWidth Width of the regulating element. Specified as an integer value in pixels. Ifthere are multiple slider bars, these can be individually designed with individual slide controls.Multiple widths can be specified, separated by spaces. If there are more sliders than specifiedwidths, the last specified will be used further.Default: 15

sl_imageHeight Height of the regulating elements. Specified as sl_imageWidth.Default: 25

sl_color Color of the regulating element. Specified in HEX (6 digits) or transparent. Ifthere are multiple slider bars, these can be individually designed with individual slide controls.Multiple colors can be specified, separated by spaces. If there are more sliders than specifiedwidths, the last specified will be used further.Default: e6e6e6

sl_image outdated Instead of sl_image the label can get the graphic via @slider(grafik.png) .The mechanism is more robust especially when labels must be filtered or randomized.[Otherwise, it applies: Graphic of the control element. It is displayed centered on the bar andin its original size. The file name of a graphics incl. the ending must be specified. If there aremultiple bars, the regulating elements can be individually provided with graphics via severalslide controls, by making multiple space-separated entries. If there are more sliders than specifiedgraphics, in each case the last specified image file will be used further.]

17.4.2 Functional Parameters

With the functional parameters can be configured as follows: start values, increments, displayfields, redistributable points, behavior modes, input abstention and abstention options:

Fields for total sum and rest It may be useful with the multiple sliders to display the totalsum of all set values and/or the number of points, left to be distributed. Corresponding fieldscan be placed anywhere in the title of the question. By the keyword @slider_sum is placed afield for the sum and with @slider_rest(<VALUE>) a field for the points left to be distributed,where <VALUE> represents the sum of all the redistributable points.

sl_startValues Start values of the slider bar. Specified as an integer value within the valuerange. By the multiple slider bars within a question, the start values can be written separated byspaces in a succession. The minimum value from the OpenNumFormat is used in case of missingor incorrect information.Default: Minimum value from OpenNumFormat

sl_stepSize Increments of the slider bar. Specified as an integer within the value range. Bythe multiple slider bars within a question, the start values can be written separated by spaces ina succession. In case of missing or incorrect information, the smallest possible increment is used



according to the number of decimal places from the OpenNumFormat.Default: The smallest possible increment

sl_visibility Initial visibility of the regulating elements. Indicates one or more through thespace-separated values from the options. In case of missing or incorrect information is used thedefault value.Options: hidden | visible

Default: visible

sl_showValues Display of the adjusted values next to the slider bar. On the right and left sidescan appear a display with the set value. The setting yes is identical to right. The optionslider displays the set value on the respective control element itself.Options: yes | no | left | right | both | slider

Default: no

sl_maxSum sets a maximum adjustable total sum. Identical to the parameter in @slider_rest(

XX). If both entries are made, the specified value in @slider_rest(XX) has the higher priority.Default: ∞

sl_mode sets whether and how multiple slider bars behave and influence each other. It is onlyuseful if the maximum totals of the slider bars are defined with @slider_rest(XX) or sl_maxSum.Option block prevents the exceeding of the maximum sum, without affecting other slider bars.The option modify contrariwise turns back the other controller automatically in equal proportions,when exceeding the maximum sum.Options: block | modify | none

Default: none

Abstention: sl_unspecified_button_checked specifies the file name of a graphic incl. endingfor a marked abstention-button. To use different buttons within a question, multiple space-separated file names can be specified. The integration is carried out in accordance with thewritten label sequence in the GESS Q. Script. If there are more labels than specified graphics,the last file will be used.Default: button_checked.gif

Abstention: sl_unspecified_button_unchecked specifies the file name of a graphic incl. end-ing for a marked abstention-button. The use of different buttons within a question correspondsto sl_unspecified_button_checked.Default: button_unchecked.gif

17.5 Example code

Code for this example in figure 17.1:

HTML{ numQClass=SliderQ; };

missingValue=999;

OpenNumFormat f1 = 1 2 0 1 0.0 10.0 "Enter number between 0 and 10";

HTML{

//outdated (s.o.): setProperty("sl_image" "gess.gif"); // regulating

element

setProperty("sl_barImage" "gtor.png"); // bar

setProperty("sl_showValues" "yes"); // display of values

setProperty("sl_startValues" " 4 5 6 "); // startup values

setProperty("sl_mode" "block"); // mode: block



};

NumQ sl6;

Text="Please divide 20 points on these brands.";

Title="

Previously assigned points: @slider_sum<br>

Other points: @slider_rest(20)

";

labels=

1 "@slider(gess.gif) brand A" format f1

2 "@slider(gess.jpg) brand B" format f1

3 "@slider(gess.png) brand C" format f1

;

assert sl6.1 + sl6.2 + sl6.3 eq 20 "Sum must arise 20!";

17.6 Graphical Formatting and Layout

The slider bars fit seamlessly into the formatting concept of graphical buttons. Your layout cantherefore be customized via CSS. The basic procedure is described in detail and exemplified inimage section 15.3. The necessary CSS classes are shown in image figure 17.2.

Figure 17.2: CSS Classes SliderQ

Optionally, the already moving slider bar can distinguish from those in the initial state. For thispurpose is used the CSS classes .qslidermoved, e.g .:

.qslidermoved{ background:url(/media/@insert(_surveyname)/img.png) no-repeat

50% 50%; }


Chapter 18. QSortable: The NumQ as Drag & Drop List

18 QSortable: The NumQ as Drag & Drop List

As QSortable we denote the optical redesigning of one or more NumQs in lists with Drag & Dropfunction, which can be used for building of ranking or the simple sorting into different categories.

Figure 18.1: Example: NumQs as QSortable

18.1 Script Syntax

The concept is, that the NumQ(s) are placed in one screen along with empty HTML list definitions<ul> (= unsorted list). A JavaScript-call hides the NumQs and fills the lists, that are still emptywith its labels as movable items. So the placement of the HTML lists determinates at whichlocations on the page the lists will be later represented. The HTML syntax of such a list canlook like as follows and is explained below:

<ul type='TARGET|SOURCE' numq='NUMQ' maxitems=NUMBER></ul>

18.1.1 HTML Lists Attributes

type specifies what kind of list it is, valid values are SOURCE and TARGET.

SOURCE means that it is a source list. For each label which was defined in the linked NumQ, iscreated an element in the list. This element corresponds to the content of the label text (text,images, videos, etc.).

TARGET refers to the target list. The items brought in this list are placed in the list in one of 1 inascending order via drag and drop. These place numbers are stored in the linked NumQ.

numq Here is defined the NumQ with which the list is to be linked. A NumQ can be linked at thesame time to both, a source list and a destination list. Usually, it makes no sense to makemultiple links as destination list, because only the position of the item is saved, but not if, forexample, position 1 was in the I-like-it-list or in the I-do-not-like-it-list.



maxitems specifies how many items can be stored in a list. The value 0 defines an unlimitednumber.

This definitions show the following: The NumQs from source lists must always be created withoutmandatory entry, while the mandatory input by the NumQ of a target list defines how manyitems must be sorted. Functionally the items can be stored per Drag & Drop only in all target

lists and their original source lists. When moving an item a placeholder indicates, if it can bedropped.

Minimal example for the use of the QSortable:

opennumformat rank1_5 = 1 1 0 0 0 5 "Please arrange the 5 items in a sequence

.";

numq myNumQ;

text="Which item do you like best?";

title="

Items

<div><ul type='source' numq='myNumQ' maxitems='0'></ul></div>

Ranking

<div><ul type='target' numq='myNumQ' maxitems='0'></ul></div>

";

labels=

1 "Item A" format rank1_5

2 "Item B" format rank1_5

3 "Item C" format rank1_5

4 "Item D" format rank1_5

5 "Item E" format rank1_5

;

// assert (num(myNumQ) eq 3) "Exactly three items must be sorted.";

javascript="qSortable.numQ2Sortable();";

The above example utilizes a NumQ simultaneously as a source list and as a target list, whichare represented one below the other. There is no apparent information on the input obligation.Depending on the setting in defaultnomissing thus either all items should be sorted or not.The commented out assert would only make sense under lifting of the general input obligation.It will cause that exactly 3 items must be transferred to the target list. If the input obligation isactive, we would have two contradictory requirements, which can not be fulfilled together. Theinterviewee would reach a dead end. When assert is used alone, maxitems='3' would also beuseful on the target list, so that the interviewee is already supported filling out the question.



Depending on the frame layout, the presentation of this example could look as follows:

Figure 18.2: QSortable Minimal Example

18.2 Settings

Currently, an error text qSortable.errorMsg is available for the QSortable. It appears bythe attempt to fill target lists with more items than it was intended and ways to modify theappearance via CSS. The error text can be changed directly before calling the JavaScript function:

javascript="

qSortable.errorMsg = 'You can place up to 3 items in the target area.';

qSortable.targetOnly = true;

qSortable.numQ2Sortable();

";

With the parameter qSortable.targetOnly can be determined, whether the items of a sourcelist may be sorted in a different source list or only in the target list (default: only in thedestination list).

For multilingual studies is important to ensure that JavaScript sections are not considered in thetranslation. To refer the error text from a source, the @insert() can be used here.

The layout of the QSortable can be customized with CSS. Over the following CSS classes thecomponents of the display can be selected:



Figure 18.3: QSortable CSS Layout

Some examples for clarification:

css="

.connectedSortable { width:400px } /* list width 400 Pixel */

.connectedSortable li { width:380px } /* item width 380 Pixel */

.connectedSortable[type=target]{ } /* relates only to target

lists */

/* Sortable to NumQ f1 without place numbers */

.connectedSortable[numq=f1] .ui-sort-placeholder{ display:none; }

";


Chapter 19. PackagingQ: Packaging Configurator

19 PackagingQ: Packaging Configurator

19.1 General

Figure 19.1: Packaging Configurator

With the packaging configurator respectively the PackgingQ the respondents are able to assemble,consider and choose the layouts (e.g. of packaging) in any way with various picture elements.Figure 19.1 illustrates an exemplary application. In the following description are explained thefunctionality and possibilities for representation. Here frequently is spoken of groups. A group

is always a certain number of identical picture elements from which exactly one can be selected.The exemplary image shows 4 groups: the general appearance of the package, colored lettering»NEW«, white lettering »bittersweet« and the bio seal.

19.2 Requirements for the Usage

To use the PackagingQ, the GESS Javascript library gesstmpl.js must be included in thetemplate, please refer to section 15.1.5. This is essential for the fading effects. In addition, allthe images must be saved in the respective survey media path (./media/<Survey Name>/). Allimages must have the same size and must have a transparent backgrounds, independently fromthe bottom image plane. For example, there is transparency in the image formats .png and .gif.

19.3 PackagingQ

The PackagingQ is an alternative to MultiQ and can be used instead it with the following scriptstatement:

HTML{ multiQClass = PackagingQ; };

The functionalities described in this section are demonstrated in the final sample code for betterunderstanding.




All adjustments of the PackagingQ are made with the help of the setProperty() mechanism,please refer to section 15.2.2. The parameters start with the prefix pg_ and can be subdividedinto three categories:

• Image area / Corpus

• Grouping adjustments

• Visibility menu (optional)

19.4.1 Image area / Corpus

With the following parameters can be adjusted for the central display area: width, height,background and distances.

pg_width Width of the image area. Specified as an integer value in pixels.Default: 300

pg_height Height of the image area. Specified as an integer value in pixel.Default: 300

pg_corpus Background picture / Base corpus. Optionally specified as a file name with extension.Default:

pg_corpus_padding Distance between the image area and the surrounding groups. Specified asan integer value in pixels.Default: 10

19.4.2 Grouping options

The following parameters can be adjusted: in which groups, where and whether the labels mustbe displayed around the central display area.

pg_grouping summarizes the labels of the question in groups. Let’s assume that there are ninelabel and the indication »6 3«. Now the first six labels are defined independently of the labelcodes as group 1 and the last three specified labels are defined as a group 2. If there are excesslabels, those are applied automatically in a new, final group with default settings (left andvisible).Options: Space-separated, integer valuesDefault: One group of all labels and default settings

pq_orientations Orientation of the groups. Space-separated combinations of the options haveto be entered. The first entry refers to the first group, the second entry to the second group andso on. If there are more groups than details left is used as default.Options: top | bottom | left | right

Default: left for all groups

pg_fading sets the fading effects on / off.Options: Integer value for the fade time in msDefault: 0

pg_visibility set the visibility of the groups on / off. Space-separated combinations of theoptions have to be entered. The first indication refers to the first group, the second indication tothe second group and so on. For excess groups is used indication visible.



Options: visible | hidden

Default: visible for all groups

19.4.3 Adjustments of the visibility menu

The menu visibility is displayed optionally. If it is enabled, a check box for each group appears,by which the corresponding group is faded in and all other groups are faded out.

pg_visibility_menu set the visibility menu on / off.Options: yes | no

Default: no

pg_visibility_orientation Positioning of the visibility menus.Options: top | bottom | left | right

Default: top

pg_group_names Texts in the clickable fields of the visibility menus. For each group have to beentered terms that are space-separated. If there are more groups than terms the »Group <x>«is used as default, where x represents the group number.Default: Group1 Group2 ...

19.4.4 Correspondence label - Graphic

In order to define the connection of the labels in the appropriate fields, the label text of thekeyword @target(<NAME>) is available, where NAME is the filename of the image with a fileextension, stored in the media path. Now, with a click on the label shows the target image(independently of the content). Otherwise, it is possible to be edited in the label text withor without HTML. So, for example, a small graphic preview can also be integrated without aproblem.

19.4.5 Randomization and filter

All kind of filters and randomizations can be attached on the label. The only distinctive featureis that the randomization refers only to the labels inside the groups. Thus it is not mixed acrossthe groups.

19.4.6 Optical design with CSS

There are 3 different locations with CSS-classes 1, within the PackagingQ, which can be used tocreate any optical configurations:

• (1) for the individual groups

• (2) for the individual orientations

• (3) for the visibility menu

The names of the classes are formed as follows:

• (1) <QUESTION>_labels_group_<X> with QUESTION as a question name and X as agroup numbering (counting from 1)

1Information to the CSS-classes: http://de.selfhtml.org/css/


http://de.selfhtml.org/css/


• (2) <QUESTION>_<OR>_groups with QUESTION as a question name OR as an orientationleft, right, top or bottom.

• (3) <QUESTION>_menu and <QUESTION>_menu_item with QUESTION as a question name.

The CSS-designs can be written either in template or with text replacement turned offenableTextReplace=no; ; also directly in the text or in the title area of the correspondingquestion. The above-mentioned is exemplified in the following example code.

19.5 Example Code

Code for the example in figure 19.1. The media path has been abbreviated of space reasons.

HTML{

setProperty("pg_grouping" "3 4 3 3");

setProperty("pg_orientations" "left top right bottom");

// setProperty("pg_visibility" "visible hidden hidden hidden");

setProperty("pg_corpus" "corpus0.png");

setProperty("pg_corpus_padding" "25");

setProperty("pg_width" "500");

setProperty("pg_height" "399");

setProperty("pg_fading" "500");

// setProperty("pg_group_names" "Packaging edelbitter NEW logo");

// setProperty("pg_visibility_menu" "yes");

// setProperty("pg_visibility_menu_orientation" "top");

};

enableTextReplace=no;

multiq m1;

text="

Please use the Packaging Q.

<style type='text/css'>

.m1_labels_group_1, .m1_labels_group_2, .m1_labels_group_3,

.m1_labels_group_4, .m1_menu_item{

margin:1px; border:1px solid #000000; background:#888888;

}

.m1_menu_item{

float:left;

width:100px; padding:5px; background:#eeeeee;

}

.m1_menu{

display:inline-block;

}

// .m1_left_groups{vertical-align:top;}

// .m1_right_groups{vertical-align:bottom;}

</style>

";

labels=

51 "@target(corp.png) <img width='125px' src='./(...)/corp.png'>" random

52 "@target(corp1.png) <img width='125px' src='./(...)/corp1.png'>" random

53 "@target(corp2.png) <img width='125px' src='./(...)/corp2.png'>" random

1 "@target(text1.png) <img width='125px' src='./(...)/text1.png'>" random






21 "@target(neu1.png) <img width='125px' src='./(...)/neu1.png'>" random



32 "@target(bio2.png) <img width='125px' src='./(...)/bio2.png'>" random



;


Chapter 20. Additional Graphical Components

20 Additional Graphical Components

20.1 General

Experienced users can insert scripts and HTML in the text, in the title and in the labels

of every question and unleash their creativity. This section addresses various components thatcan give ideas or help the presentation to be adapted accordingly to the wishes, even withoutprofound knowledge of HTML or similar. Since the Internet is a constantly evolving medium, wecan only offer, at this point, a selection of options with no guarantee that these will indefinitelymeet the current standards of the web technology. We are available at any time and happyto help in the implementation of individual ideas.

20.2 Image Preview with Thumbnails

Figure 20.1: Image Preview with Thumbnails

In the HTML world by Thumbnails is meant small preview images, which open a bigger pictureby clicking with the mouse. As illustrated in figure 20.1, our variant opens a semi-transparentlayer which is closed when you click on the big picture. It fills the whole screen and remainsalways on top when scrolling the screen segment. The picture is displayed in original size.However, it is at maximum as large as permitted by the visible browser area.

20.2.1 Requirements for the Use

In order to use the thumbnails, the following requirements must be met:

• The GESS JavaScript library gesstmpl.js must be integrated.1

• Image (small) in the media path of the service

• Image (big) in the media path of the service

20.2.2 Example Code: Thumbnail

In the script, first the display layer must be initialized. This is done once in the title of theparticular question with the calling of the JavaScript function insertLayer().

With the function addImage('SMALL', 'BIG') the small preview images can be inserted in alltext fields. SMALL and BIG stand for the paths to the images.

1Please refer to section 15.1.5



The code figure 20.1 looks like this:

TextQ s1;

Text="(1) Picture as thumbnail with preview (JavaScript)";

Title="

Please click on the image to vie in original size.<br>

<script type='text/javascript'>

insertLayer();

addImage('./MEDIAPATH/001s.jpg','./MEDIAPATH/001b.jpg');





</script>

";

20.3 Integration of Videos

This section focuses on the integration of videos in the survey. The technical requirements, thevariety of browsers and mobile devices make it difficult. Ever since the mobile devices, such assmartphones and tablets are connected to the Internet, the choice can no longer be the FlashPlayer, since it is not supported in principle on such devices any more. GESS Q. offers a simpleinterface that uses the current HTML5 standards with a fallback solution for Flash.

Under the GESS Q. Android is referenced to an integrated in the app media player, which isideally suited to play videos.

20.3.1 Formats and Scripts Syntax

The flexible solution of GESS Q. requires providing the video in 3 formats:

• MP4 (.mp4)

• OGV (.ogv)

• WEBM (.webm)

If not all of these formats are available, we recommend the free program Freemake VideoConverter2, which is easy to use, purposefully offers HTML5 as a target format and producesprecisely the same above mentioned formats from a variety of input formats.

Now, to integrate the video in the survey, the three formats must be stored with the same nameand with lowercase file extensions in the media directory. A minimal notation for integration inGESS Q. script would look like this:

textq video;

text="Video Demo";

title="<div id='example_video'></div>";

javascript="

QDot.videoplayer.video.path = './media/@insert(_surveyname)';

QDot.videoplayer.video.name = 'big_buck_bunny';

QDot.videoplayer.create($('#example_video'));

";

2http://www.freemake.com/de/


http://www.freemake.com/de/


Here in the title a HTML field (div) is defined with an ID. Subsequently, the video is to beemployed in this. Path and file name (without extension) are then placed in the filed JavaScript,before the actual video is created - ready!

20.3.2 Configuration of the Player

The video starts by default with complete control bar, maximum volume and in HTML5 browsersthe context menu (right click) disabled. Not only the parameters for the path and name of thevideos, but also the player can be configured further. Preliminary was however said, that therestrictive approach must be avoided, if it isn’t previously known, via what technical equipment(browser, PC / Mobile) the participants are going to make the interview. For example, the mobiledevices block all attempts to play videos automatically. Reason for that is the convenience ofthe user. He must always be in control while surfing and the data volume must not be increasesby automatically running videos. Removing of the play / pause buttons in favor of auto startcan even lead to uselessness of the video. On older mobile devices the internal Media Player cansometimes be accessed, where the controls (Play / Pause / progress bar ...) cannot be modifiedat all. It would be an illusion to try and force the interviewees to a particular sequence withthe videos. Here, there are no 100% solutions and not least every web published media is alsodownloadable and usable offline at will. However, some configurations of the player can be quiteuseful.

Summarized, what options are provided:

QDot.videoplayer.video.path = './media/@insert(_surveyname)';

QDot.videoplayer.video.name = 'big_buck_bunny';

QDot.videoplayer.video.width = 640;

QDot.videoplayer.video.height = 360;

QDot.videoplayer.features = ['playpause','progress','current',

'duration','volume','fullscreen'];

QDot.videoplayer.settings = function(player){

player.play(); //

AUTOSTART

$(player).bind('ended', function(){ $('form')[0].submit(); }); //

AUTOSUBMIT

$(player).bind('ended', function(){ $('#continuebutton').show(); }); //

CONTINUEBUTTON

}

QDot.videoplayer.create($('#example_video'));

The details of width and height of the player are in pixels. The features contain a listing of thecontents of the control bar. In sequence is: play / pause button, progress bar, current time, totaltime, volume and full screen button. The settings define functions and event handlers that aregiven to the player after creation. In the example, the 1st line starts the video automatically (ifpossible), at the end of the video the 2nd line triggers an imaginary click on ’next’ in order toaccess the next screen, where line 3 only makes visible again a button which was made invisibleby CSS.

Examples and ideas:

Test video for the screening With a simple video it can be checked if the interviewee is able toperceive sound and image. The video should display a checking digit and parallel provideacoustically another checking digit. The participant should be able to enter both in anumeric input fields.



progress bar + autosubmit Without a progress bar it is impossible to jump in the video time.So the interviewee would have to watch the video to the end in order to proceed with theinterview with the AutoSubmit. It is assumed here, that the screen has no further buttonincludes. Instead of AutoSubmit a button Next (previously hidden by CSS) can also bemade visible again at the end of the video.

AutoPlay Starts the video automatically. When mobile devices are expected never to be usedwithout Start / Pause buttons, because this feature is blocked from the devices.

Hide volume control In order the video to remains at 100% volume. Prevents the error, whereat this point the sound is turned off (accidentally). The overall system volume cannot beinfluenced.

20.4 Integration of Audio

The audio integration into GESS Q. works similarly to the video integration. More detailedexecution of the here briefly shown information can be found in its chapter.

20.4.1 Formats and Scripts Syntax

The only difference to video integration is that here only 2 formats are needed:

• MP3 (.mp3)

• OGG (.ogg)

If all of these formats are not available, we recommend the free program Freemake AudioConverter 3, which is easy to use and can produce the above mentioned formats from a varietyof output formats.

Similar to the video: the minimum script with an audio file

textq audio;

text="Audio Demo";

title="<div id='example_audio'></div>";

javascript="

QDot.audioplayer.audio.path = './media/@insert(_surveyname)';

QDot.audioplayer.audio.name = 'bing';

QDot.audioplayer.create($('#example_audio'));

";

20.4.2 Configuration of the Player

Again, reference is made to the detailed explanations of the video integration. The nearlyidentical parameters for the audio player are as follows:

QDot.audioplayer.audio.path = './media/@insert(_surveyname)';

QDot.audioplayer.audio.name = 'bing';

QDot.audioplayer.audio.width = 300;

QDot.audioplayer.audio.height = 30;

QDot.audioplayer.features = ['playpause','progress','current','duration','

volume'];

QDot.audioplayer.settings = function(player){

3http://www.freemake.com/de/


http://www.freemake.com/de/


player.play(); //

AUTOSTART

$(player).bind('ended', function(){ $('form')[0].submit(); }); //

AUTOSUBMIT

$(player).bind('ended', function(){ $('#continuebutton').show(); }); //

CONTINUEBUTTON

}

QDot.audioplayer.create($('#example_audio'));

20.5 Dynamically show / hide Questions in Screens

For some questions, it may be useful to display other questions within a screen only if conditionsare met. If the interviewee is asked if he/she has a job, a follow-up question about his/her jobwill only be displayed when he/she has clicked on "Yes" Please also refer to figure 20.2.

Figure 20.2: Dynamically show / hide Questions

20.5.1 Requirements for the Usage

To use the dynamic show / hide questions, the following requirements must be met:

• The GESS JavaScript library gesstmpl.js must be integrated into the template.4

20.5.2 Example-Code: Show / Hide

The script code has to be inserted into two places:

• Creating two arrays (QuestionIDs and LabelIDs) and definition of the start action whenthe page loads.

• Adding the JavaScript handler to the action triggering question.

One of the arrays has to include the name of the question(s), which must be dynamically displayedor hidden. The other must include the LabelIDs of the action triggering question, in which thedesired questions appears.

4Please refer to section 15.1.5



In the example below, the array contains qsToHide (1) the questions f4 and f5. The names of thearrays can be freely assigned and the contents of the comma-separated list can be be expandedas desired. The array hideLabels (1) includes the LabelIDs 1 (Yes) and 3 (maybe).

The JavaScript handler (2) on question f3 is executed every time you click a label of f3. Thefunction hideq(...) deals with the rest. At the first place, in the parentheses comes the namethat triggers the action question. After the comma, in second place stands the name of the arraywith the IDs of the questions to be hidden. At third place is the array with the LabelIDs.

Now the dynamic show-hide is already working with a mouse clicks on the label. Immediatelyafter loading the page (for example, by error or by navigating back), the user has not clicked onanything yet. Therefore (3) starts the presentation function hideq(...) when the page loadsonce explicitly.

The code to figure 20.2 looks like this:

singleq f3;

text="This is an absurd example question...";

labels=

1 "Yes"

2 "No"

3 "Maybe"

;

jsHandler="hideq('f3', qsToHide, hideLabels)"; // (2)

javascript="

qsToHide = new Array('f4', 'f5'); // (1)

hideLabels = new Array('1', '3'); // (1)

$(document).ready( function(){ hideq('f3', qsToHide, hideLabels); } ); //

(3)

";

singleq f4;

title="blabla";

labels=

1 "1"

2 "2"

3 "3"

;

openq f5;

title ="If yes or maybe, why?";

screen scr = column(f3 f4 f5);

20.6 Tachistoscopic Question Options

The classic tachistoscop shows the interviewees a text, an image or something similar for a shortperiod of time and hides it again. Afterwards the most eye-catching elements or eye-catcherscan be queried. GESS Q. provides this option with the variant 2. Please refer to figure 20.4. Inaddition, it is possible to demand from the interviewees to answer within a specific time frame(variant 1). Refer to figure 20.3.



20.6.1 Requirements for Usage

To use the tachistoscopic options in any type of question, the following requirements must bemet:

• In the template, the GESS JavaScript library gesstmpl.js must be integrated 5

• The tachistoscopic options are not currently usable in multiple screens.

20.6.2 Tachistoscope Option 1 (Timer)

Figure 20.3: Tachistoscopice Option 1

In general in the script the following JavaScript must be written in the text or in the title:

defaultnomissing=yes;

SingleQ tachisto1;

text="


var qname = 'tachisto1';

var input=\"Text, Image, Video, ...\"+

\"further...\";

var tVisib = 'visible';

var tTime = 10000;

var tWait = 1000;

var tWidth = 500;

var tHeight = 10;

var tColor = '#990134';

addTachistoCode(qname,input,tVisib,tTime,tWait,tWidth,tHeight,tColor);

</script>

";

labels=

1 "Yes , I like that"

2 "No I do not want that"

;

5Please fefer to section 15.1.5



javascript="hide_labels('tachisto1')";

defaultnomissing=no;

The JavaScript code consists of two parts. First, the parameters are set (in the example startingwith var); These are then passed to the function addTachistoCode(...) . The names of theparameters can be selected freely, but must be passed in fixed prescribed sequence to the function.The meaning of the parameters will be explained using the assigned name:

qname The name of the invoking question in GESS Q. script.

input The content to be displayed on the tachistoscope. If the content extends over multiplelines, the the end of the line must be marked with \"+ and a new line must be marked with \".

tVisib sets whether the time should be displayed in the form of a decreasing horizontal barunder the content.Options: visible | hidden

tTime Time in ms, which is available for the answer.

tWait Time in ms, starting from when the answer choices will be displayed. For this purposethe answer labels must be previously hidden using the htmlPostText instruction. This assumesthe function hide_labels() where the name of the corresponding question in quotes is passing.

tWidth Width of the time bar in pixels.

tHeight Height of the time bar in pixels.

tColor Color the time bar in pixels.

After the time tTime has passed a click is triggered on the Next button automatically. If theinterviewee has not given a response till this time, generally he will be forwarded to the nextquestion without an answer. To make this work, the parameter defaultnomissing in GESS Q.script must be set to yes.

20.6.3 Tachistoscope Option 2 (classical)

Figure 20.4: Tachistoscope Option 2 (classical)

It also applies to the classic tachistoskop that basically only the following JavaScript code mustbe written in the text or title of any question:



SingleQ tachisto2;

text="


var qname = 'tachisto2';

var input=\"Text, Image, Video, ...\"+

\"further...\";

var tTime = 1000;

var tWait = 1000;

addTachisto2(qname, input, tTime, tWait);

</script>

";

labels=

1 "I saw a horse in the picture"

2 "I saw a donkey on the screen"

;

javascript="hide_labels('tachisto2')";

The JavaScript code consists of two parts. First, parameters are set (in the example thesestart with var); Then they are passed to the addTachisto2(...) function. The names of theparameters can be selected freely, but must be passed in fixed prescribed sequence to the function.The meaning of the parameters is now explained based on the name, given in the example.

qname The name of the invoking question in GESS Q. script.

input The content to be displayed in the tachistoscope. If the content should be extended overmultiple lines, an end of a line must be marked with \"+ and new line - with \".

tTime Time in ms, for how long the content is to be display.

tWait Time in ms, from when the answer choices will be displayed. For this purpose the answerlabels must be previously hidden by the means of the htmlPostText instruction apparent inexample. This is done by the function hide_labels() which gets the name of the correspondingquestion in quotes.

20.7 Heat Plotter

Often interviewees must indicate which part of the screen they find particularly good or bad orwhat the most noticeable thing is For this purpose GESS Q. provides two different options.

With the HeatPlotter an area in the image can be marked directly. Any number of points canbe selected with a mouse click and these are stored as x, y coordinates in a JSON list. Using theremove button below the image, the last label can always be deleted.



Figure 20.5: Heat plotter: Select Image Points

OpenQ f1;

text="Please mark the beautiful spots";

title="<img id='mouse' src='./media/@insert(_surveyname)/mouse.png' />";

coordinates(10);

assert (numCoords(f1) ge 3 and numCoords(f1) le 10) "3-10 selections";

javascript = "

QDot.heatplotter.create('f1', 'mouse');

QDot.heatplotter.maxCoords = 10;

// QDot.heatplotter.indicator = './media/@insert(_surveyname)/circle.png';

// QDot.heatplotter.removeButtonTxt = 'Remove last';

// QDot.heatplotter.drawImages('@insert(f0)', './@insert(_surveyname)/circle.

png');

// QDot.heatplotter.restrict = function(coords){

// coords.y = 0;

// return coords;

// // return undefined; // if the click must be discarded

// };

";

To implement that, the GESS Q. uses internally an OpenQ of which the input field is hidden andfor each click on the image coordinate pairs are stored. In the title field the desired imageis read as HTML <img>. It is important here to assign a corresponding ID (for example, hereid = 'mouse' ).

The instruction coordinates the server checks the coordinate’s syntax in hidden input field. Inaddition, the parameter »NUM« limits the click function to the specified value. This allowes theincorrect information, such as text entries to be sort out by GESS Q. In such a case the contentsof the open field is cleared and an error message is displayed.

Coordinates(NUM);



For conditions (for example: asserts), the new function numCoords is available, It returns howmany coordinates are specified using the question name as a parameter.

numCoords(OPENQ)

With xCoord the X-value of a certain point is returned. The index assigns to the correspondingpoint (1 = 1. point, 2= 2. point, ... )

xCoord(OPENQ, Index)

With yCoord the Y-value of a certain point is returned. The index assigns to the correspondingpoint (1 = 1. point, 2= 2. point, ... ).

yCoord(OPENQ, Index)

With the JavaScript instruction QDot.heatplotter.create GESS Q. generates the HeatPlotter

and hides the open field, where the XY coordinates are stored.

QDot.heatplotter.create('OPENQ', 'Image-ID');

The second JavaScript instruction QDot.heatplotter.maxCoords specifies the maximum numberof selections.

QDot.heatplotter.maxCoords = NUM;

The HeatPlotter mechanism has another two optional parameters.QDot.heatplotter.removeButtonTxt replaces the default text of the Remove button ("RemoveLast Selection").

QDot.heatplotter.removeButtonTxt = 'TEXT';

In addition, the image for the marking of the selected spots can be changed by another specificationfor QDot.heatplotter.indicator. The size of the image is arbitrary. By default it is a crosshair(16x16px).

QDot.heatplotter.indicator = 'MEDIAPFAD';

Furthermore, fixed elements can be drawn with QDot.heatplotter.drawImages (points fromprevious HeatPlotter questions, etc.) The value of a variable can be inserted into the firstquotes with @insert(). In the second quotes is the associated media path of the indicator. Thisinsertion does not affect the rest of the details (for example, maximum number of marks).

QDot.heatplotter.drawImages('@insert(VARIABLE)', './images/kreis.png');

The CSS class controls whether the HeatPlotter marker is located before or after the targetimage. If this is before the target image, the area is occupied for further points and is notre-clickable.

heatplotter-drawn-image (CSS-class)



The positioning can be changed over the restrict function QDot.heatplotter.restrict. This isuseful if, for example, only certain parts of the image should be clickable, but requires knowledgeof JavaScript.

QDot.heatplotter.restrict = function(coords){

CONDITION

};

QDot.heatplotter.restrict = function(coords){

// Restrict clickable area

if(coords.y > 500){ // (Y-coordinate must be less than 500)

return undefined;

}

// Centering / fixing of an axis

coords.x = 25; // (X-coordinate is always set to 25)

return coords;

};

20.8 Data Storage

The coordinates recorded by HeatPlotter are stored separately as an X-Y coordinate pairs inthe record. So, two new fields are made for each selection. Over the numerical limitation in thecoordinates(NUM)-command, the intended maximal number is reserved in the record. For eachcase, the corresponding number of the specified points is outputted before the coordinates pair.

20.9 Integration of ImageMaps

ImageMaps are so called referring graphics. With the help of various free tools available online(such as GIMP) ImageMaps can be generated from any graphics. The graphics are overlayedwith a freely definable grid which areas can respond to mouse events.

Figure 20.6: ImageMap

Figure 20.6 is an image example of an vintage car with its defined raster. Each area in a definedcolor is understood as a representative label.

Base for the ImageMap is a SingleQ or a MultiQ when multiple answers are possible. Thefollowing script example uses the vintage car as MultiQ:



multiq oldi1;

text="

Have a look at the image displayed below.<br />

Which areas do you like in particular.

";

title="Please click on these areas in the picture.";

labels =

1 "the front left turn signal"

2 "the front right turn signal"

3 "the door handle"

4 "the footboard"

5 "the rear left tyre"

6 "the front left rim"

7 "the forward cooling grille"

8 "the number plate"

9 "the passenger door"

10 "the front left window"

11 "the rear left window"

12 "the motor hood"

13 "the grille to the left"

14 "the front left headlight

15 "the front right headlight"

16 "the figure"

17 "the wheel"

18 "of the sunscreen"

19 "the front right side mirror"

20 "the rear left wing"

21 "the front left wing"

;

css="

.qtable {display:none; }

canvas{

border: 1px solid black;

position: absolute;

top: -621px;

z-index:1;

}

";

htmlposttext= "

<img src='./media/@insert(_surveyname)/oldtimer/oldtime2.png' width='900'

height='621' style='position:relative; z-index:2;' usemap='#map'/>

<map style='display:block; position:relative;' name='map' id='map'>

<canvas height='621px' width='900px'>Canvas is not supported by your

browser.</canvas>

<area shape='circle' qlabel='1' class='mapPart' coords='718,443,21'

nohref='nohref' />


nohref='nohref' />


nohref='nohref' />



<area shape='poly' qlabel='4' class='mapPart' coords

='138,367,168,358,363,408,333,425,305,417' nohref='nohref' />


='41,270,86,269,110,369,91,426,37,398,29,309,41,270' nohref='nohref' />


='490,383,531,381,584,432,591,518,542,548,479,515,458,439,481,389,483,388,491,385'

nohref='nohref' />


='665,233,684,227,711,228,715,247,712,320,658,336,672,297,666,272,654,260,660,238'

nohref='nohref' />


='657,341,674,369,729,353,727,323' nohref='nohref' />


='203,203,310,212,327,379,210,348,201,203' nohref='nohref' />


='215,71,215,72,306,65,301,176,211,169,211,70,212,71' nohref='nohref' />


='114,67,183,68,183,169,113,161,112,160,113,65' nohref='nohref' />


='419,219,634,241,659,196,493,177,427,190,425,192' nohref='nohref' />


='421,336,431,250,591,272,587,295,501,281,425,334' nohref='nohref' />


='619,261,647,261,667,282,662,326,646,336,612,307,597,291,605,264,616,261'

nohref='nohref' />


='732,249,759,250,774,266,764,310,750,319,723,315,716,278,722,247,731,250'

nohref='nohref' />


='693,200,689,201,674,201,665,182,682,154,702,187,695,197' nohref='nohref' />


='405,155,463,159,456,135,433,129,415,136,402,142,399,155,402,154' nohref='

nohref' />


='329,52,369,79,542,93,508,71' nohref='nohref' />


='517,167,520,135,503,130,498,165,503,170' nohref='nohref' />


='18,306,57,237,93,274,112,352,157,348,124,264,100,218,41,231,21,269' nohref='

nohref' />


='392,410,441,331,509,309,576,325,623,385,658,392,673,378,642,331,572,290,506,288,438,322,404,371,396,401

nohref='nohref' />

</map>

";

javascript="

qImageMap.defaultColor = 'rgba(0, 255, 0, 0.5)';

qImageMap.onClick = function(q, id, isSingleQ, isMultiQ){

// ...

};



qImageMap.makeQImageMap('VARIABLENNAME', 'MAP-ID');

";

This is a normal MultiQ, the labels of which are transffered to the areas of the ImageMap. Theusual tabular presentation of MultiQ is hidden using the CSS, so that only the graphic remains.

The definition of the map is almost entirely delivered by GIMP for example. Only two additionalinputs should be added for GESS Q.

With qlabel are given the corresponding values of the labels to assign them clearly.

qlabel='LABELCODE'

class='mapPart' inserts a CSS class. This is essential for the desired view.

Furthermore, with <canvas></canvas> a definite drawing surface is stretched over the wholeimage. Over this area the green semi-transparent surfaces are shown.

The javascript command qImageMap.makeQImageMap activates the click function and checkswhether it is a SingleQ or MultiQ.

qImageMap.makeQImageMap('VARIABLENNAME', 'BILD-ID');

With the addition in qImageMap.defaultColor the default color for highlighting can be changed.

qImageMap.defaultColor = 'FARBCODE';

With qImageMap.onClick the entire highlighting respond to a click can be modified. This settingrequires knowledge of Javascript.

qImageMap.onClick = function(q, id, isSingleQ, isMultiQ){

CONDITION

};

20.10 3D Rotation Viewer

The 3D Rotation viewer is a component, based on JavaScript and individual images, withwhich it is possible to generate a 3D effect. Objects can be rotated or panoramic views can becreated using mouse control or swipe gestures (Android).

Figure 20.7: 3D Rotation Viewer

Figure 20.7 represents the 3D Rotational viewer exemplified with two views of a three-dimensional GESS cube. The following script example demonstrates the integration:



textq bip;

text="The GESS cube";

title="


insert3dRotationViewer('./media/SURVEYNAME/gess_cube_[#frame].jpg', 50, 1);

// insert3dRotationViewer('./media/SURVEYNAME/gess_cube_[#frame].jpg', 50, 0);

</script>

After the series of images is stored in the media folder of the study, the viewer can be startedwith a single JavaScript function call. For this is required, that in the file names of the images areincluded two-digit sequential numbers, starting with 01, with leading zeros and are representedwith [#frame] by the function call.

For example: image01.jpg, image02.jpg, image03.jpg, ... image50.jpg.

Furthermore, the function call gets the total number of images (here: 50) and defines with 1 or 0whether after the loading time the viewer will carry out an independent, slow 360° turn.

In addition, can also be displayed a control buttons. The following example adds a 5 buttonswith which the viewer performs different animations.

<div style=\"text-align:center;\">

<a href=\"javascript://\" class=\"linkedJs buttonLink\" title=\"spin (360,2700,

Uize.Curve.easeInOutPow (4))\">360 clockwise</a>

<a href=\"javascript://\" class=\"linkedJs buttonLink\" title=\"spin

(-360,2700,

Uize.Curve.easeInOutPow (4))\">360 counter-clockwise</a>

<a href=\"javascript://\" class=\"linkedJs buttonLink\" title=\"spin

(1080,4000,

Uize.Curve.easeInOutPow (4))\">3 spins</a>


Uize.Curve.Rubber.easeOutBounce (5,-2,1.5))\">spin with bounce</a>


Uize.Curve.Mod.bend (Uize.Curve.Rubber.easeOutElastic (.1),3))\">elastic spin</

a>

</div>

";

The display area of the RotationViewer, in particular the size and shape, can be formatted viathe CSS class rotationViewer.

css="

.rotationViewer {

width:600px;

height:423px;

}

";


Chapter 21. Invitation Links, Participant IDs and Panel Connection

21 Invitation Links, Participant IDs and PanelConnection

21.1 Participant-IDs

In an online survey the respondents often receive a link with their invitation, with which theycan identify themselves as a participants and start the interview. If in that case must be used apanel, the links must be matched with the panel and forwarding must be set.

An invitation link to a study always includes a participant ID which can consist of the charactersa-z, A-Z and 0-9. How the string looks like and what length it has, is not specified. The ID isavailable as a variable (_respid) with the call of the link. This makes it possible to divide theparticipants by the ID and to send specific information or questions to the respective groups. Forexample, if a study should run in several languages at the same time, the IDs under the number100.000 can get the interview in English, the IDs between 100.000 and 200.000 could receive it inSpanish, these over 200.000 - in French. With this introduction, a subscriber would receive thesurvey "s02" in Spanish. More details on invitation links follow in section 21.3:

https://survey.gess.de/SurveyServlet?action=startsurvey&survey=s02&idmode=s&

respid=123456

IDs can be entered via web interface, as described in section 25.3.7, but they can also be depositedby hand as a file. Single Mode-IDs belong in the file respo.lst, which must be found in thestudy directory. The file must have one ID with the keyword fresh per file. When the surveyruns, GESS Q. notes in the file for each ID, whether the interview was completed or cancelledand enters the serial number, the last question answered and the time that was needed for theinterview, in seconds.

1073 fresh

1074 finished 1291 a_c26 305

1075 cancelled 144 a_a0

1076 finished 687 a_c26 750

1077 fresh

1078 fresh

1079 fresh

GESS Q. expects the IDs for Multi mode interviews, where multiple participants can use thesame ID, in the file respm.lst, where each ID appears in one line, without further additions.Since GESS Q. uses the IDs only for access control, the file doesn’t change unlike the filerespo.lst.

21.2 Survey Modes

GESS Q. offers 3 survey modes which can be used (also in parallel) in a study: multimode,singlemode and testmode. An interview may be conducted in the intended mode using aparameter in the link.

Multimode In Multimode IDs respectively invitation links can be used multiple times, in order tostart interviews. This alternative is particularly appropriate at onsite interviews or CATI, wherethe timing constraints are well defined. A major disadvantage is that interrupted interviewscannot be redone in a later time. Furthermore, there is no protection from having participant



complete the interview several times. If the technical conditions allow it to select a link from apredefined list, the single mode is preferable in any case. Link parameter:

idmode=m

Test mode The Test mode behaves exactly like the multimode with the ID 0. Accordingly, thereis only one start link for the Test mode. However, the ID doesn’t appear explicitly in the link.For the Test mode (respectively the ID 0) in the script can be specifically set, whether recordshave to be written, quotas have to be counted, error pages have to be displayed or other selectionlogic has to be executed. Link parameter:

idmode=t

Internally, with the start of an interview in Test mode, GESS Q. starts also the preprocessordirective

#define testmode

This allows enabling or disabling interview parameters specifically for the Test mode. Here thename of the question appears only in Test mode:

#ifdef testmode

HTML{ showQuestionName=yes; };

#endif

Single mode The most flexible options are offered by the Single mode. If many IDs are stored,a invitation link can be utilized which can be used just for one interview. The so personalizedinterviews can be continued after an interruption (for example, explicitly using a button or aftera timeout due to inactivity) with a reopening of the links on the question, taht is last displayed.If the interview is completed, the invitation link is used. By using a (random) IDs list (whichcan be defined in advance), it can be prevent as far as possible, that interviewees participatemore than once in the study by trying multiple IDs. This variation offers the greatest possiblecontrol over the participants and safety in critical surveys, as well as known subscriber circles orcollaborations with institutions.Link parameter:

idmode=s

21.3 Invitation Links

In the following, the structure of the invitation link is summarized - as example for the serversurvey.gess.de. It is advisable to use the Hypertext Transfer Protocol Secure (https)if the server supports it.

-------------------------------------------------------------------------------

HTTPS://SERVER/SurveyServlet?action=startsurvey&survey=NAME&idmode=MODE[&

IDPARAM=ID]

HTTPS Transfer Protocol {http, https}

SERVER Server URL or IP

NAME Name of the Study

MODE ID Modus (test, multi, single) {t, m, s}

IDPARAM URL name of the parameter of the Participant ID



ID Participant ID

WHITELIST File Name

-------------------------------------------------------------------------------

Example 1: Study s01 in test mode

https://survey.gess.de/SurveyServlet?action=startsurvey&survey=s01&idmode=t

Example 2: Studie s02 in multi mode with ID 123

https://survey.gess.de/SurveyServlet?action=startsurvey&survey=s02&idmode=m&

respid=123

Example 3: Studie s02 in single mode with ID 456


respid=456

Example 4: Studie s02 in single mode with ID 456 and URL parameter myID


myID=456

Example 5: Studie s02 in single mode with ID 456 and whitelist


respid=456&whitelist=whitelist.wl

It is not necessary to compose the link together manually from the individual components. Theweb interface generates the proper links for Testmode, Singlemode and Multimode via the pointStart (please also refer to section 25.2).

For the whitelist see section 4.5.

Upper and lower case are taken into account in the links. These could be ignored when specifyingprotocol and server, but the details after the slash are processed by GESS Q. and upper andlower case must be taken into consideration:

hTTp://sErVeR.dE/SurveyServlet?action=login (1)

http://server.de/SurveyServlet?action=Login (2)

(1) functions, on (2) follows an error message.

21.4 Panel Connection

In general, when working with a panel, there are few general arrangements, that must be made,concerning the interfaces from panel to the online study and the other way around. Figure 21.1represents the most frequent information exchange between the panel and the actual survey.

Figure 21.1: Scheme Panel Connection



Typically, as soon as an interview ends, the panel requires direct feedback in its system. In thisway the field statistics can be observed live and the sending of further invitations is controlled.Here the panel must learn which participant was successful or for example, which were screen-out.At the technical level, two steps are necessary, which are explained in the following subsections.

21.4.1 Using the Panelists ID as GESS Q. Participant ID

Ideally, before the field starts, the panel delivers either a list of random IDs (which are used forthe upcoming survey) or it receives a predefined list of such. Stored as a single mode IDs, theinterviews automatically have a cancelation and resumption mechanism. The usage of randomlydistributed and not incremental IDs, multiple participation or single participants can be largelyprevented.

If the panel can’t designate IDs in advance also doesn’t work with a predetermined list, thepossibility remains to accept unknown (not stored) IDs in singlemode. The Multimode is rathernot suitable for working with the panel.

The easiest way for the integration of the ID in the invitation link is when it can be placedfrom the panel to any location. In the following example, the respective link parameter is calledrespid for historical reasons:


respid=45

Often, a whole series of system conditioned parameters from the panel are attached to the link.This can be done as desired, as long as the parameter names do not duplicate the GESS Q.specific names. In following fictive example, the participants ID is hidden behind the parameterpid and that is also the only way to accommodate it from the panel to the link:

https://survey.gess.de/ ... &ppanel=47&session=0421&charge=zasdk&pid=85674&

gzu=lkf77d

In this case, the name of the parameter can be adjusted on the side of the GESS Q. in the IDmenu of the web interface to the default pid. Please also refer to section 25.3.7.

21.4.2 Redirect to Panel

After completing an interview of any kind, the participants can be automatically forwarded toany other websites / URLs. It must be ensured in advance, that the annotation @forward isentered at any location in the HTML template of the survey, outside of the script fields.For example, at the end of the HTML document:

@dummy

@forward

</body>

</html>

@dummy

A forwarding rule can then be defined in the GESS Q. script. For this purpose the finishforward

command is available.

-------------------------------------------------------------------------------

finishforward = {

( "TARGET-URL" "TEXT" (CONDITION) SECONDS )



...

};

TARGET-URL: URL / Website to which the interviewee must be forwarded

TEXT: Note on the final page of the interview

CONDITION: Condition when the forwarding is performed

SECONDS: Viewing time of the final page before the forwarding is initiated

-------------------------------------------------------------------------------

Example:

finishforward = {

(

"http://www.gessgroup.de"

"You will be redirected in 3 seconds to www.gessgroup.de"

(_finished eq 1)

3

)

(

"http://www.gessgroup.de/@insert(_respid)"

"

If you are not redirected to www.gessgroup.de in 5 seconds, please click on

the following link:

<a href='http://www.gessgroup.de/@insert(_respid)'>

http://www.gessgroup.de/@insert(_respid)

</a>

"

(_finished eq 2)

5

)

};

After the abstract syntax definition, the above example illustrates how the commandfinishforward is used in the GESS Q. script. The example contains a forwarding rule with twopossible, different forwardings which depend on the final code of the interview. The final codeis available in GESS Q. script in the variable _finished. If the interview ends with the finalcode 1, the interviewee sees the respective note and after 3 seconds is automatically forwarded tothe page www.gessgroup.de. The final code 2 will, however, initiate forwarding after 5 secondsto a URL that contains the subscribers ID. This is accessible in the GESS Q. script by thevariable _respid and can be inserted into the text with the usual text replacement @insert().Furthermore, the note text additionally contains a link, with which the respondent could alsoaccess the destination URL by a click, in case the automatic forwarding is disabled for unexpectedreasons.


Chapter 22. The Local Installation - GESS Q. Desktop

22 The Local Installation - GESS Q. Desktop

22.1 Installation and Setup

The following section explains, what is needed to install and get running the various versions ofGESS Q.

22.1.1 Installation

The latest versions of GESS Q. Desktop and GESS Q. Android are available for free as auto-matically installable archives under http://www.gessgroup.de/qdownload. Similar to the fileGESS_Q_xxx_Setup.exe the page for Android offers a .apk file, in order to be able to installthis application on a tablet / smartphone. At this point it should be noted, that the chapter 24explains in details the configuration of Android devices and the special GESS Q. functionalitiesfor Android. The installation under Windows can be accomplished easily by following the setupinstructions. If in doubt, there is a video in the GESS Youtube Channel, that might be helpful:GESS Youtube Channel.

In order for GESS Q. Desktop to run, on the computer must be installed Java RuntimeEnvironment 8. 1 By using the command prompt (cmd.exe) or command line command, you cancheck with java-version whether Java is installed or if the system finds the Java installation.

If your system is familiar with the Java command, a corresponding version information is returned.If no Java RE is installed, you can download the latest version here: www.java.com/de/download/.

Existing GESS Q. installations can be easily overwritten by more recent setup programs. Studies,data and user-specific settings are maintained.

With Java Version 8 under Linux it is possible that GESS Q. Desktop can not be started. Theautomatic call of the browser goes wrong and then the program is terminated again. Thisbehavior is caused by an error in Java. With the copying of the file noautostart.txt in thefolder, where also startcapi.bat is found, GESS Q. starts the browser no longer automaticallyThe address http://localhost:8080, under which GESS Q. Desktop runs, can be then enteredmanually.

In addition to Java, a Server Installation requires an application server like JBoss or Tomcat,which GESS Q. provides as a web service. For full support of international studies and charactersets as Cyrillic or Chinese, the application server must be configured so that all requests andresponses are interpreted and encoded with UTF-8. In this context, the GESS Q. server istypically hosted as a Web Archive (.war) in the application server. Of course, GESS providesany kind of service around the server: delivering, installation, maintenance, ...

22.1.2 Folder Structure

GESS Q. is working mostly with file-based human readable content in the files, without the needof a database. This has the advantage, at any time to be able »just to take a look in a file«without relying on additional programs. On Android there is so far no reason to deviate fromthe standard structure, by GESS Q. Server and GESS Q. Desktop, depending on the workingenvironment, can be usefull to make individual adjustments. While a self-employed may also

1https://www.java.com/de/


http://www.gessgroup.de/qdownload

http://www.youtube.com/user/gesssoftware

http://www.java.com/de/download/

https://www.java.com/de/


work good with an independent stand-alone installation, the businesses with many users, whocould work simultaneously on the same project, will need to store the studies centralized, sothat all parties have access. Section 22.2.1 and section 1.2.5 among others, describe the possibleadjustments, which can be made and describe three typical scenarios.

At first glance it may appear strange, that a GESS Q. project is separated compulsory in aproject- and a media-folder. A brief explanation about this:As an online survey, a questionnaire from the Web browser has to be shown. While GESSQ. outputs the actual content of the page screen for screen, the media files (photos, videos,applications) must be accessible (and therefore public). Each media file is now directly accessiblevia a specific web address. But this is not desired for all other relevant information of the studies,such as the GESS Q. script, the quote levels, the log files or approved IDs. While the mediapath on the server is in a public area, all other parts are inaccessible externally.

After installation and without configuration changes GESS Q. expects the following structure inthe installation folder.

InstallationFolder/config/

root/media/[questionnaire]/

surveys/[questionnaire]/text/

gtc/

In the installation folder are located the Java files of the program GESS Q. Desktop and the files,with which the program can be started: for Windows startcapi.bat, for Linux startcapi.sh.Configuration files are in directory config. Files that must be public for use on a web server areunder root. The scripts, that make up a questionnaire are located per study (here marked withthe placeholder [questionnaire] ) in its own directory under surveys. The questionnaire itselfmust be with text and can contain further subdirectories with gtc. In the folder text GESS Q.searches for the file script.q, which serves as a starting point for a questionnaire. The foldergtc contains control files for GESS-tabs, when the program is linked for an output in tables.

22.2 Configuration

The GESS Q. is tematically installed in the directory c:\\Program Files\GESSQ under WindowsOS. Without changes in the configuration GESS Q. expects to find scripts and media files for astudy in this directory.

22.2.1 Configuration File qonline.cfg

Basic settings in handling projects and ongoing interviews may be made in the configurationfile. It is called default qonline.cfg and is located in the folder config of the installationfolder. Also, the path and name of this folder can theoretically be modified, at least for GESS Q.Desktop and GESS Q. Server. It is passed as a startup parameter for the corresponding Webapplication. The configuration file is loaded once at startup. Changes therefore always require areboot of the GESS Q. application.

After the exemplary full representation of a configuration file, the contained parameters aredescribed individually. Parameters marked with an asterisk are essential for the basic programfunctions.

adbApp=config/adb/adb.exe

archivePath=archive



backupPath=backup

docPath=doc

documentRoot=root

gtcApp=C:/Program Files/GESStabs/GTC.exe

logRequests=false

maxIdleSeconds=20

maxMemoryLoad=80

mediaRoot=root/media

method=GET

modelPath=models

presetDataPath=preset

surveyPath=surveys

timeOutCheckInterval=20

URLName=SurveyServlet

jdbcDriver=org.postgresql.Driver

jdbcUrl=jdbc:postgresql://localhost:5432/translation

jdbcUser=qdot

jdbcPassword=XpAssWoRdY

jdbcDropAndCreateTables=false

adbApp contains a path to Android Debugging Bridge (ADB). ADB is a tool for communicationbetween Android devices and the PC. It is used by GESS Q. Desktop, to exchange data viaa USB cable with Android GESS Q. Under Windows, the program is called adb.exe and issupplied by default with the GESS Q. Desktop installation directory. /adb/.

archivePath If you specify here a path to an existing folder, the user interface GESS Q. providesthe option of archiving studies. They are then saved in the specified folder as GESS Q. projectfile (.qp).

backupPath If this parameter is provided with a path to a folder, it is used when deleting andresetting of projects to automatically create a backup.

docPath If this parameter is provided with a path to a folder, the user interface of GESS Q.offers the menu option help , which refers to help documents and additional content from thespecified folder.

documentRoot* This parameter must include the path to the server root directory. This is wherethe the externally accessible program files are stored, the HTML representation of the relevantquestionnaire CSS and JavaScript files.

gtcApp In order to be able to display live evaluations in form of a table in the online reportingand to download directly SPSS files, GESS Q. works seamlessly with GESStabs. This parametermust contain the path to the executable program GTC, so that the GESStabs can be used fromGESS Q.

gtcSurveyDir Tables can be generated automatically from the interview data. The GESStabs(gtc) needs to know where the questionnaires are found to make this. This path is however soonto drop off. At the moment, within the interface definition to GESStabs, it is comparative thatit is identical to the surveyPath.

maxIdleSeconds* controls how many seconds an active interview must be idle, before GESS Q.places it in abort state. This process releases the RAM occupied by the interview.



maxMemoryLoad sets the maximum allowed memory usage in percent (Default:80). By an interviewquestion, during overload the GESS Q. triggers the Java GarbageCollection no more than oncein 5 minutes. In case that the specified maximum load is yet exceeded, new users are rejectedwith status page memoverload.html. memoverload.html must be located next qonline.cfg

in the configuration folder. Rejected interviews and GESS Q. initiated garbage collections arelogged in /config/serverlog.lst. The maximal capacity is also marked in the interface underServer status using a black line.

mediaRoot* This parameter specifies the directory in which the related to the projects mediadata are stored. In order to be publicly available from the server perspective, this folder must belocated below documentRoot. GESS Q. searches for a folder in the mediaRoot folder which hasthe same name as the script folder surveyPath. It is used to separate the questionnaire with itstext files and the media files used in it, such as images, animations, sound recordings or films.As GESS Q. requires the same name for the media directory, media files can be included withoutadditional path information for their filenames.

method* determines whether the interview is to be carried out via the HTTP GET or via POST.

modelPath defines a folder, where templates for studies can be stored. If new studies are createdthrough the user interface one of the templates with all its preferences can be selected as anstarting point. If there is a .png image file in the folder /documentRoot/model_previews withthe same name as the template, it is displayed as a preview when selecting templates.

presetDataPath GESS Q. offers the opportunity to export certain data from interview variablesduring the interview. This information can be read again by other interviews, for example, incase a variables must assume values in advance. The parameter presetDataPath determinesa central folder from which the interviews can retrieve information with the action commandreadJsonDataFile.

surveyPath* defines the folder, where the projects are stored. The path information refers tothe installation folder in this relative form ("Path = survey surveys"), so that GESS Q. willsearch in the unchanged default installation script files under c:\Program Files\GESSQ\surveys.With an absolute path information, you can also store studies outside the program directory:surveyPath=c:/Umfragen.

In the variable names (surveyPath) the program does not distinguish between uppercase andlowercase. This applies for Windows for the path information, on the other hand under Linux/Unixthe spelling of the path is taken into account (»Surveys« does not match »surveys« under Linux).

Unlike the Windows standard, Java uses the slash instead of the backslash character to separatedirectories in pathnames.

timeOutCheckInterval* determines in which intervals in seconds GESS Q. checks, how longactive interviews have remained unchanged, in order to place them, if necessary, in cancelationstate. Please also refer to maxIdleSeconds.

URLName* determines, the name under which GESS Q. is offered as a Web service. This isnormally SurveyServlet.

jdbcDriver The variable contains the reference to the database interface for any translations tobe used by the GESS Q. Depending on the type of database, the appropriate database drivermust be integrated. (please also refer to Java documentations). Currently GESS Q. workspreferably with PostgreSQL.Presetting: org.postgresql.Driver



jdbcUrl This parameter specifies under which address the GESS Q. can reach the database fortranslations.Presetting: jdbc:postgresql://localhost:5432/translation

jdbcUser takes the name of the assigned database user who can access the translation tables.Presetting: postgres

jdbcPassword provides the password of the jdbcUser in plain text.Presetting: postgres

jdbcDropAndCreateTables When setting up the database, the value should be first set to true.After that it must be set to true. If the value is true, all tables and content will be discarded atthe first access and newly generated. After the data base is set up, this is no longer desirable.Presetting: false

22.2.2 User Accounts and Access Rights: users.lst

In the folder config, which GESS Q. expects to find in documentRoot , also can be found thefile users.lst. The file contains one user account per line and each user is defined by five fields:

id=demo;company=GESS;name=demo;password=omed;access=full

id contains the unique name of an account

company To which company the user belongs

name The login name of the user

password The password for the account, as in the example above, can be stored in plain text.In terms of security, this is not welcome. Therefore, the server stores the passwords in this file asa hash, a fingerprint of the actual password. At each logon the hash of the entered passwords isdetermined and then compared with the stored fingerprint.

access The field determines by the entry full, reduced, etc. the role and thus the access rights ofthe user. It also determines which menu options, if any, will be visible for the user in the serverinterface.

Although the entries can be made manually, the server interface features in the menu Mainunder Users also a menu item, where can be edited the file users.lst. Since the role name inthe file differs from the name of the rollers, it would be more practical to use the web interface.In this case, the server carries only the hash of a password.

Roles can be roughly divided into two groups: admin and regular user suitable for users whomanage the studies or script. The various combinations of reporting, data export, data processingand quotas corrections are on the other hand rather intended for customers who accompany anongoing study.

22.2.3 User Roles

Admin Users with the admin role have access to all functions in all studies (access=full).

Regular User allows access to all functions in the studies, which users are assigned.(access=reduced).

Reporting provides access to the reporting (access=rep).



Reporting + Export extends the reporting role with the ability to download data and togenerate SPSS files (access=rep_export).

Reporting + Data Edit extends the reporting role to the ability to edit and delete datarecords (access=rep_data).

Reporting + Quota-Edit extends the reporting role to the ability to edit nominal quotas(access=rep_quota).

Translator allows controlled access to the translation files in the user interface. (access=

translator) Please refer to section 25.3.13.

The other roles Rep + Exp + Data (rep_export_data),Rep + Exp + Quota (rep_export_quota), Rep + Data +Quota (rep_data_quota),Rep + Exp + Data + Quota (rep_export_data_quota) offer different combinations ofdifferent access rights.

22.2.4 access.lst

The counterpart to the generally specified access rights users.lst forms the file access.lst atthe level of the individual study. It is located right in the questionnaire directory. The IDs ofthe users, who have access to the study, are recorded in lines. The access rights for the user aredetermined by his assigned role in the file users.lst. So, if the user demo should have access toa study, the corresponding file access.lst must contain the entry.

demo

The web interface of GESS Q. allows you to manage the file (please refer to section 25.3.11).

22.2.5 Blacklist

In the configuration directory GESS Q. saves a file called blacklist.txt, which lists all thekeywords, reserved by GESStabs. These words should not be used in a questionnaire in ordernot to complicate to the further processing of the data. Keywords can be added to the blacklist.

22.2.6 server.lst

GESS Q. supports the separation of development and live systems. For copying a completedquestionnaire from the development system to a server, the user interface GESS Q. Admin offersunder Surveys the item Upload . The drop-down menu shows a server list, which GESS Q.finds in the file server.lst. It contains one entry per line for a server in the form of a URL towhere GESS Q. installation is accessible:

https://test1.domain.de/SurveyServlet

http://test2.domain.de/SurveyServlet

22.3 Starting and Ending

With the Windows setup.exe the installation process from the home page creates a shortcuton the desktop called "GESS Q.". This refers to the file startcapi.bat in the the installationfolder and a double click will start GESS Q. Desktop. Under Linux it is sufficient to enter in thecommand line the installation folder ./startcapi.sh. The file noautostart.txt prevents onthe same level that GESS Q. Desktop starts automatically with the default browser.



With the launch of the program under Windows, a command window with the name »GESS Q.«opens, in which the initializing server process writes various messages. At the same time, theweb browser is invoked, in which in a new tab appears the login page of the GESS Q. Server.(The same thing happens under Linux, solely the server messages will appear in the window inwhich the command was entered.)

The program start has launched an internal Web server written in Java, which can be addressedon port 8080 This means the URLs:

• http://localhost:8080

• http://127.0.0.1:8080

• http://[lokale.ip.adresse]:8080

all refer to the login page on the same server on the local computer. With the last option youcan access the server from another computer in the local network

Under Windows the program can be terminated by closing the command window "GESS Q.".Under Linux the server process can be terminated by pressing Strg-c.

22.4 Licensing and Update

The following section explains how the GESS Q. Desktop is licensed on a computer and how aversion update is performed.

22.4.1 Licensing

There are two ways to license a GESS Q. Version: Manually in the file system or via the userinterface. In general, it should be noted that only one version of GESS Q. Desktop must operatein parallel, otherwise they will mutually cancel the license. In addition, the license key does notrecognize the PC again, so that each new license is counted as a new activation.

Licensing in the File System

The file key.lic, sent from GESS, must be saved in the folder config of the installationfolder.

Figure 22.1: Folder - Integration of the License Key



The next start time, when GESS Q. starts, it checks automatically the validity of the licensecode, generates a check.lic file and the file key.lic disappears.

Licensing in the User Interface

Using the User Interface the GESS Q. can be licensed by clicking on the lock. It opens a newlayer in which the full license code should be entered.

Figure 22.2: Interface - Opening and Integration of the License Key

At the end the red lock becomes green. In addition, the company name, the remaining durationand a unique ID is shown within the license. If the license code is changed, this can be enteredby clicking on the (green) lock.

Common Errors in Both Options

• Insufficient user rights – You must have sufficient user rights on the PC in order to beable to perform a licensing.

• No Internet – In order for the license key to be checked is required a connection to theInternet.

• Firewall or similar blocking communication to the server – Port 80 must beenabled.

22.4.2 Update

Under Windows simply run setup.exe and install/overwrite in the directory of the existinginstallation. Individual settings (user, server list, configuration, studies, ...) are preserved.

22.5 Requirements for GESS Q. Desktop

For GESS Q. Desktop there are no significant demands on CPU, memory or HDD. The onlyrequirement is the installation of Java.

• Oracle Java 8

• Postgres 9.1 (in case translation tool is needed locally) - Connection please refer tosection 22.2



• Firefox (for the robot - section 25.2.1)


Chapter 23. The Productive Operation - GESS Q. Server

23 The Productive Operation - GESS Q. Server

23.1 Recommendation for GESS Q. Webserver

In general, almost all of the points on this list are optional. Imperative, however, are therequirements marked with an asterisk.

• A minimum of 2 virtual CPUs (fast processing of inquiries)

• A minimum of 4 GB RAM (more parallel interviews)

• A minimum of 20 GB disk space

• Access via SSH with Root permissions for the maintenance of the GESS Q.

• Preffered OS is Ubuntu Linux 12.04 64bit

• Apache Tomcat 7 *

• Oracle Java 8 *

• Postgres 9.1 (translation tool)

• Mozilla Firefox (headless, locally, no GUI required - for the robot)

• Xvfb (for the robot)

In your interest is a daily backup and a continuous monitoring of the service availability to beset up.


Chapter 24. The Android App - GESS Q. Android

24 The Android App - GESS Q. Android

24.1 General

In addition to standard PCs and servers, GESS Q. can operate on devices that are workingunder Android operating system. With the app GESS Q. Android scripted questionnaires canbe filled out offline as often as desired. The saved data can be sent at a later stage using theUSB or WLAN to the GESS Q. Desktop or on the Internet to the GESS Q. Server. Figure 24.1demonstrates the interaction of the applications with the other GESS Q. products.

Figure 24.1: GESS Q. Android Overview

In this chapter are introduced the special features of the GESS Q. Android App and it isexplained how they can be used. But before it comes to the actual features of Android GESS Q.,it would be useful first to make a general overview of the menu structure and organization of theapplication.

24.2 Menu Navigation and Language

Figure 24.2 illustrates how the interface pages are arranged inside the app. Each page has a menunext to the visible content which gives access to additional functions. This menu is accessible viathe respective device menu button and may vary with the different manufacturers and Androidversions.



Figure 24.2: The User Interfaces

The Home page contains two different login functions and also contains the menu items Info ,License , Update and Exit . In the Login as an Interviewer are used the IDs which areassigned as interviewer names in the studies. After being promoted to enter his interviewers,the user gets a list of the available questionnaires. The selection of a study leads then toStudy Main Menu , where can be started a new interview and cancelled cases can be continuedor deleted, also the finished data records can be transferred to a configured server, when anInternet connection is available.

The Web Server Login however, leads to a GESS Q. typical authentication request with the

information of Company , Name and Password . Already on this Login Page can be configuredvia the menu functions, with which GESS Q. Server will normally communicate with the app.Ones this has been already set, a connection to this server can be made via the Login. A list ofthe studies of the GESS Q. Server is shown, on which the particular login has access authorization.Each study can either be loaded into the app or can be examined more closely in the form of thecurrent Reportings.

The app comes with language resources for English and German. The language, used in the userinterface, depends on the language setting of the Android operating system. In case the languageof the Android system is different, than the existing English setting is the default.

24.3 Installation und Updates

The latest version of Android GESS Q. can always be downloaded from the GESS homepage 1

The app is available as a .apk file. This is an installation file which can be run by any Androidoperating system. Please note that the app is not available at the Google Play Store. In order tobe able to install non Google Play applications, a check mark must be previously checked into thedevice settings. This allows the installation of applications from unknown sources. This usuallycan be found under Device Settings Menu (normaly in the menu Security). The best wayto get the .apk file on the Android device is to copy it directly from the home page or to useUSB data connection to copy it from a PC. The actual installation process is self-explanatory.

Once installed, updating the app is done quickly. The function Update can be found in the MenuHome. If the device has Internet connection, the program checks whether there is published anewer version and if necessary initiates a download and makes new installation. All previoussettings including licensing are retained.

1www.gessgroup.de


http://www.gessgroup.de/qdownload


After installation GESS Q. starts automatically with the startup of the device.

24.4 Licensing and Case Numbers

A freshly installed app is first in demo mode and the program brings the user’s attention on thatregularly. Demo mode means, that the app is fully functional, but does not produce any data.To unlock the app, is required a license code, which can be provided by the GESS at any time,even in the short term.

A license key can be entered in the menu item Licensing on the home page. If Internet connectionis available, the app contacts the GESS license server and if the conditions are met, the device isunlocked. All previously visible (red) notes on the demo mode switch now to the (green) notesfor the remaining license period. The manual typing of license codes on many devices may provequite time consuming. For this reason, a license key can be scanned as a QR Code. In case thedevice has no camera or the camera is sealed, the licensing can be done using the USB control ofthe app. More information under section 24.5.

In case that multiple devices with Android GESS Q. are in use for one survey, GESS Q. mustnevertheless provide unique case numbers. In order to prevent any overlap, each device getsassigned a unique range of 10,000 case numbers during the licensing process. The license serverrecognizes the device again, so it also gets repeatedly the same range.

Additional comments: The situation, concerning Android, but also concerning the producersof devices, can be very different. Especially cheap tablets or rooted devices (possibly equippedwith a different firmware) may encounter a situation, where the license server information, thatholds tablets apart, is missing. The software attempts to find different characteristics of thedevices in order to distinguish them. These include the Android-ID, which should be uniquefor each device, the hardware addresses of WLAN and Bluetooth adapters, the Android versionetc. If for example, multiple tablets from the same manufacturer provide an invalid AndroidID and don’t provide any information about the network adapters, the license server will notbe able to distinguish the devices and will always assigns the same device ID, and consequentlyalso the same case numbers. In that case the problems already begin, with the attempt to copyinterviews with the same case number. It should be ensured in advance that all the tablets areprovided with a respective unique ID.

24.5 Data Exchange via USB

The GESS Q. Android apps can be managed via a USB connection using GESS Q. Desktop forstandard Windows PCs and Linux. To make this work a little preparatory work is required. Atfirst summarized and then in detail:

1. Enabling USB debugging on the Android device

2. Install ADB driver for Android device on the Windows PC respectively adb for each Linuxdistribution, for example, android-tools-adb (Debian / Ubuntu) and set a link (s.u.).

3. Start GESS Q. Android App

4. GESS Q. Desktop initiates communications

The USB data exchange is done via a communication channel, which is typically intended fordevelopment purposes. In order the Android device to be ready for this type of communication,must be activated USB Debugging in the device settings. The corresponding check box isnormally found among the developer options. If this setting is done, Windows installes other



device drivers when re-connecting via USB. In the Device Manager of the Windows ControlPanel the connected device should be listed as ADB-Device etc. If this is not the case, otherdrivers for the device must be selected (often USB compound device respectively USB CompositeDevice) or special ADB drivers must be installed by the manufacturer.

On Linux the program adb.exe in folder config/adb/ must be replaced with the usually globallyinstalled program /usr/bin/adb:

cd config/adb

ln -sf /usr/bin/adb adb.exe

After connecting via USB, it usually takes a few seconds, until the PC correctly detects theconnected device, especially when also are installed drivers. It should be noted that someWindows versions differ each device based on the serial number and it is possibly to install adriver for each newly connected device, despite of the same device type and drivers.

In the user interface GESS Q. Desktop the menu item Android Manager is found. Afterselecting this menu item, GESS Q. Desktop is looking for a GESS Q. Android apps connectedvia USB. Only one app can be administrated at the time. In general, in order to be able torespond to requests via USB, the app must be running on the connected Android device too.Ideal way is to ensure that any operating page of the app is currently visible on the device.

If the connected Android device is eventually successfully detected by GESS Q. Desktop, theAndroid manager provides information about the device and offers some interaction possibilities,please refer to figure 24.3.

Figure 24.3: The Android USB Manager

In the field Connected device the following information is to be found: which version of theapp is on the connected device, whether it is licensed, for how long and with what range ofongoing numbers. For example, the device in the figure works with App version 2.2 r1000, islicensed until 28/02/2015 and uses sequential numbers ranging from 1200000 to 1209999. The



key symbol opens a dialog, which expects a license key ot license the application at this point.

Reset App resets the app completely to its factory setting (incl. removes the license).

The following list contains information about: which questionnaires are currently available in theapp, which users have access to it (interviewer name) and whether any records exist. The buttonswith the Arrow Symbols are used to import the respective data and the Recycle Bin Icon atthe end of each line for removing the study along with the data.

Finally the areas for App-Block and Net-Block give information whether the services are runningor not. A green icon means, that the service is running. With the button on the side, the servicescan be individually started and stopped again. The additional Auto Start Setting manageswhether the services have to be controlled when the application starts and possibly should alwaysbe run automatically at start up. What exactly the services do is described in section 24.6.

The second main functionality in addition to the data import is the Upload of a study to theconnected device. This feature is not found directly on the Android manager, but as part of theupload function. Instead of a web server, the user interface of GESS Q. Desktop provides alsothe possibility to choose an recognized Android device as a destination for uploading. Since theamounts of transferred data are negligibly small for USB transfer rates, the complete studies willalways be transmitted (excluding data records).

24.6 Services App-Block and Net-Block

App-Block and Net-Block are two independent services contained in the app, which can bestarted with the app. The symbols on the Home Page show their current status.

Net-Block prohibits any form of wireless communication. When enabled, Net-Block puts thedevice into airplane mode and disables all wireless communication like WLAN, Bluetooth andInfrared. Further, the state of that connection types is continuously monitored and is ensuredthat they cannot be reactivated. Net-Block can be started and stopped as desired during thesurvey using GESS Q. Script with the JavaScript functions startNetBlockService() and

stopNetBlockService()

App-Block restricts the use of your Android device to GESS Q. Android. In the activated stateno other applications can be used, where the system settings and functions such as the cameracount as apps. As long as App-Block is running, only GESS Q. Android can be used on thedevice.

24.7 Features and JavaScript Functions

In this chapter are listed and described all the features around the app.

24.7.1 Startdefines

Every interview, which is started by GESS Q. Android, uses automatically: #define android

24.7.2 Cancel / Resume of interviews

The option to cancel the interview is always available in the menu during the survey. If the appis licensed and in this case, the datawritecondition requires that also records are to be written,



an abort record is stored. In the Survey Main Menu is found a list of cancelled cases, which canbe recognized by their respective termination date and the case number and can be continued.

24.7.3 writerescuedata

Writerescuedata should always be set the script parameter writerescuedata basically (sec-tion 5.2). If the app or the entire device crashes unexpectedly, the previous entries are alwaysbacked up and there is the possibility of resume the interview in Survey Main Menu . Rescuedrecords can be found in the list of aborted cases and are marked with an "r".

24.7.4 Record Audio (MP3) in the Background

With Android devices that have a microphone (internal or external), voice recordings can bemade. Beginning and ending of the recording are flexibly selectable and can be initiated viaJavaScript functions. For example, this can be done at the click of a button or automaticallywith the display of a page of the questionnaire. The recording can also extend over several pagesand is visualized on the top of the display.

startBackgroundAudioRecording("filename")

starts an audio recording. The audio file is stored with the name "audiofile", as soon as therecording has finished. If a recording has already started, executing this command remainsfunctionless.

stopAudioRecording()

terminates the currently running audio recording.

// Example:

textq audiorec2;

text="Recording continues and ends with a click on next.";

javascript="

startBackgroundAudioRecording('rec_@insert(_caseid)');

$('form').eq(0).submit( function(){

stopAudioRecording();

});

";

At the end GESS Q. Android checks the recording: If the record is too short or too quiet, awarning symbol (head with question mark) appears.

24.7.5 Record Audio (MP3) Selectively via Recorder

As an alternative to recording in the background, a Record Menu can be selectively open. Itdisplays the recording level and makes it apparent, if sound comes to the GESS Q. Android.Record can then be replayed or erased and re-recorded. A maximum recording time can bespecified in seconds. The recorder is always linked to OpenQ, where the file name of the MP3file is saved. By hiding the input field of OpenQ via CSS, it is possible to make the recordingmandatory.

showAudiorecorder("OPENQNAME", SECONDS, [QTEXT])



executing the command opens the Audio recorder menu.

OPENQNAME: Name of OpenQ, that must be present on the Screen

SECONDS: Maximum recording time in seconds

QTEXT: Optional question text in the recorder. By default, the question text of openQ is adopted

// Example:

OpenQ audiorec3;

text="Which book in your newspaper interests you the most?";

title="

<input type='button' value='Record'

onclick=\"showAudiorecorder('audiorec3', 20, 'Please tell us the

reasons for your interest.');\">

";

css="

.qtitle{ text-align:center; }

.qopenfield{ display:none; }

";

Figure 24.4: GESS Q. Android: Audio Record

24.7.6 Take Fotos

With Android devices that have a camera, can be made photos during an interview. The photoscan then be integrated into the survey process. The process of taking photos is executed in thescript along with an OpenQ, which contains the automatically generated name of the image file.The actual command for the camera is made with the JavaScript function openCamera.

openCamera("myOpenQ")

Starts the camera and references to the OpenQ with the name myOpenQ that must be presenton the same display screen. The file name of the captured image is stored in myOpenQ as text.

// Example:

openq cam;

text = "Please click on the button to take a picture.";

title = "<input type='button' value='Camera' onclick=\"openCamera('cam');\">";

css = ".qopenfield{display:none;}"; // hides the input field of the OpenQ



assert (num(cam) gt 0) "You have to take a photo first.";

openq cam_pic;

text = "Why have you photographed this?";

title = "<img width='500px' src='./media/@insert(_surveyname)/@insert(cam)'>";

24.7.7 Net-Block start/stopp

The service Net-Block, described in section 24.6 can be started and stopped as desired withJavaScript functions. For example, this can happen at the click of a button or automaticallywith a displaying the page of the questionnaire. If access to an external resource is needed in thecourse of the interview, (for example, an image or external conjoint) Net-Block can be disabledat the certain point, so that the Android device can be connected to a previously configuredlocal WLAN and be restarted with a connection.

startNetBlockService()

starts Net-Block.

stopNetBlockService()

stops Net-Block.

24.7.8 System Start

The version R843 of the GESS Q. Android app starts automatically with the Android systemstartup.

24.7.9 Play Videos

The GESS Q. Android uses an internal media player for video playback. It can be started viaJavaScript, and then immediately starts a video in full-screen, that exits by itself (only) whenthe video has finished.

playVideo(PATH_TO_VIDEO)

// Example:

TextQ video1;

text="Videoplayer";

javascript="playVideo('/media/@insert(_surveyname)/nilpferd.mp4');";

24.7.10 Web Browsing

If a survey links to external HTML content, it will be presented within the survey window ofGESS Q. Android without opening additional browser app. Along with the JavaScript functionreload external content can be incorporated harmoniously without complicated system change.The concept is explained in the following. It requires some knowledge of JavaScript. We canhelp you with a practical implementation.



reload("JAVASCRIPT")

reloads the current screen of the survey. Instead of JAVASCRIPT can be listed JavaScriptcommands which are inserted at the end of the screen.

Integration of External Survey Modules (JavaScript)

1. Screen A contains JavaScript variable X with the initial value of 1

2. Screen A examines X

a) if X eq 1: Jump to external evaluation module MOD

b) if X eq 2: Move on to Screen B

3. MOD is called

4. At the end of MOD, reload("X = 2;") is execute

5. Screen A reloads and now jumps to Screen B

24.7.11 Number Keypad

If numqinputtype = "number" is set, the Android operating system opens automatically thekey pad, when entering NumQs. However, caution is advised, in case the inputs are desired withdecimals. The presentation of the questionnaire in GESS Q. Android is done in a system internalweb browser. The producers are partially too careful with the numerical input and validate theinput even before the software can grab it. Depending on the language settings of the browser,this may cause unwanted effects in the interpretation of the decimal separator.

24.8 Short Passage: GESS Q. Android on the Tablet

Mainly two scenarios have emerged when performing surveys: In the first case, the Androiddevices must operate as secure as possible and therefore also must (as far as it goes) work withoutnetwork connection (for example standard by Car Clinics). The management of the Androiddevices is then done via the Android manager (please refer to section 25.7) via USB and a PC ora laptop locally. At the beginning the study is copied to each device. After the interview(s), thedata is uploaded to the computer.

In the second case, the Android devices are granted access in a network and after logging candownload the questionnaires from a preconfigured server. The data from the interviews can becopied to the server in the same way. The interface is very minimalistic and straightforward:

Figure 24.5: GESS Q. Android: Home Screen



The selection Login as an interviewer requires login and leads to the selection of the question-naires, available on the device.

Figure 24.6: GESS Q. Android: Login as an Interviewer

After selecting the study, the main menu appears. The selected questionnaire can be started withStart Survey . A checkmark at Testmode ensures that no data will be stored. The program liststhe interviews that have been cancelled, so that they can be continued, if necessary. (internalycancelled interviews are moved to the folder deleted_data). The data from the interviews canbe copied to the preconfigured server using Upload .

Figure 24.7: GESS Q. Android: Main Menu

The questionnaires are hardly different from their online version, as long as the screen of theAndroid device doesn’t set limits. The device’s standard menu (normally »Home«, »Menu«,»Back«) usually remains visible uring the interview and appears under or beside the questionnaire.The back button is disabled by the GESS Q. Android, so that the interviews cannot go back (inmost cases by mistake). The menu button however, offers the function to cancel the interview orto go back to the initial screen from the Main Menu.



Figure 24.8: GESS Q. Android: Questionnaire

For security reasons, a login to the web server requires more entries than the login as an interviewerusing Android device:

Figure 24.9: GESS Q. Android: Login to the Server

After selecting a study, the menu can offer an entry for reporting, along with the downloadingthe study:

Figure 24.10: GESS Q. Android: Reporting as Overview

Control is made by the entries in the page header and can also launch the automatic creation oftables, which summarize the current state of the survey.



Figure 24.11: GESS Q. Android: Reporting in Tables

To the screen, that offers the application at the Web server, also belongs a menu (possiblyaccessible via the menu button) or an entry (usually placed at the top right site, which somewhatdependents upon the Android version), over which the settings are accessible.

Figure 24.12: GESS Q. Android: Settings

There are three settings. The Server URL receives the address of the GESS Q.-server, withwhich the app should connect. The Company and Name specify the items for the Login, sothat only the password must be entered.

After starting GESS Q. on the Android device, the Menu button calls up the entries in thebottom of the page.

Info displays the version number of the software.

License allows the licensing of the software.

Update checks on the preconfigured server if a new version from the software is available.

Exit provides the only way to exit the program normally.



Figure 24.13: GESS Q. Android: Additional Functions

Please note: GESS Q. as App for Android is based on the specifications that Google has setfor Android. Meanwhile, there are unmanageable diversity of Android devices and especially inthe cheap segment, where the Google’s specifications are often not strictly followed. This cancause problems. Therefore GESS recommends to use GESS Q. on a standard Android. If thereis any doubt, the compatibility could also be checked:http://source.android.com/compatibility/cts-intro.html

24.9 Troubleshooting

In case the app responds unexpectedly, this may be caused by various reasons. It may help toreview systematically the following points:

• If the URL for the server is entered correctly in the app?Login on Webserver -> Menu -> Settings

• If the device is actually online or only registered at a local (offline) WLAN? The browsercan give that information, if you try as a test to open an external web page.

• Can the app download the study from the server? -> Login on Webserver

• What serial number did the app get by the licensing and what is the version of the appLogin Screen -> Menu -> InfoPlease also refer to the problems with non-standard compliant Android versions and cheaptablets mentioned in section 24.4.

• If the cases are already on the server and are not properly cleared. Case numbers, whichalready exist on the server, are denied and cannot be uploaded again.

• For troubleshooting, it is always helpful to get a specific unsuccessful case number fromthe interviewer - say, the error should be reproducible in a concrete example.


http://source.android.com/compatibility/cts-intro.html

Chapter 25. The User Interface

25 The User Interface

25.1 General

Although the user interface strives basically to be self-explanatory, some functions require acertain amount of background knowledge to understand what happens in details and what kind ofpossibilities are offered to work with. This chapter describes the user interface with its essentialfunctional capabilities and background processes.

Figure 25.1: GESS Q. Menu

For simplicity, the chapter follows a structure of the user interface with its menu, structured insections. The sections at the left edge of the screen are about Surveys and Main. Reportingis left out because the section only appears when the reporting has been set for a questionnaire inthe section Surveys under the menu item Reporting Setup . When it comes to the configurationof the reporting all the essentials about the theme reporting can be found in section 25.3.8

The entries under Surveys refer exclusively to the study, selected in the drop-down. Thatassumes, of course, that questionnaire is already created. If this is not the case, section 25.8explains how a new study can be applied. In addition, the user, currently logged in, must haveaccess rights for a study, otherwise the section Surveys does not appear. On the other hand,menu items under Main refer to the management interface and to the functionality of the systemoverall as a server.

25.2 Start of interviews

Normally, interviews start when the interviewees open the URL, that they are given (pure onlinesurvey) or get a tablet device with the ongoing questionnaire. For other scenarios, the webinterface of GESS Q. offers further options in the section Start in the Surveys. Since the menuitems in the section Surveys only relate to the study, selected in the drop-down menu, it shouldbe ensured that the right one is selected here.



Figure 25.2: Start of an Interview

By the development of a questionnaire the mask can start the questionnaire for a test. Byclicking on Test Mode the interview starts in testmode. In order to start the interview in thesingle mode (each respondent logs is with an individual ID) or multimode (multiple respondentsuse a shared ID), the ID must be given in the corresponding field. More details on IDs follow insection 25.3.7.

Here, at the start of the interview, for testing purposes, can be made another Define-Statement.This is explained in section 2.4.

25.2.1 Robot: Autofill

Figure 25.3: Start of the Robot

Next to the standard options for starting an interview (test mode, single mode, multimode),the Start Menu also offers the option to send a robot through the interview. The serveruses the installed browser Firefox in order to make a screenshot of every screen, without anyvisual feedback. The mask asks for a URL and the robot starts from there. Specification ofa time periods between the screenshots is optional. How the robot moves through the scriptcan be affected by the script with the script parameters ignoreFilter, ignoreAssert andignoreNoMissing (refer to section 5.2). After the robot has passed through, the browser offersa download of a zip archive, containing the screenshots as PNG files.

Intended is the possibility of using the robot for documentation purposes - to print the fullquestionnaire (for that all three script parameters should be switched on with »yes«). This shouldbe done before the start of a study because with each run the program generates a new interview.In addition, the robot can be used to print a specific interview or to reproduce it on the screen.This is possible under the menu item Data / Export and further under Native Data .

In this way the respondents can be enabled do download the questionnaires that they havecompleted. The internal variable _encryptedcaseid allows to publish the URL because the casenumber only appears encrypted and so doesn’t permits connections to other valid URLs.

group grp_finished;

labels=

1 "Thank you for your participation. You can find your questionnaire here: http

://server.de/SurveyServlet?action=printcase&survey=test&lfd=@insert(

_encryptedcaseid)" (_finished eq 1)



2 "Thanks for your interest. Unfortunately, you do not fit in our target group

." (_finished eq 2)

3 "Thanks for your interest. Unfortunately, enough people with your profile

have participated in this survey" (_finished eq 3)

;

The link works without login to the server and the study does not need to be active.

25.3 Configuration of the Study

Under the key word Configure the web interface holds lots of possibilities to adjust the study.Please make sure that the correct study is selected in the drop-down menu.

Figure 25.4: Configuration of the Study

25.3.1 Enable / Disable

Only active studies are available. Studies that have been created over the Survey Manager of theweb interface are automatically active because the file active.cfg was copied in the study intothe folder of the questionnaire, while creating the framework. GESS Q. uses the file as a switch:if it is present, the study is considered active, whereas if it is not present, the questionnaire isnot active. The mechanism proves to be particularly useful when, for example, the specifiednumber of interviews is reached and the study can be disabled. Latecomers will automaticallysee a message, saying that the study has been closed. Please also refer to Configuration Files inthe Questionnaire Folder.

25.3.2 Export

By clicking on Export , the complete study (questionnaire folder and media folder) will bearchived in a GESS Q. project file and will be offered for a download. Although the file has theextension .qp, it is a zip archive.

25.3.3 Archive

If archivePath is set in the configuration file qonline.cfg (refer to section 22.2.1) - for exampleon archive , the folder archive in the root of the GESS Q. installation serves as an archive.If the parameter is not set, the icon for Archive appears with a »No Entry« sign and has nofunction.



When the archive function is active, GESS Q. puts the study folder and the media folder in onearchive, compresses the file and saves it in the archive folder with the name of the study andan ending .qp. While moving the folders into the archive, GESS Q. deletes the correspondingdirectories of the study in the surveys folder and in the media folder.

25.3.4 Reset

The button Reset cleans up the study folder and sets the study back to the starting point. Thatmeans that log files are removed, ID lists and quotas are reset and also ongoing interviews aredeleted. In general, the function is likely to come in handy when it comes to eliminate the testdata and to prepare the study for the actual interview. If backupPath is defined in qonline.cfg

(refer to section 22.2.1.), at reset GESS Q. sets a backup in the specified directory.

Also during the test operation GESS Q. lays administrative data in the folder of the questionnaire.The following files are included:

respo.lst managed in the GESS Q. book via the IDs, with which the participants are loggingin. The file can also be specified, refer to section 25.3.7.

surveylog.lst managed in the GESS Q. protocol via the individual interviews with start andend times and the last answered question.

lfdcount.lst GESS Q. counts the number of the interviews in lfdcount.lst. File and numberare retained even after a reset.

id_unknown.lst If unknown IDs are allowed, GESS Q. notes the used IDs also in id_unknown.

lst.

25.3.5 Delete

Deletes the study (questionnaire folder and media folder) if the re-queried credentials are enteredcorrectly.

25.3.6 Check Script

There are different possibilities to help yourself by the troubleshooting of scripts of the question-naires. In addition to the output of variables in special, additionally inserted debug questions,the script check is especially helpful. GESS Q. checks if the syntax is correct and outputscorresponding error messages, respectively warns of possible sources of error. These include, forexample, multiple assigning of initActionBlock, resumeActionBlock, startActionBlock, etc.(which overwrite themselves) or questions, defined in the script, which are not even included orare repeatedly included in survey process. In addition, the Script Check provides informationon the total number of screens and helps with the adjustment of the progress bar.

Changes to the script can be made in parallel and the script can be checked again with thebutton load again .

The program indicates errors as a link in dark red in the field for summary at the top of thepage. The link refers to the error location in the complete report, following below. GESS Q. isnot able to deliver a specific number of the line location of the error, because the script can becomposed from individual parts, before the GESS Q. to edit it. Therefore, at this point one mustsettle the source of the error with the approximate locality. This can be the references to thecontent of the questions before and after.



The program displays warnings in chartreuse (a kind of light green). These can be hints to names,that appear on the black list or question, which although scripted are, are not considered in anyblock. The program also warns of certain conditions, such as filters, which address in general anarray, but not a specific value of the array. A script that caused warnings is executable. However,especially with lax formulated filters, it can contain misunderstandings which could lead to errorsin the questionnaire. Therefore, a sea green confirmation is definitely desirable: Script checkfinished successfully!

25.3.7 ID Settings

The conditions for the IDs can be specified over the ID settings .

Figure 25.5: Configuring the Study: IDs

The checkmark at Test mode enabled specifies that a study can also be invoked in the testmode. The checkmark at Accept unknown IDs allows the participation of interviewees, whodon’t have to identify themselves with a stored ID.

The URL Parameters defines the variable names with which the respondents IDs are indetifiedin the URL (default: respid). Often, this plays a role when connecting panels, because the panelshave different defaults here. Even if the parameter can be freely defined at this point, within theGESS Q. script the ID is always accessed with _respid.

With the menu item Manage the individual IDs can be viewed and other actions are performed.

Figure 25.6: Managing of IDs



Automatically up to 10,000 IDs are listed. Furthermore, it can be searched for IDs and the viewcan be filtered with the checkmarks for showing or hiding of Single IDs or Multi IDs. The IDscan also be filtered by their status - Fresh stands for not yet used, and active for currentlyused IDs, cancelled for aborted, and finished for completed interviews.

The status of the individual IDs can be changed in the view and they can also be deleted. Thismay be necessary, for example, if IDs were used for testing purposes and a reset of the studyhas been forgotten. In this case, even after the start of the study, the status of these IDs can beaccessed and set to fresh. Problems with ’faulty’ links can also be fixed like this. For example,if server problems or similar have led to inconsistent ID statuses.

With the menu item Add new random IDs can be generated. In addition to the desired numbera span width must be defined for numeric IDs. Attention must be paid for a sufficiently widerange of values in relation to the desired number of IDs, as the software will stop the process at100 randomly generated duplicate IDs. After entering the desired number of IDs, alphanumericIDs are automatically created with 32 digits of uppercase and lowercase letters and digits from 0to 9. In addition, already existing ID lists can be copied, also the duplicates of existing IDs arerecognized and skipped.

Existing ID information (Single IDs, Multi IDs or all) can be completely erased with Delete .This is password protected. This process (and in general all settings in this menu) affect onlythe ID information - records are not changed or deleted!

By clicking on the both buttons Single IDs and Multi IDs the current ID information is offeredfor download.

For more information on the different survey modes (Test, Single, Multi), the structure of theinvitation link and the panel integration, please also refer to section 21.2.

25.3.8 Reporting Setup

It is configurable, what aspects of an ongoing survey must appear in the reporting:

Figure 25.7: Configuration of a Study: Reporting

overview provides information on ongoing, finished and aborted interviews via a simple graphic.

quota unlocks the quota management, so that the target quotas can be increased or decreasedin an ongoing study.

stats shows basic statistical information about the survey via the menu item Statistics :Contacts in total, terminations, successfully finished interviews; where was cancelled and wherewas finished etc. GESS Q. illustrates this information with pie graphs.



Data Menu has no function yet.

tables shows the tables, which GESStabs automatically produces from the current data. Thisis found under the menu item GESStabs tables . Therefore, GESStabs must be installed.

Changes, made via the web interface, take effect in the file summary.cfg in the folder of thequestionnaire, which stores the five variables (overview, quota, stats, datamenu, tables). Thevariable gets yes or no as value.

How the GESStabs tables should look like, can be determined using the instruction files (*.tab

files). The files can be copied to the server via the upload mechanism GTC files . The directorygtc must be provided in the questionnaire directory. In this way, own tables can each be assignedto the different user accounts (»Login specific GTC tables«).

25.3.9 Quotas

Figure 25.8: Configuring a Study: Quotas

The management of quotas on the administrator level consists not only of editing but also ofadding and deleting of quotas variables. Nevertheless, the variables and quota stands must bedeclared and calculated within the script, Changes are made in the file quotavars.lst.

25.3.10 File System

With the item File System GESS Q. provides information on the files and their coding in thedirectory text. Earlier, longtime users will remember, the coexistence of ASCII, DOS code pagesand ISO encodings was often a problem. Different encodings are not a problem for GESS Q. -they are detected automatically. The output of GESS Q. is always done in UTF-8. For thisreason, it is the essential that the line

<meta name="Content-Type" content="text/html; charset=utf-8"/>

appears in the header of the HTML template. This is the only way to ensures that the output inthe browser with different languages from English to Chinese will have no problem. Also GESSQ. exports the OPN files with UTF-8 encoding.

GESS Q. provides for download all the files of the list (second column), the .q-files are alsoprovided for editing via button with wrench illustration, which means that the files are openeddirectly in the editor, which has set the standards for .q-files



Figure 25.9: Configuring the Study: Character Encoding

If, against all expectations, there is a problem with the encoding, the automatic detection ofGESS Q. can be overridden by creating the file encoding.lst. This arranges line by line theencoding in a file in the form

filename character set

Now there are not so many character sets although the tendency is such and not all charactersets are inevitably treated properly. In this case the short solution would be to generally avoidthe UTF-8.

25.3.11 User Assignment - User Accounts

Under User assignment appears a list of all known users to the system. The accounts that arealready provided with a check have access to the current study. Other users may be assigned tothe study by providing marking the checkbox at the beginning of the line and confirming the listwith the button Save .

In this way, the entries in the file access.lst can be managed.

The user access rights to the study are determined in the user management account (under Mainmenu item Users ) For more about the theme access rights refer to section 22.2.2.

25.3.12 Print - Print Questionnaire

With Print an HTML output for scripted questionnaire can be saved or printed as a PDF. Allthe asserts, filters, labels attributes are shown. Print is ideal for checking of, for example,filter definitions.



25.3.13 Language Management

A question can be understood as a data set, which includes various fields: text, titles, labels

etc. Each field has its own name consisting of a question name (for example, f1) and field names(for example, qqtext), so that the question text is accessed via the appropriate field ( f1_qqtext ).Translations work table-based: The field names in the first column are associated with the textin the second column. It is irrelevant in which language and which alphabet is written the text.The desired language can be set for each interview, as the corresponding translation is assignedto the field names.

Creating the translation table using table calculation has proved to work in the past, but alsoprovided a source of error: HTML formatting in the texts was lost, not all fields were translated,because many of them appear multiple times etc. Therefore GESS Q. offers a unique approachto create and manage translations. The basic principle remains the same: The field name in thetable is assigned with a translation. But GESS Q. also brings some special features that makethe translation easier.

Requirement for language management is a PostgreSQL database. Which database and howmust be used by GESS Q. is determined in the file qonline.cfg. For more details please referto section 22.2.1.

Figure 25.10: Language Management

In the figure 25.10 the box Native language appears filled, because a translation has alreadybeen created. If no translation exists, the box contains only a warning triangle and the wrenchsign. By clicking on the wrench sign appears the option to create a translation table. By clickingon Rebuild & Save appears a choice, through which the source language, used in the script, canbe set. When the selection is made, GESS Q. generates a two-column overview: on the left is thefield with the names and on the right, the field with the contents. The table can be downloadedusing the Download Button. Back in the overview of the language management, the box »NativeLanguage« now identifies the output language and displays the date on which the initial tablehas been created.

In the box on the side we can add tables for the translation using the button Add LanguageThe click opens again the language selection with which we can specify the abbreviation for thetarget language of this table. Then, the overview shows the language ID and the language, aswell as the date on which the table was last modified. The table for the translation is openedwith the wrench button (see below). With the arrow icon under Import available, existingtranslation files (.lrs) can be imported, creating a new translation as a basis in the database.In this way, language variations can be handled. For example, an existing German translationcan be imported for the Austrian version and there, only the deviations must be corrected.

Clicking on the plus sign under Assigned Translators allows assigning each language table toone or more translators. Clicking on the plus sign opens the selection for the translators and



shows the user names which are registered in the user table (refer to section 25.9) with therole Translator and are assigned in the study with User Assignment (refer to section 25.3.11).Click on the white field opens the list of translators. Click on the name assigns the selected as atranslator. The individual entries can be removed again from the list with a click on the »x«.

After clicking on the diskette icon, GESS Q. offers to save the translation table with the file namelanguage code .lrs (for example for French, »fr.lrs«). The system stores the table in the scriptdirectory and from there it can be read in the script with the instruction readTextRessource.Refer to section 14.2.

If the translation is changed, only the language tables must once again be saved as lrs file, sothat it can be read by the next start of an interview. On the other hand, if the questionnaire ischanged with adding questions or changing the names of the questions, the basic database tablemust be rebuild. This is done with the wrench button, under Native language by clicking on

Rebuild & Save . A rebuild of the script language can be done at any time. New texts are addedautomatically, no longer available texts are removed (but not deleted from the database) andmodified texts are marked in orange. So if a question is changed from SingleQ to SingleGrid;question, question title, interviewer instructions etc. are preserved as long as the names ofthe questions remain identical. If the name of the question is changed, it must be translatedagain completely. If everything in the script is changed to its original state, the old translationinformation emerges again (orange).

The Translation Tool

Figure 25.11: The Translation Table

Figure 25.11 shows a table with English as a source language in the script (en) and the translationin Russian (ru). The table is sorted by field name, thus it shows the fields of one question nextto each other. In the section shown GESS Q. has identified total of 881 fields that have to betranslated. The system has found no problems with 823 existing translations (the links aremarked with green). By eight translations, GESS Q. warns (marked yellow) that the source texthas been changed again after the translation. In order to remove the warning, the translationmust be corrected or confirmed. The system marks the number of the translations with possibleerror, because elements from the source text (HTML formatting, GESS Q. instructions) arenot included or are faulty in the translation. 50 fields (marked white) are not translated. Thebuttons with the number of fields also function as a filter: after a click on the eight, marked inyellow, the table only shows the eight translations, which have to be inspected. A click on the881 disables the filter again and displays the first page with 250 entries.

Text, that don’t have content for translation but consist only of key words like @insert() orHTML content, are filtered automatically.

With an entry in the search field and a click on the magnifying glass, the view is limited to the



entries that contain the search term. This also applies to the field names, so that for examplethe search for »f1_« will show all the fields that contain that string. Again here, the buttonswork as a filter and by clicking on the yellow button, we can narrow the view of the fields to thetranslations that has been changed. In order to cancel the filtered view, the search box must beemptied. The search term QSYNTAX returns all texts with special syntactic features (for example,HTML, GESS Q. commands).

Only the blank fields in the right column must be filled out for the actual translation. Thereare some particularities: If the cursor is placed in the next field, the system checks the entry. Ifa text occurs often, it is offered, as shown in figure 25.12, that all occurrences in the text areprovided with the selected translation.

Figure 25.12: Confirmation: Translate All Occurrences

GESS Q. accommodates small marks additional information between the script text and thetranslation:

• A check marked in green means ok.

• A exclamation marked in red indicates a problem with the translation and describeswhen the mouse pointer is hovered over it.

• The clock symbol marked in gray indicates that the translation has been changed. Aclick on the icon displays the previous versions of the translation.

25.3.14 Translations

The texts that make up a questionnaire must be translated in order to perform studies in multiplelanguages A file for translation can be downloaded with the button Language resource (Defaultfile name: def_lang.lrs) The file consists of two columns: The first column (before the firstspace) contains the unique identifier for each text in the questionnaire; the second column (afterthe first space) contains the text.

The identifiers (in the first column) and the translated texts (in the second column) are arrangedin a individual file - separated by a space. Such a language file can be read by GESS Q. at thebeginning of an interview in order to output the questionnaire in the requested language.

As a rule, csv plays a role as an exchange format, because it is easy to work on the translationtables with spreadsheet programs such as Excel.

25.3.15 Expanded Script

For debugging, it may be useful to look at the full script, as it is executed by GESS Q. Thismeans that GESS Q. excludes all the separations to different files that are combined via include

statements, all blank lines that have been inserted in the script for organized structure and alsoall macros are expanded. Then, GESS Q. offers for download the complete script under the nameskript_expanded.q.



25.3.16 Logfile

GESS Q. builds protocol in the questionnaire folder using the individual interviewer IDs. Therecord includes information about: when and on which question interviews were started, ended orwere cancelled. The corresponding file surveylog.lst is offered for download with the buttonLogfile .

25.4 Upload of Studies

The menu item Upload can be used to copy a questionnaire from the development system tothe test environment on the production server or on an Android device.

25.4.1 Server Upload

The server for the upload must be selected from the drop-down list. The content of the list isdetermined by the file server.lst in the config folder (refer to section section 22.2.6).

Figure 25.13: Uploading Studies

The user must also have an account with the same login on the target system, He must at leasthave the access right reduced. If the study already exists, perhaps it only should be updated, itmust be deactivated before uploading on the destination server.

Individual components of the study can be selected respectively skipped when uploading to theserver:

GTC folder The folder gtc with the instructions for the automated creation of tables usingGESStabs.

Text folder The script folder itself, in which the file skript.q must be located.

Media folder The data directory of the study with the graphic elements.

Quota The files quotavars.lst and, if descriptions of quotas are present, qdesc.lst

IDs copies the local state of the ID lists in the files respo.lst and respm.lst.

Datasets copies the interviews.

Config files copies on the server the configuration files access.lst (please refer to sec-tion 22.2.2), active.cfg, idproperties.cfg and title.txt. Details of the last three files canbe found in the overview Configuration Files in the Questionnaire Folder.



25.4.2 Android Upload

If GESS Q. notices an Android device in the USB port, it automatically offers the option tocopy the study to the device. In contrast to the various server options, the study can only becompletely copied to Android. As an option, the program only offers to skip the media directorywhen copying.

If the questionnaire that is to be copied, already exists on the device, it will be only updated withthe upload, otherwise the study will be created again. The difference is noticeable on tablets,especially by the case numbers: The update leaves it with the ongoing count and in newly createdquestionnaires the count starts from the beginning.

25.5 Data and Export

Figure 25.14: Data and Export Options

Before we get to the subject of data export some information on the initial data, the so-calledraw data.

Each interview is stored in a separate data set. In addition to the actual user data, the recordcontains futher information as, for example: dates, times, duration information; if necessary,information about the duration per question.

The raw data is stored under variable names, assigned during the interview. This has theenormous advantage, that one don’t have to worry in advance about a record structure or apossible separation in columns. Even if, after the half of the period, it turns out that the customerwould like to extend a label list; for example would like to include questions 2a and 2b betweenquestion 2 and question 3, or the Multiq should now have 20 questions instead of 15, the question5 is to be subsequently filtered - there is no problem. With GESS Q. the column shifts andcolumns plans belong to the past.

Now let’s look once again at the interface for the data export:



Figure 25.15: Interface for the Data Export

back to the previous screen

reload current screen

accesses the view for the data export

displays the current number of records. Over the wrench menu, we access theEdit Data .

25.5.1 Edit Data

Figure 25.16: Edit data

The page provides information on the data records, which are available at the moment. Thetable marks the status with flags with different colors (green: completed, yellow: not completed);shows the case number, assigned by the system, the interviewee ID, the date, on the date onwhich the interview was started, and the number of interruptions. By clicking on the columnheader, the overview can be sorted by each column.

The icons at the end of the line allow different ways of access to each record: View (magnifyingglass), print (printer), edit (wrench), delete (recycle bin). By accessing using the magnifyingglass not simply the record is displayed. GESS Q. goes through the individual screens, as therespondent has filled them. For that, the interview is started once again with negative case



number, so the interview view cannot be started in parallel again. A new start will not workuntill the system has removed the »artificial« record.

Through the printer, the system offers screenshots of each filled screens as one .zip archive of.Here, GESS Q. uses the same mechanism like by the integrated Robot for screenshots: theinterview is started again with negative case number and the screen are filled as specified in therecord. (for details, refer to section 25.2.1).

The wrench opens another selection window. All the variables of the data record are listed there.

Figure 25.17: Access to All Variables in the Data Record

The wrench after each variable gives the option to change the value of the variable. (Note: GESSQ. doesn’t check the input at this point. In this case SingleQ could also receive an alphabeticvalue). A record can be deleted with the recycle bin option. While deleting the quotas areautomatically counted down, log entries removed and thus the statistics are takes into account.

Figure 25.18: available data

You have the option to delete records for the selected period. Here you have to mark the box onthe left and then click on Delete Selected

Please be careful, there is no undo function.

A green flag means that this is a complete interview. A yellow flag means that the interview isincomplete. With the wrench you can reach the data record and edit it.



Figure 25.19: edit dataset

Here we are in the record with the number 1234-1. You can see all variables for this record andmake changes if necessary. If you have made any changes, please, confirm these with Save .

Please be careful, there is no undo function.

As already described, this record consists of the variable name and the corresponding inputs. Inthe next step we will create a complete data from the individual records. For this we need theso-called colmap.

25.5.2 Column Mapping (colmap.lst)

At the beginning of the data export you will see the following:

Figure 25.20: First Step of the Data Export

That means that currently the system has no information on how the data is going to be built.If you click on the wrench, GESS Q. reads the file skript.q and processes it. This is the filethat you previously scripted and with which the data is layed.

GESS Q. generates a column map and every variable is assigned a fixed place in the record. Ifyou have to change your scrip, since you might want to add the aforementioned questions 2aand 2b, you’ll have to generate a new colmap.lst file at the end. With this is demonstrated thestrength of the individual record for each respondent.

The questions 2a and 2b were not in the already layed data. Therefore the variables don’t appearin the respective raw data record. For the new respondents the new questions remain emptyin the total data record, simply because the assignment in the data record is made using thevariable names and is not based on a fixed column map.

However you should avoid changing the variable types while the survey is in the field. This canlead to unwanted side effects, for example, if you make a Numq out of a Multiq. This would alsochange the variable name for example F2 to F2.1. Making a MultiQ from a SingleQ functionswithout a risk, but in the other direction in will go wrong.

With a click on the wrench the following view is displayed:



Figure 25.21: Data Export: Generate colmap.lst

At this point you can generate a colmap or also upload an already generated one. Let’s limitourselves at this point with Rebuild & Save .

We see the following after the generation of Colmap.lst:

Figure 25.22: Content of colmap

On the left you see the content of colmap (GESS Q. writes a set of internal variables at thebeginning of the table. These were addressed in chapter 9.). The 3 buttons on the right areself-explanatory: With the Rebuild & Save the file colmap is generated again, with Downloadcolmap can be downloaded, edited - in order to possibly not take certain variables in the completedata record. With Upload you can upload it again and use it for the further data export. Withthe little green arrow you go back again and see the following screen:

Figure 25.23: Generated Colmap

In the box at the left you can see when the Colmap was created. A variable definition file isautomatically created together with Colmap. You can edit it immediately further with GESStabs.

Let us take a look at the wrench in the middle box. The wrench brings us to the heart of thedata export where the variable definitions and the data records are merged into the completedata set in combination with the Colmap.



25.5.3 Variable Definition (var.inc)

Here you can see a section of the var.inc. GESS Q. declares again the internal variable,mentioned in chapter 9, and puts a sys in front of the variable name.

Figure 25.24: Editing Options for the var.inc file

You can download this variable definition with the button Download .

You can adjust variable definitions to suit your needs with Rebuild & Save .

Figure 25.25: Options by Saving the var.inc file

By encoding you can set (ANSI, UTF-8, UTF-16). It depends on the platform on which you areworking. Typically, you don’t need to set anything here.

You can choose the language in which the variable definition is outputted using the itemLanguage . As example, you have an international study in multiple languages. You can nowspecify if your SPSS data record is displayed in the native language (the language of the script)or in another language, used in the study.



Figure 25.26: Translation Options when Saving the var.inc file

For example in this study, you can create a SPSS data record, labeled in German or in English,or a ASCII data record with a German or English data description.

GESS Q. removes the filter from the file var.inc, important for the further processing, withthe setting legacy in Type. The export should always work with this setting. When choosingnormal GESS Q. provides the file var.inc with more information - for example the takes overthe filter in the questionnaire.

In GESS Q. the formatting of the screens for the questionnaires are made with HTML tags, butthese cannot be used by any software for further processing. Here you have the option to removethe HTML tags in advance. The same applies to system comments.

25.5.4 ASCII, OPN and SPSS Files

Figure 25.27: Save ASCII Data Record or SPSS Data Record

This leads us to the last box to the right. Here, you can choose if you want to generate anASCII data record or a SPSS data record. At this point we recommend our basic tutorial for thetabulation, which can be found on our home page. It clearly explains the difference betweenASCII and SPSS data sets. (http://gessgroup.de/de/content/software/gess-tabs-dokumentation).

The button OPN is interesting.

In addition to the classic variable types singleq, numq and multiq), GESS Q. also supportsother variable types. One of these is openq.

This variable type can be used for open-ended questions, as well as, for example, to take picturesor record sound or videos. This requires an Android operating system, which can be found onmany tablets or smartphones.


http://gessgroup.de/de/content/software/gess-tabs-dokumentation


After clicking on the button OPN we see the following:

Figure 25.28: Save Open Answers

One option is to save the literal answers as opn file, which can be used by GESStabs directly.You can also save as CSV file, so you can use for example Excel to work with it. In addition, youhave the option to add more variables to these files: For example, in a question about preference,the coder can also be given the variable, where the preferred product is stored.

If image files, audio files or video files are required in a study, these are clearly managed for eachrespondent as links in an Excel file. The files can be accessed directly form the Exel file. GESSQ. provides additional field next to the links to the multimedia files the Excel file. There, forexample, the transcriptions can be entered.

25.6 Overview

In the field Main with the item Overview GESS Q. gives information via diagrams aboutongoing, finished and failed interviews to any active study.

25.7 Android Manager

The menu item Android Manager gives the option to manage a connected USB Android device.GESS Q. informs about software and license on the instrument and allows downloading ofinterviews. It also offers the control of two security aspects of GESS Q. on the device, withNet-Block and App-Block.

The interface controls the Google software adb (Android Debug Bridge), which is installedtogether with GESS Q. On Windows, the program adb.exe is accessed directly. On Linuxthe program adb.exe in the folder config/adb/ can be replaced with a link to the program/usr/bin/adb, which is usually globally installed:

cd config/adb

ln -sf /usr/bin/adb adb.exe



In the Developer Options of the device the item USB debugging must be activated, so Androidcan be addressed by GESS Q. Normally the Developer Options are not visible. These can bedisplayed by consecutively tapping on the field Build Number ->Settings ->About <Device>.

Figure 25.29: Android Manager: Connected Device

Over Connected Device GESS Q. gives information about the device, the software version andwith the wrench symbol gives the option of licensing the device with a license number. TheReset button resets the device to factory defaults. The licensing information is lost in this case.

Figure 25.30: Android Manager: Blocker

Net-Block blocks Wlan, Bluetooth and Infrared, so prevents any network connection. App-Block

limits the operation of the device to GESS Q. Android, other apps (such as the camera) cannotbe started. Green icons show if a block is active or if the services start automatically. BothNet-Block and App-Block remain active even after the device is restarted. The two servicesindicate the operation on the welcome screen of GESS Q. Android of the device with green (on)or red (off) icons.

Figure 25.31: Android Manager: Surveys

The program provides information which questionnaires are available on the device in thequestionnaire overview, Each questionnaire is indicated with name and title, and the access.lst(who has access to the study). The number of completed and cancelled interviews appearsunder Completed and Cancelled. A third column appears if media files must be created duringthe interview, for example audio recordings. The number of the media files is shown there. Ifinterviews or media files are available, a clickable arrow will appear next to the number. The filescan be copied to the computer with it. The questionnaire can be deleted from the device withthe icon at the end of the line. Please note: Interviews on the devices are assigned ongoing



numbers (device ID + case number). If a questionnaire is deleted and downloaded again, thecount of the case numbers starts from the beginning. After updating the questionnaire usingUpload , the count is maintained and continued (refer to section 25.4.2).

25.8 Survey Manager - Creating New Studies

Also new studies can be created, with the local web interface. A new study can be providedwith a name (the folder name) and a title. This option is found in section Main, menu itemSurvey Manager , under the tab New . The name, as all variables, may only consist of theletters "a" to "z", "A" to "Z", the numbers and the underscore character. If available, the studycan also be provided with a template for the design of the questionnaire, using the drop downmenu Use model . The menu item Survey Manager is not available for server installations,because locally generated studies can be copied to the server via upload. Refer to section 25.4.1.

With a click on Create GESS Q. creates a folder with the desired name in the surveyPath andone in the mediaRoot (the two variables include the paths, set during the installation). Refer tosection 22.2.1. GESS Q. copies the graphical components of the selected template in the mediafolder. A set of files is copied to the questionnaire folder - its function must be explained.

By the selection of a template, GESS Q. accesses the templates found in CONFIG/models andillustrates them with preview images from SERVER-ROOT/model_previews. Of course, theselection of templates can also be expanded.

GESS Q. offers the possibility to import a GESS Q. project file with the tab Import , as it would

be exported using Configure with the button Export . For safety reasons, the import will fail ifa directory with the name of the study already exists in the study folder or in the archives folder.

25.8.1 Configuration Files in the Questionnaire Folder

access.lst The file contains the IDs of the users who can access the study. The file is part ofthe selected template.

active.cfg In the file itself stands simply »dummy«, since it only serves as a switch thatindicates to the server whether the study is active or not. If the file does not exist, the serveranswers the inquire of the questionnaire with the message »The survey is currently inactive«,otherwise the questionnaire appears. The file can be created or deleted in section Surveys underthe menu item Configure by changing the status - ( Activate ) to create and ( Deactivate ) todelete.

idproperties.cfg Using the key words, the file determines if the interviewee needs an IDnumber and what must be the name of the variable for an ID:

acceptUnknown=[yes|no] Will participants have access to the questionnaire with unknown ID?Default: yes.

testMode=[yes|no] Should the questionnaire be accessible in test mode?Default: yes.

urlName=[character] The ID receives a variable name (for example, respid=12345) in the URL,with which the participant accesses the questionnaire. Panels have very different ideas how thevariable should be called.Default: respid (for respondent id).



title.txt The file contains the title of the study as it was entered by creating the questionnairein the Survey Manager in the field Title.

25.8.2 File Templates in the Questionnaire Folder in text

skript.q The file skript.q in the text folder of a questionnaire is always the starting point.An example is copied in the text folder via the selected template. This can be used as startingpoint.

formats.q is integrated in the script via the include mechanism in the file skript.q.

25.9 Users - User Management

We can receive an overview of all users over the link Users in the field Main. The overview isunsorted (it shows the content of the file users.lst) and identifies every user with five fields:

company The company, to which the user belongs.

name The login name of the user.

password The server stores the passwords in this file as a hash, a fingerprint of the actualpassword. At each logon the hash of the entered passwords is determined and compared to thestored fingerprint.

id contains the unique name of an account.

access The field shows the access rights. For more on the subject of access rights refer tosection 22.2.2.

The end of the table consists of three buttons with which the accounts can be managed in thesystem:

New user After a click appears a mask. It has fields for company, login name, password andID. The entries may only consist of alphanumeric characters: a-z A-Z 0-9. Company, name andpassword must be entered (as indicated by the asterisk) that ID is optionally composed of theCompany and Name fields. The ID is composed of the fields company and name. The ID of theaccount must be unique.

Remove user The account, marked with the radio button at the beginning of the line, can beremoved with the click on the button.

Edit user The account, marked with the radio button at the beginning of the line, can be editedwith the click on the button.

In any case the web interface of GESS Q. will not store the password itself but only the SHA1fingerprint. If a password should be stored in plain text, the file users.lst in the folder config

should be edited.

25.10 Help - References to Other Sources of Information

Under the item Help in Readme you can find links to the continuously updated informationabout new developments. More about GESS GmbH and GESS Q. can be found on Youtube,Facebook and Google+.


http://gessgroup.de/dokuwiki/public:qdot:readme

http://www.youtube.com/user/gesssoftware

http://www.facebook.com/GESS.Software

https://plus.google.com/110494047193934810958


25.11 Server Status

Figure 25.32: Server status

GESS Q. gives information about the memory usage and the software version over theServer status . To check if a new software version is available, you can click on the magnifyingglass icon next to the field »GESS Q. Version«.

Furthermore, the program reveals which questionnaires are currently filled, how many interviewstake place at the moment and which questions are currently being answered. A check on»Auto reload« ensures that the data is continuously kept up to date. Ongoing interviews,which are marked in the list, can be stopped or put into cancelation state, using the buttonFreeze interviews For the selection of interviews that should be stopped »Auto reload« must beswitched off.

25.12 Tables

This chapter explains the integration of GESStabs for purposes of online reporting as flexiblecustomer interface. The following steps are needed in order to use GESStabs during studies fortabulation of the actual data:

1. Setting up GESStabs on the survey server (done once)

2. Definition of the tables

3. Customer specific jobs for making tables

25.12.1 Setting up GESStabs on the Survey Server

Starting from an existing GESStabs installation (for information, refer to the GESStabs docu-mentation), two entries must be made in the GESS Q. configuration file: The path to the studyfolder gtcSurveyDir, the path to the executable application GESStabs gtcApp. The exampleshows a possible configuration:

gtcSurveyDir=/home/gessuser/surveys

gtcApp=/home/gessuser/gtc/gtc

25.12.2 Definition of the Tables

Each tabulation in GESStabs starts with the execution of a.tab file. It must be found in thestudy folder next to text in the folder gtc. If there is no other explicit instruction (refer tosection 25.12.3), the .tab file has the default name a.tab. GESS Q. provides copies of theautomatically generated ASCII and OPN data records for every inquiry for table (refer to



section 25.5). Along with a copy of the variable definition (var.inc), also found here, these filesrepresent the data base for GESStabs:

cmpl_tabs.dat - completed in ASCII format

cmpl_tabs.opn - open entry of the completed in the OPN format

brk_tabs.dat - cancelled in the ASCII format

brk_tabs.opn - pen entry for cancelled the OPN format

var_tabs.inc - definition of variables

The file with the instructions for the table maker a.tab can hereby be freely defined. Ifinstructions file is not available, GESS Q. helps itself by copying a standard template of thea.tab file from /CONFIG/gtc/ on its place and using it. Normally, this standard case makes asimple tallying over all variables in completes (see below) How the standard is supposed to looklike can again can be defined freely.

encoding = latin1;

splitchar = ~;

stylefile = style.css;

trimstrings = yes;

citefirstvar = TOPTEXT yvalid;

datafile = cmpl_tabs.dat;

casenumber = 31 30;

openqfile = cmpl_tabs.opn;

include = var_tabs.inc;

html = htmltabs;

codebook;

end;

25.12.3 Customer Specific Tables

Specific tables can be stored for different customers or their logins. This can be done withmultiple table maker files, to which the Login IDs can be assigned. Logins without explicitassignment received by default the a.tab. The assigning is optional and can be done using theuser interface in the study configuration.


Chapter 26. Other Features and Help

26 Other Features and Help

26.1 HTTP Requests

By now GESS Q. includes a small collection of useful, independent HTTP requests which arepresented below.

getRemoteContentByURL sets the GESS Q. server as pure forwarding point. It gets the datafrom URL and forwards it. This is very useful in a survey, if one must, for example, accessinformation of the client, located in a XML file on its own server. Modern browsers followthe same-origin-policy and for security reasons doesn’t allow access to a foreign server underscript control. The request getRemoteContentByURL makes it look for the browser, as if thedata comes directly from the server itself and not from the remote address.

http://SERVER-URL?SurveyServlet?action=getremotecontentbyurl&url=URL

// The address that is transffered as url must be coded http compliant.

// Best use via JavaScript:

"http://" + window.document.location.host +"/SurveyServlet?action=

getremotecontentbyurl&url=http%3A%2F%2Fwww.gessgroup.de%2infos.xml"

getStatus retrieves various server details that give information about things like GESS Q.version, capacity, response time, etc. The function can serve for the server monitoring, forexample, to send notifications via email in case of problems.

http://SERVER-URL?SurveyServlet?action=getstatus


Chapter 27. Bug Hunting

27 Bug Hunting

All softwares are prone to errors. There are many reasons why the attempts of preliminaryexcluding of errors and their sources are unsuccessful so far. The programmed questionnairesmake a software by themselves, therefore more often the situation occurs, searching of errors inthe script to be necessary.

27.1 Script Check

The starting point is the Script check that is offered in the graphical user interface in the fieldSurveys under Configure (GESS Q. Desktop or GESS Q. Server). The test does not provideinformation about the exact error lines, but shows the context in question, in which an erroroccurs. The Script check takes various sources of error into consideration and indicates thesyntax errors such as invalid characters in variable names or an incorrectly defined Opennumformat. The Script check takes into account also the process and warns about any questionsthat are not included in the interview sequence.

The written script is different from the executed script, because GESS Q. brings together theindividual files from which the script consists and then replaces all the placeholders and macroswith actual values. Therefore, with macros can be particularly helpful, also to keep the expandedscript in mind. It can be downloaded with Expanded script , (available at Configure ).

Under certain circumstances, an error could occur for the first time at a later stage, although itdoes not appear at the source. In such a case taking a part of the script gradually, in order toisolate the source of errors, can help.

27.2 Variables value check

Another approach is to investigate the values taken by variables. That can be done most easilythrough the @insert-reach mechanism.

textq debug;

text="

1: @insert(nq.1) <br />



numq: @insert(nq)

";

The example outputs the different values of a NumQ, individually at the designated points ofthe array and finally the total array. It works exclusively in real text fields such as text=""; ,

title=""; , etc... Variables can also appear in other locations in a script. Therefore, the sameinformation can also be reached by print-command in an action block, which is attached to thequestion.

continueActionBlock={

print(nq.1);

print(nq.2);

print(nq.3);

print(nq);

};


Chapter 27. Bug Hunting

Through the print-command,the values in a file called actionlog.txt in text-directory arewritten:

PrintAction: variable: nq.1; value: 4.0



PrintAction: variable: nq; value: 4.0 5.0 6.0

Since @insert is not available in the actionblocks, the variables in there can only be checkedwith print. It is also indispensable to be able to keep an eye on the self-defined and calculatedvariables that occur solely in action blocks.

27.3 HTML-output check

Errors that occur in the presentation of the questionnaire in the browser are probably not causedby the script itself, more likely they are generated by the relevant CSS- or JavaScript-codes, whichcan be located not only in the script file, but also in its template. Most current browsers providea ready possibility to examine in detail the GESS Q. generated HTML-page (->Right-click onan item in the page ->examine an element). For Firefox with a Firebug exists an old plugin thatenables different layers of an HTML page, from the HTML-code through the CSS-file in details,up to the structure representation or the views of the JavaScript-code.


Index

Index

.apk File, 172/* */, 6//, 6@back, 102@body, 102@cancel, 102@dummy, 102@error, 101@form, 102@forward, 102, 159@header, 102@htmllabels, 102@input, 16, 28, 101@insert, 48@insert(), 159@javascript, 102@language, 102@open, 16, 28@pbar, 102@posthelptext, 101@prehelptext, 101@qtext, 101@src, 52@src1 ... @src4, 102@submit, 102@surveyname, 102@target, 135@tt1 ... @tt8, 101#define, 6#endif, 6#endmacro, 7#ifdef, 6#ifndef, 6#include, 6#macro, 7$surveyname, 101, 102_breakcount, 63_browser, 64_cancel, 65_caseid, 64_currentScreen, 63_currentdate, 63_currentmillis, 63_currenttime, 63_duration, 63_encryptedcaseid, 64, 185_finishdate, 63

_finished, 64, 74, 86, 159_finishtime, 63_idmode, 63_missing, 63_os, 64_randomid, 63_respid, 64, 159, 188_resume, 65_revision, 63_startdate, 63_startdayofweek, 63_starttime, 63_surveyname, 63_useragent, 633DRotationViewer, 152

a.tab, 207access.lst, 166, 191, 205Action Block, 88Action Command, 88active.cfg, 205ADb Driver, 173adbApp, 163add, 89AddProperty, 41always, 22, 25anchorText, 18, 20Answer Order, 106appendText, 60, 90archivePath, 163Arithmetic Operators, 56Array, 61ArrayInitMode, 36arraySortOrder, 79ASCII, 190assert, 64, 74attempts, 74Audio-Record

GESS Q. Android, 176autoChangePBar, 36automatic forwarding, 86

Back Button, 118BackButton, 41BackButtonCnd, 42BackButtonSrc, 42backButtonSrc (HTML parameter), 119


Index

BackButtonText, 42backupPath, 163bipolar, 20Bipolar Scales, 20Blacklist, 166Block, 32Block Counter, 60block_, 60brk_tabs.dat, 207brk_tabs.opn, 207BrowserNavigationMessage, 42button_checked, 106button_checked (HTML properties), 106button_inactive, 107button_inactive (HTML properties), 106button_preview, 108button_preview (HTML properties), 108button_unchecked, 107button_unchecked (HTML properties), 106

Cancel Button, 118Cancel Code, 65CancelButton, 42cancelButton, 65CancelButtonCnd, 42CancelButtonSrc, 42cancelButtonSrc (HTML parameter), 119CancelButtonText, 42cancelMenu, 65cancelMenuDefault, 65cancelMenuErrorMsg, 65Case Number, 64Case Number, GESS Q. Android, 173changePBar, 90changepBar, 72, 103ChangeProperty, 43Character set, character encoding, 190clear, 90ClearScreenOnBack, 36Click Order, 106cmpl_tabs.dat, 207cmpl_tabs.opn, 207cmplActionBlock, 88colspan, 51column, 33, 50Comment, 6CompletedExitCode, 36compute, 56, 88ComputeMissingAsZero, 37Conditions, 67containsText, 68

continueActionBlock, 88ContinueButton, 43ContinueButtonCnd, 43ContinueButtonSrc, 43continueButtonSrc (HTML parameter), 119ContinueButtonText, 43Control Structures, 98coordinates, 147count, 68count_block, 60CreateDefaultSortId, 37createDefaultSortId, 80CreateLabelOpenValidation, 37CSS

text area, 114text_area, 10

CSS Classcheckable, 117numinput, 128numq, 128qanchortext, 111qbuttoncell, 110qcolseparator, 112qerror, 110, 128qgriderrorcell, 112qgridheader, 111qgridspacing, 111qhighlight, 112, 117qitemtextcell, 111qlabelopen, 110qlabeltextcell, 110, 128qopencell, 110qrightitemtextcell, 112qrowclass, 112qscreencell, 112qslidercell, 128qsliderleftlabelcell, 128qslidermoved, 128qsliderrest, 128qsliderrightlabelcell, 128qslidersum, 128qsliderunspecifybuttoncell, 128qsliderunspecifytextcell, 128qslidervaluecell, 128qtable, 110qtext, 110, 128qtextitemcell, 111qtextlabelcell, 110, 128qtitle, 110, 128qvlabelcell, 110


Index

rotationViewer, 153CSS media queries, 115CssLayout (HTML parameter), 43cssLayout (HTML parameter), 112current, 82

DataWriteCondition, 37Date, 63dec, 90DecimalFormat, 49DecisionVar, 59DefaultNoMissing, 37defaultnomissing, 124Define, 6Demo Version, 2DictFileVar, 59Directionals, 20DisableExitOnAssert, 37docPath, 163documentRoot*, 163Dynamic Screen Content, 54

else, 98Embed audio, 141EnableTextReplace, 38Encoding, 190EndIf, 6eq, 67ErrorPostText, 43ErrorPreText, 43Examination by Arrays and Multivariable,

68exists, 69exit, 74, 86, 90Exit-Code, 64exit-code, 86export, 56ext, 64

Filter, 67findMaxValIndex, 90findMinValIndex, 90finish forward, 87finishForward, 86, 159flt, 25, 33, 71formats.q, 206forwarding, automatic, 86Full Version, 2Funktions and Conditions, 68

ge, 67GESS JavaScript Library, 105

GESS Q. Android, 1, 171GESS Q. Desktop, 1

Configuration, 162GESS Q. Server, 1getCountValue, 91getRemoteContentByURL, 209getStatus, 209GNumQ, 17Grid-Question, 18

transposed, 19gridHighlighting (HTML properties), 108gridItemRestrict, 22gridItems, 18griditems copy, 29gridLabelFooter, 21gridLabelHeader, 18, 20gridLabelRestrict, 21gridLabels, 18gridlabels copy, 29GridOpenNoMissing, 38Group, 48, 56

Filter, 73Text Replacement, 73

group, 24, 80gt, 67gtcApp, 163gtcSurveyDir, 163

hasDuplicateValues, 69hasLabel, 69HTML Intagration, 52HTML Label, 53HTML Properties

ki_active, 122ki_autoCheck, 122ki_autoComplete, 122ki_autoFocus, 122pg_corpus, 134pg_corpus_padding, 134pg_fading, 134pg_group_names, 135pg_grouping, 134pg_height, 134pg_orientation, 134pg_visibility, 134pg_visibility_menu, 135pg_visibility_orientation, 135pg_width, 134sl_barColor, 125sl_barColorLeft, 125sl_barHeight, 125


Index

sl_barImage, 125sl_barImageLeft, 125sl_barWidth, 125sl_color, 125sl_image, 125sl_ImageHeight, 125sl_ImageWidth, 125sl_maxSum, 126sl_mode, 126sl_showValues, 126sl_startValues, 126sl_stepSize, 126sl_unspecified_button_checked, 126sl_unspecified_button_unchecked, 126sl_visibility, 126

htmllabels, 53htmlPostLabels, 53HtmlPostText, 9, 10htmlPreLabels, 53HtmlPreText, 9, 10http, 155https, 155

idproperties.cfg, 205IDs, 154if, 98IfDef, 6IfNDef, 6ignoreAssert, 38ignoreFilter, 38ignoreNoMissing, 38ImageMap, 149in, 68inc, 89, 91Include, 6incQuota, 83, 91initActionBlock, 88Input, 43input (HTML parameter), 116insert, 57insertLabels, 30, 91internal variables, 63Interview Settings, 35IntRandom, 59InvalidIdMsg, 38InvalidSingleMsg, 38Invitation Links, 155ISO-8859-1, 190ItemMissingText, 39

JavaScript, 10, 54

gesstmpl.js, 105Javascript

addImage(), 138addTachisto2(), 145addTachistoCode(), 144bbIaImg, 118bbId, 118bbImg, 118bbOmoImg, 118cbIaImg, 118cbId, 118cbImg, 118cbOmoImg, 118ccIaImg, 118ccId, 118ccImg, 118ccOmoImg, 118hide_labels, 144hide_labels(), 145hideq(), 143insertLayer(), 138

JavascriptSingleMode, 44javascriptSingleMode (HTML properties),

108jdbcDriver, 164jdbcDropAndCreateTables, 165jdbcPassword, 165jdbcUrl, 164jdbcUser, 165jsHandler, 54JSON, 97

Label, 24Label Group, 19LabelOpenErrorMessage, 39labelRepeat, 21labels copy, 29lalign, 92Layout-Areas, 113le, 67load, 92lrs files, translations, 193, 194lt, 67

Macro, 7Main, 32maxIdleSeconds*, 163MaxLabelsPerCol, 44maxMemoryLoad, 163maxNumAnswers (HTML properties), 108media queries, 115


Index

mediaRoot*, 164method*, 164minNumAnswers (HTML properties), 108MissingText, 39MissingValue, 39modelPath, 164mouse_event (HTML Properties), 108Multi IDs, 154multi_button_checked, 107multi_button_checked (HTML properties),

106multi_button_inactive, 107multi_button_inactive (HTML properties),

106multi_button_unchecked, 107multi_button_unchecked (HTML proper-

ties), 106MultiExportLimit, 39multiexportlimit, 14MultiGridQ, 22MultiGridQClass, 44multiGridQClass (HTML parameter), 106Multimode, 154MultiQ, 14MultiQClass, 44multiQClass (HTML parameter), 106MultiQTextInsert, 48

Navigation Buttons, 118ne, 67Next Button, 118NoAnswerLabel, 39NoMissing, 12num, 69Number of the Interviewee, 64numerical values, 49NumQ, 15NumQClass, 44NumQInputType, 44

open, 16, 25OpenNumFormat, 16, 124OpenQ, 15oversizeArray, 91

Panel Connection, 158panel integrating, 86PasswdQ, 15PBarMax, 40PBarWidth, 45performHttpRequest, 92

Plausibility Conditions, 74PostHelpText, 9, 11PostInterviewerHelpText, 9, 11pow, 93preAssertionActionBlock, 88PreHelpText, 9, 10PreInterviewerHelpText, 9, 11Preprocessor Directives, 6presetDataPath, 164print, 93printText, 93

QDot.heatplotter.create, 148QSortable NumQ, 129QuotaGroup, 83Quotas, 82quotaVar, 82QuotaWriteCondition, 39

ralign, 93random, 25–27, 33Random Numbers, 59readDataFile, 93readJsonDataFile, 94readTextRessource, 94regexp, 69remove, 94removeDuplicates, 94repeatGridAnchor, 21respm.lst, 154respo.lst, 154responsive design, 115restrict, 24, 31, 57RestrictVar, 62resumeActionBlock, 88Resuming of Interviews, 65robot, 185rotateLeft, 94round, 95row, 33, 50rowspan, 51

same origin policy, 209Screens, 50screens, 32screenshots, automatic, 185screentext, 15script, 95Server Monitoring, 209server.lst, 166set, 64, 95


Index

setCurrentScreen, 96setDecimalSeparator, 96setGroupingSeparator, 96setNextScreen, 96setProperty, 45setProperty (HTML parameter), 106setText, 60, 102shareLabels, 30showAllErros, 18showHelptext, 40ShowIndividualErrors, 45showInterviewerHelptext, 40ShowMaxLabels, 11ShowQuestionName, 45ShowSingleQValues, 45shuffle, 96single, 22, 26, 28Single IDs, 154SingleGridQ, 18SingleGridQClass, 45singleGridQClass (HTML parameter), 106Singlemode, 154SingleQ, 12SingleQAutoSubmit, 46SingleQClass, 46singleQClass (HTML parameter), 106SingleQFormat, 46singleQFormat, 12SingleQTableLabelsFirst, 46skript.q, 206slider_rest, 126slider_sum, 126sortID, 9, 10, 76

automatic, 80Sorting, 76splitcolumn, 24Start links, 155startActionBlock, 88strcmp, 70strCutLeft, 97strCutRight, 97SurveyClosedMsg, 40surveyPath*, 164syncsort, 97sys_browser, 65sys_caseid, 65sys_currentScreen, 65sys_duration, 65sys_finishdate, 66sys_finished, 66

sys_finishtime, 66sys_os, 66sys_respid, 66sys_startdate, 66sys_starttime, 66

Tablet-ID, GESS Q. Android, 173target, 82Template, 105template1 ... template8, 101template1...8, 63Test Mode, 154testmode, 155Text, 10text, 26text replacement, 48textAreaCols (HTML-parameter), 15textAreaRows (HTML-parameter), 15TextArray, 61TextElement, 60Textlabel, 24TextQ, 15thumbnails, 138Time, 63timeoutActionBlock, 88timeOutCheckInterval*, 164timesSent, 70Title, 10title, 32title.txt, 205to, 50transpose, 19

Update, 2Uppercase and Lowercase Letters, 4URL parameter, 188URL-parameter, 64URLName*, 164USB Debugging, 173users.lst, 165UTF-8, 190

var_tabs.inc, 207VarArray, 62variable names, 4Version, 2video integration, 139

while, 98Whitelist, 34writeJsonToSurvey, 97WritePostText, 46


Index

WritePreText, 46WriteQText, 46WriteRescueData, 40

GESS Q. Android App, 176WriteTitle, 47WriteViewingTime, 41

Zoom factor, responsive design, 115


gess q. · gess q. user manual gesellschaft für software in der sozialforschung mbh waterloohain 6...

Documents