Usage

Form Structure

Each form is made up of any number of question groups, within each group there are any number of questions. Questions can accept free form text or present a list of options to the user. In some cases a particular answer may require additional information, this can be done using subquestions. Subquestions can be nested to any depth, i.e. a subquestion can present a set of answers, which in turn can present another subquestion with another set of answers and so on. The diagram below shows the structure of a survey:

  Survey Structure

Form Definition File

Currently a form definition file is used to define the contents of a form, in future it is envisaged that a web interface will be available to do it. To create a new form we define the content of the form using a YAML file. I decided to use YAML as it seems to be the defacto standard for Rails, its simple and has a nice hierarchical structure which suits the way forms are structured. All form definition files are assumed to be located in the /smerf directory.

The definitions within the file is space sensitive, be very careful to get this correct otherwise items will be grouped incorrectly. The structure must be as follows with items at the following levels:

smerfform
    groups
        questions
            answers

The name of the form definition file is used to identify the form. If you change the name of the file then a new DB record will be created with the new code and all links to any history will be lost as this will be treated as a brand new form. When the system loads the form file for the very first time a new record will be created with a code that is set to the name of the file.

To create a link to display a form you can use the Standard REST Path method used for the show action passing the name of the form definition file as a parameter, for example 

1

 link_to('Complete Test Smerf Form', smerf_form_url('testsmerf'))

Defining the Form

When setting up a new form the first thing we do is define some settings for the form as a whole. Currently the following items can be defined for the form:

name: Name of the form (mandatory)
welcome: Message displayed at the start of the form (optional)
thank_you: Message displayed at the end of the form (optional)
group_sort_order_field: Nominates which group field to use when sorting groups for display (mandatory)
groups: Defines the question groups within the form (mandatory)

Here is the definition for the test form included with the plugin:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

 
    --- 
    smerfform:   
      name: Test SMERF Form
      welcome: | 
        <b>Welcome:</b>
 
        Thank you for taking part in our Test survey we appreciate your
        input.
 
 
 
        <b>PRIVACY STATEMENT</b>
 
        We will keep all the information you provide private and not share
        it with anyone else....
 
 
      thank_you: | 
        <b>Thank you for your input.</b>
 
 
 
        Should you wish to discuss this survey please contact
 
        Joe Bloggs
 
        Tel. 12 345 678
 
        e-mail <a href="\&quot;mailto:jbloggs@xyz.com.au\&quot;">Joe's email</a>
 
 
 
        February 2007
 
      group_sort_order_field: code
 
      groups:
      ...

Defining Groups

Each form is divided up into groups of questions, you must have at least one group per form. Here are the fields that are currently available when defining a group:

code: This code must be unique for all groups within the form as it is used to identify each group (mandatory)
name: The name of the group, this is displayed as the group heading (mandatory)
description: Provide more detailed description/instructions for the group (optional)
questions: Defines all the questions contained within this group (mandatory)

Here is the definition for the Personal Details group of the test form:

1
2
3
4
5
6
7

personal_details:
      code: 1
      name: Personal Details Group
      description: | This is a brief description of the Personal Details Group
        here we ask you some personal details ...
      questions:
      ...

Survey Group

Defining Questions

A group can contain any number of questions, there must be at least one question per group. When defining a question you must specify the question type, the type determines the type of form field that will be created. There are currently four types that can be used, this will be expanded as needed. The current question types are:

multiplechoice: Allows the user to select all of the answers that apply from a list of possible choices, check boxes are used for this question type as multiple selections can be made
singlechoice: Allows the user to select one answer from a list of possible choices, radio buttons are used for the question type as only a single answer can be selected
textbox: Allows the user to enter a large amount of free text, the size of the text box can be specified
textfield: Allows the user to enter a small amount of free form text, the size of the text field can be specified
selectionbox: Allows the user to select one or more answers from a dropdown list of possible choices

Question types

The following fields can be used to define a question:

code: Unique code that will identify the question, the code must be unique within a form (mandatory)
type: Specifies the type of field that should be constructed on the form for this question, see above list for current types (mandatory)
question: The text of the question, this field is optional as subquestions do not have to have question text
textbox_size: Specifies the size of the text box to construct, rows x cols, defaults to 30x5 (optional)
textfield_size: Specified the size of the text field that should be constructed, specified in the number of visible characters, default to 30 (optional)
header: Specifies a separate heading for the question. The text will be displayed above the question allowing questions to be broken up into subsections (optional)
sort_order: Specifies the sort order for the question
help: Help text that will be displayed below the question
answers: Defines the answers to the question if the question type displays a list of possibilities to the user
validation: Specifies the validation methods (comma separated) that should be executed for this question, see Validation and Errors section for more details
selectionbox_multiplechoice: Specifies if the selection box should allow multiple choices

Below is an example question definition:

