Adding Error Messages

Adding Error Messages

Error messages can be used to tell end-users that they have not given a response to a specific interaction and need to do so before moving on to the next page.

Error messages are useful if you want to ensure that end-users interact with the page in a certain way. Examples of when you might want to do this include:

• You need end-users to respond to a specific interaction(s)
• You need to make sure that an end-user’s login details have not already been registered
• You need to check if an e-mail address that an end-user enters is valid
• You need to check if a mobile number that an end-user enters is valid
• You want end-users to confirm their response by entering it twice
• You need to check that an end-user has entered the correct combination of letters and/or numbers given to them previously (e.g. a participant number)
• You want end-users to enter a specific response (e.g. a study code)

NB: An end-user cannot move to the next page in the intervention until the specified interactions have been completed correctly.

Adding Error Messages to Intervention Pages

Error messages are added to pages using a text box that has been set as an error type. Although the error message is always visible on the page in the authoring tool, it will only be shown to end-users if the error it refers to has occurred (e.g. if they have not entered the required information).

We recommend writing error messages in bold text or in a different colour to the rest of the text on the page so that it will be easier for end-users to see.

Naming your error message

Each error message needs to be given a name that is unique to the page that it is on so that it can be used in the logic.

Important: You cannot give an error message the unique name error as error is a key command that is used by the logic. However, as long as it is prefixed with another word e.g. ageerror then this is fine.

The Error Message Logic

Error messages require logic but unlike other commands in LifeGuide, the logic needs to be written on the error message view of the page that you want the error message to show on, not in the intervention file.

Each intervention page has a page creator view for creating the page and an error messages view to write the error message. This is located below the insert panel (Figure 1)

Figure 1 The Error Messages tab

Once you have added an error message text box to the page you can click on the error messages view to add your logic.

Tip: You can use comments in the Error Message view. Comments are notes to yourself which will be ignored by the Authoring Tool. To make a comment, simply insert the # symbol at the beginning of new line, e.g. #error message for age. You can place a # at the beginning of any error message which you do not want to use until later. N.B. Comments in the intervention.lgil file will appear green, but comments in the Error Message view will not change colour.

Below is a list of example error messages that can be used with a breakdown of what they mean. Examples can also be found in the tutorial folder on the LifeGuide Community website.

Example 1: Error messages for unanswered single/multiple choice and text entry interactions

This example uses the isempty command to check that an end-user gives a response to a specified interaction. If a specified interaction is left empty, an error message will appear to ask end-users to respond before they move onto the next page.

The example given below is to ensure end-users enter a response to a single choice interaction, but the isempty logic command can be used to provide an error message for single/multiple choice and text entry interactions. The isempty command cannot be used for numeric interactions – see example 2 for how to write error messages for numeric interactions that end-users have not given a response to.

Show generror if (isempty (gender))

In this example, generror is the name given to the error message; gender is the name given to the interaction that end-users are required to fill in before they move onto the next page; isempty is a logic command that checks if the interaction has been filled in or not. So if the interaction uniquely named gender is empty, the error message generror will be shown to end-users.

Please note: Unlike logic commands written in the intervention.lgil file, error message logic does not require the page name to be included with the interaction name, e.g. use gender rather than page1.gender.

Example 1.1: Error messages for unanswered single-choice drop-down interactions

This example will check that an end-user gives a response to a specified single-choice interaction which is displayed as a drop-down.

Important: When creating drop-down single-choice interactions, please make sure that the very first response in the drop-down is a response that you do not want end-users to select, e.g. "Please select an option from the list below".

show err1 if (interaction1 = "default")

In this example, default is the unique response name for the very first response in the drop-down which should be a response that end-users will not select.

The error message err1 will show if a response from the drop-down is not chosen.

=Example 1.2: Error messages when specific responses are given to single/multiple choice interactions that then need another response to another question

Example 2: Error messages for unanswered numeric interactions

This example will check that an end-user gives a response to a specified numeric interaction.

Show ageerror if (isempty(age))

In this example, ageerror is the name given to the error message; age is the name given to the interaction that end-users are required to fill in before they move onto the next page. If an end-user does not select an age (and so the default value of 0 remains), or selects an age under 18 (in this example, we want end-users to be over the age of 18), an error message will appear.

Example 3: Error messages for more than one unanswered interaction

The isempty command can be used with the or command when responses are needed for more than one interaction.

This error message can be used with the messages in example 1 so that end-users know exactly which interaction they have not given a response to.

Show message1 if (or (isempty (interaction1), isempty (interaction2), isempty (interaction3)))

In this example, the end-user will see the error message called message1 if they have not entered anything for interaction1, 2 or 3.

Example 4: Checking email addresses are valid

The checkemailvalidity command can be used with the not command to check that the end-user has entered a valid e-mail address into a text entry interaction (i.e. the email address includes an @ symbol).

Show message2 if (not (checkemailvalidity (interaction2)))

