You are on page 1of 248
d      Survey Programming      Fundamentals    Survey Programming Fundamentals  Copyright © 2007 by Verge Consulting, Inc.  All rights reserved. No part of this work may be reproduced or transmitted in any form or my any  means, electronic or mechanical, including photocopying, recording, or by any information storage or  retrieval system, without prior written permission of Verge Consulting.  Trademarked names may appear in this book. Rather than use a trademark symbol with every  occurrence of a trademark name, we use the names only in an editorial fashion and to the benefit of  the trademark owner, with no intention of infringement of the trademark.  For additional information please contact Verge Consulting directly at 4146 Sherel Lane, Cincinnati, OH  45209. Phone 513‐282‐3762, fax 866‐822‐9333 or visit http://www.VergeConsulting.com.   The information in this book is distributed on an “as is” basis, without warranty. Although every  precaution has been taken in the preparation of this work, neither the author(s) nor Verge Consulting  shall have any liability to any person or entity with respect to any loss or damage caused or alleged to  be caused directly or indirectly by the information contained in this work.    Version:    SPF12 (Dimensions 4.5) Survey Programming Fundamentals    Table of Contents  Table of Contents  Chapter 1  Introduction to Survey Programming ..................................................................................... 1  The Big Picture ........................................................................................................................................ 1  What is Survey Design About? ............................................................................................................ 2  The Survey Process ................................................................................................................................. 2  Dimensions Scripting Overview .............................................................................................................. 2  Interview Object Model .......................................................................................................................... 2  Object Oriented Programming ............................................................................................................... 3  What is Object Oriented Programming? ............................................................................................ 3  Dimensions Development Library Overview .......................................................................................... 3  Navigating the DDL ............................................................................................................................. 4  Examples ............................................................................................................................................. 4  DDL Links ............................................................................................................................................. 5  What is mrStudio? .................................................................................................................................. 6  What’s Next? ........................................................................................................................................... 7  Chapter 2  Constructing Questions ........................................................................................................... 9  Metadata Items Format .......................................................................................................................... 9  Information Items ................................................................................................................................. 10  Numeric Questions ............................................................................................................................... 11  Minimum and Maximum Parameter Options ................................................................................... 12  Text Questions ...................................................................................................................................... 12  Categorical ............................................................................................................................................ 14  Parameter Options ‐ Restricting the Number of Responses to be Chosen ...................................... 14  Date ....................................................................................................................................................... 17  Boolean ................................................................................................................................................. 19  Chapter 3  Creating an mrStudio Interview Script .................................................................................. 21  Opening mrStudio ................................................................................................................................. 21  Overview of Toolbars/Shortcuts ........................................................................................................... 23  Formatting Toolbars ......................................................................................................................... 23  View Toolbar ..................................................................................................................................... 24  Interview Options Toolbar ................................................................................................................ 25      I  Table of Contents    Survey Programming Fundamentals  Tips for Creating Metadata ................................................................................................................... 25  Viewing and Testing the Survey in mrStudio ........................................................................................ 26  Exercise ................................................................................................................................................. 28  Chapter 4  Special Responses and Options ............................................................................................ 31  Single Response Choices in Multiple Selection Questions ................................................................... 31  Special Responses with Categorical Questions ..................................................................................... 34  Categorical Responses with Non‐Categorical Questions ...................................................................... 36  Collecting Other Text Responses in Categorical Questions .................................................................. 38  Subheading ........................................................................................................................................... 39  Exercise ................................................................................................................................................. 42  Chapter 5  Basic Routing Logic................................................................................................................ 45  Asking Questions ................................................................................................................................... 47  Read Only Items .................................................................................................................................... 49  Conditional Statements ........................................................................................................................ 50  If… Then… Else .................................................................................................................................. 50  Select Case ............................................................................................................................................ 52  Goto ...................................................................................................................................................... 55  Logical Expressions ............................................................................................................................... 56  Numeric Questions ........................................................................................................................... 56  Boolean Questions ............................................................................................................................ 57  Text Questions .................................................................................................................................. 57  Categorical Questions ....................................................................................................................... 58  Logical Operators .............................................................................................................................. 60  Tips for Routing Section Syntax ............................................................................................................ 62  Adding Error Handling ........................................................................................................................... 63  Exercise ................................................................................................................................................. 64  Chapter 6  Shared Lists ........................................................................................................................... 67  Creating Subheadings with Shared Lists ............................................................................................... 69  Chapter 7  Sorting Categorical Response Lists ....................................................................................... 73  Sorting in Metadata .............................................................................................................................. 74  Routing Section Sorting ........................................................................................................................ 75  Not Sorting Specific Responses ............................................................................................................. 75  II      Survey Programming Fundamentals    Table of Contents  Keeping Specific Categories Grouped Together ................................................................................... 77  Exercise ................................................................................................................................................. 78  Chapter 8  Restricting Responses ........................................................................................................... 79  Filter Categories .................................................................................................................................... 79  Limiting Numeric Question Ranges Based on Logic .............................................................................. 86  Exercise ................................................................................................................................................. 88  Chapter 9  Multiple Questions on One Page .......................................................................................... 91  Page....................................................................................................................................................... 92  Block ...................................................................................................................................................... 94  Controlling How Page and Block Questions are Displayed ................................................................... 98  Filtering a Page/Block ....................................................................................................................... 98  Sorting a Page/Block ......................................................................................................................... 99  Exercise ............................................................................................................................................... 100  Chapter 10  Repetitive Questions ‐ Loops & Grids ............................................................................. 101  Categorical Loops/Grids ...................................................................................................................... 102  For Each loops ................................................................................................................................. 106  Categorical Loops with a Numeric Question .................................................................................. 108  Numeric Loops .................................................................................................................................... 111  Exercise ............................................................................................................................................... 114  Chapter 11  Debugging Tools within mrStudio ................................................................................... 115  Auto Answer Questionnaire ............................................................................................................... 115  Producing Test Data ............................................................................................................................ 117  Adding Additional Data Sources ..................................................................................................... 119  Setting Breakpoints ............................................................................................................................. 120  Troubleshooting Specific Sections of Code ......................................................................................... 121  Working with Macros .......................................................................................................................... 123  Updating/Deleting Existing Macros ................................................................................................ 123  Adding Additional Macros .............................................................................................................. 123  Chapter 12  Conditioned Loops and Grids .......................................................................................... 125  Previous Responses Within the Loop ................................................................................................. 125  Loops/Grids Filtered on Previous Responses Outside the Loop/Grid ................................................ 127  Loops/Grids Filtered on Responses to a Different Loop/Grid’s Questions ......................................... 129      III  Table of Contents    Survey Programming Fundamentals  Loops/Grids Filtered on a Sublist of Categories .................................................................................. 131  Exercise ............................................................................................................................................... 134  Chapter 13  Controlling the Look of Your Survey ............................................................................... 137  Overview of the Formatting of a Survey ............................................................................................. 137  Templates ........................................................................................................................................... 137  Applying a Template within Your Script. ........................................................................................ 139  Folders ............................................................................................................................................ 140  Tips for Scriptwriters Regarding Templates .................................................................................... 141  Styles ................................................................................................................................................... 141  Default Styles ...................................................................................................................................... 141  Default ............................................................................................................................................ 142  Categories ....................................................................................................................................... 143  Grid ................................................................................................................................................. 144  Labels .............................................................................................................................................. 146  Navigation ....................................................................................................................................... 146  Questions ........................................................................................................................................ 147  Question Styles ................................................................................................................................... 148  Categorical Questions ..................................................................................................................... 148  Text Questions ................................................................................................................................ 149  Metadata Styles .................................................................................................................................. 150  Custom Controls ................................................................................................................................. 151  XHTML in Labels .................................................................................................................................. 151  What is XHTML? .............................................................................................................................. 151  Final Thoughts on Formatting ............................................................................................................. 152  Exercise ............................................................................................................................................... 153  Chapter 14  Text Substitutions and Text Headings ............................................................................. 155  Displaying Responses to Previous Questions ..................................................................................... 155  Insert Text into the Metadata that will be controlled in the routing section ..................................... 158  Text Headings ...................................................................................................................................... 162  Chapter 15  Enhancing Survey Flow ................................................................................................... 165  Must Answer ....................................................................................................................................... 166  Default Answers .................................................................................................................................. 166  IV      Survey Programming Fundamentals    Table of Contents  Hidden default responses ............................................................................................................... 169  Initial Response ................................................................................................................................... 170  Exercise ............................................................................................................................................... 172  Chapter 16  Customizing the Standard Error Messages ..................................................................... 173  Global changes to error messages ...................................................................................................... 175  Error messages changes for a specific metadata file .......................................................................... 175  Error messages changes for a specific question ................................................................................. 176  Customizing the error message .......................................................................................................... 177  Chapter 17  Functions & Subroutines ................................................................................................. 179  Definition of Functions and Subroutines ............................................................................................ 179  Subroutine ...................................................................................................................................... 180  Subroutine Example ............................................................................................................................ 180  Function .......................................................................................................................................... 184  Exercise ............................................................................................................................................... 188  Chapter 18  Validation ........................................................................................................................ 189  Validating Text Question Patterns ...................................................................................................... 189  Checking Custom Logic ....................................................................................................................... 192  Adding custom errors ......................................................................................................................... 193  Adding custom properties to metadata ......................................................................................... 198  Chapter 19  Compound Questions ..................................................................................................... 201  Defining Compound Questions ........................................................................................................... 201  Validating a compound question ........................................................................................................ 204  Compound vs. Loop ............................................................................................................................ 206  Chapter 20  Working with Sample ...................................................................................................... 207  Testing sample information within mrStudio ..................................................................................... 209  Alternative to Sample Management to pass information into the survey ......................................... 213  Chapter 21  Working with Quotas ...................................................................................................... 215  Defining Survey Quotas ...................................................................................................................... 215  Checking Quotas ................................................................................................................................. 218  Quotas In mrStudio ......................................................................................................................... 221  Activation with Quotas ....................................................................................................................... 222  Viewing & Changing Quotas ............................................................................................................... 222      V  Table of Contents  Chapter 22    Survey Programming Fundamentals  Creating Multi‐Lingual Projects ....................................................................................... 227  Overview of Translating Studies in Dimensions .................................................................................. 227  Setting the language within the script ................................................................................................ 228  Ask a question to collect and set the language .................................................................................. 228  Set language from a sample field variable .......................................................................................... 229  Tips for creating multi‐lingual projects ............................................................................................... 230  Chapter 23  Additional information for Analysis ................................................................................ 231  Alternate Text for Analysis .................................................................................................................. 231  Adding Analysis Context with mrStudio ......................................................................................... 231  Factors ................................................................................................................................................. 232  Creating Question Items for Analysis.................................................................................................. 233  ElementTypes.................................................................................................................................. 234  Axis Expressions .............................................................................................................................. 236  Tips creating analysis elements .......................................................................................................... 239  Summary ............................................................................................................................................. 239    VI      Survey Prrogramming Fundamentalls  Chapte er 1    Chapter 1  Introd duction to Surrvey Program mming  Inttroductio on to Surv vey Progra amming   This courrse is designed to provide a firm foundaation in understanding thee Dimensions Scripting  languagee, specifically the task of prrogramming ssurveys.  This chap T pter will contain:: An overvieew of the interview process A definitio on of Dimensions scripting An introdu uction to docum mentation and d  mrStudio     The Big g Picture   The overall process off running a su urvey can be ggrouped into three main categories.  • • • Design:  Creatting the surveey instrumentt and the queestions associated with it  D C Collect:  Colle ect the inform mation requireed of the survvey instrumen nt  R Report:  Analy yze the resultts and report the findings o of the research  For each stage there aare different ttools we can use. For Dimeensions this ccould look likee…    C Collect t •mrStudio •Build A Activity •mrPap per •Author •mrTranslate •mrInterview •mrD Dialer •mrSScan Design •SSPSS •R Reporter •m mrTables •m mrStudio •C Clementine Report           1    Chapter 1  Introduction to Survey Programming    Survey Programming Fundamentals  What is Survey Design About?  Here are some of the tasks involved in survey design:  • • • • • • • Creating a quality survey instrument  Programming survey content and logic  Survey testing (Quality control)  Transferring the project to data collection servers (Activation)  Survey translation  Sample integration  Defining quotas    The Survey Process  The historic process for the survey process has at times been tedious.  There are a lot of repetitive  tasks that take time and money.  Dimensions is changing that paradigm.   Dimensions scripting allows  users to incorporate more automation and reusable code in the process.  Dimensions scripting is one  unified language for survey design, collection and reporting, so there is less repetition and a more  streamlined process.  Dimensions Scripting Overview  When working in mrStudio we will be using Dimensions Scripting. There are two languages in  Dimensions scripting.  Language  mrScriptBasic  Description  A programming language that is based on Microsoft VBScript.  mrScriptMetadata  Proprietary Dimensions syntax used to define survey questions/  metadata.    When programming surveys we will make use of both languages. mrScriptMetadata will be used to  create the question for our survey. mrScriptBasic will control when and if we ask those questions.    Interview Object Model  The Interview Object Model, typically referred to as IOM, is the foundation of survey programming in  Dimensions. IOM defines, for Dimensions, what the components of a survey are and what actions we  can take with each component.    2        Survey Programming Fundamentals    Chapter 1  Introduction to Survey Programming    Object Oriented Programming  When programming a survey in Dimensions you will be using object oriented programming (OOP).   What is Object Oriented Programming?  A basic definition would read something like: A type of programming in which programmers define not  just the data type of a data structure, but also the types of operations (functions) that can be applied  to the data structure. In this way the data structure becomes an object that includes both data and  functionality.  If you have not been exposed to OOP in the past, the concepts and terminology can seem confusing at  times. However, don't get caught up in the terminology. If you understand the concept of creating a  questionnaire, then you can learn the content of this manual.  Think about OOP in terms of a survey.  Specifically, let's look at a survey question as an object. A  question has question text, potential responses, as well as many other possible items. These are in fact  the data structure, what can make up part of a question. At the same time a question will require  functionality, such as asking the question or filtering the responses. These potential actions would  make up the operations that can be applied to the data structure.  If this makes sense to you, then you  are on your way to grasping the concepts of OOP.  (If it doesn’t, this concept will make more sense as  you continue your learning.)  Dimensions Development Library Overview  Commonly referred to as the DDL, the Dimensions Development Library is a collection of resources. It  consists of extensive technical documentation as well as a wide variety of example code.          3    Chapter 1  Introduction to Survey Programming    Survey Programming Fundamentals  You can access the DDL through the Help ‐ Contents menu choice in mrStudio, or through:   Start – Programs – SPSS Dimensions – Dimensions Development Library – Documentation 4.5    Navigating the DDL  There are many different ways to navigate around the DDL.  Tab  Contents  Index  Search  Favorites        Description  All the DDL topics arranged in a table of contents. You can use this view like looking  through a book. It is also helpful for identifying topics related to a page you are  currently reading.  The index is an alphabetical list of keyword contained in the DDL. Use this view  when you know the keyword and want to quickly find topics related to it.  A full‐text search of the DDL. You can search on a single word, combination of  words and phrases.  Create a list of topics you have found valuable.  All the Dimensions product documentation is contained in the DDL, so finding specific topics  is a skill in itself and will take time to develop.   For this course, a good place to start is in the Contents tab:  mrStudio – Interview Scripting – Getting Started    Examples  When you installed the DDL you also installed many examples files. The default path for these  examples is:  C:\Program Files\SPSS Dimensions\DDL\    Specifically for survey programming you should be aware of:  C:\Program Files\SPSS Dimensions\DDL\Scripts\Interview    These example projects will prove very valuable to give you new ideas for programming.  4      Survey Programming Fundamentals    Chapter 1  Introduction to Survey Programming    DDL Links  Throughout these materials you will see links pointing you to the DDL for additional information on a  topic. These are jump links and will look like:    For more information on the Interview object model, see the DDL diagram:   IOMLib.chm::/interview_Object_Model.html        To use a link, right click on the title bar in the DDL:      Select the Jump to URL… menu item.                5    Chapter 1  Introduction to Survey Programming    Survey Programming Fundamentals  Enter (or copy and paste) the link into the Jump to this URL: textbox. Then click OK.    This will take you to the page requested.  You can also do the reverse, and copy the current URL shown  above and share with others.    What is mrStudio?  mrStudio is a desktop program that assists programmers with creating scripts. Its core component is an  integrated development environment (IDE) that allows you to create, edit, run and debug Dimensions  scripts.  For survey programmers, one of the big strengths is the ability to run surveys directly inside mrStudio,  without the need for a server. You can create, test and debug a survey directly on your machine.    6      Survey Programming Fundamentals    Chapter 1  Introduction to Survey Programming    Since you will be using mrStudio throughout this course, let’s start with a brief overview of the  toolbars:  Toolbar  Description  File: Used to create, open, save and print files.    Edit: Cut, copy, paste, undo and redo, find.        View: Controls which tabs are showing in  mrStudio.  Debug: Used to start, stop, pause and move  through a script.  Formatting: Indentations, commenting,  macros and options.  Workspace: Create and manage workspaces.    Interview Options: routing context options,  activation, quotas, and metadata tools.      You will get to see many features of mrStudio as you move through this training.    What’s Next?  So now you have been introduced to Dimensions Scripting, object oriented programming, the  Dimensions Development Library, and mrStudio.  This manual will focus on using mrStudio to create  surveys for data collection with mrInterview.  We will start with basic questions and quickly move into  advanced concepts to help you create more complex surveys.           7    Chapter 1  Introduction to Survey Programming    Survey Programming Fundamentals          8  Survey Prrogramming Fundamentalls  Chapte er 2  Chaapter 2  Consttructing Quesstions  Constructin ng Questio ons  The core of a survey iss the question ns.  In this chapter, we will build our kn nowledge of ccreating questions  within mrStudio.   In this chapter w we will: Create baasic questionss Create a m metadata filee in mrStudio View and test a surveyy within mrStudio     Metada ata Items F  Format  Metadataa items follow w a distinct paattern you wiill see as we ccomplete thiss chapter:  N Name "Text"  type parame eters;  Item  Name  "Text"  Type  Parameters  Semicolo on    Desscription  Uniique identifier for the item m within your questionnairre.  They must start with a  lettter or undersccore ( _ ) and contain onlyy alpha‐numeric characterss or the  sym mbols @, $, #,, or _   Texxt associated w with the item m (considered the label in tthe object mo odel).  Identifies the iteem for its funcctionality (cattegorical questions, text o only items,  etc.)  The ese are option nal and vary b by item type.  An example would be thee responses  to aa question.  Bettween each item in the meetadata sectio on there is a ssemicolon.    er many of th he different tyypes of questtions.  The next sections cove       9    Chapter 2 2  Constructin ng Questions  Surveey Programm ming Fundameentals  Inform mation Item ms  To createe an opening page with an introduction n or have a paage with graphics or opening text witho out  questions, you need to create an in nformation item.  The synttax is as follow ws:    N Name "Text"  info;  Item  Name  Desscription  Uniique identifier for the item m within your questionnairre.  They must start with a  lettter or undersccore ( _ ) and contain onlyy alpha‐numeric characterss or the  sym mbols @, $, #,, or _   Texxt associated w with the item m (considered the label in tthe object mo odel).  Keyyword to creaate a text‐onlyy item.  This is the default type if it is no ot specified.    Bettween each item in the meetadata sectio on there is a ssemicolon.  "Text"  info  Semicolo on    Example  Intro ""Please particcipate in our rresearch abou ut travel.  You ur answers w will help us to better  undersstand the travvel needs of cconsumers." info;        The intro oduction will d display in mrIInterview likee this:            10      Survey Programming Fundamentals    Chapter 2  Constructing Questions    Numeric Questions  To collect numeric data from your respondents, use one of the following item types:  Name "Text" long [min..max];  Name "Text" double [min..max];    Item  Name  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _.  Text associated with the item (considered the label in the object model).  Whole‐numbers only (no decimals). The range is from ‐2,147,483,648 to  2,147,483,647.  Decimal numbers.  64‐bit floating point number with at least 15 digits of  precision, in the range ‐1.79769313486232E308 to ‐4.94065645841247E‐324 for  negative values; 4.94065645841247E‐324 to 1.79769313486232E308 for  positive.  Optional parameters.  Controls the minimum and maximum values the  respondent can enter.  Automatically issues an error message if the amount  entered is below the minimum or above the maximum.   "Text"  long   double  [Min..Max]      The following example will display boxes for the respondent to fill in with a numeric response.  DaysTravelYr "On average how many days per year do you travel for business or leisure?"  Example  long [0 .. 365];      AmtSpentAccom "What price did you pay for your last overnight accommodations?"  double [0 .. 3999.99];                  11    Chapter 2  Constructing Questions    Survey Programming Fundamentals  The browser will display a box and the respondent can fill in amounts of their choice, as shown below:        Minimum and Maximum Parameter Options  When specifying the minimum and maximums for numeric questions, [min..max], you have many  options to collect the numeric data necessary.  Item  [1..]  [..]  [1..100,^50]  [1,3,5]  [1..10,50..100]    Description  Minimum amount without specifying a maximum    No minimums or maximums (will allow negative numbers)  Number after ^ symbol are excluded from the range.    Commas denote single values or breaking ranges.      Text Questions  When you want to create a question that collects any type of text information, use a text type.    Name "Text" text [min..max];  Item  Name  "Text"  text  [Min..Max]  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Text associated with the item (considered the label in the object model).  Keyword to enter any characters in the question.  Allows up to 4000 characters.  Optional parameters.  Controls the minimum and maximum characters allowed  for the question.     Here is a simple example of an open ended question.  12      Survey Programming Fundamentals    Chapter 2  Constructing Questions    BestVacation "Please tell us about your best vacation experience."  Example   text [1..];        Will display like the picture below:          If you state the maximum at 40 or less, you will see a line instead of a box.  You also  have full control of the box size with styles, covered in the “ Controlling the Look of Your  Survey” section.            13    Chapter 2  Constructing Questions    Survey Programming Fundamentals  Categorical  To create a question which offers a list of options to choose from is considered a categorical type  question.  Name "Text" categorical  [min..max]  {ID1 "AltText1" ,   IDn "AltTextn" };  Item  Name  "Text"  categorical   [Min..Max]  {   }  ID1, IDn  AltText1,  AltTextn  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Text associated with the item (considered the label in the object model).  Keyword to create a question with categories for response choices.    Optional parameters.  Controls the minimum and maximum amount of  categories that can be chosen by a respondent.  Default is open to any amount  of choices.  Automatically issues an error message if the number of responses  chosen is below the minimum or above the maximum.   Indicates the start of the categories you wish the respondent to choose from for  the question  Unique identifying name for the response.  This needs to be unique per  question, not metadata file.  Rules for the response names are the same as the  name of the question.  Optional text to show the respondent instead of the name of the question.  This  will apply when the name of the question is not the same as the text you wish to  show the respondent.    Parameter Options ­ Restricting the Number of Responses to be Chosen  As stated above, the minimum and maximum options provide the number of responses that can be  answered for a specific question.  There are some variations in syntax to consider.  Item  [1]  [1..]  [1..3]  [..]    14  Description  When only one number is specified in the minimum/maximum parameter, it is  assumed that this number is both the Minimum AND maximum amount.   Example shown allows for a single response to be chosen for the question.  Is  the same as typing [1..1]    Allows for multiple categories to be chosen (multiple response question).  Not  stating a maximum amount allows ease of updating the question with additional  responses as needed.  States the minimum amount of categories to be chosen is 1 and the maximum is  3.  Useful for questions which ask for responses “Answer up to X categories”.       No minimums or maximums (this is the default)      Survey Programming Fundamentals    Chapter 2  Constructing Questions    Be aware that not stating a minimum number of answers will allow the respondent to move forward in  the survey without providing a response. Allowing no answer in this way provides no method to  determine if the respondent was presented this question. The data for the respondent will simply  contain a blank.    Later in the course we will learn how to allow for the respondent to not answer a question, yet  have the data store a value showing that the respondent was exposed to the question.    Example  TravelItem "From the list below, which one item would you most want to bring with you  on a leisure trip?"      categorical [1..1]        {          Camera,          Map,          ComfortableFootwear "Comfortable Footwear",          FriendTravelCompanion "Friend/Travel Companion"      };    Creates a single categorical question with radio buttons:          15    Chapter 2  Constructing Questions    Survey Programming Fundamentals  CountryVisited "Which of the following countries have you visited?"  Example      categorical [1..]      {          Antarctica,            Africa,          Asia,          Australia,          Europe,          NorthAmerica "North America" ,          SouthAmerica "South America"      };      Note in the examples above, alternate labels are not required when the text you want to  display is also a legal label name.    The checkboxes indicate that more than one response can be given as stated in the syntax as [1..].    16      Survey Programming Fundamentals    Chapter 2  Constructing Questions    Date  When requesting a date from the respondent, it is easier to collect a date type versus multiple long  type fields.  Name "Text" date ["min".."max"];  Item  Name  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   "Text"  Text associated with the item (considered the label in the object model).  date  Keyword to enter a date and time field.   Can enter dates and times or one or the  other.  Takes many different date formats (See below).    ["Min".."Max"]  Optional parameters.  Controls the minimum and maximum date range allowed  for the question.   Note the addition of the double quotes around the min/max.      Key points regarding dates:  • • • • The format for the date is very flexible.  Some (not all) of the formats taken are:  o DD‐MonthName‐YYY  (7 – April – 2007)  o DD‐ShortMonthName‐YYY (7 – Apr – 2007)  o YYYY/MM/DD   (2007/04/07)  o MM/DD/YY (04/07/07)  If you leave off certain portions of the date/time field, it will make assumptions.  An example  would be if you were collecting only month and year and enter “April 2007”, mrInterview will  record the date as April 1, 2007.  If a time is not chosen, it assumes the current time.  When you run the interview you may enter times in 12‐hour or 24‐hour format; for example,  2:30pm or 14:30.  If you do not specify AM or PM, it will assume a 24‐hour clock.   Metadata language controls the format of the date taken.  An example would be trying to  enter a UK English date of dd/mm/yy when the metatdata languages do not contain English  UK, only English US.  In this case, the date would be transformed to the English US version of  mm/dd/yy.      If you want more control over the date field, create a custom control, such as the example  calendar.htm in the DDL: DDL.chm::/interviewscripting_templates_custom_writing.htm.           17    Chapter 2  Constructing Questions    Survey Programming Fundamentals    Example  LastTripDate "What was the date you left for your last trip?"    date;      TimeforTravel  "What time of day do you prefer to travel in the morning?"      date ["1:00am" .. "11:59am"];          The result of the LastTrip date question would look like this:            18        Survey Programming Fundamentals    Chapter 2  Constructing Questions    Boolean  Boolean type questions record a true or false value.  In web surveys, this type is an easy way to provide  a single checkbox response.  Name "Text" boolean;  Item  Name  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Text associated with the item (considered the label in the object model).  Keyword to create a true/false question.  Creates a checkbox on web surveys.    Checking the box is a True response and leaving it empty is false.    "Text"  boolean          You can add categories to a Boolean question to simulate a categorical question.  Be sure  if you use this option that you will only have 2 responses, never any more.        Here is an example of a Boolean question and what it will look like in the browser:   ReceiveTravelInfo "Check here if you wish to receive an email regarding travel safety."  Example  boolean;            19    Chapter 2  Constructing Questions    20    Survey Programming Fundamentals        Survey Prrogramming Fundamentalls  Chapte er 3    Chap pter 3  Creatin ng an mrStudio Interview SScript  Cre eating an n mrStudio o Intervie ew Script  t  Now thatt you know ho ow to create some basic q question types, let’s start u using mrStudiio to create and  test our sscript.  We wiill use mrStud dio to create tthe Dimensio on Scripting fo or our surveys.  This cha T apter will cover: How to creeate an mrStud dio metadata ffile Overview o of mrStudio an nd the toolbarss and  menus How to tesst your survey with mrStudio o     Openin ng mrStud dio  You will ffind mrStudio o at:   Start – P Programs – SP PSS Dimensio ons – mrStudio.          21    Chapter 3  Creating an mrStudio Interview Script    Survey Programming Fundamentals  Under File – New File you will see the different types of files you can create in mrStudio.        For this course we will be creating a Metadata File (.mdd).  Under file name fill in a file name for your  project and choose Open.  Now you are ready to start typing the code discussed in Chapter 2  into the  metadata section.        If you need help at first, Control – M displays the list of question types that you can choose  one and have the structure of the question to start with.  The macros can be a nice place  to start when you don’t want to go back to the DDL or manual for syntax questions.           22        Survey Programming Fundamentals    Chapter 3  Creating an mrStudio Interview Script      Overview of Toolbars/Shortcuts  mrStudio has many tools to help you with the creation of your script.  Let’s review the different  toolbars and parts of the mrStudio screen.    Formatting Toolbars  The formatting toolbars provide basic but needed editing skills in mrStudio.  File Toolbar:  Used to create, open save and print files.        Edit Toolbar:  Cut, copy, paste, undo, redo and find.      Formatting Toolbar:  Indentations, commenting, macros and options.      • • • Indenting left or right icons.  Indenting will become a very important aspect of your script  writing in the routing section.  It will help make your code easy to follow.  Comment and Uncomment Selection icons.  The comments in Dimensions Scripting are  indicated by a single quote mark and will turn the commented text green.  By highlighting large  blocks of text, you can comment and uncomment the sections easily with the toolbar icons  above.  The macros icon allows you to access the pre‐defined syntax for mrStudio.  You also have the  ability to add your own macros as well.      Note that you can copy macro definitions from one machine to another by copying the file  MacroDefinitions.xml from the default mrStudio directory.            23    Chapter 3  Creating an mrStudio Interview Script    Survey Programming Fundamentals    View Toolbar  This toolbar controls which tabs are showing in mrStudio.  Depending on what you are trying to  accomplish, you will want to show different aspects of mrStudio.      For now, let’s start with two helpful aspects, Metadata Explorer and the locals pane.    Metadata Explorer  As you create your metadata, you can open the Metadata viewer to see a treeview version of your  script:    The icons shown in this viewer are used throughout all Dimensions products to represent the question  types.        24        Survey Programming Fundamentals    Chapter 3  Creating an mrStudio Interview Script    Locals  As you run a survey, the locals allows you to see your responses to the questions as shown below.    In addition, the locals pane will provide extremely helpful in this course as you start to understand the  questions as objects, as you can see the different properties of the questions.    Interview Options Toolbar  The Interview Options toolbar gives you access to mrStudio tasks.    From left to right the options are:  • • • • • • • Adding routing contexts  Removing routing contexts  Metadata tool1  Metadata tool2  HTML tidy (tries to improve your HTML code in your templates to be perfectly formed)  Creating quotas (opens the Quota Tool Application)  Activation of the survey to mrInterview    Tips for Creating Metadata  We will discuss the mrStudio environment and the tools provided to help you create your scripts  throughout the manual.  Here are a few tips to get you started:  • • • • All keywords are color coded in blue.   All text within double quotes is also color coded.  When troubleshooting syntax errors, look for the appropriate color coding to help you find the  problems.  Save frequently, as your metadata will be checked for syntax errors when you save.  Error messages will state the line numbers associated with it.  Notice the line numbers on the  left side of your code in mrStudio to help you with this.      25    Chapter 3  Creating an mrStudio Interview Script  •   Survey Programming Fundamentals  After saving and closing the document, mrStudio reformats your metadata into a standardized  format.  The term used for this is re‐hydration.  Be aware of this so you don’t spend additional  time on proper formatting in the metadata section.    Viewing and Testing the Survey in mrStudio  When you have saved so that you know all errors are gone, you are ready to view the results of your  script.  Click the start button on the toolbar:      On the browser tab in mrStudio (if you cannot see the browser tab, from the menu choose View –  Browser ) you will be able to see the interview as it will appear when it is activated in mrInterview.        26        Survey Programming Fundamentals    Chapter 3  Creating an mrStudio Interview Script        Later in this course we will add formatting and templates to enhance the look of the  interview; these will also be viewable in the mrStudio browser window.     You can choose to answer the questions yourself, or you can choose F5 to let mrStudio automatically  answer the questions on the screen for you. (This will prove helpful later when testing surveys with  large grid questions).  The interview will complete, but if you wish to interrupt the script, click on the Stop button in the  browser window, or the Stop (square icon) in the toolbar.      As you can see, there are many features in mrStudio to help you create your interview scripts.  Some  features you will use immediately, such as the local testing of surveys and the auto‐answering  questions with F5.  Others, such as creating macros and viewing the locals pane information will come  later in your learning.          27    Chapter 3  Creating an mrStudio Interview Script    Survey Programming Fundamentals  Exercise  Open mrStudio and create a metadata file called GroceryBill.mdd.  Complete the following questions  in this document, then test the survey within mrStudio.  GroceryIntro   As you agreed to previously, please have your last grocery bill available for reference for  this next section of the survey.      GroceryDate  Looking at your last grocery bill, what date did you go to the store?      StoreName  What was the name of the store in which you shopped?                  Walmart  Safeway  Kroger  Albertsons  Ahold USA  Delhaize  Publix  Winn‐Dixie    ItemTypes  Which of the following categories of groceries did you purchase on this shopping trip?                Cheese/Olive Bar Salad Bar  Deli Items  Meat/Seafood  Produce  Canned Goods  Pasta/Grains    Generic  On this particular shopping trip, did you purchase any generic brand items?      Yes  No        28        Survey Programming Fundamentals    Chapter 3  Creating an mrStudio Interview Script    ItemsBought  How many items did you buy?      GroceryCost  Exactly how much did you spend?        PurposeTrip  Briefly describe the reason for your trip to the grocery store on that particular day.          AgreeContact  Please check the box below if you agree to allow us to contact you later if we have  additional questions regarding your trip to the grocery store.                29    Chapter 3  Creating an mrStudio Interview Script    30    Survey Programming Fundamentals        Survey Prrogramming Fundamentalls  Chapte er 4  Chapter 4  Special Respo onses and Op ptions  Special Resp ponses an nd Option ns  In Chapteer 2 we coverred basic question syntax.  This chapterr will expand on the conceepts of that  chapter aand add addittional optionss to enhance those questio on types.  In tthis chap pter we w will coveer: Special keyywords to provvide additionall  functionality Collecting specific text reesponses when n  nt chooses other responden Creating su ubheadings to improve the  appearancce of categorical questions     n Multiple e Selection n Question ns     Single  Response Choices in With multiple selectio on categoricall questions, yyou may wantt to have certtain responses that cannott be  chosen in n combination n with any otther responsee.  In order for that logic to o happen, you u must indicate  that the rresponse sho ould be a single‐select choiice using the keyword, excclusive.  N Name "Text " " categorical [[min..max]  { {ID1 "AltText1 1",   IIDn "AltTextn n" exclusive }};        31    Chapter 4  Special Responses and Options  Item  Name    Survey Programming Fundamentals  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Text associated with the item (considered the label in the object model).  Keyword to create a question with categories for response choices.  Question  type must be categorical to use the exclusive keyword.  Optional parameters.  Controls the minimum and maximum amount of  categories  that can be chosen by a respondent.  Default is open to any amount  of choices.  Automatically issues an error message if the number of responses  chosen is below the minimum or above the maximum.   Indicates the start of the categories you wish the respondent to choose from   Unique identifying name for the response.  This needs to be unique per  question, not metadata file.  Rules for the response names are the same as the  name of the question.  Optional text to show the respondent instead of the name of the question.  This  will apply when the name of the question is not the same as the text you wish to  show the respondent.  Makes a specific response the only choice that can be chosen in a multiple  selection question.  Keyword is placed after the category name and alternate  text (if present).  "Text"  categorical  [min..max]  {   }  ID1, IDn  AltText1,  AltTextn  exclusive      AirlinesFlown "In the past year, which of the following airlines have you used for travel?"  Example      categorical [1..]      {             American,          Delta,          United,          OtherAirline "Other airline",          NeverFlown "Never flown before" exclusive      };        32        Survey Programming Fundamentals    Chapter 4  Special Responses and Options    If the respondent tries to choose the response “Never flown before” and any other response, the  following error will appear:            Exclusive responses show up in bold by default.  This can be overwritten by templates or  styles, which will be discussed in Chapter 13 .            33    Chapter 4  Special Responses and Options    Survey Programming Fundamentals  Special Responses with Categorical Questions  There are special keywords which represent some common responses to interviews, No Answer, Don’t  Know, and Refused to Answer.   Name "Text" categorical   {ID1 "AltText1",   ID2 "AltText2" ,   IDn "AltTextn" Keyword};  Item  Name  "Text"  categorical  {   }  ID1, ID2, IDn  AltText1,  AltText2,  AltTextn  Keyword  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Text associated with the item (considered the label in the object model).  Keyword to create a question with categories for response choices.  Indicates the start of the special response categories you wish the respondent to  choose from for the question  Unique identifying name for the response.  This needs to be unique per  question, not metadata file.  Rules for the response names are the same as the  name of the question.  Optional text to show the respondent instead of the name of the question.  This  will apply when the name of the question is not the same as the text you wish to  show the respondent.   Represents one of the keywords NA (No Answer),  DK (Don’t Know), or REF  (Refused)    Benefits for using these keywords:  • • •   34  The response is automatically set to be exclusive and fixed in the position in which it was typed  when the category order is changed.  When using the CATI (Computer Aided Telephone Interviewing) option, these keywords have  shortcut keys for the ease of use for the interviewers  These responses can be identified in a systematic way, which makes it easier to reference  these question types when creating subroutines or functions.          Survey Programming Fundamentals    Chapter 4  Special Responses and Options        Example  HotelChainStayed "Choose the hotel chains you have stayed at this past year."   categorical [1..]      {            InterContinental,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };          You can use the keywords as the names for the responses; however after re‐hydration the names will  show as a dash (‐).          35    Chapter 4  Special Responses and Options    Survey Programming Fundamentals  Categorical Responses with Non­Categorical Questions  You can add categorical responses to question types that are numeric, text, or date.  The special  keyword options of NA, DK and REF are typically used in this scenario, as this can prove valuable to  provide respondents with a way to indicate they don’t know or prefer not to answer the question.  Name "Text" qtype [min..max]  codes (   {ID1 "AltText1" Keyword,   IDn "AltTextn" Keyword}  );  Item  Name  "Text"  Qtype  [Min..Max]  codes  {   }  ID1, IDn  AltText1,  AltTextn  Keyword  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Text associated with the item (considered the label in the object model).  Represents the non‐categorical question types of long, double, text or date.    Optional parameters.  Controls the minimum and maximum values that can be  chosen by a respondent.    Keyword to indicate you are adding special response categories to a non‐ categorical question.  Indicates the start of the special response categories you wish the respondent to  choose from for the question  Unique identifying name for the response.  This needs to be unique per  question, not metadata file.  Rules for the response names are the same as the  name of the question.  Optional text to show the respondent instead of the name of the question.  This  will apply when the name of the question is not the same as the text you wish to  show the respondent.   Represents one of the keywords NA (No Answer),  DK (Don’t Know), or REF  (Refused).  This keyword is optional.      36        Survey Programming Fundamentals    Chapter 4  Special Responses and Options      AmtSpentYr "What price did you pay for your last airline flight?"  Example  double [0 .. 3999.99]  codes (       {        dontknow "Don’t remember" DK,        Refused "Prefer not to answer" REF     }  );    This code would create checkboxes below the numeric response box as shown below:                37    Chapter 4  Special Responses and Options    Survey Programming Fundamentals  Collecting Other Text Responses in Categorical Questions  The other keyword allows the respondent to enter an answer that is not on the category list.  Name "Text" categorical   {ID1 "AltText1",   IDn "AltTextn" other};  Item  Name  "Text"  categorical  {   }  ID1, ID2  AltText1,  AltText2  other    Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Text associated with the item (considered the label in the object model).  Keyword to create a question with categories for response choices.  Indicates the start of the categories you wish the respondent to choose from for  the question  Unique identifying name for the response.  This needs to be unique per  question, not metadata file.  Rules for the response names are the same as the  name of the question.  Optional text to show the respondent instead of the name of the question.  This  will apply when the name of the question is not the same as the text you wish to  show the respondent.  Keyword to create a text box on the response to collect additional information.  HotelChainStayed "Choose the hotel chains you have stayed at this past year."  Example      categorical [1..]      {  InterContinental ,            Cendant,          Marriott,          Accor,          Choice,          Hilton,          OtherHotel "Other Hotel Chain" other,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF    };  38      Survey Programming Fundamentals    Chapter 4  Special Responses and Options    This will create a text box to collect the specific name of any hotel chains not listed.      You can have multiple other specify responses per question.        Subheading  You can create text‐only items to describe a group of responses by creating subheadings.                                                                                                                  Name "Text"   categorical      {          Subhead1 "SubText1"    {       ID1 "AltText1",       ID2 "AltText2"     },           Subheadn "SubTextn"    {      ID3 "AltText3",      IDn "AltTextn"    }       };        39    Chapter 4  Special Responses and Options    Survey Programming Fundamentals    Item  Name  "Text"  categorical  {   }  Subhead1,  Subheadn  SubheadText1,  SubheadTextn  ID1, ID2,IDn  AltText1,  AltText2,  AltTextn    Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Text associated with the item (considered the label in the object model).  Keyword to create a question with categories for response choices.  Indicates the start of the subheadings and categories   Name for Subheading item  Represents alternate text for the Subheadings.  Unique identifying name for the response.  This needs to be unique per  question, not metadata file.  Rules for the response names are the same as the  name of the question.  Optional text to show the respondent instead of the name of the question.  This  will apply when the name of the question is not the same as the text you wish to  show the respondent.    Example    TravelHelp "Have you used any of the following to help you with your travel  arrangements?"      categorical [1..]      {          TravelBooks "Travel Books"          {              LonelyPlanetBook "Lonely Planet",              Fodor "Fodor's",              Frommer "Frommer's"          },          Websites "Websites"          {              Expedia "Expedia" ,              Orbitz "Orbitz" ,              Govt "Government Websites"          }      };        40        Survey Programming Fundamentals    Chapter 4  Special Responses and Options    The previous code will create the following question in the browser:                41    Chapter 4  Special Responses and Options    Survey Programming Fundamentals  Exercise  Update the first exercise (GroceryBill.mdd ) with the following additions that are highlighted below:  GroceryIntro   As you agreed to previously, please have your last grocery bill available for reference for  this next section of the survey.      GroceryDate  Looking at your last grocery bill, what date did you go to the store?      StoreName  What was the name of the store in which you shopped?                    Walmart  Safeway  Kroger  Albertsons  Ahold USA  Delhaize  Publix  Winn‐Dixie  Other (Specify) ______________   ItemTypes  Which of the following categories of groceries did you purchase on this shopping trip?  Prepared Foods    Cheese/Olive Bar   Salad Bar    Deli Items  Non‐Prepared Foods   Meat/Seafood   Produce    Canned Goods   Pasta/Grains None of These      Generic  On this particular shopping trip, did you purchase any generic brand items?        Yes  No  Don’t Remember     42      Survey Programming Fundamentals  ItemsBought    Chapter 4  Special Responses and Options    How many items did you buy?      GroceryCost  Exactly how much did you spend?        Prefer not to Answer   PurposeTrip  Briefly describe the reason for your trip to the grocery store on that particular day.          AgreeContact  Please check the box below if you agree to allow us to contact you later if we have  additional questions regarding your trip to the grocery store.                    43    Chapter 4  Special Responses and Options    44    Survey Programming Fundamentals        Survey Prrogramming Fundamentalls  Chapte er 5  Chapter 5  B Basic Routing Logic  Ba asic Routin ng Logic   So far, we have only ccreated the m metadata porttion of our survey.  This chapter focusess on how to  control th he flow of the e survey quesstions.   This ch hapter co overs: Understan nding, adding, reemoving routingg  context Changing the order of you ur questions Adding skip logic/routing to your survey Understan nding Dimension ns Functions and use  with logic statements     Here are some of the many things the routing section allowss you to do:  • • • • Control what questions aree asked  C T The order of q questions  A Add condition nal statementts about quesstions to conttrol if/how theey are asked  A Allows a singl e metadata fiile with differrent routings for ease of ch hanges to mu ulti‐mode survveys    mdd file as sh hown below:  To accesss the routing section, clickk on the Web tab in your .m     45    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals    You can add additional routings to your questionnaire.  This would be necessary for surveys fielded  with multiple collection methods, such as web, paper scanning, and telephone interviewing.  You  would also need to add routing if you originally created your metadata using either mrInterivew’s Build  activity or the accessory Word Capture, as they create a paper routing that is read only.    To add an additional routing:  • • Tools  Add Routing Context        46      Survey Programming Fundamentals    Chapter 5  Basic Routing Logic    You will be prompted for a name for the routing.    To remove a routing context, click on the tab of the context you wish to remove and choose  Tools ‐ Remove Routing Context as seen in the diagram above.  When setting up your routing, here are a few things to remember:  • • There is no re‐hydration of the routing section, so format counts.  Use Tabs to indent and make  your code easy to read.  Saving does not check the routing syntax; only when you start the survey will you see the  runtime problems.    Asking Questions  All we have done so far is create metadata and run the survey to review the questions.  mrStudio will  run all the questions in the metadata if there is nothing in the routing section.  This is not a practical  option, as almost all scripts have some routing.  Additionally, mrInterview will not run a script without  having a proper routing section.  The main items in your routing are statements to ask the questions.  Name.Ask()  Item  Name  .Ask()    Description  Metadata item name   Displays and asks the question    We will need to create .Ask() statements for each question in our survey.  To quickly ask all the  questions in your metadata,     • • • • View the Metadata Explorer  Click on the Fields folder  Right‐click to choose “Copy as Ask”  Paste in the routing section            47    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals          By expanding the Fields folder, you can pick and choose specific questions to copy as .Ask  statements.       48        Survey Programming Fundamentals    Chapter 5  Basic Routing Logic    Read Only Items  There is a way to show the question and current response for a question without the ability to change  the response:  Name.Show()    Item  Name  .Show()    Description  Metadata item name   Displays the question and its current response in read‐only format  When .Show() is used with a question, the choices are grayed out and you are only able to see the  current response for the question as shown below.          .Show() can also be used with info items; there is no difference using a .Show() or .Ask with  an info item.              49    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals  Conditional Statements  Now that we have asked all the questions, let’s look into ways to determine if a respondent should be  asked certain questions.  This is usually called routing or skip patterns.  There are two conditional items  we will review to help us create the routing for our surveys.  • • If… Then… Else  Select… Case    If… Then… Else  If – then – else is a conditional statement which will compare two or more statements and test the  results. If the results are true, the “then” actions are taken; if not, the “else” actions are taken.  The  syntax in Dimensions scripting is:  If condition Then             Actions  End if  For simple conditions it can all be stated on a single line:  If condition Then Action    Additionally, you could add the options for Else if and/or Else:  If condition Then             Actions  ElseIf condition Then      Actions  Else      Actions  End If      50        Survey Programming Fundamentals    Chapter 5  Basic Routing Logic    Now let’s look at some examples of these conditional statements.  To do this, we will need to  understand the syntax for some of the “Actions” you could use in the conditional statements.  One  action to use in the routing section is testing the response to a previous question.  We will look at  many ways to do this throughout the manual.  For this conditional section, here is some basic  information.  Name.Response.Value = condition or response  Item  Name  .Response.Value  Condition or  response    Description  Represents the metadata item name   Property to reference the named question’s current response value  Any condition to represent a possible response for the named question, or  specify an actual response   In the next example, we have the following questions as shown in the metadata:  Metadata (en‐US, Question, Label)  Example  TravelItem "From the list below, which one item would you most want to bring with you  on a leisure trip?"      categorical [1..1]      {          Camera,          Map,          ComfortableFootwear "Comfortable Footwear" ,          FriendTravelCompanion "Friend/Travel Companion"      };    'If Friend/Travel Companion is chosen in TravelItem, ask FriendRelate  FriendRelate "What is the relationship of that person to you?"      text;    'If Camera is chosen in TravelItem, ask TravelItemCost  TravelItemCost "How much would you expect to pay for the camera?"   Double [0..5000];      End Metadata              51    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals  The logic for the questions is, if the answer to the TravelItem question is “Friend/Travel Companion”,  then ask the FriendRelate question.  The logic is achieved in the following routing section with the use  of an If – Then statement:  Routing(Web)  Example      TravelItem.Ask()      If TravelItem.Response.Value = {FriendTravelCompanion} Then          FriendRelate.Ask()      End If      If TravelItem.Response.Value = {Camera} Then          TravelItemCost.Ask()      End If  End Routing  If the question is categorical, you will need to refer to the Name of the response (not the label that is  shown to the respondent) and enclose this in curly brackets as shown in the above example.    Select Case  Select Case statements work similar to an If – Then statement.  Select Case statements allow you to  create conditional actions based on a question type that can only have a single value (single‐ categorical, numeric, Boolean).  Select Case Name.Response.Value      Case Response1          Actions1      Case ResponseN          ActionsN           ...      [Case Else          ActionsN]  End Select  52      Survey Programming Fundamentals  Item  Select Case  End Select    Chapter 5  Basic Routing Logic    Description  Marks the Start and end of the select case statement    Name.Response.Value  Question and its response that you are testing  Case Response1, Case  Represents responses to a question or expressions that group responses to  Response2  the question.    Actions1, Actions2  Represent one or more statements to be executed if the question's response  matches the response for the current Case statement.    Case Else  Represents one or more statements to be executed for respondents who fail  ActionsN  all the previous Case tests    The case statement can be useful when you have many responses to test since you only specify the  question name once.  The following shows the previous example for an if then statement, now with  the select case syntax.  Example  Metadata (en‐US, Question, Label)  TravelItem "From the list below, which one item would you most want to bring with you  on a leisure trip?"      categorical [1..1]      {          Camera,          Map,          Comfortablefootwear "Comfortable Footwear",          FriendTravelCompanion "Friend/Travel Companion"      };    'If Friend/Travel Companion is chosen in TravelItem, ask FriendRelate  FriendRelate "What is the relationship of that person to you?"      text;    'If Camera is chosen in TravelItem, ask TravelItemCost  TravelItemCost "How much would you expect to pay for that item? "   Double [0..5000];    End Metadata                      53    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals      Routing(Web)      TravelItem.Ask()        Select Case TravelItem.Response.Value          Case {FriendTravelCompanion}              FriendRelate.Ask()          Case {Camera}              TravelItemCost.Ask()      End Select  End Routing          To have mrStudio create the case statement for you, view the metadata explorer, then  choose the question in which you will be basing the select statement.  Choose the question’s  categories folder and right‐click to choose Copy as Select statement.  You can then paste a  shell of the select statement with the question’s categories as a starting point.        54        Survey Programming Fundamentals    Chapter 5  Basic Routing Logic    Goto  In the examples above, we have been creating our routing based on good programming practices in  which you nest questions within conditional statements.  The methods shown thus far can help make  your code easy to follow and debug.  Sometimes, however, it may be helpful to skip around statements  in the routing section.  The Goto keyword can allow you to do this when combined with a conditional  statement.  Goto lineLabel  …  lineLabel:  Item  Goto  Linelabel  :    Description  Keyword indicating the script should skip to the line label indicated   Represents a line label of your choice.  The naming convention for line labels follows  the pattern of all names in the metadata.  These are not seen by the respondent.  Needed to indicate this is the line label item.  As an example, suppose we asked if the respondent travels for business.  Then there are a series of  questions about business travel, and a series of questions about travel for pleasure.  We can use a goto  and line labels to achieve the routing necessary.    Routing(Web)  Example      TravelforBusiness.Ask()      If TravelforBusiness.Response.Value = {No} then goto PleasureSection        DaysPerYrBusinessTravel.Ask()      InternationalBusiness.Ask()    PleasureSection:      TravelforPleasure.Ask()      …  End Routing      55    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals  Logical Expressions  In the previous section, we looked at some very simple logical expressions, such as  QuestionName.Response.Value = response.  We will cover additional options for creating expressions.  Numeric Questions  For testing numeric questions (long or double), use the math operators listed in the table below.  Item  =  <>  <  <=  >  >=    Example    Description  Equal to  Unequal to  Less than  Less than or equal to  Greater than  Greater than or equal to  Metadata(en‐US, Question, Label)    AmtSpentAccom "What price did you pay for your last overnight accommodations?"  double [0 .. 3999.99];    'If AmtSpentAccom is $150 or greater, ask TypeAccom question  TypeAccom "At what type of accommodations did you stay?" categorical [1..1]             { Hotel,              Motel,              BedBreakfast "Bed and Breakfast",              Hostels,              Resorts,              OtherAccom "Other Accommodations" other};  End Metadata    Routing(Web)        AmtSpentAccom.Ask()        If AmtSpentAccom.Response.Value  >= 150 Then            TypeAccom.Ask()        End  If    End Routing      56      Survey Programming Fundamentals    Chapter 5  Basic Routing Logic    Boolean Questions  Boolean questions have values of True or False, so they can easily be checked with a simple statement:  Name.Response.Value = condition  Item  Name  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Response.Value  Current response to the question identified by “name” above  condition  True (checkbox was checked) or False(checkbox was left empty)    Text Questions  With text questions you can test whether the response matches a pattern. The expression format is:  Name Like "pattern"  Item  Name  like  pattern  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Keyword to indicate you are trying to match a test pattern  Represents the text with which the response is to be compared. An underscore  (_)in the text matches any single character, and a percent sign (%) matches any  number of characters, including zero    The following code checks text questions to see if it contains the word, Luftansa.  If it does, then it  follows up with another question.  Example    Metadata(en‐US, Question, Label)  BestAirTravel "Explain your best experience with air travel.  Please mention your  destinations, airports and airline."      text;    TimesWithLuftansa "And how many times over the past year have you flown Luftansa?"  long [0..365];  End Metadata    Routing(Web)      BestAirTravel.Ask()      If BestAirTravel.Response.Value Like "%Luftansa%" Then          TimesWithLuftansa.Ask()      End If  End Routing      57    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals  Categorical Questions  For single‐response categorical questions, you may find simple expressions to suffice, such as  Name.Response.Value={Yes} .  However, things will get complex, and you’ll need the Dimensions  functions to make more advanced logic statements.  Dimensions functions for categorical responses were created specifically for Dimensions scripting.  We  will cover 3 basic functions for routing purposes, ContainsAll , ContainsAny and AnswerCount.    For a full list of functions, see  DDL.chm::/funclib_overview.htm        ContainsAll  Identifies whether a category list contains all of the categories in a given list.  “And” condition for an  individual question.  Name.ContainsAll({ID1, IDn},parameter)  Item  Name  ContainsAll  Description  Represents the question name   Dimensions function testing whether a list of categories are all contained in the  named question.  (And condition)  ID1, IDn  Unique identifying name for the response.    parameter  Represents an optional parameter.  If the parameter is set to true, then the  function will be true only if the response contains all of the categories and no  others (exclusive).  If the parameter is set to false (default), then the function  will be true if the response contains all of the responses listed, regardless of  other responses chosen from the question.        Example  CountryVisited.ContainsAll({NorthAmerica,SouthAmerica})      This statement would be true if a respondent chose both North America and South America in the  CountryVisited question, regardless of other responses chosen from the question.  58      Survey Programming Fundamentals    Chapter 5  Basic Routing Logic          Example  CountryVisited.ContainsAll({NorthAmerica,SouthAmerica}, true)      This statement would be true if a respondent chose both North America and South America AND did  not choose any other responses in CountryVisited.    ContainsAny  Identifies whether a category list contains one or more categories in a given list.  “Or” condition for an  individual question.  Name.ContainsAny({ID1, IDn},true)  Item  Name  ContainsAny  Description  Represents the question name   Dimensions function testing whether any of the list of categories are contained  in the named question.  (Or condition)  ID1, IDn  Unique identifying name for the response.    True  Represents an optional parameter.  If the parameter is set to true, then the  function will be true only if the response contains any of the categories and no  others (exclusive).  If the parameter is set to false (default), then the function  will be true if the response contains any of the responses listed, regardless of  other responses chosen from the question.        Example  CountryVisited.ContainsAny({NorthAmerica,SouthAmerica})      The above statement would be true for respondents choosing North America, South America, or both.        59    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals  AnswerCount  The function AnswerCount counts the number of mentions chosen for a specific categorical question.    Name.AnswerCount()  Item  Name  AnswerCount  Description  Represents the question name   Dimensions function returning how many responses have been chosen in the  named categorical question.      It returns a numeric value, so you would use numeric operators to test the result of the function.  If CountryVisited.AnswerCount() > 3  then  Example       WhySoMany.Ask()  End if    The example above states that if the number of answers mentioned in the categorical question,  CountryVisited, is greater than 3, then ask the follow‐up question.    Logical Operators  You can also use the logical operators of Not, And, Or, and Xor to create more complex routing  conditions.  NOT  It is used to negate expressions.  It’s recommended to enclose the item to negate in parenthesis as  shown below.  Example      Not (TravelHelp.ContainsAny({Expedia}))        The above would be true if the respondent did not answer Expedia for the TravelHelp question.      60        Survey Programming Fundamentals    Chapter 5  Basic Routing Logic    AND  Returns true when both parts of the expression are true.  Example      DaysTravelYr > 5 And TravelHelp.ContainsAny({Expedia})        The above will be true if the respondent traveled more than 5 days and used Expedia.    OR  Returns true when either or both parts of the expression are true.  Example      DaysTravelYr > 5 Or TravelHelp.ContainsAny({Expedia})        The above will be true if the respondent traveled more than 5 days or used Expedia.    XOR  Returns true when one part (but not both parts) of the expression are true.  Example      DaysTravelYr > 5 Xor TravelHelp.ContainsAny({Expedia})        The above will be true if the respondent traveled more than 5 days and did not use Expedia, or if the  respondent traveled 5 days or less and did use Expedia.            61    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals  Some find xor confusing, but it can save some syntax.  The following statement is the equivalent of the  previous xor statement:   Example      (DaysTravelYr > 5 And (Not (TravelHelp.ContainsAny({Expedia}))) ) Or (DaysTravelYr <= 5 And  TravelHelp.ContainsAny({Expedia}))      As you can see when creating complex conditions with combinations of and, or, and not statements,  put parenthesis around things you want evaluated together.      If you need to refer to the special responses DK, REF, NA in a non‐categorical question, you  need to refer to it as QuestionName.Response.Coded = {ID}, where ID is the ID of the special  response.      Tips for Routing Section Syntax  There are numerous ways to write the syntax within the routing section.  Here are some hints to help  you to take full use of the ScriptAssist within mrStudio.  • • • • Ctrl‐Q to see the full list of questions in your metadata  Ctrl‐R will display the responses for a Question listed  Right‐click on a question name in the routing section and choose Goto Definition which will  take you to that question in the metadata section  Choose the period (.) to see valid choices for your statement      This may not always work, as there are multiple ways to write the statements.  You will  notice the ScriptAssist may not always provide the proper choices. A good example would  be Dimensions functions, such as ContainsAny.  The method used in this chapter,  Name.ContainsAny({Response}), does not provide script assistance.  The fully documented  way,  ContainsAny(Name.Response.Value,{Response}), will show parameters needed.      62        Survey Programming Fundamentals    Chapter 5  Basic Routing Logic    Adding Error Handling  Another important aspect of the routing section is the ability to send error messages to both the  respondent and the mrInterview logging when there is a problem with the script.  Error handling allows  the system to gracefully handle errors that occur, as opposed to a generic error messages that will not  provide appropriate information to fix the problem and possibly confuse respondents.  The code can  be standardized and placed in every script.  Below is a simple example to use as a starting point.    Example    Routing(Web)  '‐‐‐ Error handler ‐‐‐      If Not IOM.Info.IsDebug Then On Error Goto DefaultErrHandler      Goto StartOfScript    DefaultErrHandler:      Dim errmsg, numerror      errmsg = "Script error at line " + CText(Err.LineNumber) + ", " + Err.Description      IOM.Log(errmsg, LogLevels.LOGLEVEL_ERROR)      If IOM.Info.IsTest Then          IOM.Banners.AddNew("ScriptErrMsg" + CText(numerror), errmsg)         numerror = numerror + 1      End If      Resume Next    StartOfScript:  '‐‐‐ End error handler ‐‐‐    End Routing    Breaking down the example above:  • • • • The IOM.Info.IsDebug prevents the error handler being enabled if the script is being run in  mrStudio.  On Error Goto DefaultHandler sends all erros to the error handler.  When an error occurs, the  error handler writes the error message and the line number to the log file, IVW*.tmp.  IOM.Info.IsTest  displays the message on the top of the current page.  The “Resume Next” line allows the interview to continue after an error.                63    Chapter 5  Basic Routing Logic    Survey Programming Fundamentals  Exercise  Use the metadata file, Routing.mdd as your starting point.  Complete the routing section and  routing/skip  patterns shown below.    CookAtHome  Do you ever cook food at home?      Yes  No  (Skip to ItemsOwned)   CookMealWk  How many meals per week do you cook at home? __________    PeopleCookFor   Do you normally cook for any of the following at your home? Check all that apply.            Spouse/Other Adults in the household Children in the household Non‐Household Member Adults Non‐Household Member Children Only for Myself   (If  CookMealWk is greater than or equal to 5 and PeopleCookFor question has adults, ask Wine)  Wine    Do you ever serve wine with the meals you serve to others?      Yes  No        (If PeopleCookFor is both Children in HH and Non‐Household Member Children, ask AllergyKids)  AllergyKids  Do any of the children you make meals for have food allergies?       Yes  No          64        Survey Programming Fundamentals  PrepTime    Chapter 5  Basic Routing Logic    On average, how much time do you devote to preparing a single meal?          30 minutes or less 31‐90 minutes  Over 90 minutes Don’t know    (If PrepTime is 30 minutes or less, ask MealStrategy)  MealStrategy  Please list some of your strategies for preparing meals so quickly.        (If PrepTime is 31‐90 minutes, ask AmtPrep)  AmtPrep  Do you feel that your preparation time for meals is…          Too short  Too long  Just right  Don’t Know    (If PrepTime is Over 90 minutes, ask PrepDescrip)  PrepDescrip  Do you take over 90 minutes to prepare meals mainly because of…            The amount of entrees created The complexity of the dishes The number of interruptions during the process Other (specify) ______________ Don’t Know              65    Chapter 5  Basic Routing Logic  ItemsOwned    Survey Programming Fundamentals  Which of the following kitchenware items do you own?              Bread Maker  Food Processor Stand Mixer  Wok  Fondue Pot  None of These      (If respondent owns 3 or more kitchen items in ItemsOwned, ask UseItems)  UseItems  Do you use some/all the items mentioned previously…            Daily  Weekly  Monthly  Yearly  Never      (If CookAtHome is No, and UseItems not equal to Never, ask WhatUseFor)  WhatUseFor  Please explain what you use your kitchen items for if you do not cook at home.            66        Survey Prrogramming Fundamentalls  Chapte er 6  Chap pter 6  Shared d Lists  Shared Listss  When creeating a surve ey, you may rrepeat the same responsess question aftter question.  Using a sharred  list will allow you to crreate the resp ponse list oncce and use it many times.  In addition, iif changes need  to be made to your re esponse list, yyou have one central location to make tthe changes tto update many  questions at once.  This ch hapter co overs: Creating a re‐useable ressponse list Including ssubheadings in n a list Dealing wiith identical response text in two  or more lissts     Creating a shared list is very similar to adding caategories to aa categorical q question.   LListName  "Text" define  { {ID1 "AltText1 1",   IDn "AltTextn n" } ;  Item  ListName e  "Text"  Define  {   }  ID1, IDn  AltText1,,  AltTextn  Desscription  Uniique identifier for the sharred list in the metadata.  TThey must start with a  lettter or undersccore ( _ ) and contain onlyy alpha‐numeric characterss or the  sym mbols @, $, #,, or _   Opttional text wh hen list is used as a sublist.    Keyyword to creaate a shared liist  Indicates the staart of the cateegories for the define list Uniique identifying name for tthe response.  This needs to be unique per  que estion, not meetadata file.  Rules for the response names are the ssame as the  nam me of the queestion.  Opttional text to show the resspondent insttead of the naame of the qu uestion.  This  willl apply when the name of the question is not the sam me as the texxt you wish to o  sho ow the respon ndent.          67    Chapter 6  Shared Lists    Survey Programming Fundamentals  To make use of the responses in a question:  Name "Text" categorical  [Min..Max]  {use listname} ;  Item  Name  "Text"  Categorical   [Min..Max]  Use  Listname    Description  Name of the Question   Text associated with the question (considered the label in the object model).  Keyword to create a question with categories for response choices.    Optional parameters.  Controls the minimum and maximum amount of  categories that can be chosen by a respondent.  Default is open to any amount  of choices.  Automatically issues an error message if the number of responses  chosen is below the minimum or above the maximum.   Keyword to include the categories from a define list in the question.  Represents the name of the define list to use for the categories of the question.    Example    ResortTypes  define      {          Historical,          AmusementPark "Amusement Park",          Beach,          Adventure      };      ResortStayed "Of the following, which Resort types have you stayed at in the last year?"      Categorical [1..]      { use ResortTypes };      Some things to keep in mind about shared lists:  • • • You can use more than one list within the same question  You can create shared lists that are made up of other shared lists  You can use a shared list with a question in addition to adding other categories to that specific  question    68      Survey Programming Fundamentals    Chapter 6  Shared Lists    Creating Subheadings with Shared Lists  You learned to create subheadings in a previous chapter.  Now that you have learned shared lists,  there is another way to create subheadings using multiple shared lists.  Name "Text" categorical  [min..max]  {use listname1 Sublist "Sublistname1",    Use listnameN Sublist "SublistnameN"  } ;  Item  Name  "Text"  Categorical   [Min..Max]  Description  Name of the Question   Text associated with the question (considered the label in the object model).  Keyword to create a question with categories for response choices.    Optional parameters.  Controls the minimum and maximum amount of  categories that can be chosen by a respondent.  Default is open to any amount  of choices.  Automatically issues an error message if the number of responses  chosen is below the minimum or above the maximum.   Use  Keyword to use the categories from a define list  listname1,  Represents the name of the define lists to use for the sublist categories of the  listnameN  question.  Sublist  Keyword to designate the preceding define list as a subheading list  “Sublistname1”,  Optional Text to display as the subheading Text.   If not specified, will use label  “SublistnameN”  specified in the define list.            69    Chapter 6  Shared Lists    Survey Programming Fundamentals  The following example uses the concept of sublist using two define lists to create subheadings in the  categorical question.  Example    Metadata (en‐US, Question, Label)  ResortTypes "" define      {          Historical,          AmusementPark "Amusement Park",          Beach ,          Adventure      };  CampingTypes "" define      {          GovtPark "Government Park",          RainForest "Rain Forest",          River "River (Canoe/White‐Water Rafting)",          Mountain "Mountain Climbing"      };    CamporResortStayed "Of the following, which Resorts have you stayed at and what types  of camping have you participated in the last year?"      Categorical [1..]      {          use ResortTypes  sublist  "Resorts:" ,          use CampingTypes  sublist  "Camping:",          Noneofthese "None of these" style (Indent = 0) NA      };  End Metadata    70      Survey Programming Fundamentals    Chapter 6  Shared Lists      The example shows a “None of these” choice.  This demonstrates that you can have additional  categories in a question outside of any define lists used.      Instead of stating the subheading text after the keyword sublist, this could have been  placed between the empty “” in the define lists.          71    Chapter 6  Shared Lists    72    Survey Programming Fundamentals        Survey Prrogramming Fundamentalls  Chapte er 7    C Chapter 7  Sor rting Categoriical Responsee Lists  Sorting Cate egorical R  Response Lists  You may need to chan nge the orderr of the categorical responses in a questtion.  This is ssometimes do one  to preven nt bias within n a survey or ssimply to re‐o order the list alphabetically.  This chaptter will cover the  sorting options for mrrInterview.    This chapter w will show w you how w to: Change the order of your response lists Use the so orting comman nds in both the  metadata and routing seections Ensure cerrtain responsess are not sorteed  within a so orted list     The types of sorts avaailable in mrIn nterview are aas follows:  Item  Rotate  Descriptio on  The catego ory list is rotaated by one category before each preseentation of th he  list.  The catego ory list is pressented in randomized ordeer.  The catego ory list is reveersed before each presenttation. This m means that thee list  is presenteed top‐down to the first reespondent, bottom‐up to tthe next, etc..  The catego ory list is sortted in ascending alphabetical order.   The catego ory list is sortted in descending alphabetical order.  Randomiize  Reverse  Ascendin ng  Descending    use any of the e sorting feattures above in n either the m metadata or the routing seections as sho own  You can u in the next sections.    andomize fea ature in the m metadata and routing sections  There is a differencce using the ra when using the sam me response llist for multiple questions.  Using the metadata meth hod will  hold th he same patttern for each q question per respondent; tthe routing m method will ch hange  the pa attern for each question.          73    Chapter 7  Sorting Categorical Response Lists    Survey Programming Fundamentals  Sorting in Metadata  To sort a question in the Metadata section, use any of the keywords for sorting following the curly  brackets of a category list.  Name "Text" categorical  [min..max]  {ID1 "AltText1",   IDn "AltTextn" } sortingkeyword;    Item  Name  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   "Text"  Text associated with the item (considered the label in the object model).  categorical   Keyword to create a question with categories for response choices.    [Min..Max]  Optional parameters.  Controls the minimum and maximum amount of  categories that can be chosen by a respondent.  Default is open to any amount  of choices.  Automatically issues an error message if the number of responses  chosen is below the minimum or above the maximum.   {   }  Indicates the start of the categories you wish the respondent to choose from for  the question  ID1, IDn  Unique identifying name for the response.    AltText1,  Optional text to show the respondent instead of the name of the question.  This  AltTextn  will apply when the name of the question is not the same as the text you wish to  show the respondent.  sortingkeyword  Represents one of the sorting keywords rotate or rot; randomize or ran; reverse  or rev; ascending or asc; descending or desc    In the example below, adding the ran keyword randomizes the response list.    Example  Metadata (en‐US, Question, Label)    Souvenirs "Which of the following souvenirs do you prefer to purchase when on holiday  or vacation?"        categorical [1..]      {          Clothing,          Hats,          Postcards ,          SnowGlobes "Snow Globes"      } ran;    End Metadata    74      Survey Programming Fundamentals    Chapter 7  Sorting Categorical Response Lists      Routing Section Sorting  In the routing section, the syntax for sorting is:  Name.Categories.Order=orderconstants.osortingkeyword  Item  Description  Name  Represents the name of the question to sort   Osortingkeyword  Represents one of the sorting keywords oAscending, oDescending, oCustom,  oRandomize, oReverse, or oRotate.    Routing(Web)  Example  Souvenirs.Categories.Order=orderconstants.oAscending  Souvenirs.Ask()    End Routing  The above statement will sort the list alphabetically A to Z.    Not Sorting Specific Responses  There may be certain responses that you do not want sorted within a list, such as “None of These” or  “All of These”.  To force a group of categories to retain its original position when the overall category  list is sorted, use the keyword fix.  Name "Text" categorical  [min..max]  {ID1 "AltText1" fix,   IDn "AltTextn"} sortingkeyword;  Item  Fix  Description  Keyword to make the category prior to the keyword fixed in its original position,  regardless of the sort order   sortingkeyword  Represents one of the sorting keywords listed in the previous section (example  ran)             75    Chapter 7  Sorting Categorical Response Lists    Survey Programming Fundamentals  The following example will not sort the None of these option; it will stay at the bottom of the list.  In  addition, the Other responses will always be the last in the series of items for their individual lists.  Example    Metadata (en‐US, Question, Label)  TravelHelp "Have you used any of the following to help you with your travel  arrangements?"      Categorical [1..]      {          TravelBooks "Travel Books"          {              LonelyPlanetBook "Lonely Planet",              Fodor "Fodor's" ,              Frommer "Frommer's" ,              otherBooks "Other Travel Book" other fix          } ran,          Websites          {              Expedia ,              Orbitz,              Govt "Government Websites",              otherwebsite "Other Website" other fix          } ran,          Noneofthese "None of these"  style (indent = 0)  fix exclusive      } ran;  End Metadata        This also demonstrates a style being used to force the “None of these” response to be lined up with  the Subheadings instead of indented (indent=0).  You will learn more about styles in Chapter 13   Controlling the Look of Your Survey.      76        Survey Programming Fundamentals    Chapter 7  Sorting Categorical Response Lists    Keeping Specific Categories Grouped Together  You may need to keep pairs or groups of categories together within a list, even when adding  randomization.  You can achieve this by creating a sublist with the items that need to be kept together,  while randomizing the main question.  The example below will randomize the TypeAccom question but  always keep the responses in the define list resorts together.  Example    Metadata (en‐US, Question, Label)    Resorts define      {          FamilyResorts "Family Resorts",          CouplesResorts "Couples Resorts"      };    TypeAccom "At what type of accommodations did you stay?"      categorical [1..1]      {          Hotel ,          Motel ,          BedBreakfast "Bed and Breakfast",          Hostels ,          use Resorts sublist ,          OtherAccom "Other Accommodations" other fix      } ran;    End Metadata              77    Chapter 7  Sorting Categorical Response Lists    Survey Programming Fundamentals  Exercise  Update the following questions by adding the features highlighted below in your GroceryBill.mdd file  to include sorted categories.  StoreName  What was the name of the store in which you shopped? (RANDOMIZE)                    Walmart  Safeway  Kroger  Albertsons  Ahold USA  Delhaize  Publix  Winn‐Dixie  Other (Specify) ______________   ItemTypes    Which of the following categories of groceries did you purchase on this shopping trip?  (RANDOMIZE BOTH THE GROUPS AND THE ITEMS WITHIN THE GROUPS)  Prepared Foods    Cheese/Olive Bar   Salad Bar    Deli Items  Non‐Prepared Foods   Meat/Seafood   Produce    Canned Goods   Pasta/Grains   None of These              78        Survey Prrogramming Fundamentalls  Chapte er 8  Ch hapter 8  Resttricting Respo onses  Re estricting  Response es  The logicc behind the ssurvey is an im mportant partt of research to ensure acccurate data.  In this section,  we can leearn how to p present the reespondent wiith logical cho oices.  In this chapter w we will: Filter responses displayeed on a questio on  previous answeers to question ns based on p Filter responses based on your internal logic Limit the m maximum or m minimum amou unts  for numeric questions baased on logic     Filter C  Categoriess  The Filterr property can be used to limit the cateegories displaayed by a question in the routing section.  Routing(Web)  R     Name.Categories.Filter==condition      Name.Ask())  E End Routing    Item  Name  Categorie es  Filter  condition n    Desscription  Uniique identifier for the quesstion name.  Pro operty (keywo ord)  of the qu uestion denotting the respo onses  Pro operty (keywo ord) to state yyou are restricting the cateegories for th he question  Rep presents anytthing that stattes the categories to display for the question            79    Chapter 8  Restricting Responses    Survey Programming Fundamentals  Here is an example in which we are asking respondents to choose all the hotel chains they have stayed  in the past year.  The follow‐up question is “Of those chains, which is your favorite?”  The response list  for the follow‐up question is restricted to only the answers given in the first question.  Example    Metadata (en‐US, Question, Label)    HotelChainStayed "Choose the hotel chains you have stayed at this past year."   categorical [1..]      {          InterContinental,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };  FavHotelChain "Of those chains, which one would you most prefer to stay at again?"  categorical  [1..1]      {          InterContinental,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };    End Metadata    Routing(Web)      HotelChainStayed.Ask()      FavHotelChain.Categories.Filter=HotelChainStayed.Response.Value      FavHotelChain.Ask()    End Routing          80      Survey Programming Fundamentals    Chapter 8  Restricting Responses      If you choose:    The result will be:          Special Responses of DK, REF, and NA are not filtered out automatically.  In addition, if any  of those special responses are chosen, it skips the filtered question.          81    Chapter 8  Restricting Responses    Survey Programming Fundamentals    How does the above work?  The filters are based on the NAMES of the responses.  While it is not  necessary to use shared lists for filtering, it is a good practice when the response lists are identical to  ensure that the names are also identical.  You do NOT need to have the lists identical to filter one question off another.  mrInterview will simply  match what it can and disregards the rest.   For instance, what if our lists were different:    Example    HotelChainStayed "Choose the hotel chains you have stayed at this past year."   categorical [1..]      {          InterContinental,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };      FavHotelChain "Of the chains listed below in which you stayed, which one would you  most prefer to stay at again?" categorical  [1..1]      {          Accor,          Choice,          Hilton,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };    Routing(Web)      HotelChainStayed.Ask()      FavHotelChain.Categories.Filter=HotelChainStayed.Response.Value      FavHotelChain.Ask()  End Routing          82      Survey Programming Fundamentals    Chapter 8  Restricting Responses    If you choose:    The result is:    As you can see, even though InterContinental was chosen, it does not show in the list, since it is not  part of the categories in FavHotelChain.      The above examples assume a naming convention for your category names.  This is  recommended as names that identify the response make more sense across the entire  project lifecycle.            83    Chapter 8  Restricting Responses    Survey Programming Fundamentals  Additionally, the filter does not need to be a single question.  This can be a multitude of conditions,  such as Dimensions functions or specific categories.  Suppose our previous example was slightly different.  What if we had two separate questions that  collected the hotels stayed in the past year.  We will need two filter statements:  • • Filter the response from the first question so that it cannot be chosen from the 2nd list  Filter to combine both the first response and the 2nd response for the final question  Example    84  HotelChainStayMost "Choose the hotel chain you have stayed at the MOST this past  year."   categorical [1..1]      {          InterContinental,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };    HotelChainStayed  "Choose the other hotel chains you have stayed at this past year."   categorical [1..]      {          InterContinental,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };      FavHotelChain "Of the chains listed below in which you stayed, which one would you  most prefer to stay at again?"   categorical [1..1]      {          Accor,          Choice,          Hilton,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };        Survey Programming Fundamentals    Chapter 8  Restricting Responses    Routing(Web)      HotelChainStayMost.Ask()        HotelChainStayed.Categories.Filter= HotelChainStayed.Categories –           HotelChainStayMost.Response.Value      HotelChainStayed.Ask()        FavHotelChain.categories.filter=Union(HotelChainStayMost,HotelChainStayed)      FavHotelChain.Ask()  End Routing              See the Dimensions Development Library for more categorical functions to help with filters,  such as Difference and Intersection)  DDL.chm::/categorical_functions.htm                   85    Chapter 8  Restricting Responses    Survey Programming Fundamentals  Limiting Numeric Question Ranges Based on Logic  Another aspect of accurate data is to be able to set the minimum or maximum amount that can be  entered for a numeric response based off previous answers from the respondent.  You can control the  minimum and maximum values for a question with the following statements in the routing section.  Name.Validation.MinValue = condition  Name.Validation.MaxValue = condition  Item  Name  Validation  MinValue  MaxValue  Condition    Example    Description  Metadata item name  Property of questions  Property to control the minimum value allowed for a numeric question.  Takes  precedence over what is stated as the minimum in square brackets on the  question.  Property to control the maximum value allowed for a numeric question.  Takes  precedence over what is stated as the maximum in square brackets on the  question.  Represents the new value for the minimum or maximum limits  Metadata(en‐US, Question, label)    AmtSpentonHoliday "Approximately how much in total did you spend last year on your  holidays/vacations?" long [0..10000];      AmtSpentAir "And of that amount, how much was spent on airfares?" long [0..10000];     End Metadata      Routing(Web)      AmtSpentonHoliday.Ask()      AmtSpentAir.Validation.MaxValue = AmtSpentonHoliday.Response.Value      AmtSpentAir.Ask()  End Routing        86        Survey Programming Fundamentals    Chapter 8  Restricting Responses      If you answered 5000 for the question AmtSpentonHoliday, then tried to submit an answer greater  than 5000 for AmtSpentAir, you would see the following:        87    Chapter 8  Restricting Responses    Survey Programming Fundamentals  Exercise  Create a new metadata file called MealsOut.mdd.   Make sure that:  • • • • You make shared lists for American Cuisine, International Cuisine, and restaurant attributes.  FavCuisine only displays the cuisines the respondent has ever eaten.  The answer to EatMealOut is not greater than the OrderMealOut amount.  Make the filter for the RestaurantOthr question be the responses not chosen in Restaurant1.   In addition, the other specify choice should show in RestaurantOther regardless if it was  chosen in Restaurant1.    CuisineEaten  Which of the following types of Cuisine have you ever eaten?  American Cuisine    Barbecue    Cajun    Southern    Southwestern International Cuisine   Italian    Russian    Polish    French    Caribbean    None of These    FavCuisine  Of those mentioned, which one do you prefer?  American Cuisine    Barbecue    Cajun    Southern    Southwestern International Cuisine   Italian    Russian    Polish    French    Caribbean    None of These    OrderMealOut  On average, how many meals per week do you order from a restaurant?          (If zero to OrderMealOut, skip to Thanks)  88        Survey Programming Fundamentals    Chapter 8  Restricting Responses    EatMealOut  Of those meals, how many do you eat at the restaurant, as opposed to home delivery or  carry‐out?        (If zero to EatMealOut, skip to Thanks)    Restaurant1 When you eat at a restaurant, what one thing makes you want to return to the restaurant  again?            Good food  Good service  Nice  Atmosphere Large Selection of menu choices Other (Specify) ________________________     RestaurantOthr What other factors also influence your decision to return to a restaurant?            Good food  Good service  Nice  Atmosphere Large Selection of menu choices Other (Specify) ________________________   Thanks    Thank you for your input.            89    Chapter 8  Restricting Responses    90    Survey Programming Fundamentals        Survey Prrogramming Fundamentalls  Chapte er 9  Chapter 9  M Multiple Questtions on One Page  Mu ultiple Qu uestions o  on One Pa age  By default mrInterview w displays on ne question peer screen.  Th here will be times when yo ou will want to  display m multiple questtions on the ssame screen.    In this chapter w we will: Learn to place multiple q questions on th he  same screeen Discuss thee differences b between pagess and  blocks Learn to co ontrol if a quesstion is presented on  the screen n or in what ord der.      place multiple e questions o on the same sscreen by usin ng page or blo ock statemen nts.    You can p • • Page metadatta items referrence other questions in th P he metadata to group them m on the sam me  s screen.  If you u are only tryiing to presentt more than o one question on a screen, use a page. B Block metada ta items conttain other queestions, similar to how a ggrid question can contain  m multiple ques tions.   The block type can n be used to ggroup a list off questions fo or presentatio on  a and organizat tional purposees. For examp ple, if you aree trying to gro oup questionss together forr use  w with the analy ysis products mrTables and d Desktop Reeporter.          91    Chapter 9  Multiple Questions on One Page    Survey Programming Fundamentals  Page  Creating a page in metadata creates a metadata item that states the questions you want displayed on  a screen and the order in which they should be displayed.  In the metadata section:  Name "text" page(QuestionName1, QuestionName2, QuestionNameN);  Item  Name  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   "text"  Optional text to show on the top of the screen  page  Keyword to state we are grouping the following questions on the same page  QuestionName1,  Represents the question names to display on the page together.  QuestionName2,  QuestionNamen      In the routing section, ask the page, not the individual questions:  Name.Ask()  Item  Name  .Ask()    Description  Name of the page metadata item   Ask the questions listed in the page item    If you have many pages to create .Ask statements for, in the metadata viewer choose the  Page folder.  Right‐click to choose Copy as Ask.          92        Survey Programming Fundamentals    Chapter 9  Multiple Questions on One Page    The following is an example showing multiple demographic questions on the same screen.  Example    Metadata (en‐US, Question, label)  HouseHold "Including yourself, how many people currently live in your household?"      long [1 .. 99];        Age "To which of the following age categories do you belong?"      Categorical [1..1]      {          Under18 "Under 18",          _18to34 "18 to 34",          _35to54 "35 to 54",          _55plus "55 and over" ,          Refused "Prefer not to Answer" REF      };        Participate "Check here if you wish to participate in future studies on travel."      boolean;        Demos "Now a few demographic questions"      page(          HouseHold,          Age,          Participate      );  End Metadata      Routing        Demos.Ask()    End Routing            93    Chapter 9  Multiple Questions on One Page    Survey Programming Fundamentals  Will display as:        Block  Blocks are metadata items that contain the questions you want displayed together on a screen.  Name "text" block fields        (           QuestionName1 "text" QuestionType;             QuestionNamen "text" QuestionType;         );    94        Survey Programming Fundamentals    Chapter 9  Multiple Questions on One Page      Item  Name  "text"  block  fields  QuestionName1,  QuestionNamen    Description  Represents the name of the block   Optional text to show on the top of the screen  Keyword to identify the item as a block  Start of the questions contained in the block  Represents the questions contained inside the block  In the routing, ask the block name:  Name.Ask()  Item  Name  .Ask()    Description  Name of the block metadata item   Ask the questions listed in the block item  As you can see in the following example, blocks are like containers which hold multiple questions.  Example    Metadata (en‐US, Question, label)  Demos "Now a few demographic questions" block fields    (    HouseHold "Including yourself, how many people currently live in your household?"      long [1 .. 99];        Age "To which of the following age categories do you belong?"      categorical [1..1]          {          Under18 "Under 18",          _18to34 "18 to 34",          _35to54 "35 to 54",          _55plus "55 and over" ,          Refused "Prefer not to Answer" REF      };        Participate "Check here if you wish to participate in future studies on travel."      boolean;    );  End Metadata    Routing      Demos.Ask()  End Routing      95    Chapter 9  Multiple Questions on One Page    Survey Programming Fundamentals    The previous code will look identical to the page example when viewed in the browser.  However, the  metadata itself is very different.  The block creates a separate item for blocks, as seen in the metadata  viewer:    Since your questions are now contained within a block, this will also affect how you refer to a question  in a block.    Blockname.Name      96        Survey Programming Fundamentals    Chapter 9  Multiple Questions on One Page    The following example shows how you would refer to questions in a block within the routing section.  Example    Metadata (en‐US, Question, label)  AgeGroups "" define      {          Under18 "Under 18",          _18to34 "18 to 34",          _35to54 "35 to 54",          _55plus "55 and over"  };    Demos "Now a few demographic questions" block fields    (    HouseHold "Including yourself, how many people currently live in your household?"      long [1 .. 99];        Age "To which of the following age categories do you belong?"      categorical [1..1]      { use AgeGroups ,           Refused "Prefer not to Answer" REF       };        Participate "Check here if you wish to participate in future studies on travel."      boolean;    );    KidsAtHome "Do you have any children under the age of 18 living in your household?"       categorical [1..1]      {          Yes ,          No       };    End Metadata    Routing      Demos.Ask()        If Demos.household.Response.Value > 1 then           KidsAtHome.Ask()      End if  End Routing            97    Chapter 9  Multiple Questions on One Page    Survey Programming Fundamentals  Controlling How Page and Block Questions are Displayed  You can control the page or block questions asked on the screen by:  • • Filtering the page or block  Using a sorting keyword on the page/block    Filtering a Page/Block  Using the same principles we learned with filtering, we can use a QuestionFilter to restrict the  questions shown to certain respondents.    Name.QuestionFilter= “Question1, QuestionN”  Item  Name  QuestionFilter  question1,  questionN    Description  Name of the grid/loop question   Property (keyword) to state you are restricting the questions of the page, or  block.  This property also applies to grid/loop categories.  Represents questions that will be added to the questionfilter and shown on the  screen.   The following will not show the question asking to participate in future studies if they are already a  member of our panel group.  Example    98  Metadata (en‐US, Question, label)    Membership "Are you currently a member of our panel?"   Categorical [1..1]  {     Yes,      No  };    HouseHold "Including yourself, how many people currently live in your household?"      long [1 .. 99];        Age "To which of the following age categories do you belong?"      categorical [1..1]      {          Under18 "Under 18",          _18to34 "18 to 34",          _35to54 "35 to 54",          _55plus "55 and over"          Refused "Prefer not to Answer" REF      };        Survey Programming Fundamentals    Chapter 9  Multiple Questions on One Page        Participate "Check here if you wish to participate in future studies on travel."      boolean;        Demos "Now a few demographic questions"      page(          HouseHold,          Age,          Participate      );  End Metadata    Routing(Web)        Membership.Ask()        If Membership={Yes} then Demos.QuestionFilter=”Household, Age”          Demos.Ask()        End Routing    Sorting a Page/Block  You can control the order of the questions with the same sorting options as shown previously.  Simply  apply the sort keyword to the block or page name.    The following example would randomize the questions shown on the screen for the demos page or  block.  Example    Routing(Web)        ' Using Demos from the previous examples        Demos.QuestionOrder=OrderConstants.oRandomize           Demos.Ask()    End Routing            99    Chapter 9  Multiple Questions on One Page    Survey Programming Fundamentals  Exercise  Open the GroceryBill.mdd file and Save As CH09GroceryBill.mdd.  Modify CH09GroceryBill.mdd so that:  • • •   100  GroceryDate and StoreName are on the same page using a PAGE statement  Generic, ItemsBought, and GroceryCost are contained within a BLOCK item  Review the metadata for the block to see how it has changed          Chapter 10  Repettitive Questio ons ‐ Loops & Grids  Survey Prrogramming Fundamentalls  Chapte er 10  Re epetitive Q  Questionss ­ Loops &  & Grids  Many surrveys involve the concept of asking the same basic q question with h different atttributes multiiple  times.  Th he concept is sometimes ccalled a grid o or a loop.      In this chapter w we will: Understan nd when to usee a grid or a loo op in a  survey Create meetadata for grid ds and loops Review diffferent types o of grids/loops     If your qu uestionnaire contains a series of questiions that lookk similar to th his:  Please raate the follow wing travel de estinations on your intere est in visiting the location.  Extremely  Someewhat  Somewhat  Extremely    Aruba  Bermudaa  Florida  Hawaii  Fiji  Costa Ricca  Thailand    Interestted  Interrested  N Neutral  D Disinterested  Disinterested d  {  {  {  {  {  {  {  {  { { {  { {  { {  { {  { {  { {  { { { { { { { { { { { { { { {  {  {  {  {  {  {  e of when to use the loop//grid metadatta item.  The properties th his question h has  This is a ggood example that makke it a loop/grrid are:  • • All share the ssame responsses (Extremely Interested, Somewhat In A nterested, etcc.)  D During analys is, we will waant to see thee results of eaach destinatio on separately,, but perhapss will  a also want to s see the resultts in summaryy in the formaat they appeaar in above.  You will aalso need to d decide if you want to havee the appearaance of the qu uestions to bee exactly as w we  see them m above (i.e., o on the screen n all at once), or would wee prefer that eeach question n be on a  separate screen (i.e., ""Please rate A Aruba on you ur interest in vvisiting., Please rate Bermuda on your  interest in visiting., etc., ")    101    Chapter 10  Repetitive Questions ‐ Loops & Grids    Survey Programming Fundamentals  Categorical Loops/Grids  We will define categorical loop/grids not by the type of questions they display, but by what defines the  number of times you repeat the questions.  The first examples will show a list of categories defining  the number of times you will show the question in a loop/grid.  Name "GridText" loop  {             ID1 "Alt Text1",      IDn "Alt Textn"  } fields  (             Question1 "LoopText1 {@} ";      Questionn "LoopTextn {@}"  ) expand grid;  Item  Name  "GridText"  Loop  ID1 "Alt Text1",  IDn"Alt Textn"  Fields  Question1,  Questionn  LoopText1,  LoopTextn  {@}  expand  grid  column  102  Description  Unique identifier for loop/grid   Optional text that will be displayed when the questions in the loop are asked  together on one screen.   Keyword to mark a set of repeated questions and define the number of  repetitions required.  Defines the category list that controls the number of repetitions required.  You  define it in the same way as the category list for a categorical question.  Keyword prior to the questions to be repeated in the loop  Questions that will be repeated based on the category list (ID1, ID2).  Defines an optional label that will be displayed when the questions in the loop  are asked on individual screens.  Represents the current category to display when the questions in the loop are  asked on individual screens.  Since mrInterview supports both a hierarchical and a flattened view of the  data, using the expand keyword means that the data is represented in both  formats (bounded).  Keyword that allows SPSS Dimensions applications and components to  recognize that the loop is a grid. Example would be printing grids using  mrPaper.  Optional keyword to change the orientation of the category list to be the  columns of the grid instead of the rows. (Keyword row is the default.)  Is  placed on the end of the metadata prior to the semi‐colon.      Survey Programming Fundamentals    Chapter 10  Repetitive Questions ‐ Loops & Grids      Here is the syntax for the grid shown at the beginning of this chapter.  Example    Metadata (en‐US, Question, label)    InterestinLocation "Please rate the following travel destinations on your interest in  visiting the location." loop      {          Aruba ,          Bermuda,          Florida,          Hawaii,          Fiji,          CostaRica,          Thailand      } fields       (          Rating ""          categorical [1..1]          {              ExtremelyInterested "Extremely Interested",              SomewhatInterested "Somewhat Interested",              Neutral "Neutral ",              SomewhatDisinterested "Somewhat Disinterested",              ExtremelyDisinterested "Extremely Disinterested"          };        ) expand grid;    End Metadata    Routing(Web)    InterestinLocation.Ask()    End Routing            103    Chapter 10  Repetitive Questions ‐ Loops & Grids    Survey Programming Fundamentals  In the previous example, since we asked the question using the loopname.Ask(), the survey will appear  in this format:    This is what this manual will refer to as a grid format.        If you want to change the orientation so that the destinations are across the top of the  screen, add the keyword column after the grid keyword.         104        Survey Programming Fundamentals    Chapter 10  Repetitive Questions ‐ Loops & Grids    If we add text to the Rating question metadata and change the statement in the routing:  Example          Metadata (en‐US, Question, label)    InterestinLocation "Please rate the following travel destinations on your interest in  visiting the location." loop      {          Aruba ,          Bermuda ,          Florida,          Hawaii,          Fiji,          CostaRica,          Thailand      } fields       (          Rating "Please rate {@} on your interest in visiting."          categorical [1..1]          {              ExtremelyInterested "Extremely Interested",              SomewhatInterested "Somewhat Interested",              Neutral "Neutral ",              SomewhatDisinterested "Somewhat Disinterested",              ExtremelyDisinterested "Extremely Disinterested"          };        ) expand grid;    End Metadata    Routing(Web)        InterestinLocation[..].Ask()    End Routing            105    Chapter 10  Repetitive Questions ‐ Loops & Grids    Survey Programming Fundamentals  Then the survey will come up one question at a time on the screen.  The first time you will see:      A few things to remember about the previous example:  • • • The main grid text (text prior to the keyword loop) will not show when the questions are asked  on individual screens.  The {@} will show the label of the current category, in this case, the destinations.  The [..] indicates that you want to step through each value in your categorical loop one at a  time.        If the above is not clear, think about how you would display just one of the questions in the  loop:  InterestinLocation[{Aruba}].Ask()        For Each loops  An alternative way to write [..] and still have the questions come up individually on the screen would  be using a For Each loop statement.  Dim var  For each var in LoopName  var.Ask()  Next  106      Survey Programming Fundamentals    Chapter 10  Repetitive Questions ‐ Loops & Grids      Item  Dim  var  LoopName  For Each  Next  Description  Declares a temporary variable to be used within the routing section  Represents a temporary variable name you create  Name of our metadata loop/grid  Marks the start and end of a loop.  In this case, the loop is doing what’s inside  the for/next “for each question in “another element.  In this case our  metadata loop/grid.  Each time through the For Each/Next , var will be the   individual questions of the loop/grid and will be asked by the var.Ask()  statement.     Here is the previous example written with a For Each/Next loop instead of the [..] syntax.  This will  display the same in the browser as the previous example.  Example    Metadata (en‐US, Question, label)    InterestinLocation "Please rate the following travel destinations on your interest in  visiting the location." loop      {          Aruba ,          Bermuda ,          Florida,          Hawaii,          Fiji,          CostaRica,          Thailand      } fields       (          Rating "Please rate {@} on your interest in visiting."          categorical [1..1]          {              ExtremelyInterested "Extremely Interested",              SomewhatInterested "Somewhat Interested",              Neutral "Neutral" ,              SomewhatDisinterested "Somewhat Disinterested",              ExtremelyDisinterested "Extremely Disinterested"          };        ) expand grid;    End Metadata              107    Chapter 10  Repetitive Questions ‐ Loops & Grids    Survey Programming Fundamentals  Routing(Web)  Dim location    For each location in InterestinLocation      location.Ask()  Next    End Routing        To help understand this, when running this code stop on one of the loop questions and  choose the Expressions tab and Evaluate location.QuestionFullName.  Or you can choose  the Locals pane and look at the current value of location.  The For Each/Next loop will prove helpful in more complex scenarios.    Categorical Loops with a Numeric Question  Another example will show changing the type of question in the loop.  This metadata example displays  numeric questions instead of a categorical scale.  ExpenseCategories define   Example      {  Transportation,          Accomodations,            FoodDrink "Food and Drinks",          OtherMisc "Other Miscellaneous"      };  BusTravelSpent "In the past year, approximately how much did you spend in each  category listed below for business travel?" loop      { use ExpenseCategories} fields       (          BusTravel "Amount Spent on Business Travel"          long [0 .. ];      ) expand grid;  108      Survey Programming Fundamentals    Chapter 10  Repetitive Questions ‐ Loops & Grids    Would display in the browser like this:        You can also have multiple questions within a grid.  The following example expands on the last  example to include two columns of numeric boxes on the screen:  Example    Metadata (en‐US, Question, label)    ExpenseCategories define       {  Transportation,          Accomodations,          FoodDrink "Food and Drinks",          OtherMisc "Other Miscellaneous"      };    TravelSpent "In the past year, approximately how much did you spend in each category  listed below for business and leisure travel?" loop      {  use ExpenseCategories  } fields       (          BusTravel "Business Travel"          long [0 .. ];            LeisureTravel "Leisure Travel"          long [0 .. ];        ) expand grid;    Routing      TravelSpent.Ask()  End Routing      109    Chapter 10  Repetitive Questions ‐ Loops & Grids    Survey Programming Fundamentals          110        Survey Programming Fundamentals    Chapter 10  Repetitive Questions ‐ Loops & Grids    Numeric Loops  Another way to create repetitive questions in a grid/loop is to create a loop in which you set a number  to represent the loop driver.    Name "GridText" loop [n1..n2]  fields  (       Question1 "LoopText1 {@}";  Question2 "LoopText2 {@}"  ) expand grid;  Item  Name  "GridText"  Loop  [n1..n2]  Fields  Question1,  Questionn  LoopText1,  LoopTextn  {@}  Expand  Grid  Description  Unique identifier for loop/grid   Optional text that will be displayed when the questions in the loop are asked  together on one screen.   Keyword to mark a set of repeated questions and define the number of  repetitions required.  Defines the number of times you want the loop to execute.  Keyword prior to the questions to be repeated in the loop  Questions that will be repeated based on the category list (ID1, ID2).  Defines an optional label that will be displayed when the questions in the loop  are asked on individual screens.  Represents the current category to display when the questions in the loop are  asked on individual screens.  Since mrInterview supports both a hierarchical and a flattened view of the  data, using the expand keyword means that the data is represented in both  formats.  Display the question as a grid when the question is printed using mrPaper. No  effect in browser based interviews.    The categories shown in previous loop examples are replaced with numbers.  There are various ways to  specify the numbers which will represent the repetitions of the loop.  Description  Ranges  Single Values  Step Values  Exclusive Values   Example  [1..10]  [1,5,10]  Results  Will display the question in the grid/loop 10 times  Will display the questions in the grid/loop 3 times, each time  representing one of the numbers listed  [1..10 step 2]  Will display the questions in the grid/loop 5 times, each time  representing an odd number 1 to 9.  [1..10 ^5]  Will display the questions 9 times, eliminating the 5th time.      111    Chapter 10  Repetitive Questions ‐ Loops & Grids    Survey Programming Fundamentals    The following will produce a pair of questions asked about the respondent’s last three trips.  Example    Metadata (en‐US, Question, label)    Last3Trips "Please think about the last three times you traveled for business or pleasure  and answer the following questions." loop [1..3] fields       (          BusorLeis "Tell us about Trip # {@}.  Was this trip for..."          categorical [1..1]          {              Business ,              Leisure,              Both          };     Accommodations "When you were traveling on Trip # {@}, which of the following types  of accommodations did you stay?"          categorical [1..]          {              Hotel,              Motel ,              BedBreakfast "Bed and Breakfast",              Hostels,              Resorts ,              OtherAccom "Other Accomodations" other          };        ) expand grid;    End Metadata    Routing(Web)        Last3Trips[..].Ask()    End Routing            112        Survey Programming Fundamentals    Chapter 10  Repetitive Questions ‐ Loops & Grids    The first time through the loop you will see:            113    Chapter 10  Repetitive Questions ‐ Loops & Grids    Survey Programming Fundamentals  Exercise  Create a new metadata file, Meals.mdd for this exercise.      Think back to the last three meals of breakfast, lunch, and dinner that you consumed.   (ASK MEALTIME & MEALORIGIN ABOUT EACH MEAL.)  MealTime  Thinking about the last [INSERT MEAL] you had, what time did you eat [INSERT MEAL]?      MealOrigin  Was your [INSERT MEAL]…      Made at home  Purchased from a restaurant       Calories  How many calories do you estimate your last three meals of breakfast, lunch and dinner  contained?  Breakfast     Lunch  Dinner  HealthAttribs  Please state your level of agreement with the following statements    Strongly Agree  Breakfast is the most important meal of the day Eating fast food can be healthy  I have a well‐balanced diet I don’t eat a lot of sugar  { { { {  Agree  Neutral  Disagree  { { { {  { { { {  { { { {  Strongly  Disagree  {  {  {  {    HealthComm  Please add any additional comments you have about the importance of healthy foods  in restaurants.        114      Survey Prrogramming Fundamentalls    Ch hapter 11  Deebugging Tools within mrStudio  Chapte er 11   De ebugging  Tools witthin mrSttudio  Now thatt we are startting to learn m more complexx question types, we need d to have som me problem  solving skkills.  mrStudiio provides m many tools to help you in creating more complex surveys.    In this chapter w we will: Review concepts to help p you troublesh hoot  your scriptt Create test data within m mrStudio Create you ur own macross     o which may h help you in teesting your sccripts are the ability to:  Some of the items witthin mrStudio • • • Have mrStudio produce test data for review.  H S Set points wit thin your scrip pt that the su urvey will stop p the action aas you are tessting to allow you  t to investigate  current values.  V View the elem ments of a queestion, such aas its style or controls, to ssee the current values as yyou  t test your scrip pt.    Auto A Answer Questionnairre  If you wo ould like to vie ew your skip patterns and view what’s happening in n your routingg at a high levvel,  then you can have mrrStudio autom matically answ wer the questtions for you aand display th he number off  responsees each question received.  From thee menu, choose the AutoA Answer icon sh hown below:           115    Chapter 11  Debugging Tools within mrStudio    Survey Programming Fundamentals  You will be prompted for the number of interviews you wish to produce and the number of attempts  the system should make per question.    The result will show in the AutoAnswer window as shown below:    This shows that the FriendRelate question only received 2 out of the possible 10 automatically created  responses.  When investigated further, this makes sense, as there was a skip pattern around that  question.  Other good things to look at in this view would be questions with no responses, which could  mean you forgot to ask the question.  116      Survey Programming Fundamentals    Chapter 11  Debugging Tools within mrStudio    Producing Test Data  Besides seeing the summary of answers created, we can also store those results to use as data checks  before the study goes live.  With mrStudio, you can write to SPSS .SAV, .XML, Dimensions Data file  (.DDF), and Dimensions RDB database formats.    • • From the menu choose Tools  Select Write to Database    You can now choose the AutoAnswer icon or Tools – Auto Answer Data Generation  You will still be prompted for the number of interviews you wish to produce and the number of  attempts the system should make per question.          117    Chapter 11  Debugging Tools within mrStudio    Survey Programming Fundamentals  The first time you run this, you will now see the following screen asking you to choose the  datatype to create.    Choose your datatype and browse and name the new datafile.      If you choose to create a SPSS .SAV file, choose metadata type as none and just specify a  case data location and name.      118        Survey Programming Fundamentals    Chapter 11  Debugging Tools within mrStudio    Adding Additional Data Sources  After setting your data source the first time, mrStudio will automatically write to this file each time.   mrStudio allows you to add multiple data sources if you wish to make test data in multiple formats.   View the Metadata Explorer and find the datasources collection.  Right‐click on the folder and choose  Add DataSources.  You will see the menu to choose the datatype and filename.        Now you will be able to Right‐click on DataSources and choose Change DataSource to choose which  datasource you want to create test data for.          119    Chapter 11  Debugging Tools within mrStudio    Survey Programming Fundamentals  Setting Breakpoints  To find out what happens at critical points in your program, you need to stop execution at these points  and look at the contents of questions or temporary variables to see if they contain the correct values.  Points at which mrStudio stops to allow this investigation are called breakpoints.    To set a breakpoint, click on the grey area on the left side of the numbering in your routing section.   This should produce a large dot on that line as shown below:    You can use this feature in many ways.  Many people test surveys and when they find a problem, they  want to stop and fix the problem and start re‐testing at that point.    • • • • • Set a breakpoint in your routing at the question you want to review  Choose AutoAnswer  When prompted, make sure to choose Number of interviews to be set to 1  This will stop auto‐answering at the question in which you set the breakpoint  Now choose F5 to continue out of AutoAnswer mode  This is an easy way to start using breakpoints.  As your code becomes more complex, you will use  breakpoints to evaluate your code even more.    120        Survey Programming Fundamentals    Chapter 11  Debugging Tools within mrStudio    Troubleshooting Specific Sections of Code  Another helpful feature is to step through the lines of the routing section, so you can pause and  evaluate each action.  Then you can see the current values of questions or variables with the  Expressions tab or the locals pane.  To step through code, choose the F10 key or Debug ‐ Single Step.  Next, investigate specific question values or properties.     Using the Locals pane (View – Locals) you can view previous answers to questions as shown in the  picture below.    In addition, you can see the properties of questions, such as the appropriate styles or proper names for  elements of a question.          121    Chapter 11  Debugging Tools within mrStudio    Survey Programming Fundamentals  Using the Expressions tab, you can view or set the values to questions or variables in order to further  test your script.  (View – Expressions).  In the example below, we are setting the value of the  TravelItem question to test the “if then” routing pattern we have created.        122        Survey Programming Fundamentals    Chapter 11  Debugging Tools within mrStudio    Working with Macros  mrStudio contains macros to help you create scripts.  You have the ability to add new macros and  modify or delete existing macros.  In mrStudio, choose Tools – Macros.  This will display the options shown below.  Notice the 3 different  areas in which you can work with macros.  For Interview Scripting, you should use:  • • mrScriptBasic:  The macros will appear in the routing section  mrMetadataScript:  The macros will appear in the metadata section      Updating/Deleting Existing Macros  Choose an existing macro from the list shown in the previous screenshot.  Make any changes desired in  the Macro Text or Macro Name areas and choose the Update Macro icon.  To delete an existing macro,  choose the macro and select the Delete Macro icon.    Adding Additional Macros  Create the code you wish to make into a macro.  Then copy the code and choose Tools – Macros.   Choose the appropriate area to place your macro (mrScriptBasic or mrMetadataScript), then copy the  code into the Macro Text window (Ctrl – V).  Create a unique name for the macro in the Macro Name  area.  Then select the Add Macro icon.        123    Chapter 11  Debugging Tools within mrStudio    Survey Programming Fundamentals  You can copy macros from one machine to another by copying the file,     C:\Documents and Settings\\Application Data\SPSS\  mrStudio\4.5.0.0\MacroDefinitions.xml.      124        Survey Prrogramming Fundamentalls  Chapter 12 2  Conditioneed Loops and Grids  Chapte er 12  Conditioned d Loops a and Grids   We have learned to crreate filtered questions baased on answ wers to previous questions and logic.   Adding filter logic to lo oops and grid ds is the samee concept.    This chapterr looks at loops/grids filtered on: Prevvious responsees within the lo oop Prevvious responsees to a simple q question  outsside the loop/ggrid Prevvious responsees to a different loop/grid’s  quesstions A su ublist of catego ories     Previous Respon nses Withiin the Loop p  Suppose you have the e following qu uestion:  pondent shou uld not see the follow up q question, “Wh hy do you  If the response is “Nevver”, the resp we wish to rep peat these pairs of questio ons for multip ple  referencee the travel guide, Lonely Planet?”  If w travel guides, then we e must place tthe questionss within a loop.  The follow wing loop dem monstrates ho ow  to write tthis logic with hin the routin ng section.        125    Chapter 12  Conditioned Loops and Grids  Example                                      Survey Programming Fundamentals  Metadata (en‐US, Question, label)    TravelGuides "Now, some questions about Travel Guides." loop      {          LonelyPlanetBook "Lonely Planet" ,          Fodor "Fodor's",          Frommer "Frommer's"      } fields      (          Read "How often do you read or reference the travel guide, {@}?"          categorical [1..1]          {              Weekly ,              Monthly ,              Yearly,              Rarely ,              Never           };            WhyRead "Why do you reference the travel guide, {@}?"          categorical [1..]          {              Hotel "Advice on Hotels",              Neighborhoods "Information on Neighborhoods" ,              Attractions "Tourist Attractions" ,              SaveMoney "Tips on how to save money" ,              Transportation "Local travel/transportation" ,              OtherReason "Other Reason" other ,              Refused "Prefer not to Answer" REF          };        ) expand grid;        End Metadata    Routing(Web)        Dim tguide      For Each tguide In TravelGuides          tguide.Read.ask()          If tguide.Read.Response.Value <> {Never} Then              tguide.WhyRead.Ask()          End If      Next      126      Survey Programming Fundamentals    Chapter 12  Conditioned Loops and Grids      Breaking down the example above:  • • • • tguide is a temporary variable that will represent the categories of the loop (the travel guides)  For Each/next loop will loop through each “tguide” in our loop question, TravelGuides  tguide.Read.Ask()  will ask just the question, read for each travel guide  The If statement checks the logic so that if the current value of tguide’s response to the read  question was not “Never”, then ask the follow‐up question, WhyRead    Loops/Grids Filtered on Previous Responses Outside the Loop/Grid  In previous examples, we could filter the response list of a question by the responses to previous  questions.  We can apply that same principle to the category list of a grid/loop. Instead of filtering the  categories of a question, we will do a QuestionFilter on a loop:  Name.QuestionFilter=categories  Item  Name  QuestionFilter  Categories  Description  Name of the grid/loop question   Property (keyword) to state you are restricting the categories of the loop/grid  question  Represents anything that states the categories you wish to display in the  loop/grid.  Setting the filter equal to Null will set the filter to all valid categories.    The following is an example of a grid which will only show grid categories that are appropriate/logical  for the respondent.    Example    Metadata(en‐US, Question, Label)    ResortTypes "" define      {          Historical,          AmusementPark "Amusement Park" ,          Beach "Beach" ,          Adventure "Adventure"      };    AttendedResort "From the list below, please indicate which types of resorts you have  stayed at."  categorical [1..] {use ResortTypes};              127    Chapter 12  Conditioned Loops and Grids    Survey Programming Fundamentals  RateResortLoop "Of the resorts you have stayed at, please rate them on your overall  satisfaction with your experiences at the resort." loop      {  use ResortTypes   } fields       (          RateResort ""          categorical [1..1]          {   VerySatisfied "Very Satisfied",              SomewhatSat "Somewhat Satisfied" ,              SomewhatDisSat "Somewhat Dissatisfied" ,              VeryDissatisfied "Very Dissatisfied"          };        ) expand grid;  End Metadata    Routing(Web)      AttendedResort.Ask()      RateResortLoop.QuestionFilter=AttendedResort.Response.Value      RateResortLoop.Ask()  End Routing    If you choose:        128        Survey Programming Fundamentals    Chapter 12  Conditioned Loops and Grids    You will only have the responses chosen as the categories of the grid:      Loops/Grids Filtered on Responses to a Different Loop/Grid’s Questions  Sometimes the filter conditions can become more complex.  Let’s think about another scenario.   Looking at the grid from the last example:      …suppose the follow‐up question was,   “Why are you satisfied overall with the [INSERT RESORT TYPE]?” This should only be asked of the resort  types they responded very satisfied or somewhat satisfied.          129    Chapter 12  Conditioned Loops and Grids    Survey Programming Fundamentals  To correctly ask this follow‐up, we need to:  • • Create a loop question containing the text question above to hold the answer separately for  each resort type (a single question would not be sufficient).  Create a QuestionFilter for the loop that holds the text question.  This QuestionFilter should  contain only the resorts (categories) in which the respondent rated Very Satisfied or Somewhat  Satisfied in the previous loop.      Example    130  Metadata (en‐US, Question, Label)    ResortTypes "" define      {          Historical,          AmusementPark "Amusement Park" ,          Beach "Beach" ,          Adventure "Adventure"      };    RateResortLoop "Of the resorts you have stayed at, please rate them on your overall  satisfaction with your experiences at the resort." loop      {  use ResortTypes   } fields       (          RateResort ""          categorical [1..1]          {   VerySatisfied "Very Satisfied",              SomewhatSat "Somewhat Satisfied" ,              SomewhatDisSat "Somewhat Dissatisfied" ,              VeryDissatisfied "Very Dissatisfied"          };        ) expand grid;     WhyLoop "" loop      {          use ResortTypes      } fields      (          WhyVerySat "Why are you satisfied overall with the {@} resort?"          text;        ) expand grid;    End Metadata        Survey Programming Fundamentals    Chapter 12  Conditioned Loops and Grids    Routing(Web)      RateResortLoop.Ask()        Dim Resort      Dim WhyLoopFilter        WhyLoopFilter = {}      For Each Resort In RateResortLoop          If Resort.RateResort.ContainsAny({VerySatisfied, SomewhatSat}) Then              WhyLoopFilter = WhyLoopFilter + CCategorical(Resort.QuestionName)          End If      Next            WhyLoop.QuestionFilter = WhyLoopFilter          WhyLoop[..].Ask()    End Routing    You must set the variable WhyLoopFilter to {} so that it starts as a filter with nothing in it.        Loops/Grids Filtered on a Sublist of Categories  As we have learned in previous chapters, we can create sublists to make define lists more reusable.   You can also use sublists to create “groups” to be used as category filters.        Name.QuestionFilter=Name.Categories.sublistname  Item  Name  QuestionFilter  Categories  sublistname    Description  Name of the grid/loop question   Property (keyword) to state you are restricting the categories of the loop/grid  question  Keyword for the categories of the grid/loop  Name of the sublist you wish to show in the grid/loop  The following example asks if the respondent primarily travels for business, leisure or both.  Based on  this response, the follow‐up grid question will display a define list with business travel attributes  (BusinessAttribs), leisure travel attributes (LeisureAttribs) or both lists.      131    Chapter 12  Conditioned Loops and Grids  Example      Survey Programming Fundamentals  Metadata (en‐US, Question, Label)    BusinessAttribs define      {          MeetInPerson "I think meeting face‐to‐face improves work communication." ,          WeekendTravel "Traveling on the weekends interferes with my personal time." ,          ArriveEarly "I like to arrive early to prepare for the next day's agenda."      };      LeisureAttribs define      {          ShortDistance"I like to take many short weekend trips vs one long vacation/holiday.",          family "Travel is a great time to reconnect with my family members.",          cost "I often splurge on vacation/holidays, picking the nicest hotels and locations."      };       primarytravel "Do you primarily travel for..."      categorical [1..1]      {          Business ,          Leisure ,          Both       };        TravelAttribs "Rate your agreement with the following statements." loop      {          use BusinessAttribs sublist           ran,          use LeisureAttribs sublist           ran      } ran fields       (  attrib ""          categorical [1..1]          {              SAgree "Strongly Agree" ,              Agree,              Neutral ,              Disagree ,              SDisagree "Strongly Disagree"          };      ) expand grid;  End Metadata      The routing section would look like this:  132      Survey Programming Fundamentals  Example      Chapter 12  Conditioned Loops and Grids    Routing(Web)      primarytravel.Ask()      Select Case PrimaryTravel.Response.Value          Case {Business}                TravelAttribs.QuestionFilter=TravelAttribs.Categories.BusinessAttribs          Case {Leisure}                  TravelAttribs.QuestionFilter=TravelAttribs.Categories.LeisureAttribs            Case Else               TravelAttribs.QuestionFilter= Null      End Select        TravelAttribs.Ask()    End Routing  The code above will display:  • • • Only the Business sublist for the TravelAttribs if they primarily travel for business  Only the Leisure sublist for the TravelAttribs if they primarily travel for leisure  Both lists if they chose “Both” for the primarytravel question    Breaking down the code above:  • • The QuestionFilter lines above are set equal to the Question.Categories.sublistname if the  respondent only chose business or leisure.  The QuestionFilter was set to Null when the respondent chose both.  Null resets the  QuestionFilter so that all categories are shown.  Another alternative is to set the filter to the  question’s definedcategories.      Using the sublists as shown above does limit your abilities to sort, as the sublists can be  sorted within themselves, but you cannot sort the two sublists together.   If sorting is an  issue and you wish to use a sublist as a filter, see filterbysublist.mdd on your CD for an  advanced function to eliminate the problem.  This example dynamically creates a filter from  the categories in a sublist, instead of using the sublist for the filter directly.             133    Chapter 12  Conditioned Loops and Grids    Survey Programming Fundamentals  Exercise  Use the metadata file, Restaurant.mdd.  The metadata has been completed; please add the routing  section and logic as stated below.     (Ask the next two questions (Eaten & OftenEat) for each of the restaurant types of:  Deli/Carry Out Restaurants without Seating  Fast Food Restaurants  Family/Casual Dining Restaurants   Upscale Restaurants)  Eaten    Have you ever eaten in [INSERT TYPE OF RESTAURANT]?      Yes  No    OftenEat  (If Yes)  How often do you eat in [INSERT TYPE OF RESTAURANT]?          Daily  Weekly  Monthly  Yearly or less    (Ask only if they said “Yes” to the type of Restaurant in the Eaten Question)   FoodQuality  Please rate your overall satisfaction with the quality of food obtained in the following  types of restaurants.  Very  Somewhat Satisfied  Satisfied    Deli/Carry Out Restaurants without Seating   Fast Food Restaurant    Family/Casual Dining Restaurant     Upscale Restaurant  Neutral  Somewhat  Very  Dissatisfied  Dissatisfied  {  {  {  {  {  {  {  {  {  {  {  {  {  {  {  {  {  {  {  {      134        Survey Programming Fundamentals    Chapter 12  Conditioned Loops and Grids    (If Yes to Fast Food in Eaten Question, ask ChainAware and FastFoodQual.)  ChainAware  Which of the following fast food chains have you eaten at?              Wendy’s  McDonald’s  Burger King  Arby’s  In‐N‐Out Burger None of these    (Of the fast food chains mentioned in ChainAware)  FastFoodQual  Please rate your overall satisfaction with the quality of food obtained in the following   fast food restaurants.    Very  Somewhat Satisfied  Satisfied  Neutral  Somewhat  Very  Dissatisfied  Dissatisfied  Wendy’s  McDonald’s  Burger King  Arby’s  {  {  {  { {  { { {  { { {  { {  {  {  {  {  {  {  {  In‐N‐Out Burger  {  {  {  {  {                135    Chapter 12  Conditioned Loops and Grids    Survey Programming Fundamentals        136  Survey Prrogramming Fundamentalls    Chapter 13  Conttrolling the Lo ook of Your Su urvey  Chapte er 13  Controlling the Look k of Your S  Survey  Look and d feel can be aa crucial elem ment of surveyy scripting.  m mrInterview p provides greatt flexibility in  terms of modifying the look of you ur survey.    In tthis chap pter we will learrn: Different w ways to changee the overall  appearancce of your survey How to ap pply different lo ooks to your su urvey How to efffectively use sttyles within your  script      Overviiew of the  Formattin ng of a Surrvey  To fully u utilize the cap pabilities of an n mrInterview w survey’s appearance, you need to und derstand how w the  overall fo ormatting of tthe survey wo orks.  The hieerarchy of item ms that affectt the appearaance of an  mrInterview survey arre:  HTML Templaates (including Cascading SStyle sheets aand .xml files)).  These are sspecial HTML  1) H p pages that are e applied to yyour survey. 2) Styles within t S the script.  Th hese are scrip pting propertiies added to eeither the meetadata or thee  r routing sectio on.    mple, if you fo ormat a speciffic question w with a style in a way that co ontradicts wh hat is in the H HTML  For exam templatee, then the qu uestion style w will override tthe template’’s format for that question n.  Now thatt you have a b basic understtanding of how w templates and styles aree applied to tthe survey, let’s  take a clo oser look at e each aspect.    Templa ates  Templatees are HTML p pages which h have special m mrInterview ““tags” that reepresent the d different partts of  a survey.  Templates ccontrol the layout of the m mrInterview p page separatee from the texxt of your  questionnaire as you ccreated it in tthe metadataa.  This allowss you the flexiibility to creatte standard  templatees for re‐use in many projeects.  You can also use morre than one teemplate with hin a survey.       137    Chapter 13  Controlling the Look of Your Survey    Survey Programming Fundamentals  The three main types of templates are:  • • • Layout Template:  Defines one page/screen layout.  This template is usually created in a way in  which you can apply this to multiple studies if you want them to all have the same basic look.   Also, this does not necessarily mean that you have to create a completely new template file if  you want to vary just one aspect of the layout for a particular part of an interview or for a  different project. If the basic page layout is the same, you can create sub‐templates for the  aspects that change.  Sub‐Template:    A template file that defines the layout of one aspect of the page.  For  example, you can create sub‐templates for questions (question and response texts), errors,  banners, navigation bars, and grids. The main page layout template (listed in the previous  bullet point) contains a basic tag indicating where the various components belong and the sub‐ templates define the exact layout for each component. You specify which sub‐templates are to  be used by naming them in the routing section of the interview script or in the main layout  template.   Localized Template:  Used for organizations that create surveys for people in multiple regions  of the world.  Localized templates allow you to set the language of an interview based on the  respondent's browser language, and the language can be changed in the interview script. The  interviewing program passes the language to the HTML Player, which searches for the  appropriate template in that language’s folder and then in the project folder.    In addition all three template types can be assigned globally or at a project level.  The order in which  mrInterview looks for templates is as follows:  1. 2. 3. 4. 5. 6. Project folder – specific language passed as the current interview’s language  Project folder – default language  Project folder   Global templates folder – specific language passed as the current interview’s language  Global templates folder – default language   Global templates folder    Because of all the variables listed above, you will want to thoroughly test your scripts in many different  ways to ensure that the proper look is being applied to your survey.      This course will only discuss how to apply the templates, not how to create the templates.   For more information, see the DDL:  DDL.chm::/interviewscripting_templates_writing.htm    138      Survey Programming Fundamentals    Chapter 13  Controlling the Look of Your Survey    Applying a Template within Your Script.    To apply a template within the routing section:  Routing(Web)  IOM.LayoutTemplate = "templatename.htm"  Name.Ask()  …  Item  Description  IOM.LayoutTemplate  Keywords to signify you are adding a template style to the survey from this  point forward in the routing section   templatename.htm  The actual name of the template to apply    If a question is tied to a specific template or sub‐template (such as java‐script logic to check a specific  question, or a complex question style), you may choose to add the template to the metadata:    Metadata(en‐US, Question, Label)  Name "text"          templates(Question = "templatename.htm" )  questiontype  Item  Description  Templates(Question=)  Keywords to signify you are adding a template style to this specific question in  the metadata   Templatename.htm  Represents the actual name of the template to apply  questiontype  Represents the question’s type (categorical, long, text, etc.)  Note that the  template goes before the question type keyword.            139    Chapter 13  Controlling the Look of Your Survey    Survey Programming Fundamentals    Below is an example of applying a template to the entire survey.  Example      Routing(Web)    IOM.LayoutTemplate= "Card_Blue_TopAndBottomErrors.htm"  InterestinLocation.Ask()  BusTravelSpent.Ask()  TravelSpent.Ask()  HotelChainStayMost.Ask()  HotelChainStayed.Categories.Filter = HotelChainStayed.Categories  HotelChainStayed.Ask()  FavHotelChain.Ask()    End Routing        You can drastically change the appearance of a question with templates.  mrStudio displays the  templates as they will appear when activated to mrInterview.        When reviewing your templates, you can choose to see a full browser view as opposed to  the smaller window within mrStudio, by changing the “Use Built‐in Browser” option to False  under Tools‐ Options.  However, with this option you cannot use the F5 Auto Answer  feature easily.    Folders   The Dimensions Development Library provides you with example templates to use and modify.  These  are included by default in C:\Program Files\SPSS Dimensions\DDL\Scripts\Interview\Templates  folder.        140        Survey Programming Fundamentals    Chapter 13  Controlling the Look of Your Survey    Tips for Scriptwriters Regarding Templates  A few things to think about as you are using mrStudio to apply your templates:  • • If you have templates from previous versions of mrInterview, you need to ensure the  templates are XHTML or perfectly formed HTML.  In the toolbar, choose HTML tidy to have  mrStudio try to “clean up” your code.  This may not always work 100%, but is may be worth  seeing what the results are.  Make a backup of your template files before attempting HTML  tidy.  Make sure that when you activate the study in mrInterview that you have included any project  specific templates you have been using locally in mrStudio.  Styles  Styles allow us to control the many formatting aspects of survey items from inside our survey script.  We can use styles on such items as questions, categories, labels and navigation controls. There are two  major groups of styles:  • • Default Styles:  Default styles are settings that get applied to an entire group of survey items.  For example, default styles would be used to make changes to all the question text font for  that script.  Question Styles:  Question styles are used to format items for specific questions.  In practice you should use default styles to perform the bulk of your formatting with styles. Use  question styles to apply unique or question specific formatting.  It is recommended that you declare  your default styles at the top of the routing section of the survey.  However, you can change the  settings of the default styles at any time in your survey.      Complete details regarding the available options of the styles object can be found in the  DDL:   IOMLib.chm::/IStyle.html  Default Styles  There are six types of default styles and each group has a number of sub‐types.  For this introductory  course, we will focus only on the main default styles:  • • • • • • Default  Labels  Categories  Grids  Navigation  Questions    While each of these different areas represents a different area for potential formatting you should also  be aware of the interaction between the areas. The style settings from one area will cascade to other  style objects. The following is the order of precedence:      141    Chapter 13  Controlling the Look of Your Survey    Survey Programming Fundamentals  1) 2) 3) 4) 5) 6) DefaultStyles.Default  DefaultStyles.Label  DefaultStyles.Navigation and DefaultStyles.Categories  DefaultStyles.Questions  DefaultStyles.Questions.Labels  DefaultStyles.Question.Categories and DefaultStyles.Grids    For example, if we set the font differently in the default and labels sections, the labels section will be  the setting that is used.  Let’s review some of the different areas of a survey in which styles can be  applied.  Default  The default style is the style settings that all other styles are derived from.  So these settings will form  the basis for all other default style types and/or question style settings.    IOM.DefaultStyles.Default      Example    Routing(Web)    IOM.LayoutTemplate= "Card_Blue_TopAndBottomErrors.htm"    IOM.DefaultStyles.Default.Font.Family = "Tahoma"    InterestinLocation.Ask()    End Routing        The example above would set all text to be Tahoma for this study, overriding what has been set in the  template.      142        Survey Programming Fundamentals    Chapter 13  Controlling the Look of Your Survey    Categories  The category default styles section is used to apply formatting to categorical responses.  IOM.DefaultStyles.Categories[CategoryStyleTypes.CategoryStyleTypeEnum]  Where the CategoryStyleTypesEnums are as follows:  CategoryStyleTypeEnum  csSingle  csMulti  csExclusive  csList    Description  Single response categorical.  Multi‐response categorical.  Exclusive response categorical.  Subheading Text.    Example    Routing(Web)    IOM.DefaultStyles.Categories[CategoryStyleTypes.csExclusive].Label.Font.Effects = _  FontEffects.feBold=null    ModeofTravel.Ask()    End Routing      The code above will turn all responses marked with the keywords exclusive, DK, REF, or NA to be  unbold.            143    Chapter 13  Controlling the Look of Your Survey    Survey Programming Fundamentals  Grid  Default grid styles are used to control the format of grid questions. It allows us to specify formatting  for column/row headings as well as alternating columns/rows.    IOM.DefaultStyles.Grids[GridStyleTypes.GridStyleTypesEnum]   Where the GridStyleTypesEnums are as follows:  GridStyleTypes Enum  gsCell  gsAltRow  gsAltCol  gsRowHeader  gsColHeader  gsAltRowHeader  gsAltColHeader    Description  The cells of a grid.  The alternating rows of a grid.  The alternating columns of a grid.  The row headings of a grid.  The column headings of a grid.  The alternate row headings of a grid.  The alternate column headings of a grid.    Example    144  Routing(Web)    'Default Grid Formatting  With IOM.DefaultStyles       'Row cell items          .Grids[GridStyleTypes.gsCell].Cell.BorderColor = "black"          .Grids[GridStyleTypes.gsCell].Cell.BorderStyle = BorderStyles.bsSolid          .Grids[GridStyleTypes.gsCell].Cell.BorderWidth = 1      'Alternate cell items          .Grids[GridStyleTypes.gsAltRow].Cell.BgColor = "#D5D5D5;"       'Row Headings          .Grids[GridStyleTypes.gsRowHeader].Cell.BorderColor = "black"          .Grids[GridStyleTypes.gsRowHeader].Cell.BorderStyle=BorderStyles .bsSolid          .Grids[GridStyleTypes.gsRowHeader].Cell.BorderWidth = 1          .Grids[GridStyleTypes.gsRowHeader].Cell.width= "120px"      'Column Headings          .Grids[GridStyleTypes.gsColHeader].Cell.BgColor = "#800000;"          .Grids[GridStyleTypes.gsColHeader].Color = "#FFFFFF;"          .Grids[GridStyleTypes.gsColHeader].Font.Effects = FontEffects.feBold         .Grids[GridStyleTypes.gsColHeader].Cell.BorderColor = "black"          .Grids[GridStyleTypes.gsColHeader].Cell.BorderStyle = BorderStyles.bsSolid          .Grids[GridStyleTypes.gsColHeader].Cell.BorderWidth = 1          .Grids[GridStyleTypes.gsColHeader].VerticalAlign = VerticalAlignments.vaBottom          .Grids[GridStyleTypes.gsColHeader].cell.wrap=true         .Grids[GridStyleTypes.gsColHeader].cell.width= "90px"      'Alternate Row Headings          .Grids[GridStyleTypes.gsAltRowHeader].Cell.BgColor = "#CECECE;"   End With      Survey Programming Fundamentals    Chapter 13  Controlling the Look of Your Survey      InterestinLocation.Ask()    End Routing    This code has been written in a With/End With block.  The With/End With statement allows you to  specify information that will be added to the beginning of each line that starts with an open dot (.)  within the block.  If there is not an open dot, then the information on the With line is not added.  The  previous code will format all grids within the project with the properties specified.  There is no  template applied to the picture below, only the styles specified above.              145    Chapter 13  Controlling the Look of Your Survey    Survey Programming Fundamentals  Labels  Label default styles allow us to specify formatting for different types of labels.  For example, we may  want all question labels to use a different size font than the category labels.  IOM.DefaultStyles.Labels[LabelStyleTypes.LabelStyleTypesEnum]   Where LabelStyleTypesEnum are:  LabelStyleTypes Enum  lsQuestion  lsCategory  lsBanner  lsError  lsNavigation  lsTitle    Description  Style for question labels.  Style for category labels.  Style for banner labels.  Style for error labels.  Style for navigation labels.  Style for title labels.  The code below will make all question text to have a font size of 24.    Example    Routing(Web)    IOM.DefaultStyles.Labels[LabelStyleTypes.lsQuestion].Font.Size = 24    AmtSpentYr.Ask()    End Routing      Navigation  Default navigation styles can be used to format the look and feel of the navigation buttons.  IOM.DefaultStyles.Navigation    Example    Routing(Web)    IOM.DefaultStyles.Navigation.BgColor = "#0099FF"    AmtSpenYr.Ask()    End Routing      The code above will create a blue background color on the navigation buttons.   146      Survey Programming Fundamentals    Chapter 13  Controlling the Look of Your Survey        The number that represents the color is a hexadecimal color value and is commonly used to  create a very specific color.  You can find many websites that provide these color codes.   Search for terms like “web safe colors”.      Questions  Question default styles allow you to define formatting specific to the type of question being displayed.    IOM.DefaultStyles.Questions[QuestionStyleTypes.QuestionStyleTypesEnum]    Where the QuestionStyleTypesEnums are:  QuestionStyleTypes Enum  qsInfo  qsLong  qsText  qsCategorical  qsDate  qsDouble  qsBoolean  qsLoopCategorical  qsLoopNumeric  qsCompound  qsBlock  qsPage  qsOther    Description  Information items.  Long (integer) questions  Text questions  Categorical Questions  Date questions  Double (real) questions  Boolean questions  Categorical loops.  Numeric loops.  Compound questions  Block questions  Multiple question page items.  Automatic Other Specify questions.  For example the following can be used to make all "other specify" textboxes a certain size.  Example      Routing(Web)    IOM.DefaultStyles.Questions[QuestionStyleTypes.qsOther].Style.Width = 220    HotelChainStayed.Ask()    End Routing          147    Chapter 13  Controlling the Look of Your Survey    Survey Programming Fundamentals  Question Styles  The same types of styles we discussed as default can be applied at the question level.  The use of  question styles should be minimal, for very specific formatting needs.  This section will discuss some  common question‐specific formatting needs.  Categorical Questions  With a categorical question you may want to display the available categories in multiple columns or  using a list box or combo box rather than the traditional checkboxes or radio buttons.    The following example will create 2 columns of responses instead of a single column.    Routing(Web)  Example    HotelChainStayed.Style.Columns = 2      HotelChainStayed.Ask()      End Routing    The following example will create a dropdown list.  Note that the categories have a subheading of  “Select One”.  This is done so that the respondent must choose an answer, since the subheading is not  a valid response.    Example    148  Metadata (en‐US, Question, Label)  Souvenirs "Which of the following souvenirs do you prefer to purchase when on holiday  or vacation?"      categorical [1..1]      {          SelectOne "Select One"          {              Clothing ,              Hats,              Postcards ,              SnowGlobes "Snow Globes"          }      };  End Metadata                    Survey Programming Fundamentals    Chapter 13  Controlling the Look of Your Survey    Routing(Web)    Souvenirs.Style.Control.Type = ControlTypes.ctDropList  Souvenirs.Ask()    End Routing                You can also control the column width for the droplist or combo box with:   Name.Style.Width    Text Questions  For a text question you may want to control the width and height of the textbox generated.  The  following will modify the width and height of the question.   Example      Routing(Web)    WhySouvenir.Style.Width=400  WhySouvenir.Style.Height=50  WhySouvenir.Ask()    End Routing      You can also change the type of textbox that will be created:  To change to a single line format:  TextQ.Style.Control.Type = ControlTypes.ctSingleLineEdit   To mask what is typed in the box with dots instead of the characters:  TextQ.Style.Control.Type = ControlTypes.ctPassword            149    Chapter 13  Controlling the Look of Your Survey    Survey Programming Fundamentals  Metadata Styles  When a style is specific to a question, it may be better to apply the style to the question directly in the  metadata.  The options available are the same as in the routing, but have a slightly different syntax.   The code below will orient the responses horizontally (orientation = row) and replaces the buttons and  text with an image.  Example    Metadata (en‐US, Question, Label)  HappyLastTravel "Choose the image below that indicates how happy you were the LAST  time you traveled."          style(Orientation = Row)       categorical [1..1]      {          VeryHappy "Very happy"              style(Image = "VeryHappy.gif", Control(Type = "Button")),                    SlightlyHappy "Slightly happy"              style(Image = "SlightlyHappy.gif", Control(Type = "Button")),                    NeitherNor "Neither happy nor unhappy"              style(Image = "NeitherNor.gif", Control(Type = "Button")),                    SlightlyUnhappy "Slightly unhappy"              style(Image = "SlightlyUnhappy.gif", Control(Type = "Button")),                    VeryUnhappy "Very unhappy"              style(Image = "VeryUnhappy.gif", Control(Type = "Button"))      };    End Metadata        The code above will produce the following question:        150      Survey Programming Fundamentals    Chapter 13  Controlling the Look of Your Survey      Custom Controls  Custom controls are a type of sub‐template that generates an interactive control that respondents can  use to answer a question. For example, if you have a date question you may want the respondent to  see a calendar. You could have the respondent flip through a calendar and then click on the date to  answer the question.        For an example of a custom control, review the calendar example in the DDL project,   C:\Program Files\SPSS Dimensions\DDL\Scripts\Interview\Projects\NewFeature.mdd    XHTML in Labels  We have seen that templates allow us to control the overall look of a survey page. We can use styles to  format individual labels or other survey items. However, sometime you may need to format just a  single word on a label. This type of granular formatting falls outside of templates and styles.  We can  use XHTML within our metadata file to perform this type of formatting.    What is XHTML?  XHTML is a markup language based on HTML. The primary difference is the need for all tags to be well‐ formed. This means that all tags must have an opening and closing tag.   Here are a few basic tags that may prove useful within your script:  Tag  text  text  text      Description  Bold Tag  Italic Tag  Underline  Carriage Return          151    Chapter 13  Controlling the Look of Your Survey    Survey Programming Fundamentals    Example    TravelItem "From the list below, which one  item would you most want to bring  with you on a leisure trip?"      categorical [1..1]      {          Camera ,          Map,          ComfortableFootwear "Comfortable Footwear",          FriendTravelCompanion "Friend/Travel Companion"      };    It is recommended that you only include XHTML tags when none of the other formatting options  provide a suitable solution. This is due to that fact that these tags can mean additional work when  relating to translation and/or reporting.    Final Thoughts on Formatting   When people are faced with so many places to apply formatting, they may be confused by what  formatting should go where.  One issue you should take into consideration when deciding where to  apply specific looks of your survey is system efficiency vs. ease of use.  Let’s say for example that you  want all the surveys to have a default font of "Tahoma"; where is the best place to declare this? Since  you want this applied to everything, ideally you should put this in the template or associated CSS file  since it is at the highest level.  In this way you get the correct font without having to declare anything  in your survey. Also if you later change your style you will not need to update any scripts. (Not to  mention mrInterview will not have to process that style detail.) And you can still use the styles to  override the templates when necessary.    152        Survey Programming Fundamentals    Chapter 13  Controlling the Look of Your Survey    Exercise  Open the Meals.mdd file and Save as MealsWithStyle.mdd  • • • Add the template, Verge_Layout.htm file to the document  The Calories grid has numeric responses; make a box size of 50 for those numeric questions.  Change the HealthComm box size to height of 100 and width of 550.    As time allows format all the grids to have the following look:    Hints:    • • • • Size of columns = 90px  Color of rating scale text = #BB342B  Color of alternate rows = #B8B8B8  Borders are solid, 1 width, and color of #B8B8B8                        153    Chapter 13  Controlling the Look of Your Survey    Survey Programming Fundamentals                          154  Survey Prrogramming Fundamentalls    Chaptter 14  Text Substitutions aand Text Headings  Chapte er 14  Te ext Substittutions an nd Text H Headings   You may need to have e text within yyour survey that changes w with the resp ponses given.  For instancee, if  you wantt to list how m many answers were chosen at a previou us question o or to have texxt that reflects a  positive o or negative raating to a previous questio on (“Why did you give the product a po ositive rating??”).    In this chapter w we will: Display an answer to a previous question in  the text off the survey Displaying answers to prrevious questio ons  within a grrid Insert textt into the metaadata that will be  controlled in the routingg section     Display ying Respo onses to P Previous Q Questions   You can d display the an nswers to preevious questio ons in the surrvey within an ny of the text in the metad data.  { {#Name}  Item  Name    Example    Description  Name of th he question that contains the responsee you want to display  Souvenirs "Which o of the following souvenirs do you prefeer to purchasee when on ho oliday  or vacation?"      cate egorical [1..1]      {          Cllothing ,          Hats,          Po ostcards,          Sn nowGlobes "SSnow Globes""      } ran n;    WhySo ouvenir "Whyy do you prefer to purchasse {#Souvenirrs} when on holiday or vacation?"  text;            155    Chapter 14  Text Substitutions and Text Headings    Survey Programming Fundamentals  If Snow Globes was chosen in the Souvenir question previously, the WhySouvenir question will appear  as:      If you are inside a loop and you want to display the item driving the loop, use the {@} sign.    Example    Metadata (en‐US, Question, Label)    InterestinLocation "Please rate the following travel destinations on your interest in  visiting the location." loop      {          Aruba ,          Bermuda,          Florida,          Hawaii,          Fiji,          CostaRica "Costa Rica",          Thailand "Thailand"      } fields       (          Rating "Please rate {@} on your interest in visiting."          Categorical [1]          {              ExtremelyInterested "Extremely Interested",              SomewhatInterested "Somewhat Interested",              Neutral ,              SomewhatDisinterested "Somewhat Disinterested" ,              ExtremelyDisinterested "Extremely Disinterested"          };      ) expand grid;  End Metadata    156      Survey Programming Fundamentals    Chapter 14  Text Substitutions and Text Headings    If the question is within a loop/grid and you need to reference it outside the loop, then the reference is  slightly different.   You need to use the root level operator  \.  in the syntax:    {#\.LoopName[{LoopCategory}].InsideQuestion}  Item  Loopname  LoopCategory  InsideQuestion    Description  Name of the loop   Specific loop/grid slice you wish to display the answer to  Question within the loop/grid  The following will display the response to a specific grid slice in the follow up text question.  Example    Metadata (en‐US, Question, Label)    InterestInLocation "Please rate the following travel destinations on your interest in  visiting the location." Loop      {          Aruba ,          Bermuda,          Florida,          Hawaii,          Fiji,          CostaRica "Costa Rica",          Thailand "Thailand"      } fields       (          Rating "Please rate {@} on your interest in visiting."          categorical          {              ExtremelyInterested "Extremely Interested",              SomewhatInterested "Somewhat Interested",              Neutral ,              SomewhatDisinterested "Somewhat Disinterested ,              ExtremelyDisinterested "Extremely Disinterested"          };      ) expand grid;        WhyAruba "Why did you rate Aruba {#\.InterestinLocation[{Aruba}].Rating}?"      text;    End Metadata              157    Chapter 14  Text Substitutions and Text Headings    Survey Programming Fundamentals  Insert Text into the Metadata that will be controlled in the routing section  There will be other times in which you will control the text to be shown instead of re‐displaying a  previous answer.  To achieve this, you need to use a text insert.  There are two parts to creating this  item.  Add a “marker” in the metadata to represent the text you wish to insert, and then create a  reference to this within the routing.   Metadata (en‐US, Question, Label)  Name "Text  {Marker}" type parameters;  End Metadata    Routing(Web)  Name.Label.Inserts[ "Marker" ].Text = Value  OR  Name.Ask(Value)  End Routing  Item  Name  Text  {Marker} or  ["Marker"]  Type  Parameters  Value  Description  Name of the metadata item that contains the placeholder or “Marker”   Text associated with the item  Represents the variable you created to be the placeholder for the text you want  to insert.  As shown above, it is referenced differently in the metadata vs. the  routing.  Identifies the item for its functionality (categorical questions, text only items,  etc.)  This varies by item type, but an example would be the responses to a question.  Represents the text you want to insert in “Marker”.  We recommend making the  text to be inserted an info item in the metadata for ease of translation.      158        Survey Programming Fundamentals    Chapter 14  Text Substitutions and Text Headings    The following example will substitute text for the ExplainChain question based on if the respondent  chose one answer or many answers to the HotelChainStayed question.  Notice the text to be  substituted is stored in info items in the metadata.  This is a good practice if the study is to be done in  multiple languages.  Example    Metadata (en‐US, Question, Label)  HotelChainStayed "Choose the hotel chains you have stayed at this past year."      categorical [1..]      {          InterContinental ,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          OtherHotel "Other Hotel Chain" other,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };        ExplainChains "Please give a brief explanation why you chose to stay at {Chain} as  opposed to others in the past year."      text [1..];      OneChain "this chain" info;      Chains "these chains" info;    End Metadata    Routing (Web)    HotelChainStayed.Ask()    If Not(HotelChainStayed.ContainsAny({DontKnow,Refused})) Then    If AnswerCount(HotelChainStayed) = 1 then      ExplainChains.Label.Inserts["Chain"].Text = OneChain.Label    Else      ExplainChains.Label.Inserts["Chain"].Text = Chains.Label    End If        ExplainChains.Ask()  End If    End Routing        159    Chapter 14  Text Substitutions and Text Headings    Survey Programming Fundamentals  There is an alternative to the method for text substitution shown above.  You can also add the insert  reference into the ask statement.  The example below shows the previous insert example, but using  the alternative method.  Example    Metadata (en‐US, Question, Label)  HotelChainStayed "Choose the hotel chains you have stayed at this past year."      categorical [1..]      {          InterContinental ,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          OtherHotel "Other Hotel Chain" other,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };        ExplainChains "Please give a brief explanation why you chose to stay at {Chain} as  opposed to others in the past year."      text [1..];      OneChain "this chain" info;      Chains "these chains" info;    End Metadata    Routing (Web)    HotelChainStayed.Ask()    If Not(HotelChainStayed.ContainsAny({DontKnow,Refused})) Then    If AnswerCount(HotelChainStayed) = 1 then      ExplainChains.Ask(OneChain.Label)    Else      ExplainChains.Ask(Chains.Label)    End If  End If    End Routing      160        Survey Programming Fundamentals    Chapter 14  Text Substitutions and Text Headings    Here is an example that gets rid of the extraneous text that mrInterview places in a text insert for a  previous question when the answer is an other specify.  You do not use the standard {#Name}, but  instead create a text insert with a condition to check for the other.  Example    Metadata (en‐US, Question, Label)    TypeAccom "At what type of accommodations did you stay?"      categorical [1..1]      {          Hotels ,          Motels,          BedBreakfast "Bed and Breakfasts",          Hostels ,          Resorts ,          OtherAccom "Other Accommodations" other      };        HowFreqStay "How frequently do you stay at {Accom}?"      categorical [1..1]      {          VeryFreqently "Very Frequently" ,          SomewhatFreqently "Somewhat Frequently",           Rarely ,          FirstTime "This was the first time"      };  End Metadata    Routing (Web)    TypeAccom.Ask()    if TypeAccom = {OtherAccom} then      HowFreqStay.Label.Inserts["Accom"]=TypeAccom.OtherAccom  else    HowFreqStay.Label.Inserts["Accom"]=TypeAccom.Response.Label  end if  HowFreqStay.Ask()    End Routing              161    Chapter 14  Text Substitutions and Text Headings    Survey Programming Fundamentals  Text Headings  You may wish to include headings that are applied to a single question or multiple screens.  This can be  achieved by creating a banner.  In the routing section, place the following statement:  To add a new heading:  Name.Banners.AddNew("BannerName", InfoName.Label)    To  reuse a banner with different text:  IOM.Banners["BannerName"].Text = NewInfoName.Label    To remove a banner:  Name.Banners.Remove("BannerName")  Item  Name  Description  Name of the question or page to apply the heading.  This can also be “IOM” to  use the same heading for multiple screens.  BannerName  Unique name for the banner.  Must follow standard naming conventions.  InfoName.Label,  Name of the info item holding the text you wish to display.  You can also choose  NewInfoName.Label  to place specific text in double quotes within this item.    When adding banners, it is recommended that you place the text in info items instead of directly in the  routing section.  This allows your surveys to be easily translated into multiple languages or contexts.  In  the example below, we are adding one banner and changing its text during the survey to accommodate  the different sections.  Example    162  Metadata (en‐US, Question, Label)    HotelChainStayed "Choose the hotel chains you have stayed at this past year."      categorical [1..]      {          InterContinental ,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          OtherHotel "Other Hotel Chain" Other,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };      Survey Programming Fundamentals    Chapter 14  Text Substitutions and Text Headings          FavHotelChain "Of those chains, which one would you most prefer to stay at again?"      categorical [1..1]      {          InterContinental ,          Cendant,          Marriott,          Accor,          Choice,          Hilton,          OtherHotel "Other Hotel Chain" Other,          DontKnow "Don’t Remember" DK,          Refused "Prefer not to Answer" REF      };    InterestinLocation "Please rate the following travel destinations on your interest in  visiting the location." loop      {          Aruba,          Bermuda,          Florida,          Hawaii,          Fiji,          CostaRica,          Thailand       } fields       (          Rating "Please rate {@} on your interest in visiting"          categorical [1..1]          {              ExtremelyInterested "Extremely Interested",              SomewhatInterested "Somewhat Interested",              Neutral "Neutral",              SomewhatDisinterested "Somewhat Disinterested ",              ExtremelyDisinterested "Extremely Disinterested"          };        ) expand grid;    HotelText "Hotel Questions" info;    DestinationText "Destination Questions" info;    End Metadata              163    Chapter 14  Text Substitutions and Text Headings    Survey Programming Fundamentals  Routing (Web)  IOM.DefaultStyles.Labels[LabelStyleTypes.lsBanner].Font.Size = 24  IOM.Banners.AddNew("Header",HotelText.Label)  HotelChainStayed.Ask()  FavHotelChain.Categories.Filter= HotelChainStayed.Response.Value  FavHotelChain.Ask()    IOM.Banners["Header"].Text = DestinationText.Label  Dim location   For each location in InterestinLocation    location.ask()  Next  End Routing    The above example will display different headings for the different screens.  We have also added a  default style to increase the font size of the Banner Text as shown below:        164        Survey Prrogramming Fundamentalls  Chap pter 15  Enhaancing Surveyy Flow  Chapte er 15  En nhancing S  Survey Flow  To obtain n accurate data, by defaultt mrInterview w requires a reesponse to eaach question.  At times, yo ou  may wan nt to either prre‐set informaation into queestions or allo ow respondents to not ansswer the  question and continue e with the surrvey.      In this chapter w we will: Pre‐assign tthe initial answeers to questions. Understand d the property th hat allows respo ondents  to not give an answer to a q question Allow for an n answer to be tthe default respo onse       As stated d above, mrIn nterview requ uires a respon nse to each qu uestion.  To o override this o option, you m must  do 2 things:    • • SSet the MustA Answer propeerty to False P Provide mrInt terview with aa default answ wer when thee respondentt does not cho oose a respon nse.  Technically, there is sttill an answerr for each queestion when yyou look at yo our data, how wever the  nd to every qu uestion when n it isn’t necesssary.  A good d use of this  respondeent will not haave to respon feature w would be a texxt question fo or optional co omments.   If the respondeent did not haave a commeent,  they could simply choose the Next button to co ontinue with tthe survey wh hile mrInterview will recorrd  the respo onse as the pre‐determineed default.        165    Chapter 15  Enhancing Survey Flow    Survey Programming Fundamentals  Must Answer  The MustAnswer property can be applied at the IOM level, or on a question, page or block level.    Routing(Web)  Name.MustAnswer=False      The first statement would only apply to a specific question.  The IOM statement above would prepare  all questions in the study to potentially not give an answer.          If mrInterview is not provided with a valid default answer, then the question will need to be  answered by the respondent before going to the next question.  The exception for this is a  categorical question in which the minimum is not stated (example  [..5]).      Default Answers   Default Answers can either be directly assigned by the programmer or use the pre‐assigned default  value of No Answer.  You can specify default answers in the metadata or routing sections.  In Metadata section:  Name "text" questiontype   DefaultAnswer(response);    Or Routing section:  Name.Response.Default=response  Item  Name  response  Description  Represents the question name   Represents a valid response to the question (valid number for long questions,  category name for categorical questions, etc.)      166        Survey Programming Fundamentals    Chapter 15  Enhancing Survey Flow    The following is an example of adding default responses in the metadata.  Example    TravelSpent "In the past year, approximately how many much did you spend in each  category listed below for business and leisure travel?" loop      {          Transportation,          Accomodations,          FoodDrink "Food and Drinks",          OtherMisc "Other Miscellaneous"      } fields      (          BusTravel "Business Travel"          long [0 .. ] defaultanswer(0);            LeisureTravel "Leisure Travel"          long [0 .. ] defaultanswer(0)      ) expand grid;      The result will not change with the addition of the defaults:    However if any cell is left blank, the default answer of zero will be entered instead of mrInterview  issuing an error message of “Missing Answer(s)”.            167    Chapter 15  Enhancing Survey Flow    Survey Programming Fundamentals  You can even set default values for categorical questions:  Example    Metadata (en‐US, Question, Label)    Age "To which of the following age categories do you belong?"      categorical [1..1]      {          Under18 "Under 18",          _18to34 "18 to 34",          _35to54 "35 to 54",          _55plus "55 and over",          Refused "Prefer not to Answer" REF      } defaultanswer ( {Refused} );    End Metadata    In the above example if the respondent doesn’t answer the question, when they click the Next button  the answer will be recorded as Refused.    Another way to set this default would be in the routing section:  Routing(Web)  Example  Age.Response.Default={Refused}  Age.Ask()  End Routing          To use defaults options, the default answer must be set to a valid response for the question.          168        Survey Programming Fundamentals    Chapter 15  Enhancing Survey Flow    Hidden default responses  The keyword NA is the assumed value for the property defaultanswer.  If you have:  • • • The MustAnswer=False  A response assigned to the keyword NA  No defaultanswer response specified  Then the No Answer response will be hidden on the screen and if the respondent does not answer the  question and goes to the next screen, the No Answer response will be automatically chosen for that  question.  Example  Metadata (en‐US, Question, Label)  AddComments "Please provide us with any additional comments."      text      codes( { NoAnswer "No Comments" NA } );    End Metadata  Routing(Web)  AddComments.MustAnswer=False  AddComments.Ask()  End Routing  The screen displays:    As you can see above, there is not a “No Comments” reply on the screen due to the presence of the  MustAnswer=False and the lack of a DefaultAnswer specified.        169    Chapter 15  Enhancing Survey Flow    Survey Programming Fundamentals  Initial Response  Instead of assigning default values when the respondent does not answer a question, you could have  an answer already assigned to the question when it is first shown to the respondent.  This could be  used for large grids in which every response may not be applicable to the respondent.   This is called an  initialanswer and is applied in the same way as the defaultanswer.    Example    TravelSpent "In the past year, approximately how many much did you spend in each  category listed below for business and leisure travel?" loop      {          Transportation "Transportation",          Accomodations "Accomodations",          FoodDrink "Food and Drinks",          OtherMisc "Other Miscellaneous"      } fields      (          BusTravel "Business Travel"          long [0 .. ] initialanswer(0);            LeisureTravel "Leisure Travel"          long [0 .. ] initialanswer(0)        ) expand grid;        This would be what the screen would look like when the respondent first sees the question:      170      Survey Programming Fundamentals    Chapter 15  Enhancing Survey Flow    The code in the routing section to set the initial value for this complex question type would be:  Example    Metadata (en‐US, Question, Label)    TravelSpent "In the past year, approximately how many much did you spend in each  category listed below for business and leisure travel?" loop      {          Transportation "Transportation",          Accomodations "Accomodations",          FoodDrink "Food and Drinks",          OtherMisc "Other Miscellaneous"      } fields      (          BusTravel "Business Travel"          long [0 .. ];            LeisureTravel "Leisure Travel"          long [0 .. ]        ) expand grid;    End Metadata    Routing(Web)    TravelSpent[..].BusTravel.Response.Initial=0  TravelSpent[..].LeisureTravel.Response.Initial=0  TravelSpent.Ask()    End Routing            Initial value will only be set the first time the respondent is shown the question, meaning if  they use the previous button to go back to questions, their answers will not be re‐set again  if they have changed the values.  If you would like to always re‐set the values, then use the  QuestionName.Response.Value = response.             171    Chapter 15  Enhancing Survey Flow    Survey Programming Fundamentals  Exercise  Open mealswithstyle.mdd file and make the following modifications.  • Make HealthComm allow the respondent to move past the question without answering   • Give the HealthAttribs loop initial values of “Neutral”  • Add the following question after the HealthAttribs grid:  FastFoodComments     Please elaborate on why you [AGREE/DISAGREE] with the statement           “Eating fast food can be healthy.”        Prefer not to Answer   • • •   Respondents who chose Neutral for the attribute “Eating fast food can be healthy”  should not be asked the FastFoodComments question.  For the insert AGREE OR DISAGREE, insert the word “agree” if the respondent chose  Strongly Agree or Agree for the “Eating fast food can be healthy” attribute; insert  “disagree” if the respondent chose Strongly Disagree or Disagree.  (Hint:  If you need help determining how to reference one attribute within a grid  outside the grid, refer to the information item on page 106.)      172        Survey Prrogramming Fundamentalls  Chapterr 16  Customizing the Standard Error Messages Chapte er 16  Cu ustomizing g the Stan ndard Errror Messa ages  There maay be times w when the stan ndard error m messages are n not descriptivve enough forr a specific  question, or your orgaanization has standards for the error teext that are diifferent than the defaults.  You  can contrrol the text off the standard error messaages.  In this chapter w we will: Learn the keywords asso ociated with the  standard eerror messagess Customizee the text of thee error messagges  within you ur script for a specific questio on Change the standard errror message for all  surveys     ndard error m message has aa name associiated with it aand is listed in n the table beelow.  Each stan Message e Name  MissingA Answer  NotNumeric  NotIntegger  NotDate  NotInRan nge  NotSingle eAnswer  TooFewA Answers  Message Texxt  Missing answ wer(s).  When d displayed   The respondent clickks Next witho out answeringg the  question, and the script does not specify a deffault  answer. Also appliess when the respondent doees  not enter answers in n all cells of a grid.   Answer '{AN NSWER}' is not  The response cannott be converteed into a valid d  long (integer) or dou numeric.  uble (decimal), as appropriiate.   Answer '{AN NSWER}' is not  The response is a numeric value, but is not an  an integer vaalue.  integer value.   Answer '{AN NSWER}' is not a  The response cannott be converteed into a valid d  valid date.  date.   Answer '{AN NSWER}' is not  The response does n not fall within the range  in range '{RA ANGE}'.  specifieed for the queestion.    Only one answer is  More th han one respo onse was cho osen from a siingle  allowed.  choice rresponse list.   There are to oo few answers,  The num mber of respo onses chosen from a multiiple  at least {MIN NANSWERS} aare  choice list is less than the minimu um number  required.  required for the queestion.     173  Chapter 16  Customizing the Standard Error Messages  Message Name  TooManyAnswers  Message Text  There are too many answers,  only {MAXANSWERS} are  allowed.  CannotCombine  Answer '{ANSWER}'  ({CATEGORY}) cannot be  combined with other answers.  Answer '{ANSWER}'  ({CATEGORY}) has a response  but is not selected.  Answer '{ANSWER}' is not valid.  OtherNotSelected  InvalidText  TooLittleText  TooMuchText  PlayerNavigationDisabled  The answer does not have  enough text, current length is  '{LENGTH}', minimum is  '{MINLENGTH}'.  The answer has too much text,  current length is '{LENGTH}',  maximum is '{MAXLENGTH}'.  You have used the browser  buttons, please use the  Next/Previous buttons below.    Survey Program When displayed   The number of responses chosen from  a multiple choice list is greater than the  maximum number allowed for the  question.   More than one response was selected,  one of which was marked as exclusive.   The 'Other' response box has text filled  in, but the Other response has not  been selected.   A text response is not in the format  specified in the question; for example,  not a valid telephone number.   The number of characters in a text  response is less than the minimum  specified in the question.   The number of characters in a text  response is greater that the maximum  specified in the question.   The respondent used the browser's  navigation buttons when the project  does not allow this.       The above table is listed in the DDL at this link:   DDL.chm::/interviewscripting_errors_standard.htm      You can change the messages associated with the errors in 3 ways:  • • •     174  Globally for all mrInterview projects  For all questions within a metadata file  For a specific question        Survey Programming Fundamentals  Chapter 16  Customizing the Standard Error Messages  Global changes to error messages  To change the wording of error messages globally for all projects, they are contained in the  StandardTexts.mdd file on the mrInterview server.  Please note that this file holds the translations for  the error messages as well.  If you produce multi‐lingual studies, you will need to translate the new  messages to any additional languages necessary.    Error messages changes for a specific metadata file  To replace the error message text for the whole script, include a StandardTexts block with an Errors  block in the metadata as shown below.                          StandardTexts block fields  (    Errors block fields    (       MessageName1 "Text 1" info;      MessageNamen "Textn" info;     ...    );  );    Item  Description  MessageName1,  Name of the standard message as shown in the table previously.   MessageNamen  Text1, Textn  Represents the replacement message text    The following example will change the default error message “Missing Answer(s)” for all questions  within this survey.  Example    Metadata(en‐US, Question, Label)  StandardTexts "StandardTexts" block fields      (          Errors "Errors" block fields          (              Missinganswer "Please answer the question."              info;            );        );    End Metadata      175  Chapter 16  Customizing the Standard Error Messages    Survey Program   If a respondent did not choose an answer for any question within the survey, they would see:      Error messages changes for a specific question  Changing the error message for a specific question is very similar to the method for every question  within the survey.  The difference is that the StandardText block must be added to a helper field  attached to the question:  Metadata(en‐US, Question, Label)    QuestionName "text" questiontype      helperfields (          StandardTexts "StandardTexts" block fields          (              Errors "Errors" block fields              (          MessageName1 "Text 1" info;          MessageNamen "Text n" info;          ...              );          );      );    Item  helperfields  MessageName1,  MessageNamen  Text1, Textn    176  Description  Keyword used to store additional information for a field/question   Name of the standard error message.   Represents the replacement message text      Survey Programming Fundamentals  Chapter 16  Customizing the Standard Error Messages  Customizing the error message  You can customize the wording of the message by using some of the substitution markers listed in the  table below.  Enclose the markers in curly brackets when inserting into the error text.  Substitution Marker  ANSWER  RANGE  QUESTION  QUESTION_NUMBER  LENGTH  MINLENGTH  MAXLENGTH  MINANSWERS  Description   The respondent's answer.   The valid answer range for the question as defined in the metadata section.   The question name.   The question number.   The length of the response text.   The minimum length for a text response.   The maximum length for a text response.   The minimum number of answers that must be chosen from a multiple choice  list.   The maximum number of answers that may be chosen from a multiple choice  list.   The text of a single multiple choice response.   The error message associated with an internal error.   MAXANSWERS  CATEGORY  ERROR    This example will make the respondent’s error message clearer in its meaning.  Example    DaysTravelYr "On average how many days per year do you travel for business or leisure?"      long [0 .. 365]      helperfields (          StandardTexts "StandardTexts" block fields          (              Errors "Errors" block fields              (                  NotInRange "{ANSWER} is more than the number of days in a year.  Please try  again."                  info;              );          );      );              177  Chapter 16  Customizing the Standard Error Messages    Survey Program When the respondent’s answer is out of the range, it will display a new error message:    178        Survey Prrogramming Fundamentalls  Chaptter 17  Functio ons & Subrou utines  Chapte er 17  Fu unctions & & Subrouttines  With Dim mensions Scrip pting (and oth her programm ming languages), you can ccreate re‐useeable code thaat  will help you to do cerrtain actions, such as valid date question logic or speccific formattin ng issues.    In this chapter w we will: Define Fun nctions and Subroutines Learn how w to write Functions and  Subroutinees in Dimensio ons Scripting See examp ples of Functions and Subrou utines  in Dimensiions Scripting     nctions an nd Subrouttines  Definittion of Fun A functio on or subrouttine is a sectio on of code wiithin a script w which performs a specific task and is  relativelyy independen nt of the remaaining script.  These are terms that are common to o other  programming languagges, not specific to Dimenssions Scriptingg.  nes, includingg:  There aree several advaantages to ussing functionss or subroutin • • • • Reducing the duplication o R of code in a prrogram  E Enabling reus e of code across multiple sscripts   complex pro D Decomposing oblems into simpler piecess (this makes tthem easier tto maintain and  a add/subtract  functionality as needed) Improved readability of a p program  The partss of a function n or subroutine may includ de:  • • • A body of cod A de to be execu uted when the subroutine is called   P Parameters th hat are passed to the subroutine from tthe point wheere it is called d   A A value that is s returned to the point wh here the call o occurs (function only)    oncept of funcctions and subroutines.    Let’s lookk at some verry basic examples to underrstand the co       179    Chapter 17  Functions & Subroutines    Survey Programming Fundamentals  Subroutine  To define a subroutine:  Sub Name(var1, var2, varN)  Statements  End Sub    To call (use) a subroutine:  Name(parameter1, parameter2, parameterN)    Item  Sub   End Sub  Name  Statements  var1, var2, varN  parameter1,  parameter2,  parameter3  Description  Marks the start and end of a subroutine   Represents a unique name given to the subroutine  Represents any statements to be executed within the subroutine  Represents the name of variables that are passed to the subroutine from the  point where it is called.  The variables together are called the argument list.  Represents the actual parameters that are passed to the subroutine.  The  order of these parameters will match up with the variables on the subroutine  (example: parameter1 is the information that will be inserted in the  subroutine represented as var1)       Subroutine Example  Depending on the specific look of your surveys, you may want to control the column widths of a grid at  a default level for all grids, or have individual control.  If you need individual control, it would be nice to  have a way to indicate the specifics per grid on a single line in the script.  We can create a subroutine  to help us with this.  Suppose you had two grids in your study that after the default styles were applied, they looked like  this:  180      Survey Programming Fundamentals    Chapter 17  Functions & Subroutines          Looking at the grids, they might look better with some specific styles applied to them.  As we learned in  the style section, you could specify the style for each grid (AirlineRating and InterestinLocation) in the  routing section:  Example    Routing(Web)  AirlineRating.Categories[..].Label.Style.Cell.Width = "300px"  AirlineRating[0].Item[0].Categories[..].Label.Style.Cell.Width = "70px"   AirlineRating[0].Item[0].Categories[..].Label.Style.Cell.Wrap = true   AirlineRating.Ask()    InterestinLocation.Categories[..].Label.Style.Cell.Width = "120px"  InterestinLocation[0].Item[0].Categories[..].Label.Style.Cell.Width = "90px"   InterestinLocation[0].Item[0].Categories[..].Label.Style.Cell.Wrap = true  InterestinLocation.Ask()  End Routing            181    Chapter 17  Functions & Subroutines    Survey Programming Fundamentals  The previous code would produce the following look:    Now we might say that this code could be useful in many studies.  As you can see, we are repeating the  same basic text each time, just changing the values of the style properties and the question it applies  to.  This repetitiveness makes it a candidate for a subroutine.      First, create the subroutine’s structure and give it a name that is easily recognizable:  Sub GridStyle1()    End Sub    182        Survey Programming Fundamentals    Chapter 17  Functions & Subroutines    Then, ask yourself what will change each time about the lines of code; the question name and the  values of the styles will change each time, so they need to be replaced with a variable to represent  those items:  Sub GridStyle1 (QuestionName, ColHeadWid, ColWid, ColWrap)  End Sub      QuestionName, ColHeadWid, ColWid, and ColWrap are similar to temporary variables, so  the names can be anything you like.      Next, add the code.   Beginners may find it helpful to add the code for one question without the  substitutions then make the changes to that code with the parameters.    Sub GridStyle1 (QuestionName, ColHeadWid, ColWid, ColWrap)  AirlineRating.Categories[..].Label.Style.Cell.Width = "300px"  AirlineRating[0].Item[0].Categories[..].Label.Style.Cell.Width = "70px"   AirlineRating[0].Item[0].Categories[..].Label.Style.Cell.Wrap = true     End Sub    Looking at the above example we will need to change AirlineRating, “300px”, “70px”, and true to  match the variable names we defined on the first line of the subroutine:    Sub GridStyle1 (QuestionName, ColHeadWid, ColWid, ColWrap)  QuestionName.Categories[..].Label.Style.Cell.Width = ColHeadWid   QuestionName [0].Item[0].Categories[..].Label.Style.Cell.Width = ColWid  QuestionName [0].Item[0].Categories[..].Label.Style.Cell.Wrap = ColWrap    End Sub          183    Chapter 17  Functions & Subroutines    Survey Programming Fundamentals  The above subroutine alone does nothing.  You need to Call the subroutine and specify the parameter  information for a specific action.  Here is the completed subroutine example:  Example    Routing(Web)  GridStyle1(AirlineRating,"300px" , "70px" ,true)  AirlineRating.Ask()    GridStyle1(InterestinLocation, "120px" , "90px" ,true)  InterestinLocation.Ask()       Sub GridStyle1 (QuestionName, ColHeadWid, ColWid, ColWrap)  QuestionName.Categories[..].Label.Style.Cell.Width = ColHeadWid   QuestionName [0].Item[0].Categories[..].Label.Style.Cell.Width = ColWid  QuestionName [0].Item[0].Categories[..].Label.Style.Cell.Wrap = ColWrap    End Sub    End Routing      Function  As stated earlier in this chapter, a function differs from a subroutine in that it can pass a value back to  where the call originated.  In the syntax below, you will see it is very similar to the subroutine, but now  you may set a value equal to the function name to pass back and use within your script.  Function Name(var1, var2, varN)    Statements  Name = value    End Function    To call (use) a function:  Name(parameter1, parameter2, parameterN)    184        Survey Programming Fundamentals    Chapter 17  Functions & Subroutines       Item  Function  End Function  Name  Statements  var1, var2, varN  Value  parameter1,  parameter2,  parameter3  Description  Marks the start and end of a function   Represents a unique name given to the function  Represents any statements to be executed within the function  Represents the name of variables that are passed to the function from the  point where it is called.  The variables together are called the argument list.  A value that is returned to the point where the function call occurred  (Optional)  Represents the actual parameters that are passed to the function.  The order  of these parameters will match up with the variables on the function  (example: parameter1 is the information that will be inserted in the function  represented as var1)         185    Chapter 17  Functions & Subroutines    Survey Programming Fundamentals  Suppose we had a shared list of travel agencies that had 30 categories:    Example    Metadata(en‐US, Question, Label)  Agencylst "" define      {          Agency1  "Travel Agency 1",           Agency2  "Travel Agency 2",          Agency3  "Travel Agency 3",          Agency4  "Travel Agency 4",    …          Agency30 "Travel Agency 30"      };    AgencyHeardOf "Which of the following travel agencies have you heard of?"      categorical      {          use AgencyLst       };    'Create a filter for AgencyUse to be the responses of AgencyHeardOf  AgencyUse "Of those you were aware of, which travel agencies would you consider using  to book your travel?"      categorical      {          use AgencyLst      };  End Metadata    Routing(Web)  agencyheardof.Style.Columns=3  agencyheardof.Ask()    agencyuse.Categories.Filter=agencyheardof  agencyuse.Ask()    End Routing      And you wanted to force the style of the number of columns for the AgencyUse question to have no  more than 10 categories in each column.    Since the categories of the question AgencyUse are  dependent on the response to AgencyHeardOf, we will need to find out the number of categories  chosen in AgencyHeardof, and divide by 10 to see how many columns we need using the AnswerCount    Dimensions Function we learned in   186      Survey Programming Fundamentals    Chapter 17  Functions & Subroutines    Basic Routing Logic, page 60.  Since dividing our number of responses by 10 may not result in a whole  number, we will also use a built‐in function, int(), which returns the integer portion of a number.      Routing(Web)  agencyheardof.Style.Columns=3  Example  agencyheardof.Ask()  agencyuse.Categories.Filter=agencyheardof    Dim Actual, IntegerValue, DecimalValue    Actual = CDouble(AgencyHeardof.AnswerCount())/10  IntegerValue = int(AgencyHeardof.AnswerCount()/10)  DecimalValue = Actual ‐ IntegerValue    If DecimalValue > 0 Then    agencyuse.Style.Columns = IntegerValue + 1  Else    agencyuse.Style.Columns = IntegerValue  End If  AgencyUse.Ask()    End Routing    Since this may be an action we would want to do on other questions or in other studies, it might be  advantageous to create a function instead.  The function below does just that.  It was created in a  similar way to the subroutine.    Routing(Web)  agencyheardof.Style.Columns=3  Example  agencyheardof.Ask()  agencyuse.Categories.Filter=agencyheardof  agencyuse.Style.Columns=ForceCols(agencyheardof)  agencyuse.Ask()      Function ForceCols(filterQ)  Dim Actual, IntegerValue, DecimalValue  Actual = CDouble(filterQ.AnswerCount())/10  IntegerValue = int(filterQ.AnswerCount()/10)  DecimalValue = Actual ‐ IntegerValue    If DecimalValue > 0 then    ForceCols = IntegerValue + 1  Else    ForceCols = IntegerValue  End If  End Function  End Routing        187    Chapter 17  Functions & Subroutines    Survey Programming Fundamentals  You can see that the function is set up very much the same as the subroutine, in that it has a name  (ForceCols) and has a parameter (filterQ).  The difference is that after the function is completed, it is  set to a value.  The values can be anything.  Exercise  Open the reusable.mdd file.  Make the following routing section code more re‐useable with the  concepts learned in this chapter.  It would be helpful to have a piece of re‐usable code that would  allow you to easily specify the number of response columns, column width, and question text color for  specific questions.  Routing(Web)  PrimaryTravel.Style.columns = 3  PrimaryTravel.Style.Width = 300  PrimaryTravel.Label.Style.Color= "#0000FF"  PrimaryTravel.Ask()    CountryVisited.Style.Columns=2  CountryVisited.Style.Width = 600  CountryVisited.Label.Style.Color= "#00FF00"  CountryVisited.Ask()   End Routing    188      Survey Prrogramming Fundamentalls  Chap pter 18  Valid dation  Chapte er 18  Va alidation   In the lasst chapter we discussed the concepts of subroutiness and function ns.  Dimensions scripting h has a  unique fu unction that aallows you to easily validatte logic in queestions.  We w will also look at additionall  conceptss that will help p us validate the logic of th he survey.  In this chapter w we will: Validate a text question to follow a patttern Understan nd how to add errors for custtom  logic Create cusstom logic with h the use of  Dimension ns validation fu unctions     Validatting Text Q  Question P  Patterns  You can iinclude statem ments within the metadatta that will check a text field to see if it matches a  specific p pattern.  Regu ular Expressio ons allow you to do create very compliccated match aalgorithms wiith a  small amount of code.  Name "Text" text  N V Validation(" e expression");  Item  Name  Descrription  Metadata item name  "Text"  text  Validatio on  expressio on    Text aassociated wiith the item  Questtion type.  Must be text to o add a regulaar expression Prope erty keyword to allow you to add a regu ular expressio on  Regullar Expression n syntax          189    Chapter 18  Validation    Survey Programming Fundamentals  Test your expressions thoroughly, as there are many variations to regular expressions, too numerous  to place in this manual.   Here are a few to help you understand the examples below.  Symbol  \w  \W  \d  Description  Matches any word character (a‐z, A‐Z, 0‐9)  Matches any nonword character.   Matches any decimal digit. Equivalent to \p{Nd} for Unicode and [0‐9] for non‐Unicode,  ECMAScript behavior.  Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0‐9] for non‐Unicode,  ECMAScript behavior.  \D        The DDL does reference regular expressions:   DDL.chm::/aliasmap_regularexpressions.htm   however, there are also many references on the web as well, such as:  http://en.wikipedia.org/wiki/Regular_expressions  and  http://regexlib.com/cheatsheet.aspx .         The following example will check the length of the phone number and also if it follows the specific  pattern with 2 dashes.       Example  Phone "Please enter your 10‐digit phone number with dashes:"      text [7..20]      validation("\d{3}‐\d{3}‐\d{4}");              The regular expression above shows you want 3 “decimal digits” (numbers) a dash, 3 more numbers a  dash and 4 numbers.        190      Survey Programming Fundamentals    Chapter 18  Validation    The next example is more flexible, allowing you to check an email address to ensure it contains an @  sign.         Email "Email:"      text [5..100]  Example          helperfields (          StandardTexts "" block fields          (              Errors "" block fields                (                  InvalidText "You must enter a valid email address with an @ and period. "                  info;              );          );      ) validation("[‐.\w]+\@[‐.\w]*[‐.\w]+\.[‐.\w]*");          This expression ensures the respondent answered a dash, period or any word character (a‐z), then a  mandatory @ sign, followed by a dash, period or any word character.            191    Chapter 18  Validation    Survey Programming Fundamentals  Checking Custom Logic  There are many times you will need to do logic checks within your survey that are not covered by the  standard error messages.  The most efficient way to achieve this is through custom validation.  The  concept is a special type of function that is tied directly to a question.      Function functionname(Question, IOM, Attempt)     Statements  functionname = True  Statements  functionname = False  End Function    Item  Function  End Function  functionname  Question  IOM  Attempt  Statements  True  False      192  Description  Defines the start and end of the function  Represents the unique name given to the function  Parameter that represents the question you are attaching to the function (this  will always be Question)  Parameter for the Interview Object Model (This will always be IOM)  Parameter for the number of current custom validation attempts  (This will  always be Attempt, if used, but it is an optional parameter).  Could be used to  set the number of times the function should attempt to receive a True value.  Represents the Dimensions scripting statements to do any action and return a  value, such as check logic  Values that the Dimensions custom validation function must pass back.  These  special functions must set the functionname to true or false        Survey Programming Fundamentals    Chapter 18  Validation    To set the validation function to use for a question, use the following statement in the routing section  somewhere prior to asking the question:  Routing(Web)  Name.Validation.Function = functionname  Name.Ask()  End Routing  Item  Name  Validation.Function  functionname    Description  Name of the question you wish to validate  Properties to set the validation function for the question.  Represents the unique name given to the function  There are a few things to note about creating custom validation functions:  • • • To reference another metadata item (besides the question you are validating) inside the  function, you need to reference the question with IOM.Questions.QuestionName.    The function must return either a True (logic is correct, move on to the next question) or False  value (logic is not correct, issue an error message if the number of attempts has not been met).  They can only have the parameters Question, IOM, and Attempt.  If you want to include more  variable information into the function, one way to achieve this is to add custom properties in  the metadata of the question you wish to validate. (More to come on this subject.)    Adding custom errors  In the next examples, we will be creating customized logic that may require you to have the  respondent re‐answer the question.  To do that action, you need to add your own error message.  You  can create errors that have the same properties as the standard error messages.  In the routing section  you would add:    Name.Errors.AddNew("errorname",  errortext.label)     Item  Name  Errors.AddNew  errorname  errortext  label    Description  Name of the question you want to apply an error message to  States you want to add a new error to the standard set of error messages  Represents the unique name given to the error message  Represents the info item created to hold the text for the error message.  You can  just add text in double quotes in the routing section for this, but it is highly  recommended to make the info item.  Will show the label of the info item as the error message text      193    Chapter 18  Validation    Survey Programming Fundamentals      You define the error message you want to use as an info item in the metadata section. This  is important for multilingual projects because it makes the message text available for  translation.     The example below is a categorical grid that displays a column of numeric boxes to enter information  that should add to 100%.  Example    Metadata(en‐US, Question, Label)  Activities  define      {          Train "On a train/train station",          Airplane "In an airplane/airport",          Vehicle "In a Vehicle driving or riding",          Subway "Subway System",          Walk "Walking",          OtherMode "Other"      };          PercActivity "Thinking of your travel over the last year, what percentage of your time  was spent using the following modes of transportation?  The total should add to 100%."  loop      {          use Activities      } fields      (          QPercent "Percentage"              style(                  Width = "30px"              )          long [0 .. 100]          initialanswer(0 );        ) expand grid;        ErrorGridAddto100 "Please check your responses.  Responses should add up to 100."      info;    End Metadata      194        Survey Programming Fundamentals    Chapter 18  Validation    In the routing section, we will create the special Dimensions validation function to make sure our grid  adds to 100% as shown below.  Example      Routing(Web)  IOM.LayoutTemplate = "Card_Blue_TopAndBottomErrors.htm"    PercActivity.Validation.Function = "ValidateGrid100"  PercActivity.Ask()    Function ValidateGrid100(Question, IOM,Attempt)      Dim category      Dim total        If attempt <= 3 Then                For Each category in Question              total = total + category.Item[0].Response.Value          Next            If total <> 100 Then                Question.Errors.AddNew("ErrorGrid",                  IOM.Questions.ErrorGridAddto100.Label)                 ValidateGrid100 = False            Else                ValidateGrid100 = True            End If          End If   End Function    End Routing                  195    Chapter 18  Validation    Survey Programming Fundamentals  Let’s change the scenario slightly.  What if you wanted to modify the question, so that the question  prior to this was:  “Thinking of your travel over the last year, approximately how many hours did you spend using some  type of transportation?”  This will involve modifying our previous example to be able to reference that question’s response  within the function.   Example    Metadata(en‐US, Question, Label)    HrsTravelMode "Thinking of your travel over the last year, approximately how many  hours did you spend using some type of transportation?"   long [0..8760];        HrsActivity "Thinking of your travel over the last year, how many hours of your time was  spent using the following modes of transportation?  The total should add to  {#HrsTravelMode}."  loop      {          use Activities      } fields      (          QHours "Hours"              style(                  Width = "30px"              )          long [0 .. ]          initialanswer(0 );        ) expand grid;        ErrorGridAddtohrs "Please check your responses.  Responses should add up to  {#HrsTravelMode}."      info;    End Metadata      196        Survey Programming Fundamentals    Chapter 18  Validation    Again, the routing section is where the validation happens.  Notice the reference to the additional  question with the “IOM.Questions” preceding it.  Example    Routing(Web)    IOM.LayoutTemplate = "Card_Blue_TopAndBottomErrors.htm"    HrsTravelMode.Ask()    HrsActivity.Validation.Function = "ValidateGridEqualDependentQ"  HrsActivity.Ask()    Function ValidateGridEqualDependentQ (Question, IOM,Attempt)      Dim category      Dim  total        If attempt <= 3 Then                  For Each category in Question              total = total + category.Item[0].Response.Value          Next            If total <> IOM.Questions.HrsTravelMode Then                Question.Errors.AddNew("ErrorGrid", IOM.Questions.                 ErrorGridAddtohrs.Label)                  ValidateGridEqualDependentQ = False            Else                ValidateGridEqualDependentQ = True            End If              End if      End Function        End Routing              197    Chapter 18  Validation    Survey Programming Fundamentals  The above works nicely, however it is very specific to the question.  The line:  If total <> IOM.Questions.HrsTravelMode Then  Would have to be changed every time it is used for a different question, which is not a good practice.    As stated above, one of the biggest differences between standard functions and custom validation  functions is that currently you cannot add any additional parameters.  This limits the flexibility of  custom validation functions.  One way that you could pass parameters into a function to make it more  reusable is by placing custom properties in the metadata.    Adding custom properties to metadata  Custom properties can be any additional information attached to a metadata item.  One basic way to  add custom properties is in the metadata section:  Name "text" [property] type   Item  Name  "text"  [property]  type  Description  Name of the question in the metadata section  Text of the question  Represents any information you want stored in the metadata associated with the  metadata item  Represents the metadata item type (categorical, long, etc.).  Notice the custom  properties are prior to this.      Custom properties are an advanced concept, but an important one to remember as you progress with  your Dimensions Scripting learning.  Let’s add a custom property to our previous example so that we  do not have to make our function so specific to these sets of questions.  Below in bold you will notice  the addition of custom properties that adds the name of the question we want to use in the function  to compare to the sum of our grid.    198        Survey Programming Fundamentals  Example      Chapter 18  Validation    Metadata(en‐US, Question, Label)    HrsTravelMode "Thinking of your travel over the last year, approximately how many  hours did you spend using some type of transportation? "   long [0..8760];        HrsActivity "Thinking of your travel over the last year, how many hours of your time was  spent using the following modes of transportation?  The total should add to  {#HrsTravelMode}."        [ dependentQ = "HrsTravelMode" ]   loop      {          use Activities      } fields      (          QHours "Hours"              style(                  Width = "30px"              )          long [0 .. ]          initialanswer(0 );        ) expand grid;        ErrorGridAddtohrs "Please check your responses.  Responses should add up to  {#HrsTravelMode}."      info;    End Metadata                        199    Chapter 18  Validation    Survey Programming Fundamentals  In the routing you will see the change to the comparison line.  Notice the addition of the comments to  identify what is needed for the function.  Routing(Web)    Example  IOM.LayoutTemplate = "Card_Blue_TopAndBottomErrors.htm"    HrsTravelMode.Ask()      HrsActivity.Validation.Function = "ValidateGridEqualDependentQ"  HrsActivity.Ask()    Function ValidateGridEqualDependentQ (Question, IOM,Attempt)      Dim category      Dim  total        If attempt <= 3 Then                  For Each category in Question              total = total + category.Item[0].Response          Next            If total <> IOM.Questions[Question.Properties["dependentQ"]] Then                Question.Errors.AddNew("ErrorGrid", IOM.Questions.                 ErrorGridAddtohrs.Label)                  ValidateGridEqualDependentQ = False            Else                ValidateGridEqualDependentQ = True            End If              End if      End Function    End Routing    Now this function can be re‐used in different projects.  You can see how a library of custom validations  will speed the programming process over time.    200        Survey Prrogramming Fundamentalls  Chaapter 19  Com mpound Quesstions  Chapte er 19  Compound  Question ns  The comp pound type h helps you to aachieve a speccial look to yo our questionn naire when yo ou wish to dissplay  multiple questions on the same scrreen horizonttally.  These q questions must have the co ommon  urveys, but caan  denominator of a shared list of cattegories.  Thiss is traditionally used in paaper‐based su also be done for web‐‐based studies.    This ch hapter co overs: The definittion of a comp pound question n Validating compound qu uestions Differencees between loo ops and compo ound  questions   Definin ng Compou und Questtions  In essencce, a compound is simply m multiple quesstions (includiing grids) whiich all share aa common listt of  categoriees.   Think of aa compound question as aa container fo or other questtions you wish to display o on  the samee page horizontally.  The syyntax for a co ompound is ass follows:  C CompoundNa ame  "Text" ccompound   { { Categories } }  fields  (      Question1;   Q   Q QuestionN;  );  Item  Compoun ndName  "Text"  compoun nd  categorie es  fields  Question n1,  Question nN     De escription  Un nique name ffor the compo ound metadata item   Op ptional Text tto display across the top of the screen o of the compo ound question n  Ke eyword to creeate a compo ound metadatta item  Re epresents thee categories fo or which the questions and loops are to o be asked.  Yo ou may use a shared list heere if you wissh.   Prrecedes the q questions with hin the compound item  ops that you w want to display side by sid de. Caategorical queestions and categorical loo     201    Chapter 19  Compound Questions    Survey Programming Fundamentals    Suppose we want to create the following look for our survey:      You will notice in the above example that all the questions on the page share a list of airlines.  The next  example will show how this can be created as a compound question.     202        Survey Programming Fundamentals  Example      Chapter 19  Compound Questions    Metadata(en‐US, Question, Label)  Airlines "" define      {          United,          Delta ,          BritishAirways "British Airways" ,          Luftansa "Luftansa"      };        AirlineQ "Please answer the following questions about the airlines listed." compound      {          use Airlines      } fields      (          FlownBefore "Flown Previously"          Categorical [1..];          Trips6MoLoop "# of Trips Past 6 Months" loop fields          (              trips ""              long [0 .. 400];            ) expand grid;          SatisLoop "Overall, how satisfied are you with each Airline?" loop fields          (              RateAirline "RateAirline"              categorical [1..1]              {                  VerySatisfied "Very Satisfied",                  SomewhatSat "Somewhat Satisfied",                  SomewhatDisSat "Somewhat Dissatisfied",                  VeryDissatisfied "Very Dissatisfied"              };            ) expand grid;      );  End Metadata    Routing(Web)  AirlineQ.Ask()  End Routing            203    Chapter 19  Compound Questions    Survey Programming Fundamentals  The questions inside of the compound are missing items you might expect to see. For example the  FlownBefore question has no responses, and the two loops have no iteration elements.   This is  because all the questions inside of a compound will make reference to the shared categories from the  first section of the compound.      The compound can be created without omitting these elements, but for the sake of  efficiency you will want to use the method shown above.    Validating a compound question  Validating compound questions can prove challenging for beginner programmers.  However, with the  skills taught in the previous sections of validations, you are on your way to validating complex  compound questions as well.  Here is a simplified version of the example above.  This example only  includes the questions FlownBefore and Trips6Mo_Loop.    Example    Metadata(en‐US, Question, Label)  Airlines  define      {          United,          Delta,          BritishAirways "British Airways ,          Luftansa      };        AirlineQ "Please answer the following questions about the airlines listed." compound      {  use Airlines      } fields      (          FlownBefore "Flown Previously"          Categorical [1..];          Trips6MoLoop "# of Trips Past 6 Months" loop fields          (              trips ""              long [0 .. 400]              codes(              {                  NoAnswer " " NA              } );          ) expand grid;      );        CompoundError "Missing answers, please try again."      info;  End Metadata    204      Survey Programming Fundamentals    Chapter 19  Compound Questions    The logic you will need to check for will be:  • • If FlownBefore is chosen, then Trips6MoLoop must be answered  If FlownBefore is not chosen, then Trips6MoLoop must be null  The following validation function creates those logic checks.  By referencing the questions inside the  compound by their position (0 = FlownBefore, 1 = Trips6MoLoop), it makes the Function more reusable  for other similar scenarios.  Example    Routing(Web)  IOM.LayoutTemplate= "Card_Blue_TopandBottomErrors.htm"    AirlineQ.MustAnswer=False  AirlineQ.Validation.Function="ValidateSimpleCompound"  AirlineQ.Ask()    Function ValidateSimpleCompound(Question,IOM,Attempt)  ValidateSimpleCompound = True  Dim Cat  For Each Cat In Question.Categories       If (Question.Item[0].ContainsAny(Cat) And Question.Item[1].Item[Cat].Item[0] = Null ) _      Or (NOT (Question.item[0].ContainsAny(Cat))  And _      Question.Item[1].Item[Cat].Item[0] Is Not Null) Then      ValidateSimpleCompound = False    End If  Next    If ValidateSimpleCompound = False Then      Question.Errors.AddNew("CompoundError",IOM.Questions.CompoundError.Label)  End If    End Function    End Routing              205    Chapter 19  Compound Questions    Survey Programming Fundamentals  Compound vs. Loop  You may have noticed similarities between compound questions and loops that have multiple different  types of questions.  There are a few main differences between compounds and loops to be aware of:  • • You cannot drop the similar category lists from the questions in a loop as you can with a  compound  Validation of a compound question is very different that for a grid      206        Survey Prrogramming Fundamentalls  Chapter 20  Wo orking with Saample  Chapte er 20  Wo orking wiith Samplle  mrInterview allows yo ou to access information you have abou ut your poten ntial respondeents and use this  to enhance the surveyy experience and/or data.  One scenario os for using the additionall information  would bee to customize e the intervieew screens baased on who iis currently taaking the inteerview.   In this chapter w we will: Retrieve in nformation from the sample table  into the Diimensions Script Send inforrmation from the Dimensionss  script to th he sample table Use a test sample record d locally in mrSStudio  ns script to check your Dimension     mple manage ement allows you the optio on to bring ad dditional information abou ut the  Using sam respondeents for use d during the inteerview eitherr by:  • • Displaying info D ormation held in the tablee to the respo ondent (“Hello o, Bob.  Thank you for  p participating.” ”)  C Creating a que estion to hold d the sample information sso it is easily analyzed with h the  r respondent’s  answers.    n the sample ttable about th he current respondent:  To refereence informattion stored in IOM.SampleR Record.Item["" sampleField d "]  Item  SampleFiield  Desscription  Rep presents the n name of the ffield in the SQ QL database tthat holds thee information  you u wish to retriieve.           207    Chapter 20  Working with Sample    Survey Programming Fundamentals  Here is an example of pulling information from a sample record into the text of a question.  We are  assuming the project’s sample table has a field named “TAgency” that holds the Travel Agencies used  by the people in the sample.  Example  Metadata(en‐US, Question, Label)    VerifyTravelAgent "Our records indicate you have used the travel agency {Agency} in the  past, is this correct?"      categorical      {          Yes,          No       };     End Metadata    Routing(Web)  VerifyTravelAgent.Label.Inserts["Agency"].Text=IOM.SampleRecord.Item["TAgency"]  VerifyTravelAgent.Ask()  End Routing    If a specific respondent’s travel agency was Travel Agency XYZ, then their question will appear as  shown below:          208          Survey Programming Fundamentals    Chapter 20  Working with Sample    The next example does not display the respondent’s information, but rather stores it in a question for  analysis purposes.    Metadata(en‐US, Question, Label)    Example  Region "Stores the region where they live."   text;    End Metadata  Routing(Web)    Region.Response.Value = IOM.SampleRecord.Item["SRegion"]    End Routing          You can also put information collected or derived in the script into a sample field.      Metadata(en‐US, Question, Label)    Example  ReceiveTravelInfo "Check here if you wish to receive an email regarding travel safety."      boolean;    End Metadata    Routing(Web)  ReceiveTravelInfo.Ask()  IOM.SampleRecord.Item["WantsEmail"] = ReceiveTravelInfo.Response.Value  End Routing    The above example will store a True or False in the sample field, providing you have a sample field  called “WantsEmail”.    Testing sample information within mrStudio  You can easily test to see if you are correctly pulling your sample information into the script.  mrStudio  allows you to create a test sample record.  To do this:  Access the file:   C:\Program Files\SPSS Dimensions\mrStudio\4.0.0.0\Interview\DefaultSample.xsu.      209    Chapter 20  Working with Sample    Survey Programming Fundamentals  This is an XML document which mrStudio reads as a sample record by default.  The default file is shown  below:      210        Survey Programming Fundamentals    Chapter 20  Working with Sample      Item                            Description  Marks the beginning and end of the samplerecord.  Can only create  a single record for testing within mrStudio.  Marks the beginning and end of the sample fields for the record.  Marks the beginning and end of a sample field.  Tags to surround the name of the sample field  Tags to surround the type of field.  SQL field types are used.  Smallint  = 2; Int = 3; Datetime = 7; Char, Text, Ntext, or NVarchar = 8; Bit = 11  Tags to surround the value you want the sample field to have.  You have the ability to create your own files and add additional Sample fields as shown below:          211    Chapter 20  Working with Sample    Survey Programming Fundamentals  In order to access the sample information, make sure that under   Tools – Options – Sample Management Record  you are referencing the correct .xsu file.    The example below will assume you are using the modified TravelSample.xsu with the additional field  for region.  Metadata(en‐US, Question, Label)    Example  Region "Stores the region where they live." text;    VerifyTravelAgent "Our records indicate you have used the travel agency {Agency} in the  past, is this correct?"        categorical      {            Yes,          No         };     End Metadata    Routing(Web)    Region.Response.Value = IOM.SampleRecord.Item["SRegion"]  VerifyTravelAgent.Label.Inserts["Agency"].Text=IOM.SampleRecord.Item["TAgency"]  VerifyTravelAgent.Ask()    End Routing  As you can see in the screenshot above, you can easily check your references to sample fields within  the text of your survey (Such as Agency XYZ), but when you are accessing the locals pane, you can also  see that the region has been correctly added to the question, Region.      212      Survey Programming Fundamentals    Chapter 20  Working with Sample    Alternative to Sample Management to pass information into the survey  If you are not using sample management, you can send out separate URL links to respondents that  speak different languages.  Then embed a parameter in the URL that will be passed into the script to  set the language.  mrInterview can pass parameters on the URL using the names I.User1 through  I.User9.  Then you can do the same things with these parameters that we did with sample  management variables.    URL to send out:  http://www.servername.com/scripts/mrIWeb.dll?I.Project=myproj&I.User1=DEU  Example    In the script:  Routing(Web)    IOM.Language = IOM.Info.User1  End Routing  The above example would set the language to German (DEU) for the interview.      213    Chapter 20  Working with Sample    214    Survey Programming Fundamentals        Survey Prrogramming Fundamentalls  Chapter 21  Wo orking with Qu uotas  Chapte er 21  Wo orking wiith Quotas  Quotas are a system ffor controllingg the numberr of respondeents interview wed matching predefined  criteria. FFor example, we may be asked to intervview 1000 resspondents with the requirrements that 500  are male and 500 are female.  In n this chapter will cover: An overvieew of the quota process How to check and respond to quotas in n the  routing secction Checking aand changing q quotas online     Definin ng Survey  Quotas  To setup a quota we n need three iteems:  • • • TThe question the quota will be based on n scripted in yyour metadatta section.  T The targets fo or the quota.  T The type of qu uota     making a quotta based on th he responden nt’s gender.  Let’s lookk at a simple example of m Gender  Targets  Male  Female  500  500    on we should d have a questtion for gender:  In our meetadata sectio Example  Metad data(en‐US, Q Question, Labeel)  Gende er "Are you...""      cate egorical [1..1]      {          M Male ,          Fe emale       };  End M Metadata        215    Chapter 21  Working with Quotas    Survey Programming Fundamentals  Once you have saved the metadata file, you can create your quota targets by selecting Tools ‐ Quotas   or choosing the quota button from the Interview Options toolbar:      You will see the quota tool as shown in the picture below.    On the left of the screen you will see a list of the questions in the survey. Drag and drop the “Gender”  question onto the quota matrix.    216      Survey Programming Fundamentals    Chapter 21  Working with Quotas    We can now see the two gender categories with a grey box to the right of each:     Next, double‐click on one of the grey boxes to set the targets:              217    Chapter 21  Working with Quotas    Survey Programming Fundamentals  Here we can set the target and quota type for the cell.  Type  Normal  Allow Over  Counter  Description  A normal quota will report quota full when the quota count of the completed and  pending interviews is equal to the target.  Allow over will report quota full when the quota count of completes is equal to the  target. Note, this does not include the pending and as such you potentially can go over  quota.  A counter quota is really not a quota at all. The system will not stop respondents from  completing interviews once the limit is reached. This type of quota is used for  information purposes only.    Once you have set the target and type for each quota cell we need to name the quota matrix. We’ll call  this example QuotaGender.    Now Save. This will create a file type with a .mqd extension.    Checking Quotas  Now that we have quota limits defined, we need to add logic to our routing section that tells the  section to check on the quota. Before we do that, let’s add an extra item to our metadata. We are  creating a scenario where respondents will be turned away from the survey based on their responses.  Let’s add a message to use for informing the respondent what has happened.    Example  Metadata(en‐US, Question, Label)  Gender "Are you..."      categorical [1..1]      {          Male ,          Female       };    OverQuota "I'm sorry, the quota is full." info;  End Metadata    In the routing section, we will start by defining a temporary variable to hold our quota check and ask  our quota question.  218      Survey Programming Fundamentals    Chapter 21  Working with Quotas      Routing(Web)  Example  Dim Quota_Pend_Result  Gender.Ask()  End Routing      You must make sure that you always check a quota after the respondent has answered.      Next add the quota check:  Routing(Web)  Example  Dim Quota_Pend_Result  Gender.Ask()  Quota_Pend_Result = QuotaEngine.QuotaGroups["QuotaGender"].Pend()  End Routing      As you can see you must reference the name you gave the quota matrix. In this way you can create  multiple quota matrixes and check them at different points of the survey.  The temporary variable  Quota_Pend_Result stores the results of the attempted quota pend. Now we need to check those  results and respond accordingly.          219    Chapter 21  Working with Quotas    Survey Programming Fundamentals      Routing(Web)  Example  Dim Quota_Pend_Result  Gender.Ask()  Quota_Pend_Result = QuotaEngine.QuotaGroups["QuotaGender"].Pend()  If Not(IsSet(Quota_Pend_Result, QuotaResultConstants.qrWasPended)) Then     IOM.Texts.InterviewStopped = OverQuota.Label     IOM.Terminate(Signals.sigOverQuota)  End If  End Routing    The If statement is checking to see if the Pend() attempt resulted in the success of one or more quota  cells. If this was not the case, then the respondent has failed the quota check.  We will set the  InterviewStopped text to the message we defined in an info item in our metadata section. Then we  terminate the interview, flagging the respondent as “over quota”.      220        Survey Programming Fundamentals    Chapter 21  Working with Quotas    Quotas In mrStudio  If you try running this in mrStudio now, you will get an error message by default.  One choice is to skip  over the code when running inside of mrStudio by adding a check for when the script is in Debug  mode.  Routing(Web)  Example  Dim Quota_Pend_Result  Gender.Ask()  If Not IOM.Info.IsDebug Then        Quota_Pend_Result = QuotaEngine.QuotaGroups["QuotaGender"].Pend()        If Not (IsSet(Quota_Pend_Result, QuotaResultConstants.qrWasPended)) Then              IOM.Texts.InterviewStopped = OverQuota.Label              IOM.Terminate(Signals.sigOverQuota)        End If  End If  End Routing      IOM.Info.IsDebug will be True whenever the survey is running inside mrStudio.      mrStudio v.4.5 and above does have the capability to simulate quotas.   Note you must  have either Microsoft SQL Server 2000 or 2005, including the free SQL Server 2005 Express  Edition and Microsoft SQL Server Desktop Engine (MSDE) to use this feature.   See the DDL  for more detail:  DDL.chm::/mrstudio_testing_quotas.htm                 221    Chapter 21  Working with Quotas    Survey Programming Fundamentals  Activation with Quotas  Now that the quotas are created, you need upload the .mqd file and activate the study with special  options for quotas.  You can do this directly from mrStudio using Tools – Activate, or through  DimensionNet.    For instructions on Activating quotas within DimensionNet, see the DDL:   DDL.chm::/quota_dimnet.htm          Viewing & Changing Quotas  You can view and change quota information online using the DimensionNet Quotas activity.      Each quota matrix in your survey will be a button on the left hand side of the activity page:    222      Survey Programming Fundamentals    Chapter 21  Working with Quotas      Selecting a quota group will display the current quota counts:      You also may see a dropdown list that allows you to change additional quota information.    Type  Do Not Edit  Targets  All    Description  View only mode.  Allows you to modify the targets for each quota cell.  Allows you to modify the target, complete, pending and type for each quota cell.          223    Chapter 21  Working with Quotas    Survey Programming Fundamentals  When the Targets option is selected textboxes will appear. You can raise or lower the cell targets. Once  you have entered the new correct targets click the Update button.        224        Survey Programming Fundamentals    Chapter 21  Working with Quotas    When the All selection is chosen you can edit the targets, complete count, pending count as well as  change between Normal, Over‐Quota and Counter quota types.          225    Chapter 21  Working with Quotas    226    Survey Programming Fundamentals        Survey Prrogramming Fundamentalls  Chapter 22  Creating Mullti‐Lingual Pro ojects  Chapte er 22  Cre eating Mu ulti­Lingu ual Projeccts  When im mplementing sstudies in diffferent languages, Dimensio ons allows yo ou to create aa survey in a b base  languagee, and then eaasily add languages to the metadata filee.  The chapteer will review w the process of  multi‐linggual studies, ffocusing on the specific taasks for the su urvey program mmer.    In tthis chap pter we w will coveer: An overvieew of how to eexecute a surveey in  multiple laanguages Setting thee language within the script Tips for creeating multi‐lin ngual projects     Overviiew of Tran nslating Studies in D  Dimension ns  When a p project will be e run in multiiple languagees, the basic steps are:  • • • • Create the surrvey .mdd filee in a base lan C nguage.  U Use mrTransla ate to add traanslations to tthe metadataa file.  U Upload and ac ctivate the reevised .mdd fiile to the projject.  B Be sure that t he ErrorMesssage.mdd filee has the error messages trranslated for the languagees  y you will have  in your project.  Once you u have a metaadata file, you u can add thee translations through the product, mrTTranslate.   mrTranslate reads the e metadata fille and presen nts the text off your survey in a format ssimilar to a  heet.   Then yo ou can add ad dditional langguages as colu umns in mrTrranslate .  spreadsh       mation on usin ng mrTranslatte, see the Usser’s Guide in the DDL:   For deetailed inform mrTra anslate.chm:://mrtranslate__overview.htm m            227    Chapter 22  Creating Multi‐Lingual Projects    Survey Programming Fundamentals  Then save the metadata file and now it will contain the additional languages.  Note that when you re‐ open the metadata file in mrStudio, you will not see the additional languages within the text of the file,  but they are in the metadata file.  To verify additional languages are in the metadata using mrStudio:  • • Choose the Metadata Explorer  Open the Languages              Setting the language within the script  To use the multi‐lingual functionality within mrInterview, you need to set the IOM.Language.  You  could accomplish this in many ways.  Here are a few common methods:  • • Create a question in which the respondent chooses the language.  Have the language stored in a sample field and retrieve the information and set the language  for the respondent.  Ask a question to collect and set the language  When you do not know the preferred language of your respondent, a simple introductory question can  be asked to collect the language.  228      Survey Programming Fundamentals  Example          Chapter 22  Creating Multi‐Lingual Projects    Metadata(en‐US, Question, Label)  LanguageQ "Choose the language for this survey:"      categorical [1..1]      {          ENU "English",          DEU "German",          ESN "Spanish"      };    End Metadata    Routing(Web)    LanguageQ.Ask()    IOM.Language = LanguageQ.Categories.[LanguageQ].Name  End Routing    Note that in the example above, the names of the responses (ENU, DEU, ESN) must be the 3‐digit  Microsoft language codes.  If the script has the translations added, you will be able to see the languages changes within mrStudio  as you run the survey.    To find a full list of the language codes, see the DDL:  UserGuide.chm::/Intug‐ mrscriptmetadata_languages_3char.htm    Set language from a sample field variable  If you already know the preferred language and you are using sample management, a field can be set  in the sample table to hold the 3‐digit language code.  The following example assumes your sample  table has a field called SLanguage.  Example  Routing(Web)        IOM.Language = IOM.SampleRecord.Item["SLanguage"]    End Routing            229    Chapter 22  Creating Multi‐Lingual Projects    Survey Programming Fundamentals  Tips for creating multi­lingual projects  Creating the scripts for multi‐lingual studies does not need to be difficult as long as you follow a few  simple rules:  • • •   230  If the templates contain text that needs to be translated, use localized templates for each  language so that the proper text is shown.  Verify the ErrorMessage.mdd file has the error messages for the languages you will be using.  Always reference info items in the routing section for any text, such as custom error messages  or text inserts.   Text in the routing section is not seen by mrTranslate, only the metadata  section.        Survey Prrogramming Fundamentalls    Chaapter 23  Additional inform mation for Analysis  Chapte er 23  Ad dditional i  informatiion for An nalysis  This sectiion shows ho ow the Dimensions scriptin ng language iss not only for creating inteerviews, but aalso  for analysis purposes.  This section adds optionss to your inteerview script tthat will speeed the analysis  process b by adding com mmon statistiics and summ mary informattion, such as ttop box scorees and alternaate  text for aanalysis.   In tthis chap pter we w will coveer: Adding alternate text forr reporting purrposes Adding speecial statistics into the intervview  script Creating faactor scores fo or use with stattistics   Alterna ate Text fo or Analysis  Many orgganizations w will alter the teext of the queestions that w were asked in n a survey for reporting or  analysis p purposes.  Th he most comm mon method is to change ffrom question n formats to sstatements  (Examplee:  “What is yo our gender?” becomes “Reespondent Geender”).   Thee alternate teext is called an n  Analysis context.  You u can add thiss information in a few diffeerent ways.  TTwo common n ways are  mrTranslate and mrSttudio to view and add anallysis context.  Using mrTraanslate will allow individuaals  who are unfamiliar wiith Dimension ns scripting to o add the alteernate text, as mrTranslatee masks the  actual co ode with its in nterface.  Sincce this is a scrripting coursee, we will focu us on adding aanalysis conteext  with mrSStudio.  Adding A  Analysis Con ntext with m  mrStudio  • Open the View O w menu  ts  • Select Contex S sis  • Choose Analy C         231    Chapter 23  Additional information for Analysis    Survey Programming Fundamentals  You will now see a blank spot by all text in the metadata labeled “ANALYSIS:”.  You can place the  alternate text in double quotes as shown in the picture below:        Factors  If you wish to add statistical elements, such as a mean or standard deviation, to your categorical  questions, then you need to add a multiplier to each response choice.  Even if you do not add the  statistical elements, factors can also be helpful to end users of the data creating cross tabulations with  mrTables or mrStudio.  Name "Text" categorical  [min..max]  {ID1 "AltText1" factor(value),   IDn "AltTextn" factor(value) };  Text  factor  value      232  Description  Keyword to identify you wish to add a multiplier to the response for statistical purposes  Represents the numeric value you wish to assign to the response for statistics.        Survey Programming Fundamentals    Chapter 23  Additional information for Analysis    This example shows you how to specify values for each age range for statistics in use with other  Dimensions products, such as mrTables, Desktop Reporter, or mrStudio with tables scripting.      Example  Metadata(en‐US, Question, Label)    Age "To which of the following age categories do you belong?"          categorical [1..1]          {              Under18 "Under 18" factor(18),              _18to34 "18 to 34" factor(26),              _35to54 "35 to 54" factor(45),              _55plus "55 and over" factor(55),              Refused "Prefer not to Answer" REF        };  End Metadata        Creating Question Items for Analysis  You can also add analysis elements to the questions to speed the availability of top‐line and final  results.  We will discuss two different methods for adding elements for Analysis, ElementTypes and  Axis Expressions.    • • ElementTypes are not seen during interviewing only in analysis, such as using mrTables or  creating cross tabulations with mrStudio.  They are a single line of information, such as a  summary item or mean score.  Axis expressions are also not seen during interviewing, but are usually more than a single line  of analysis results.  An example would be adding a predetermined range of categories to a long  or double type question for analysis purposes.            233    Chapter 23  Additional information for Analysis    Survey Programming Fundamentals  ElementTypes  You use the optional elementtype keyword to create a special element in metadata for use in analysis.     Name "Text" type  {ID1 "AltText1,    IDn "AltTextn",  IDElement "AltTextElement" elementtype (typevalue)  };  Item  Name  Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   "Text"  Text associated with the item (considered the label in the object model).  Type  Identifies the question type (categorical, long, etc.)   ID1, IDn  Unique identifying name for the response.  This needs to be unique per  question, not metadata file.  Rules for the response names are the same as the  name of the question.  AltText1,  Optional text to show the respondent instead of the name of the question.  This  AltTextn  will apply when the name of the question is not the same as the text you wish to  show the respondent.  IDElement  Unique identifying name for the special element.  Rules for this name are the  same as the name of the question.  AltTextElement  Text to represent the special element  elementtype  Keyword that indicates you will be specifying using a special element  typevalue  Represents the keywords listed in the next table to state the type of special  element you need    Below is a table with a few common analysis elements, represented by type_value in the syntax  example above.  Text  AnalysisCategory  AnalysisMean  AnalysisStdDev  AnalysisStdErr    234  Description  An element that is used only for analysis. You can use this value for categories  that you do not want to appear in interviews.  An example would be creating a  TopBox or BottomBox score.  An analysis element that is used to show the mean value of a variable.  An analysis element that is used to show the standard deviation of a variable.  An analysis element that is used to show the standard error of a variable.      Survey Programming Fundamentals      Chapter 23  Additional information for Analysis    To find a full list of Analysis Elements, see the DDL:  DDL.chm::/mrscriptmetadata_categorical.htm    To use the types listed, most require additional properties.  Here is the previous example where the  mean value has been added to the age question.  Notice the additional parameters required for a  mean with categories.    Example  Metadata(en‐US, Question, Label)  Age "To which of the following age categories do you belong?"          Categorical [1..1]          {              Under18 "Under 18" factor(18),             _18to34 "18 to 34" factor(26),              _35to54 "35 to 54" factor(45),              _55plus "55 and over" factor(55),              Refused "Prefer not to Answer" REF,            Mean "Mean Score"  [                  CalculationType = "Mean",                  HasNoData = true,                  ExcludedFromSummaries = true                                                      ]          elementtype(AnalysisMean)        };  End Metadata    Another helpful element type is the AnalysisCategory.  This allows you to create additional elements in  questions that are not seen during the interview, only in analysis.  The following define list will provide  you with a Top and Bottom Box Score for each question using the list in the analysis.  Example  Metadata(en‐US, Question, Label)  Rating5Pt define          {  Top2 "Positive Scores" elementtype(AnalysisCategory) expression("@ * {VS, SS}"),              VS "Very Satisfied",              SS "Somewhat Satisfied" ,              Neutral ,              Bot2 "Negative Scores" elementtype(AnalysisCategory) expression("@ * {SDS, VDS}"),              SDS "Somewhat Dissatisfied" ,              VDS "Very Dissatisfied"          };  End Metadata      235    Chapter 23  Additional information for Analysis      Survey Programming Fundamentals  In the previous example the @ represents any question the define is used with.  If you wish  to use a combining element directly in a question without a define list, the expression  would be "qname * {VS, SS}"        Axis Expressions  Another way to speed tabulation processes would be to create analysis items called axis expressions.   These can create many different types of analysis items, a common one in interview scripts would be  categorical ranges on numeric questions.   The axis expressions are dynamically created statements attached to the metadata questions.  The  syntax is very similar to what you would do in a data management script.    Name "Text" type  {ID1 "AltText1,    IDn "AltTextn"}  axis ("axis_spec");  Item  Name  "Text"  Type  ID1, IDn  AltText1,  AltTextn  axis  axis_spec    Description  Unique identifier for the item within your questionnaire.  They must start with a  letter or underscore ( _ ) and contain only alpha‐numeric characters or the  symbols @, $, #, or _   Text associated with the item (considered the label in the object model).  Identifies the question type (categorical, long, etc.)   Unique identifying name for the response.  This needs to be unique per  question, not metadata file.  Rules for the response names are the same as the  name of the question.  Optional text to show the respondent instead of the name of the question.  This  will apply when the name of the question is not the same as the text you wish to  show the respondent.  Keyword to represent elements will be added that will only be seen in analysis  Represents many different syntax that creates elements to be seen in analysis        236        Survey Programming Fundamentals    Chapter 23  Additional information for Analysis    The following example will collect a long question type during the interview, but easily allow people  doing analysis to view the pre‐set ranges of answers and a mean value.  Example     Metadata(en‐US, Question, Label)    HouseHold "Including yourself, how many people currently live in your household?"      long [1 .. 20]      axis("{ _1 'One' expression('Household = 1'),            _2to3 '2‐3' expression('Household >=2 and Household <=3'),            _4to6 '4‐6' expression('Household >=4 and Household <=6'),            _7plus '7 and over' expression('Household >=7'),            mean 'Mean' mean(household)}");    End Metadata    Tips creating analysis elements  Adding analysis elements can prove beneficial for speeding the time for analysis setup.  A few things to  remember:  • • These items can be added after live data collection, so don’t worry if you don’t have all the  analysis information up front.  The metadata syntax check will only be looking for syntax mistakes, not if your logic actually  works.  Make sure to create test data and have someone check the analysis fields for accuracy.          Summary  This chapter has just introduced the analysis concepts and by no means has shown all the possibilities.   As your knowledge of Dimensions scripting grows, you will see how all parts of Dimensions scripting  (interviewing, data management and tabulation) are connected.  That knowledge will allow you to use  the power of Dimensions Scripting to its fullest potential and do some amazing projects.  You are now  on the verge of doing great things with this powerful language.  Remember to think out of the box and  try new ways to do things, as this language has so many facets and capabilities.          237    Chapter 23  Additional information for Analysis    Survey Programming Fundamentals  238