Dynamic questionnaires

The dynamic questionnaire feature can be used to generate a bespoke questionnaire from a configuration table populated in ginstr web.

Each app which is enabled to use the dynamic questionnaire feature will have the following three questionnaires tables belonging to it in the list of app tables:

• questionnaires
• questionnaire configuration
• questionnaire results

Adding a new record to the questionnaires table

questionnaires table

The questionnaires table is used to store the unique names of individual questionnaires.

This table must have at least one record before the configuration table can be used.

When logged in to ginstr web, open a new portlet and scroll to the app for which you want to create a questionnaire in the list of available app tables and select the corresponding questionnaires table. To add a new record to the questionnaires table, click on the

add record

button at the top of the portlet and enter a unique, descriptive name for the new questionnaire in the name column.

questionnaire configuration table

Each row in the questionnaire configuration table represents a separate question in the questionnaire, with an array of options available for customisation.

The questionnaire configuration table consists of the following columns:

• questionnaire name
• sequence
• locale
• label value
• hint
• required
• error message
• widget
• value list
• comment

questionnaire name

This column is used to define which questionnaire each question belongs to.

The questionnaires table is used to store the unique names of any number of individual questionnaires.

Double-clicking in the questionnaire name field will display a drop down list of the individual questionnaires listed in the questionnaires table.

sequence

This column is used to define the order in which the questions are displayed in a questionnaire.

The first item/question in a questionnaire should be assigned the number 1, the second should be assigned the number 2 and so on.

It is also possible to use decimal numbers (i.e. 2.5, 2.6) between whole numbers. This can be useful when adding new questions to a pre-existing configuration table with many entries, avoiding the need to re-number the entire sequence.

locale

This column is used to define for which language selection each question will display. The following display languages are currently supported:

• en - shown to all users with English language selected in ginstr launcher preferences
• de - shown to all users with German language selected in ginstr launcher preferences
• es - shown to all users with Spanish language selected in ginstr launcher preferences
• fr - shown to all users with French language selected in ginstr launcher preferences
• ae - shown to all users with Arabic language selected in ginstr launcher preferences

It is possible to provide translations for questions in several/all of the above languages. For this purpose, each translation of the same question would be assigned the same sequence number.

label value

This column is used to define the label for each item in a questionnaire.

Refer to the widgets table for more information on how the label is displayed for each widget type.

hint

This column is used to define an optional hint for each item in a questionnaire.

Refer to the widgets table for more information on how the hint is displayed for each widget type.

required

This column is used to select whether a response is required (mandatory) for each item in a questionnaire.

If an item's required status is set to true (), an asterix (*) is automatically added to the end of the label value to indicate the question is mandatory. If a user attempts to submit the questionnaire without answering one or more required questions, they will be shown an error message at the bottom of the screen (please fill all fields which have a '*')

Note:

group, status & date widgets must have required status set to false (). For all other widgets, setting the required status to true () is optional.

error message

This column is used to define the error message displayed (for each item with required status set to true / ) when a user attempts to submit the questionnaire without providing a response.

For all items with required status set to false (), this field should be left empty

widget

This column is used to define the type of widget which is displayed for each item in a questionnaire.

The table below provides an overview of all types of widget available.

The desired widget type must be selected from the drop down list for all items in a questionnaire.