1
2
3
4
5
6
7
8
9

      questions:
        specify_your_age:
          code: g1q1
          type: singlechoice
          sort_order: 1
          question: | Specify your ages  
          help: | Select the <b>one</b> that apply 
          validation: validate_mandatory_question
          ...

Question example

Defining Answers

If the question presents a list of possible answers to the user then we can easily define these answers by using the following fields:

code: Code to uniquely identify the answer, code needs to be unique for each question (mandatory). The value specified here will be saved as the users response when the answer is selected.
answer: The text that will be displayed to the user (mandatory)
default: If set to Y then this answer will be selected by default (optional)
sort_order: The sort order for this answer (mandatory)
subquestions: Some answers may need additional information, another question can be defined to obtain this information. To define a subquestion the same fields that define a normal question is used (optional)

Here is an example answer definition:

1
2
3
4
5
6
7

      answers:
        1_20:
          code: 1
          answer: | 1-20
          sort_order: 1
          default: N
          ...

Defining Subquestions

Additional questions can be defined for an answer if more information is required if the user selects the answer. For example you may have an answer ‘Other’ that requires additional information from the user. A subquestion can be defined for the ‘Other’ answer that takes an additional input from the user. To define a subquestion you use the same fields as for a normal question (Refer to the Defining Question section above).

Below is an example subquestion definition:

1
2
3
4
5
6
7
8
9
10

      subquestions:
        other_industries:
            code: g1q3a4s1
            type: textbox
            sort_order: 1
            question: 
            help: | Please specify 
            textbox_size: 30x3
            validation: validate_sub_question
            ...

Subquestion example

Data Store

There are three tables used by SMERF:

smerf_forms: contains details about each form
smerf_forms_users: contains a record for each of the forms a user completes
smerf_responses: contains a record for each response given to each question on the form. This allows analysis of answers via SQL queries.

When a user selects to view a form the system checks the form definition file to see if any changes have been made since the last time the form was loaded, if it has the form definition file is processed and validated. A set of classes and objects are created that describes the form including SmerfFile, SmerfGroup, SmerfQuestion, SmerfAnswer, these are serialized to YAML format and stored in a single database field within the smerf_forms table. If no changes have been made to the definition file then the form is simply read from the smerf_forms table and unserialized from YAML with all classes and objects reconstructed.

The users responses to questions on a form are stored in the smerf_responses table which stores a separate record for each response to a question. If a question has multiple answers then multiple records will be created for the question. Responses for a question can be found by using the unique question code assigned within the form definition file. So for example if we had a question with code ‘g1q1′ and the user selects two answers which have been assigned code values 3 and 5 then two records will be created, i.e.

 g1q1, 3
 g1q1, 5 

Check your DB or the migration file to see the table and column definitions for each table.

Validation and Errors

All validations are specified as part of the question (or subquestion) definition using the ‘validation:’ field. The SMERF validation system is very flexible and allows any number of validation methods to be specified for a question by comma separating each method. 

1

validation: validate_mandatory_question, validate_years

Currently there are two validation methods provided with the plugin:

validate_mandatory_question: This method will ensure that the user has answered the question
validate_sub_question: Only applies to subquestions and makes sure that the user has selected the answer that relates to the subquestion, it will also ensure the subquestion has been answered if the answer that relates to the subquestion has been selected.