In this example, the error message called message2 will be shown to end-users if the interaction asking for an e-mail address (interaction2) does not include an @ symbol.

Example 4.1: Checking mobile numbers are valid

The checkphonenumbervalidity command can be used with the not command to check that the end-user has entered a valid mobile phone number into a text entry interaction (i.e. the number starts with 07 and has 11 digits in total).

Show message2 if (not (checkphonevalidity (interaction2)))

In this example, the error message called message2 will be shown to end-users if the interaction asking for a mobile phone number (interaction2) does not start with 07 and/or does not contain 11 digits.

Example 5: Checking that registration details are unique

The checkuserexists command can be used to check if the e-mail address or username that an end-user tries to register with is unique and hasn’t been used by another user.

Show message3 if (checkuserexists (interaction3)

In this example, the error message called message3 will be shown to end-users if the information they enter into interaction3 has already been used for another end-user’s user account.

Example 6: Asking end-users to confirm their response by entering it twice

This example uses the not command to check that end-users have entered exactly the same response into two different interactions.

Show message4 if (not (interaction1 = interaction2))

In this example, the error message called message4 will be shown to end-users if the information they enter into interaction2 is not the same as the information they enter into interaction1. This type of error message is useful when you are asking end-users to confirm details such as their email address or password when creating a user account.

Example 7: Asking end-users to enter a response which consists of a certain combination of letters and/or numbers

The patternmatch command can be used when you want end-users to enter a combination of characters into a text entry box.

show message5 if (not( patternmatch("study[0-9][0-9][id][0-9][0-9]", interaction1)))

In this example, the error message called message5 will be shown to end-users if they do not enter a response into interaction1 which fits in with the pattern specified.

The response needed in this example is studyxxidxx, where x is any number between 0 and 9. You can also use [a-z] which means that end-users can enter any letter from a-z.

This type of error message is useful for example if you have assigned each participant in your study a different code which they will need to enter in order to take part.

Please note: The patternmatch command can only be used with text entry interactions.

An example of how patternmatch can be used to allow several numbers to be entered into a text entry interaction is shown below:

show err1 if (and(not(patternmatch ("[0-9][0-9][0-9][0-9]", amount)),not(patternmatch ("[0-9][0-9][0-9]", amount)),not(patternmatch ("[0-9][0-9]", amount)),not(patternmatch ("[0-9]", amount)) ))

The above logic will allow up to 4 numbers to be entered into the text entry box called amount. If anything other than numeric characters are entered, or if more than 4 numbers are entered, the error message called err1 will be shown.

See the [Logic Dictionary] for more information about patternmatch

Example 8: Asking end-users to enter a specific response

This example uses the not command to check that end-users have entered a specific response into an interaction.

Show message6 if (not(interaction1 = “study101”))

In this example, the error message called message6 will be shown to end-users if they do not enter ‘study101’ into the text entry box called interaction1. This type of error message is useful for example if you only want people who you have given the code to, to have access your study.

Example 9: Error messages for when an end-user gives a specific response to one interaction and are then required to give a response to another interaction

This is an example of an error message you would use if you asked end-users a single-choice question (with the responses yes or no), that then required them to give another response question if they answered yes.

show message7 if (and(interaction1 = “yes”, interaction2 < 1))

In this example, the error message called message7 will be shown to end-users if they give the response yes to interaction1 and then do not give a response to interaction2 (which is a numeric interaction and an answer less than 0 would be a non-response). If end-users give the response no to interaction1, this error message would not show because the and command means that both conditions have to be met in order for the error message to show.

Here is another example involving a numeric interaction and a single-choice interaction:

show message8 if (and(interaction1 = 1, isempty(interaction2)))

In this example, the error message called message8 will be shown to end-users if they give the response 1 to interaction1 and do not give a response to interaction2, i.e. interaction2 is left empty. If end-users give the response 2 to interaction1, this error message would not show because the and command means that both conditions have to be met in order for the error message to show.

Example 10: Error messages for use with a calendar - selecting a date within a specific time period

In this example, the error message called message9 will be shown to end-users if they pick a date on the calendar which is more than 14 days in the future.

show message9 if (comparetimes(currenttime(), interaction1, "days") > 14)

In this example, the current time is compared with the time in 14 days time. If a date which is more than 14 days in the future is picked on the calendar called interaction1, message9 will be shown.

You can replace "days" with "weeks", "months" and "years".

Example 11: Asking end-users to enter a response that consists of a certain number of characters

The stringlength command can be used if you want to check that end-users have entered a certain number of characters into a text entry interaction:

show message10 if (stringlength (interaction1) < 5)

In this example, the error message called message10 will be shown to end-users if they enter less than 5 characters into the text entry interaction called interaction1.

This type of error message is useful if you want end-users to create usernames which are a specific number of characters.

Please note: The stringlength command cannot be used with text entry interactions set as passwords.