widget	Description
group	Displays text entered in label value field above subsequent questions, allowing you to group several questions into different sections. Text which is entered in the hint field is not displayed.
text single line	Displays single line text input box below text entered in label value field. Input box does not allow line breaks. Text which is entered in the hint field will be displayed in the input box until some text is entered by the user. Response is saved to the text value column of questionnaire results table.
text multi line	Displays multiple line text input box below text entered in label value field. Input box allows line breaks. Text which is entered in the hint field will be displayed in the input box until some text is entered by the user. Response is saved to the text value column of questionnaire results table.
number decimal	Displays single line numerical input box below text entered in label value field. Input box does not allow text entry. Text which is entered in the hint field will be displayed in the input box until some number is entered by the user. Response is saved to the number value column of questionnaire results table.
number integer	Displays single line numerical input box below text entered in label value field. Input box does not allow text entry or decimal values. Text which is entered in the hint field will be displayed in the input box until some number is entered by the user. Response is saved to the number value column of questionnaire results table.
status	Displays a check-box next to text entered in label value field. required status must be set to false. Text which is entered in the hint field is not displayed. Response is saved to the status value column of questionnaire results table.
date	Displays a date selection input below text entered in label value' field. required status must be set to false. Text which is entered in the hint field is not displayed. Response is saved to the date value column of questionnaire results table.
radio group	Displays a list of RadioButtons below text entered in the label value field. Requires list of values (one for each RadioButton required) defined in value list field - items in list must be on separate lines. Text which is entered in the hint field is not displayed. Response is saved to the text value column of questionnaire results table.
picture	Displays a take photo button below text entered in label value field, along with a counter starting at #0. When the take photo button is pressed, the camera app is opened on the device to capture a photo. Once a photo is captured, the counter value increases to indicate how many photos have been captured. Text which is entered in the hint field is not displayed. Photo is saved to the picture value column of questionnaire results table.
drop down list text	Displays a drop down input box below text entered in label value field. Requires list of values defined in the value list field - items in list must be on separate lines. Text which is entered in the hint field is displayed at the top of the drop down list (visible when drop down is collapsed). Response is saved to the text value column of questionnaire results table.
drop down list numeric	Displays a drop down input box below text entered in label value field. Requires list of numeric values defined in the value list field - items in list must be on separate lines. Text which is entered in the hint field is displayed at the top of the drop down list (visible when drop down is collapsed). Response is saved to the number value column of questionnaire results table.
signature	Displays a button below text entered in label value field. When the signature button is pressed, the signature dialog is opened. Once a signature is drawn and the save button is clicked, the signature dialog will be closed. Text which is entered in the hint field is not displayed. Signature is saved to the picture value column of questionnaire results table.

value list

This column is used to define a list of values for radio group buttons and drop down lists

Items in the value list field must be on separate lines.

comment

This field is only visible when viewing/editing the configuration table in ginstr web and is used to store an optional comment for each item in a questionnaire.

questionnaire results table

The questionnaire results table is used to display the responses to all questionnaires.

The questionnaire results table consists of the following columns:

• user name
• serial
• timestamp
• gps
• gps address
• questionnaire name
• label value
• text value
• number value
• date value
• status value
• picture value

user name

This column is used to display the ginstr user name used to submit the questionnaire, making it easy to sort or filter the questionnaire results table by user.

serial

This column is used to display the serial number of the device used to submit the questionnaire, making it easy to sort or filter the questionnaire results table by specific device.

timestamp

This column is used to display the date & time when the questionnaire was submitted, making it easy to sort or filter the questionnaire results table by date range, specific date, time range or specific timestamp.

gps

This column is used to display the GPS coordinates of the device when the questionnaire was submitted, making it easy to sort or filter the questionnaire results table by location. You can filter the table by GPS location by defining a rectangular area of the map to include in the filter - this requires north, west, south & east coordinates to be entered in the corresponding gps filter fields.

gps address

This column is used to display an address based on the GPS coordinates of the device when the questionnaire was submitted, making it easy to sort or filter the questionnaire results table by address. You can filter the table by gps address by entering a text string (such as a street name) in to the corresponding filter field.

questionnaire name

This column is used to display which questionnaire each response belongs to, making it easy to sort or filter the questionnaire results table by each individual questionnaire.

label value

This column is used to display the label value for each response, making it easy to sort or filter the questionnaire results table by each individual question.

text value

This column is used to store the response entered by users for all questionnaire items using text single line, text multi line, radio group and drop down list text widget types.

number value

This column is used to store the response entered by users for all questionnaire items using number decimal, number integer and drop down list numeric widget types.

date value

This column is used to store the response entered by users for all questionnaire items using date widget types, making it easy to sort or filter the questionnaire results table by date range or specific date.

status value

This column is used to store the response entered by users for all questionnaire items using status widget types, making it easy to sort or filter the questionnaire results table by status.

picture value

This column is used to store the photos captured by users (with picture widget type). The questionnaire results table can be filtered by filename of pictures.

Worked example

In this section you will be shown how to create a short example questionnaire configuration table in ginstr web using all of the aforementioned features.

The purpose of the example questionnaire is to collect customer feedback and will consist of two sections, Personal Details and Your feedback.

Getting started

The first step to creating a questionnaire is to define a unique name for the new questionnaire in the questionnaires table (see here for instructions).

Next, open a new portlet and select the corresponding questionnaire configuration table for the app which you want to create a questionnaire for from the list of available app tables.

Adding a new record to the questionnaire configuration table

Adding a header (group widget) to the questionnaire configuration table

Each item in a questionnaire is represented by a different row in the questionnaire configuration table.

To add a new row to the table, click on the

add record

button at the top of the portlet.

A new row will be added to the table and a drop down list of available questionnaire names will be displayed in the questionnaire name field.

For this example we will be using the questionnaire name "My Custom Questionnaire" which was added to the questionnaires table here.

Adding a header

Let us begin by adding a group widget to denote the start of the first section of the questionnaire.

As this will be the first item in the questionnaire, we will enter the number 1 in the sequence field.

For this example we will only be adding English translations, so for all items en should be selected from the locale drop down list.

For group widgets, the label value field is used to define the text which should be displayed as a header. For this example, the first section of the questionnaire will be for collecting personal details of the user and so we will enter "Personal Details" in the label value field.

For group widgets, the hint, required, error message and value list fields are not used.

The final step for adding the group header is to select group from the widget drop down list.

Adding questions

Adding a single line text entry field (text single line widget) to the questionnaire configuration table

Adding a multi line text entry field (text multi line widget) to the questionnaire configuration table

To add the first question to the Personal Details section, click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 2 in the sequence field and select en from the locale field drop down list.

The first item in this example questionnaire will be a single line text entry box with label "Please enter your full name", so enter this text in to the label value field.

The hint field can be used optionally to show the specified text inside the entry box until some text is entered by the user. For this example we will enter the hint "Please enter your full name here".

We will set the required status of this question to true by double-clicking the in the required column so that it changes to a blue tick

The question will now have an asterix (*) added to the end of the label value to indicate that a response is required. If a user attempts to save the questionnaire without answering this question, they will be shown a generic error message at the bottom of the screen (please fill all fields which have a '*'). We can also define a specific error message to be displayed in the input field following this generic message. For this example we will enter "Your name is required" in the error message field.

The final step required to add this question to the questionnaire is to select text single line from the widget drop down list.

For address entry, we will use a text multi line input box.

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 3 in the sequence field and select en from the locale field drop down list.

In the label value field we will enter "Please enter your address", and in the hint "Please enter your address here including postcode" which will be displayed within the input box until some text is entered by the user.

Again we will set the required status of this question to true () and add a suitable error message ("Your address is required").

Finally, text multi line should be selected from the widget drop down list.

As the next question ("How many times have you visited us before?") requires a whole-number (integer) numerical response, we will use a number integer input box.

Adding a number entry field (number widget) to the questionnaire configuration table

Note that if the question requires a decimal value response (i.e. 2.7 or 3.14), then the number decimal widget must be used instead.

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 4 in the sequence field and select en from the locale field drop down list.

In the label value field we will enter the question "How many times have you visited us before?"

For this item we will omit the hint and leave the required status set to false ()

As the question is not required, the error message field should be left empty.

Finally, number integer should be selected from the widget drop down list.

For the next question ("Are you a loyalty card member?") we can use a status check-box.

Adding a status check-box (status widget) to the questionnaire configuration table

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 5 in the sequence field and select en from the locale field drop down list.

In the label value field we will enter the text "Tick here if you are a loyalty card member"

For all status items, the hint is not required and the required status must be set to false (). Logically, status items cannot be required as the response is saved as false () by default so there is no way to determine whether the checkbox has been missed accidentally or left empty intentionally. Subsequently, setting required to true () in a row with status widget selected will result in an error. We can use the comment column to store a note ("NOT required!!") as a reminder of this fact.

As the required status is set to false (), the error message field should be left empty.

Finally, number integer should be selected from the widget drop down list.

Adding a new section header (group widget) to the questionnaire configuration table

Adding a new section

This brings us to the end of the "Personal Details" section of the questionnaire so we will now add another group header to denote the start of the second section.

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 6 in the sequence field and select en from the locale field drop down list.