SMERF also allows you to define your own custom validation methods. During the installation process SMERF creates a helper module called smerf_helpers.rb in the /lib directory. You can add new validation methods into this module and access them by simply referencing them in the form definition file. For example we have question ‘How many years have you worked in the industry’ and we want to ensure that the answer provided is between 0-99 we can create a new validationmethod called ‘validate_years’.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

  # Example validation method for &quot;How many years have you worked in the industry&quot;
  # it uses a regex to make sure 0-99 years specified.
  #
  def validate_years(question, responses, form)
    # Validate entry and make sure years are numeric and between 0-99
    answer = smerf_get_question_answer(question, responses)    
    if (answer)
      # Expression will return nil if regex fail, also check charcters
      # after the match to determine if &gt; 2 numbers specified
      res = (&quot;#{answer}&quot; =~ /\d{1,2}/)      
      return &quot;Years must be between 0 and 99&quot; if (!res or $'.length() &gt; 0)      
    end
 
    return nil
  end

Note: There are some helper methods that you can use within these methods included in the smerf_system_helpers.rb module which you can find in the plugins lib directory.

Your question definition may then look like this:

1
2
3
4
5
6
7
8
9

    how_many_years:
      code: g2q3
      type: textfield
      sort_order: 3
      header: 
      question: | How many years have you worked in the industry
      textfield_size: 10
      validation: validate_mandatory_question, validate_years
      help:

When the form is validated your custom validation method will be called. When an error is detected, a summary of the errors are displayed at the top of the form, additionally an error message is displayed for each question that has an error. This makes it very easy for the user to see which question they need to fix.

Error example

Complete Example

Here is the complete form definition file for the test form included with the plugin:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208

    --- 
    smerfform:   
      name: Test SMERF Form
      welcome: | 
        <b>Welcome:</b>
 
        Thank you for taking part in our Test survey we appreciate your
        input.
 
 
 
        <b>PRIVACY STATEMENT</b>
 
        We will keep all the information you provide private and not share
        it with anyone else....
 
 
      thank_you: | 
        <b>Thank you for your input.</b>
 
 
 
        Should you wish to discuss this survey please contact
 
        Joe Bloggs
 
        Tel. 12 345 678
 
        e-mail <a href="\&quot;mailto:jbloggs@xyz.com.au\&quot;">Joe's email</a>
 
 
 
        February 2007
      group_sort_order_field: code
 
      groups:
        personal_details:
          code: 1
          name: Personal Details Group
          description: | This is a brief description of the Personal Details Group
            here we ask you some personal details ...
          questions:
            specify_your_age:
              code: g1q1
              type: singlechoice
              sort_order: 1
              question: | Specify your ages  
              help: | Select the <b>one</b> that apply 
              validation: validate_mandatory_question
              answers:
                1_20:
                  code: 1
                  answer: | 1-20
                  sort_order: 1
                  default: N
                21_40:
                  code: 2
                  answer: | 21_40
                  sort_order: 2
                  default: N
                &gt;40:
                  code: 3
                  answer: | &gt; 40
                  sort_order: 3
                  default: N
                  subquestions:
                    &gt;40:
                      code: g1q1a3s1
                      type: singlechoice
                      sort_order: 1
                      question: | Are you aged over 40
                      help: | Select the <b>one</b> that apply 
                      validation: validate_sub_question
                      answers:
                        41_50:
                          code: 1
                          answer: | 41-50
                          sort_order: 1
                          default: N
                        51_60:
                          code: 2
                          answer: | 51_60
                          sort_order: 2
                          default: N
                        &gt;61:
                          code: 3
                          answer: | &gt; 61
                          sort_order: 3
                          default: N
                          subquestions:
                            &gt;61:
                              code: g1q1a3s1a3s1
                              type: textfield
                              sort_order: 1
                              header: 
                              question: | If you are older than 61, please specify
                              textfield_size: 10
                              validation: validate_sub_question
 
            are_you_married:
              code: g1q2
              type: singlechoice
              sort_order: 2
              question: | Are you married  
              help: 
              answers:
                no:
                  code: 1
                  answer: | No
                  sort_order: 1
                  default: Y
                yes:
                  code: 2
                  answer: | Yes
                  sort_order: 2
                  default: N
 
            hobbies:
              code: g1q3
              type: multiplechoice
              sort_order: 3
              question: | What are your hobbies 
              help: | Mark <b>all</b> that apply      
              header: Another header that you can group questions under
              answers:
                chess:
                  code: 1
                  answer: | Chess
                  sort_order: 1
                  default: N
                woodwork:
                  code: 2
                  answer: | Wood work
                  sort_order: 2
                  default: N
                sleeping:
                  code: 3
                  answer: | Sleeping
                  sort_order: 3
                  default: N
                other:
                  code: 4
                  answer: | Other 
                  sort_order: 4
                  default: N
                  subquestions:
                    other_industries:
                        code: g1q3a4s1
                        type: textbox
                        sort_order: 1
                        question: 
                        help: | Please specify 
                        textbox_size: 30x3
                        validation: validate_sub_question
 
        employment_details:
          code: 2
          name: | Employment Details Group
          description: | Brief description of the employment details group  
          question_sort_order_field: sort_order
          questions:
            which_industry:
              code: g2q1
              type: multiplechoice
              sort_order: 1
              question: | Which industries have you worked in  
              help: | Mark <b>all</b> that apply    
              validation: validate_mandatory_question
              answers:
                it:
                  code: 1
                  answer: | Information Technology
                  sort_order: 1
                  default: N
                accounting:
                  code: 2
                  answer: | Accounting 
                  sort_order: 2
                  default: N
                finance:
                  code: 3
                  answer: | Finance 
                  sort_order: 3
                  default: N
                other:
                  code: 4
                  answer: | Other 
                  sort_order: 4
                  default: N
                  subquestions:
                    other_industries:
                        code: g2q1a4s1
                        type: textbox
                        sort_order: 1
                        question: 
                        help: | Please specify 
                        textbox_size: 30x3
                        validation: validate_sub_question
 
            how_many_years:
              code: g2q3
              type: textfield
              sort_order: 3
              header: 
              question: | How many years have you worked in the industry
              textfield_size: 10
              validation: validate_mandatory_question, validate_years
              help: