Logic Dictionary: Difference between revisions
| Line 358: | Line 358: | ||
In your logic, you will first need to create a new variable (e.g. | In your logic, you will first need to create a new variable (e.g. "username") which will tell the intervention which user times need to be compared for: | ||
<code>set</code> username <code>to</code> login.name | <code>set</code> username <code>to</code> login.name | ||
| Line 370: | Line 370: | ||
'''1.''' You first need to show the page users see before they are directed to particular sessions (e.g. | '''1.''' You first need to show the page users see before they are directed to particular sessions (e.g. "mainpage"): | ||
<code>show</code> mainpage | <code>show</code> mainpage | ||
| Line 387: | Line 387: | ||
<code>after | <code>after mainpage if ( comparetimes ( loadvalue ( username, "session3time" ), currenttime ( ), "seconds" ) <= 120 ) goto waitpage</code> | ||
This line of logic tells the intervention that the user cannot continue to session 4 because it has been less than two minutes since they completed session 3. Users are directed to a “waitpage” instead. | This line of logic tells the intervention that the user cannot continue to session 4 because it has been less than two minutes since they completed session 3. Users are directed to a “waitpage” instead. | ||
Repeat this process for the various sessions or pages contained within your intervention, for which you want to control access. The variables <code> | Repeat this process for the various sessions or pages contained within your intervention, for which you want to control access. The variables <code>"session3time"</code> and <code>"session4time"</code> are created in step 3. | ||
Revision as of 11:09, 5 April 2011
This page includes a basic break down of all the different logic commands available in the authoring tool along with basic examples to illustrate.
Key Commands (text in red) and Commands (text in pink) should be written as they appear in the examples.
Key commands (red)
after
The after key command is used after a page to perform functions that relate to that page.
The after key command is an important command to learn. It is likely that you will use this command quite regularly in your intervention logic. The most common way of using the after key command is with the if and goto key commands in the following formula:
show page1
after page1 if (any_commands_you_want_to_relate_to_this_page) goto page2
Example
after page1 if (page1.interaction1 = "yes") goto page2
In this example the end-user will be directed to page2 if they have answered 'yes' to 'interaction1' on page1.
As will be seen throughout this dictionary any command can be used with the after key command.
begin
The begin key command is always used with the end key command
If your intervention has separate sessions or groups (e.g. different weekly sessions in your behavioural intervention, or a different set of pages for different user groups) then splitting your pages into sections can make it easier for you to organise parts of your intervention and find sections easily.
Things to remember when splitting you intervention into sections:
- If you begin a section, you should always end the section.
- All the logic related to the section must be between begin sectionname and end
- The name of the section should not be the same as any unique name that has been given to an object or page in your intervention.
- As you can only ever end the section that you are currently in you do not need to write the section name after end.
Example 1
begin session1
show page1
show page2
end
This will begin session1, show page1 and page2, and will end session1. All the pages related to session1 (page1 and page2) are between begin session1 and end.
Example 2 – Beginning and ending a section within another section
begin stress
begin causes
show page1
show page2
end
begin relieve
show page3
show page4
end
end
This will begin the section stress. The section causes will then begin and page1 and page2 in the section causes will be shown. he first end will end the section causes. The section relieve will then begin and page3 and page4 will be shown. The next end will end the ection relieve. The final end will end the section stress.
end
See begin
for
The for key command is used with the save and graph key commands.
goto
The goto key command always follows the after key command. See above.
graph
The graph key command is used when you have used the graph interaction. It is used to plot the information given by end-users to the graph.
This key command always follows the same formula and requires users to set up a user account.
graph value to "data variable determined on the graph interaction" for unique_identifier_for_the_end-user_e.g._a_username
Another line of logic is then needed for the page where the graph occurs. This will also always follow the same formula:
set pagename.graph-1 to graph "data variable determined on the graph interaction" for username
Here, pagename.graph-1 is the automatically generated name of the graph that has been put on the page where the graph occurs.
Example1
In this example the number entered in the interaction ‘kg’ on the page ‘progresschart’ will be used as the data for the “weight” variable for the graph. The variable username has been set earlier in the logic as the unique identifier for the end-user (see the set key command for more information).
show progresschart
graph progresschart.kg to "weight" for username
Later in the logic the following line is needed after the page where the graph occurs:
show weightgraph
set weightgraph.graph-1 to graph "weight" for username
A full tutorial for using graphs will soon be available.
if
The if key command is always used with the set or after key commands.
load
The load command is always used with the save command.
named
Use this key command to re-show a page you have already shown.
For example, if you had a page that you need to keep showing back to your end-users you could use the named key command as so (note that in the example below the line [etc, etc] has been used to indicate that there would be other lines of logic here):
Example
show page1
[etc, etc]
show page1 named page2
[etc, etc]
show page1 named page3
save
The save key command allows you to save the responses that an end-user enters on a page. This can then be loaded using the load key command onto another page to re-show it to your end-user. The save and load commands can be used across sessions and requires end-users to have registered a user account.
Example:
show page1
save page1 for username
Then, later on in the logic (either in the same session or a later session) the following logic would be used:
show page20
set default page20.interaction2 to load page1.interaction1 for username
So, in the first part of this logic page1 is saved for the end-user. Then when they get to page20 in the intervention the response that they entered on interaction1 on page1 will be reshown to them on interaction2 on page20.
saveandload
This key command can be used after a page that includes interactions so that if an end-user moves away from that page and then comes back to it, the page will automatically show them what they entered the last time they were on that page. This line of logic would simply be written as so:
show page1
saveandload page1 for username
Any interaction on page1 would then be saved and loaded each time the end-user comes back to that page.
set
The set key command can be used to set variables within the logic or for performing calculations.
Example 1
The most common use of setting variables will be to set a username for the user. Many of the logic commands such as save will need a username to be set. This will need to be done at the start of your logic file.
Set username to login.loginuname
This will set the variable username to whatever the end-user enters into the interaction uniquely named loginuname on the login page. The word username can then be used any time throughout the logic to mean whatever the person entered in that interaction.
Example 2
The set key command can also be used to set a variable based on how end-users respond to certain interactions. This can then be used to tailor the intervention based on this variable.
show page1
set condition1 to and (page1.chooseoptions contains "optiona", page1.chooseoptions contains "optiond")
after page1 if condition1 goto page3
So in example 2, the variable ‘condition1’ is set if end-users select options a and d from the interaction ‘chooseoptions’ on page1. Then those that are in this condition are sent to page 3 where they will receive tailored information based on the options they selected.
Example 3
In this example, the set key command is used to set a score based on the calculation that follows. In this calculation the number that the end-user selects in the interaction ‘dailyexercise’ on page1 is multiplied by 5 to create their exercise score
set exercisescore to (page1.dailyexercise * 5)
show
The show key command is the first and most important logic command you will need to know. It is also probably the most common one that you will use.
This key command shows each of the pages that you have created. Pages will be shown in the order they are mentioned in the logic. When an end-user clicks on a Next button on a page, they will be moved to the next page written in the logic.
Example 1
show page1
show page2
show page3
show page4
In the example above the end-user will first be presented with the page uniquely named ‘page1’. Then, when they click on the next button on page1 they will see the page called ‘page2’. This is followed by ‘page3’ and finally ‘page4’.
Note: Before you can preview your intervention you will need to have the show key command in the logic file for each page you want to view.
As the logic requires you to use unique names for each page in your logic, you can only use the show key command once for each page. However, see the named key command above for how to re-show the same page to users.
You can also reshow pages to your end-user by using a jump button on a previous page.
to
The to key command is used with the set key command to set variables.
Commands (pink)
add
The add command is used when performing calculations in the logic. This may also be written as sum or +.
Example 1
This can be used to perform a calculation using the end-user's responses to specific numeric value interactions:
set score1 to add (page1.interaction1, page1.interaction2, page1.interaction3)
Example 2
The add or sum commands can also be used to calculate variables that have been set earlier in the session:
set overallscore to sum (score1, score2, score3)
and
The and command can be used for a number of reasons:
- If there is more than one response that is involved in presenting tailored advice to end-users, i.e. if one response and another response is needed to show feedback to an end-user.
- If you need to perform a number of logic commands after a page
Example 1
show page6 if (and(page3.exercise = "yes", page3.intensity = "moderate", page3.frequency = "three"))
End-users will be shown pagename6 if they selected yes to the interaction exercise on page3, moderate to the interaction intensity on page3 and three to the interaction frequency on page3.
append
The append command allows you to attach strings of logic together or to attach a variable within a string.
Example 1
In this example the append function is used to attach a person's username (which has been set in a previous part of the logic) to the text used in an email message:
after login if sendemail ("welcomeemail", login.uname, "Welcome to the lifestyle study", append ("Thank you for registering for the study", username, "remember to chart your progress everyday"), 60) goto page1
authenticateuser
This is important logic for ensuring that a user is registered with the intervention and is usually found after the login page.
The authenticateuser command can be used in the logic (intervention.lgil) file or in the error message logic.
Example
after login if (authenticateuser (login.username, login.password)) goto page1
So in the example above the details that the end-user enters into username and password interactions on the login page will be used to check that they are a registered user.
cancelemail
This command is used to cancel an email that has already been set up earlier on in the logic. For example if you set up e-mail reminders for people to login to upcoming sessions in the intervention then you will need to then cancel them if they subsequently login before the e-mail is due to be sent out.
This command uses the same basic formula:
after pagename if cancelemail ("unique name for email", e-mail address) goto nextpage
Example
after session2welcome if cancelemail ("session 2 reminder", login.email) goto session2page1
cancelsms
This command cancels an SMS message that has already been set up earlier on in the logic.
It uses a similar basic formula that is used for cancelling emails except it uses the cancelsms command and a phone number:
after pagename if cancelsms ("unique name for sms message", phonenumber) goto nextpage
changepassword
This command enables users to change their password. The formula for using this command would be:
after pagename1 if changepassword (username, pagename1.name_of_interaction_for_entering_old_password, pagename1.name_of_interaction_for_entering_new_password) goto pagename2
Example
after passworddetails if changepassword (username, passworddetails.old, passworddetails.new) goto confirmchange
checkemailvalidity
Checks that the e-mail that a user has entered is valid (i.e. contains an @ symbol).
This command is often used in an error message (please refer to the [http:www.lifeguideonline.org/releases/documentation researcher help manual] for details of writing error messages).
Example
show invalidemail if (not (checkemailvalidity (email)))
In this example 'invalidemail' is the name of the error message and 'email' is the name of the interaction on this page where the end-user would enter their e-mail address.
checkphonenumbervalidity
Checks that the mobile number that a user has entered is valid (i.e. begins with +44 or 07).
This command is often used in an error message (please refer to the [http:www.lifeguideonline.org/releases/documentation researcher help manual] for details of writing error messages).
Example
show invalidenumber if (not (checkphonenumbervalidity (phone)))
In this example 'invalidnumber' is the name of the error message and 'phone' is the name of the interaction on this page where the end-user would enter their phone number.
Please note that this logic is only set up to work with UK based numbers. Researchers will need to create their own phone number validator for international numbers or arrange this with a member of the LifeGuide team.
checkuserenabled
checkuserexists
This command would check whether an email address or username has already been registered for the intervention (i.e. if the details that have been entered is already registered with another user). This command is often used with an error message (please refer to the researcher help manual for details of writing error messages).
Example
show registeredemail if (checkuserexists (email))
In this example registeredemail is the name of the error message that would show if what they person enters in the 'email' interaction has already been registered.
comparetimes
This command can be used to compare two points in time.
Example 1
This example shows how comparetimes can be used to control users’ access to different sessions or pages within an intervention.
In your logic, you will first need to create a new variable (e.g. "username") which will tell the intervention which user times need to be compared for:
set username to login.name
if ( not ( isempty ( signup.name ) ) ) set username to signup.name
(For this logic to work, you will need to have already created “login” and “signup” pages which contain free text interactions to allow the user to enter their name or other identifier such as an email address – see also section 1.12 of the logic dictionary)
The order of your logic is very important when using the comparetimes function:
1. You first need to show the page users see before they are directed to particular sessions (e.g. "mainpage"):
show mainpage
2. Using the comparetimes function you now need to write the logic which directs the user to a particular session or page of the intervention:
after mainpage if ( comparetimes ( loadvalue ( username, “session4time”) , currenttime ( ), “seconds” ) >= 120 ) goto endpage
This tells the intervention that the user can continue to the end of the website if the difference between the current time, and the time the user completed session4, is more than or equal to two minutes. “seconds” may be replaced by “minutes”, “hours”, “days”, “weeks” or “months” (Don’t forget to end each with an ‘s’!)
after mainpage if ( comparetimes ( loadvalue ( username, “session3time” ), currenttime ( ), “seconds” ) >= 120 ) goto session4
This line tells the intervention that the user can continue to session4 of the intervention if it has been at least two minutes since they completed session3
after mainpage if ( comparetimes ( loadvalue ( username, "session3time" ), currenttime ( ), "seconds" ) <= 120 ) goto waitpage
This line of logic tells the intervention that the user cannot continue to session 4 because it has been less than two minutes since they completed session 3. Users are directed to a “waitpage” instead.
Repeat this process for the various sessions or pages contained within your intervention, for which you want to control access. The variables "session3time" and "session4time" are created in step 3.
3. Finally, using the show function you need to display the individual pages or sessions of your intervention, e.g.:
show waitpage
show session3
after session3 if ( savevalue ( username, “session3time”,
currenttime ( ) ) )goto session3end
show session3end
Using the currenttime function (see section 2.15 of the logic dictionary), this logic instructs the intervention to save a new variable “session3time”. This new variable records the time at which the user completed session3.
So, in this example, the intervention compares the time at which the user completed a given section of the intervention, with the current time, to determine whether enough time has elapsed to allow them to continue on to the next session.
contains
This command is used with multiple choice interactions. It can be used to check if users have chosen a specific response in a multiple choice interaction and then show them tailored information based on this.
Example
after page1 if (page1.exercise contains "nodays") goto page4
In this example the enduser would be directed to page 4 if they selected had selected the option that they had not done any exercise on any day in the past week (i.e. they selected the response 'no days'.
countif
This command can be used to count how many interactions an end-user has filled in.
Example
after page1 if (countif (not (isempty (page1.interaction1))), (not (isempty (page1.interaction2))), (not (isempty (page1.interaction3))), (not (isempty (page1.interaction4)))) <3) goto page4
This example counts how many interactions on page1 that the enduser fills in. If they respond to less than 3 of the interactions they will be directed to page4 of the interaction.
currenttime
divide
This is used when performing calculations. The symbol / can also be used.
Example 1
set score1 to (page1.interaction1 / page1.interaction2)
score1 would be the result of dividing the response given in interaction 1 by the response given in interaction 2.
Example 2
set overallscore to (score1 / score2)
In this example the overallscore is calculated by dividing score1 by score2 where score1 and score2 have already been calculated elsewhere in the logic.
hasseen
hasseen is used to show end-users pages based on what they have or have not seen before.
Example 1
If you wanted to show end-users a different page each time they logged in depending on what sessions they had seen before you may use the hasseen command like so:
show login
show s1welcome if (not(hasseen (username, "s1welcome")))
show s2welcome if (not(hasseen (username, "s2welcome")))
show s3welcome if (not(hasseen (usernme, "s3welcome")))
This would mean that the first time they login they would see the session 1 welcome page which is labelled s1welcome. The next time they log in, because they have already seen the s1welcome page the logic will skip that line of logic and show them s2welcome because they have not yet seen the s2welcome page.
If you want the hasseen function to include the pages end-users have seen in the session they are currently in, you will need to add"true" to the line of logic:
show s1welcome if (not(hasseen (username, "s1welcome","true")))
Example 2
The hasseen logic can also be used without not to tailor the intervention for users.
For example, you may want to show something on a later page only if an end-user has seen something on a previous one. You can use the hasseen logic in one of three ways depending on when you want it to be seen:
E.g.
show sessionspage.session3details if (hasseen (username, "session3final"))
This will show the end-user the session3details text box if they have seen the page called "session3final" in any session but the one they are currently in. In other words they will only be shown this once they have logged in for the next session.
show sessionspage.session3details if (hasseen (username, "session3final", "this"))
By adding "this" into the hasseen command here you can make sure that what you are wishing to show will be shown ONLY in the current session.
show sessionspage.session3details if (hasseen (username, "session3final", "true"))
Adding "true" to the hasseen command enables the person to see this in ALL sessions INCLUDING the current one.
isempty
This command checks if an interaction is empty.
Example1
after page1 if (isempty (page1.interaction1)) goto page4
The end-user would be directed to page4 if they did not enter anything in interaction1 on page1.
Example2
set none if (isempty (page1.interaction1))
If the end-user does not enter anything in interaction1 on page1 they would be set to the condition 'none'.
or
The or command is used in much the same way as the and. It can be used to check if a user has responded in particular ways to an interaction (or number of interactions):
after page1 if (or (page1.interaction1 = "none", page1.interaction1 = "sometimes")) goto page3
lessthan
This command can be used when performing calculations in the logic to check if one value is lower than another. The symbol < can also be used.
set condition1 if (page1.interaction1 < page1.interaction2)
lessthanequal
This command can be used when performing calculations in the logic to check if one value is lower than or equal to another. The symbol <= can also be used.
set condition1 if (page1.interaction1 <= page1.interaction2)
loadvalue
makenewuser
The makenewuser is very important; it is used to set up an account for the user using a username (or e-mail address) and password.
Example
show signup
after signup if (makenewuser(signup.signup_username, signup.signup_password)) goto thankyou
So in the example above the information that the end-user enters into the interactions 'signup_username' and 'signup_password' is used to create a user account.
morethan
This command can be used when performing calculations in the logic to check if one value is higher than another. The symbol > can also be used.
set condition2 if (page1.interaction1 > page1.interaction2)
morethanequal
This command can be used when performing calculations in the logic to check if one value is higher than or equal to another. The symbol >= can also be used.
set condition2 if (page1.interaction1 >= page1.interaction2)
multiply
This command can be used when performing calculations to multiply one value by another. The symbol * may also be used. This value may be taken from an end-user's response to an interaction:
Example 1
set score1 to (page1.interaction1 * page1.interaction2)
Example 2
The value may be taken from the calculations performed elsewhere in the logic: E.g.:
set overallscore to (score1 * score2)
not
The not command is used to refer to a response which had not been selected.
Example 1
set condition1 if (not (page1.interaction1 = "yes"))
So condition1 would be set for this user if they did not select the "yes" response in interaction1. We can then use this condition to tailor the rest of the intervention that the end-user sees.
Note: Do not confuse the not command with the isempty command. not is used to refer to a specific response to an interaction that has not been chosen. isempty is used to refer to an interaction that an end-user has not answered.
not and isempty can be used together to refer to an interaction that is not empty (i.e. something has been entered).
after page1 if (not (isempty (page1.interaction1))) goto page5
Or
set condition1 if (not (isempty (page1.interaction1)))
patternmatch
printtime
The printtime converts a value from a number to a string
randomnumber
This command allows you to randomise your users into different groups and always follows the same formula:
after page1 if (randomnumber (lowestvalue , highestvalue) = value) goto page3
For example:
after page1 if (randomnumber (0, 1) = 1) goto page3
show page2
show page3
Thus, users that are randomised to group 1 will be directed to page3. Those that are randomised to group 0 will carry on to page2.
A full tutorial for randomisation is available in the LifeGuide Researcher Help Manual.
replaceall
This command can be used to do text replacements inside a string.
Example
In the following example the replaceall command is used to replace all the 'a's in a string to 'b's. So this would change 'I like apples a lot' to 'I like bpples b lot'
replaceall ("a", "b", "I like apples a lot")
resetpassword
savevalue
The savevalue command allows you to save a variable for a username that can then be loaded again in later sessions.
sendemail
This is the command for setting up e-mails to send out to the end-user at specific points in the intervention. The function for sending out an e-mail always uses the same basic formula:
after pagename1 if sendemail("unique name for e-mail", e-mail address, "Subject message for e-mail", "E-mail content", number in seconds indicating how long after the end-user views pagename1 that you want the e-mail sent out) goto pagename2
Example
after page1 if sendemail("welcomeemail", login.email, "welcome to the intervention", "Thank you for registering for the lifestyle intervention. Please remember to check back regularly for more information.", 60) goto page1
In this example a welcome email will be sent to the e-mail address that the end-user has entered on the login page 60 seconds after they have clicked away from the page.
A full tutorial is available for Sending Emails including details of how to send e-mails to a researcher or healthcare professional instead of the end-user.
sendtext
This is the command for sending sms text messages to an end-user. It uses a similar basic formula as the command for sending email messages. The only differences are:
- it uses the end-user's mobile phone number instead of an e-mail address
- it does not need a subject message
- there is a restriction for how long a text message can be
after page1 if sendtext ("welcometext", login.phone, "Thank you for registering for the lifestyle intervention. Please remember to check back regularly for more information.", 60) goto page1
Note: You will need to set up an sms account for your intervention before you can send sms messages. See LifeGuide Community Website FAQs for more information.
stringlength
sum
See add
timesincelogin
This command can be used to show users how much time has passed since they last logged into the intervention.
Example
Using the timesincelogin command involves 3 basic steps:
1. In your logic, show the page (e.g. “time”) where you want to display how long it has been since the user last logged into the website:
show time
2. In your logic, create a new variable (e.g. “username”) to tell the intervention, which user, time since login data should be displayed for:
set username to login.name
if (not(isempty (signup.name))) set username to signup.name
(For this logic to work, you will need to have already created “login” and “signup” pages which contain free text interactions to allow the user to enter their name or other identifier such as an email address – see also section 1.12 of the logic dictionary)
3. On your “time” page, create a new variable to represent where the time since login data should be displayed to the user (e.g. “secs”). (This is done using the ‘set as variable’ function). Then, in your logic, set this variable to display the desired time since login for a particular user, using the timesincelogin command.
set time.secs to timesincelogin (username, "seconds")
So, in this example, on the page named “time” you have shown the user the time in seconds since they last logged into the intervention.
The third step can be repeated to show the user the time in “minutes”, ”hours”, “days”, “weeks” or “months” since they last logged into the intervention.