For group widgets, the label value field is used to define the text which should be displayed as a header. For this example, the second section of the questionnaire will be for collecting customer feedback so we will enter "Your feedback" in the label value field.

For group widgets, the hint, required, error message and value list fields are not used.

The first item in the new section will be labelled "Date of your visit" and use the widget date.

Adding a date entry field (date widget) to the questionnaire configuration table

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 7 in the sequence field and select en from the locale field drop down list.

In the label value field we will enter the text "Date of your visit"

For date widgets, the hint, required, error message and value list fields are not used. As with status widget, setting required to true () in a row with date widget selected will result in an error. We can use the comment column to store a note ("NOT required!!") as a reminder of this fact.

Finally, date should be selected from the widget drop down list.

For the next question we will provide a list of options for the user to select from to rate their customer experience. For this we will use a radio group widget.

Adding a radio group selection (radio group widget) to the questionnaire configuration table

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 8 in the sequence field and select en from the locale field drop down list.

In the label value field we will enter the text "How would you rate your experience on this date?"

For radio group widgets, the hint is not required so this field should be left empty.

We will set the required status to true () by double-clicking in the required field and add a suitable error message ("Please rate your experience") to the error message field.

radio group should be selected from the widget drop down list and a list of values added to the value list field. For this example we will add the following choices, each on a separate line (by pressing Enter after entering each value)

Excellent

Very good

Good

Fair

Poor

The next item allows the user to submit a photo captured on their device camera using the picture widget.

Adding a photo capture (picture widget) to the questionnaire configuration table

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 9 in the sequence field and select en from the locale field drop down list.

In the label value field we will enter the text "If you were unhappy with your service, please take a photo of your receipt"

For picture widgets, the hint is not required so this field should be left empty. As this response is optional, we will leave the required status set to false () and the error message field empty.

Finally, picture should be selected from the widget drop down list.

For the next item, the user will select an item from a drop down list containing several branch locations (drop down list text widget). A drop down selection is useful for offering a long list of possible options as the options remain hidden until the drop down is activated.

Adding a text drop down selection (drop down list text widget) to the questionnaire configuration table

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 10 in the sequence field and select en from the locale field drop down list.

In the label value field we will enter the text "Please select which branch you visited on this occasion"

In the hint field we will enter the text "Select branch" which will be displayed in the drop down box when the list is collapsed.

We will set the required status to true () by double-clicking in the required field and add a suitable error message ("Please select which branch you visited on this occasion") to the error message field.

drop down list text should be selected from the widget drop down list and a list of values added to the value list field. For this example we will add the following choices, each on a separate line (by pressing Enter after entering each value)

High Street

Park Road

Green Lane

For the next item, the user will select an item from a drop down list containing numbers (drop down list numeric widget) to rate the staff out of 10. drop down list numeric widget is preferred here instead of drop down list text as the responses will be saved to the number value column of questionnaire results table and can therefore be used for later analysis, for example calculating average ratings.

Adding a numeric drop down selection (drop down list numeric widget) to the questionnaire configuration table

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 11 in the sequence field and select en from the locale field drop down list.

In the label value field we will enter the text "Please rate (out of 10) how helpful the staff were"

In the hint field we will enter the text "10 = most helpful" which will be displayed in the drop down box when the list is collapsed.

We will set the required status to true () by double-clicking in the required field and add a suitable error message ("Please rate how helpful the staff were on this occasion") to the error message field.

drop down list numeric should be selected from the widget drop down list and a list of values added to the value list field. For this example we will add the numbers 1 to 10, each on a separate line (by pressing Enter after entering each value).

The final item in the questionnaire is a multi line text input field (text multi line widget) for the user to enter their comments.

Completed example questionnaire configuration table

Click on the

add record

button at the top of the portlet again to add a new row to the table.

In the questionnaire name drop down list, select "My Custom Questionnaire", enter the number 12 in the sequence field and select en from the locale field drop down list.

In the label value field we will enter the text "Your comments" which will appear above the text input box.

In the hint field we will enter the text "Please enter your comments here" which will be displayed within the input box until some text is entered by the user.

We will leave this final item optional, so the required status remains set to false () and the error message field left empty.

Finally, text multi line should be selected from the widget drop down list.

Filtering results

Because all responses to all questionnaires belonging to a given app are saved in to the same questionnaire results table (with each response saved in a separate row), it is recommended that you take advantage of the powerful filter settings in order to easily manage questionnaire results.

The filter settings can be accessed using the icon in the top right-hand corner of the portlet. Different filter options can be combined as necessary, giving you full control over which records are shown in the questionnaire results table at any one time.

When you have finished defining the desired filters, click the

apply

button at the top right corner of the filter settings window to filter the questionnaire results table accordingly.

Note:

Filter settings applied to the questionnaire results table are retained between sessions on ginstr web.

To remove filter options applied previously, click the

clear filters

button at the top of the filter settings window to clear all applied filter options.

There is also a

clear

button at the top right of each section to remove all filter settings related to that section only.

user name

Filter options for questionnaire results table

contact name

entering a text string in this field will filter the questionnaire results table to only show questionnaire responses submitted by a user name containing the specified text string in the contact name field.

e-mail

entering a text string in this field will filter the questionnaire results table to only show questionnaire responses submitted by a user name containing the specified text string in the e-mail address field.

serial

min. value

entering a number string in this field will filter the questionnaire results table to only show questionnaire responses submitted by a device serial number greater than or equal to the number specified.

max. value

entering a number string in this field will filter the questionnaire results table to only show questionnaire responses submitted by a device serial number less than or equal to the number specified.

To show questionnaire responses from a specific device serial number only, enter the specific serial number in both fields.

timestamp

The two date/time calendars in this section can be used to define a custom date/time range.

By entering the earlier date/time in the left date/time calendar and the later date/time in the right date/time calendar, the questionnaire results table will be filtered to only show questionnaire responses with a timestamp value between the two date/times specified.

There are also shortcut options below the calendars which set the calendars to pre-defined date/time ranges.

show latest entry only per

• serial - hides all but the most recent response for table with multiple records with the same device serial number
• gps address - hides all but the most recent response for table with multiple records with the same gps address
• text value - hides all but the most recent response for table with multiple records with the same text value
• number value - hides all but the most recent response for table with multiple records with the same number value
• status value - hides all but the most recent response for table with multiple records with the same status value

gps

corner 1 - defines upper left corner of GPS filter area

north - defines Northern latitude

west - defines Western longitude

corner 2 - defines lower right corner of GPS filter area

south - defines Southern latitude

east - defines Eastern longitude

With the gps filter settings applied, only results submitted with GPS coordinates within the GPS filter area defined between NW corner 1 and SE corner 2 will be displayed

gps address

text string

entering a text string (such as a street name) in this field will filter the questionnaire results table to only show questionnaire responses submitted with a gps address containing the specified text string.

questionnaire name

text string

entering a text string in this field will filter the questionnaire results table to only show questionnaire responses submitted with a questionnaire name containing the specified text string.

label value

text string

entering a text string in this field will filter the questionnaire results table to only show questionnaire responses submitted for label values containing the specified text string.

text value

text string

entering a text string in this field will filter the questionnaire results table to only show questionnaire responses submitted with a text value containing the specified text string.

number value

min. value

entering a number value in this field will filter the questionnaire results table to only show questionnaire responses submitted with a number value greater than or equal to the number specified.

max. value

entering a number value in this field will filter the questionnaire results table to only show questionnaire responses submitted with a number value less than or equal to the number specified.

To show questionnaire responses with a specific number value only, enter the specific number value in both fields.

date value

The two calendars in this section can be used to define a custom date range.

By entering the earlier date in the left calendar and the later date in the right calendar, the questionnaire results table will be filtered to only show questionnaire responses with a date value between the two specified dates.

There are also shortcut options below the calendars which set the calendars to pre-defined date ranges.

status value

set - filters the questionnaire results table to only show questionnaire responses with 'checked' status value (true )

not set - filters the questionnaire results table to only show questionnaire responses with 'un-checked' status value (false )

any - does not filter the table by status value (default)

picture value

filename

entering a text string in this field will filter the questionnaire results table to only show questionnaire responses submitted with a picture value containing the specified text string in the filename.