Logic Dictionary: Difference between revisions
(→and) |
|||
(197 intermediate revisions by 11 users not shown) | |||
Line 1: | Line 1: | ||
A quick reference guide to LifeGuide logic. For more detailed information, please refer to the '''How to...''' Guide. | |||
It is important to insert '''Next''' buttons on your pages (instead of '''Jump''' buttons) whenever possible in order for your logic to work correctly. If you show a page and have a vital line of logic written after you show that page (such as randomisation or saving logic), or have error messages on that page, your intervention will not work correctly if you use a '''Jump''' button - you will jump to another page and skip parts of the logic in your logic file and Error Messages section. | |||
= | =A= | ||
== <code> add </code> == | |||
This may also be written as '''sum''' or '''+'''. The '''add''' command is used when performing calculations in the logic. It is used to add together more than two values. | |||
'''Example 1''' | |||
This can be used to perform a calculation using the end-user's responses to specific numeric value interactions: | |||
<code>set score1 to add (page1.interaction1, page1.interaction2, page1.interaction3)</code> | |||
'''Example 2''' | |||
The '''add''' or '''sum''' commands can also be used to calculate variables that have been set earlier in the session: | |||
<code>set overallscore to sum (score1, score2, score3)</code> | |||
For simple addition or subtract calculations <code>+</code> and <code>-</code> can be used normally. | |||
For example: | |||
<code>set score to (100 - page1.interaction1)</code> | |||
Make sure you leave a space between the numbers/variables and the subtraction symbol. | |||
== <code> after </code> == | == <code> after </code> == | ||
The | The '''after''' command is used after a page to perform functions that relate to that page. | ||
It is likely that you will use this command quite regularly in your intervention logic. The most common way of using the '''after''' command is with the '''if''' and '''goto''' commands, e.g. | |||
<code>show page1</code> | <code>show page1</code> | ||
<code>after page1 if (any_commands_you_want_to_relate_to_this_page) goto page2</code> | <code>after page1 if (any_commands_you_want_to_relate_to_this_page) goto page3</code> | ||
'''Example 1''' | |||
<code>after page1 if (page1.interaction1 = "yes") goto page3 | |||
show page 2 | |||
show page3</code> | |||
In the above example, the end-user will be directed to '''page3''' if they have answered '''yes''' to '''interaction1''' on '''page1'''. If they answer '''no''' to '''interaction1''', they will be directed to the next line of logic and will see '''page2'''. | |||
'''NB If you use the <code>after</code> command with the <code>goto</code> command, the page that you goto should NOT be the next page shown in your logic, it should be a page further down in your logic''' as in the example above. | |||
As will be seen throughout this dictionary, any command can be used with the '''after''' command. | |||
== <code> and </code> == | |||
Can also be written as '''&&'''. | |||
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''' | |||
<code>show page6 if (and(page3.exercise = "yes", page3.intensity = "moderate", page3.frequency = "three"))</code> | |||
End-users will be shown page6 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'''. | |||
'''Example 2''' | |||
<code>after login_successful if (and( not(hasseen(username, "q_demographics")), (isempty (loadvalue(username, "baselinecomplete"))) )) goto q_intro </code> | |||
End-users will be shown '''q_intro''' if they have not seen page '''q_demographics''' and if the variable '''baselinecomplete''' is empty (i.e. '''the variable baselinecomplete hasn't been saved because the end-user hasn't finished the baseline questionnaire). | |||
== <code> append </code> == | |||
The <code>append</code> command allows you to attach logic commands together, and/or to attach a variable to a string (a string is something that you create - a sequence of characters between quotation marks, e.g. "session1". | |||
<code>append</code> is most often used with the logic commands <code>sendemail </code> and <code>cancelemail</code> | |||
'''Example 1''' | |||
<code>sendemail (append(username,"user_reg1"), username, "StressLess - Session 1 is ready", append("Dear ", loadvalue (username, "personsname"), "\n\n", reg_part1, reg_part2), 10) </code> | |||
In this example, '''append''' is used to attach: | |||
*a username (which has been set in a previous part of the logic) to the unique name of the email message: | |||
<code>append (username,"user_reg1")</code> | |||
*a user's name to the text used in an email message (the append function here allows the content of the email message to be made of different parts): | |||
<code>append ("Dear ", loadvalue (username, "personsname"), "\n\n", reg_part1, reg_part2)</code> | |||
The '''\n\n''' in the logic above means a new line in the email message content. | |||
'''Example 2''' | |||
<code>cancelemail (append("user_regs2rem", username), username) </code> | |||
In this example, '''append''' is used to attach: | |||
*a username to the unique name of the email message: | |||
<code>append ("user_regs1", username)</code> | |||
'''Example 3''' | |||
Append is not only useful for emails. It can be used to combine interactions and other parts of text and save values. | |||
For example: | |||
<code>set fullname to append(registration.firstname, " ",registration.surname) | |||
savevalue(username,"fullname", fullname) | |||
</code> | |||
This code takes the interaction items "firstname" and "surname" from the registration page and combines them into a fullname. | |||
''Important:'' When you use append in this way, make sure you add a string i.e. a letter, number or space in quotation marks like "a" or it may not work! | |||
'''Example 4''' | |||
In this example, we add information to a previously saved value: | |||
<code>savevalue(username, "oldgoals","RESULTS_") if isempty(loadvalue(username,"oldgoals")) | |||
set oldgoals to loadvalue(username,"oldgoals") | |||
savevalue(username, "oldgoals", (append(oldgoals,"_", printtime(currenttime(),"dMy"),"_", goalsetpage.newgoal)))</code> | |||
First, we create the variable "oldgoals" and save it if it doesn't exist. We then set oldgoals to load this value. Lastly, we save the value oldgoals again, appending the old value of "oldgoals", adding the date the new value is being added and adding the value of the newgoal set on the page "goalsetpage". Underscores are used to separate the data and make it more readable. This will create a user variable like this, that gets longer over time: | |||
"RESULTS_181016_firstgoal_191016_secondgoal_221016_thirdgoal" | |||
== <code> authenticateuser </code> == | |||
This is important logic for ensuring that a user is registered with the intervention and is written directly after the '''show login''' logic. This logic should be used with the <code> makenewuser </code> logic function, which creates a new user. | |||
The <code>authenticateuser</code> command can be used in the logic (intervention.lgil) file or in the Error Message logic. | |||
'''Example 1''' | |||
<code>show login | |||
after login if (authenticateuser (login.username, login.password)) goto login_confirmation | |||
show login_fail | |||
show login_confirmation </code> | |||
The logic in this example is written in the logic file. The details that the end-user enters into the username and password interactions on the login page will be used to check they are a registered user. If they are not a registered user, they will be shown the '''login_fail''' page. | |||
'''Example 2''' | |||
<code>show err1 if (isempty(username)) | |||
show err2 if (not(authenticateuser(username, password)))</code> | |||
The logic in this example is written in the '''Error Messages''' tab of a page. The details that the end-user enters into the username and password interactions on the login page will be used to check they are a registered user. If they are not a registered user, they will be shown the error message '''err2''' and will not be able to proceed to the next page. | |||
=B= | |||
== <code> begin </code> == | == <code> begin </code> == | ||
Line 32: | Line 167: | ||
* If you begin a section, you should always end the section. | * If you begin a section, you should always end the section. | ||
* All the logic related to the section must be between begin | * All the logic related to the section must be between <code>begin</code> and <code>end</code> | ||
* 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. | * 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. | * 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''' | '''Example 1''' | ||
Line 70: | Line 205: | ||
<code>end </code> | <code>end </code> | ||
This will begin the section stress. | This will begin the section '''stress'''. | ||
The section causes will then begin and page1 and page2 in the section causes will be shown. | The section '''causes''' will then begin and '''page1''' and '''page2''' in the section '''causes''' will be shown. | ||
The first <code>end</code> will end the section '''causes'''. | |||
The section relieve will then begin and page3 and page4 will be shown. | The section '''relieve''' will then begin and '''page3''' and '''page4''' will be shown. | ||
The next end will end the section relieve. The final end will end the section stress. | The next <code>end</code> will end the section '''relieve'''. The final <code>end</code> will end the section '''stress'''. | ||
=C= | |||
== <code> | == <code> cancelemail </code> == | ||
Used to cancel an email that has been set up earlier in the logic. | |||
You may want to: | |||
* cancel emails to end-users (e.g. if you set up email reminders for end-users to login to upcoming sessions, you will need to cancel them if they login before the email is due to be sent. | |||
* cancel emails to the study coordinator (e.g. if you set up email reminders to notify the study coordinator when end-users do not complete study questionnaires, you will need to cancel them if they complete the questionnaires. | |||
This command uses the same basic formula: | |||
<code>cancelemail (append(username, "unique_email_name", e-mail address))</code> | |||
'''Example 1''' | |||
<code>cancelemail(append(username, "email_session2r"), username)</code> | |||
This will cancel the email '''email_session2r''' for an end-user. The '''append''' function links an end-user's '''username''' to the name of the email ('''email_session2r''') to give each email a unique name. | |||
'''Example 2''' | |||
<code>cancelemail(append(username,"q1_notcomplete"), "study@test.ac.uk")</code> | |||
This will cancel the email '''q1_notcomplete''' that was due to be sent to '''study@test.ac.uk'''. The '''append''' function links an end-users '''username''' to the name of the email ('''q1_notcompleteto''') to give each email a unique name. | |||
== <code> cancelsms </code> == | |||
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 <code>cancelsms</code> command and a phone number: | |||
<code> after pagename if cancelsms ("unique name for sms message", phonenumber) goto nextpage</code> | |||
== <code> changepassword </code> == | |||
Enables end-users to change their password. | |||
Please see the LifeGuide Community Website for a tutorial intervention that shows how to create the pages and write the logic for this. | |||
'''Example 1''' | |||
<code> after passworddetails if changepassword (username, passworddetails.old, passworddetails.new) goto confirmchange</code> | |||
This will allow a password to be changed if the old password is correctly entered into the interaction called '''old''' on page '''passworddetails''', and a new password is entered into the interaction called '''new''' on page '''passworddetails'''. | |||
== <code> checkemailvalidity </code> == | |||
Checks that the e-mail address a user has entered contains an @ symbol. | |||
This command is used with an error message and is written in the '''Error Messages''' tab (please refer to [[Adding Error Messages]] for information about writing error messages). | |||
'''Example 1''' | |||
<code> show invalidemail if (not (checkemailvalidity (email)))</code> | |||
''' | '''invalidemail''' is the name of an error message and '''email''' is the name of the interaction on this page where the end-user would enter their e-mail address. | ||
<code> | == <code> checkphonenumbervalidity </code> == | ||
Checks that the mobile number a user has entered begins with '''+44''' or ''''0'''. | |||
This command is used with an error message (please see [[Adding error messages]] for more information. | |||
'''Example 1''' | |||
<code>show | <code> show invalidnumber if (not (checkphonenumbervalidity (phone)))</code> | ||
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 error messages to check the correct numbers are entered for international numbers. | |||
== <code> | == <code> checkuserenabled </code> == | ||
== <code> | == <code> checkuserexists </code> == | ||
This command checks whether an email address or username has already been registered with the intervention (i.e. if the details that have been entered are already registered with another user). This command is often used with an error message (please see the '''How to guide''' for details on how to write error messages) | |||
'''Example 1''' | '''Example 1''' | ||
<code>show registeredemail if (checkuserexists (email))</code> | |||
In this example '''registeredemail''' is the name of the error message that would show if a user enters an email address that has already been registered in the text box called '''email'''. | |||
== <code> comparetimes </code> == | |||
This command can be used to compare two points in time. It can also be used to convert a number of seconds to days, hours, minutes and seconds (see Example 2). | |||
'''Example 1''' | |||
This | This example shows how <code>comparetimes</code> 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: | |||
<code> | <code>set</code> username <code>to</code> login.name | ||
<code> | <code>if</code> ( <code>not</code> ( <code>isempty</code> ( signup.name ) ) ) <code>set</code> username to signup.name | ||
(For this logic to work, you will need to have already created '''login''' and '''signup''' pages, which contain text-entry interactions to allow end-users to enter their email address and password) | |||
The order of your logic is very important when using the <code>comparetimes</code> function: | |||
''' | '''1.''' You first need to show the page users see before they are directed to particular sessions (e.g. "mainpage"): | ||
<code>show</code> mainpage | |||
'''2.''' Using the <code>comparetimes</code> function you now need to write the logic which directs the user to a particular session or page of the intervention: | |||
<code>after</code> mainpage <code>if</code> ( <code>comparetimes</code> ( <code>loadvalue</code> ( username, <code>"session4time"</code>) , <code>currenttime</code> ( ), <code>"seconds"</code> ) <code>>=</code> 120 ) <code>goto</code> endpage | |||
This | 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. <code>“seconds”</code> may be replaced by <code>“minutes”</code>, <code>“hours”</code>, <code>“days”</code>, <code>“weeks”</code> or <code>“months”</code> (Don’t forget to end each with an ‘'''s'''’!) | ||
<code> | <code>after</code> mainpage <code>if</code> ( <code>comparetimes</code> ( <code>loadvalue</code> ( username, <code>"session3time"</code> ), <code>currenttime</code> ( ), <code>"seconds"</code> ) <code>>=</code> 120 ) <code>goto</code> 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 | |||
<code> | <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. | |||
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. | |||
'''3.''' Finally, using the <code>show</code> function you need to display the individual pages or sessions of your intervention, e.g.: | |||
<code>show</code> waitpage | |||
<code>show</code> session3 | |||
<code>after</code> session3 <code>if</code> ( <code>savevalue</code> ( username, <code>“session3time”</code>, | |||
<code>currenttime</code> ( ) ) )<code>goto</code> session3end | |||
<code>show</code> session3end | |||
Using the <code>currenttime function</code> (see [[currenttime]]), this logic instructs the intervention to save a new variable <code>“session3time”</code>. 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. | |||
'''Example 2''' | |||
In this example we use <code>comparetimes</code> to convert the difference between two times to weeks, days, hours, minutes and seconds to tell the user how long they need to wait before features of the intervention are unlocked. In this example, we display the time until Christmas 2016. | |||
<code>set timenow to (currenttime()) | |||
set christmas to (1482624000) | |||
set weeks to (comparetimes(timenow,christmas,"weeks")) | |||
set days to (comparetimes(timenow,christmas,"days")) | |||
set hrs to (comparetimes(timenow,christmas,"hours")) | |||
set mins to (comparetimes(timenow,christmas,"minutes")) | |||
set days2 to (days - (weeks*7)) | |||
set hrs2 to (hrs - (days*24)) | |||
set mins2 to (mins - (hrs*60)) | |||
set secs to ((christmas - timenow) - (mins*60)) | |||
</code> | |||
This logic first uses <code>comparetimes</code> to set variables - the time between now and Christmas in weeks, days, hours and minutes. However, we want to display the time between now and Christmas as a whole, not the total number of days, total number of hours, total number of minutes and total number of seconds. | |||
We need to set the number of days to the total number of days minus the days in the weeks that we have already counted, so that the number of days is less than 7. We do the same for hours and minutes. | |||
For seconds, we simply calculate the difference between christmas and now and subtract the total number seconds in minutes that we have already set. You don't need to use <code>comparetimes</code> for calculating the difference in seconds as <code>currenttime</code> is already in seconds. | |||
To display the time between now and Christmas on a page, the following logic can be used: | |||
<code>show intro | |||
set intro.hrs to hrs2 | |||
set intro.mins to mins2 | |||
set intro.secs to secs | |||
set intro.days to days2 | |||
set intro.weeks to weeks | |||
</code> | |||
== <code> contains </code> == | |||
Used with multiple-choice interactions. It is used to show tailored information based on a specific response an end-user has given. | |||
'''Example 1''' | |||
<code> after page1 if (page1.exercise contains "none") goto page4</code> | |||
In this example, the end-user will be directed to '''page4''' if they had selected '''none''' to the interaction '''exercise''' on '''page1'''. | |||
'''Example 2''' | |||
<code>after | <code> after page1 if (or( page1.exercise contains "1day", page1.exercise contains "2days" )) goto page4</code> | ||
An end-user will be shown '''page4''' if they selected '''1day''' or '''2days''' to the interaction '''exercise''' on '''page1'''. | |||
== <code> countif </code> == | |||
This command can be used to count how many interactions an end-user has filled in. | |||
'''Example''' | '''Example''' | ||
<code>after | <code>after page1 if (countif (not (isempty (page1.interaction1))), (not (isempty (page1.interaction2))), (not (isempty (page1.interaction3))), (not (isempty (page1.interaction4)))) <3) goto page4</code> | ||
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. | |||
== <code> | == <code> currenttime </code> == | ||
This command | This command instructs the intervention logic to load or save the time as it is at that particular moment. | ||
The <code>currenttime</code> function can be used to create new variables which save the time at which users completed a particular session of the intervention. | |||
'''1.''' In your logic, you will first need to create a new variable (e.g. “username”) which will tell the intervention which particular user a time is being saved for: | |||
<code>set username to login.name</code> | |||
<code> | <code>if ( not ( isempty ( signup.name ) ) ) set username to signup.name</code> | ||
(For this logic to work, you will need to have already created “login”, “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 [[1.12 set]]) | |||
'''2.''' Using the “username” variable you have just created, you can then save the time at which each user completes a particular section of your intervention, in this case ‘session 3’: | |||
<code>show session3</code> | |||
<code> after | <code>after session3 if ( savevalue ( username, “session3time”, currenttime ( ) ) )goto session3end</code> | ||
<code>show session3end</code> | |||
Here, the logic instructs the intervention to save the time at the particular moment a user completes the session 3 page. The saved time is represented as a new variable called <code>"session3time".</code> | |||
<code> | '''3.''' The <code>currenttime</code> function can also be used as a comparison or reference point. This is particularly useful if you want to put time controls on when users can access particular sessions of the website (see also [[2.12 comparetimes]]): | ||
<code>after mainpage if ( comparetimes ( loadvalue ( username, "session3time" ), currenttime ( ), "minutes" ) >= 120 ) goto session4</code> | |||
This line tells the intervention that the user can continue to session 4 of the intervention if it has been at least two hours since they completed session 3 | |||
<code>after mainpage if ( comparetimes ( loadvalue ( username, "session3time" ), currenttime ( ), "minutes" ) <= 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 hours since they completed session 3. Users are directed to a “waitpage” instead. | |||
You may have noticed that the <code>currenttime</code> function is always followed by (). These empty brackets tell the intervention that <code>currenttime</code> should act as a logic function rather than an intervention variable that you have created yourself. | |||
=D= | |||
<code> | == <code> decimalplaces </code> == | ||
This command will round a number to a specified number of decimal places. For example, it would round 6.6666666 to 6.67 if 2 decimal places was selected or 6.6667 for 4 decimal places. If you want to round a number to 0 decimal places (i.e. you want a whole number), the simpler <code>round</code> command can be used. | |||
You cannot use <code>decimalplaces</code> to abbreviate whole numbers to a number of significant figures (e.g. setting 1,234,567 to 1,234,600) by asking for a negative number of decimal places; a negative number of decimal places will be treated as 0 decimal places. This can be done using <code>round</code> (see example 3 of <code>round</code>). | |||
'''Example 1''' | |||
In this example we shorten a long decimal number to 4 decimal places. | |||
<code>set numberpi to decimalplaces(3.1415926,4)</code> | |||
<code> | This will set the value of <code>numberpi</code> to 3.1416. | ||
'''Example 2''' | |||
In this example we calculate the area of a circle and return the answer to 2 decimal places. | |||
<code>show circle_page | |||
set cradius to circle_page.radius | |||
set pi to 3.14159 | |||
set carea to ((cradius*cradius)*pi) | |||
set careashort to decimalplaces(carea,2) | |||
show results_page | |||
set results_page.circle to careashort | |||
</code> | |||
<code> | Firstly we get the radius from the user's interaction on <code>circle_page</code>. | ||
Then we set the value of pi. | |||
= | Then we calculate the area of the circle using the formula area=pi*(radius*radius). | ||
We then shorten the value back to 2 decimal places. We still have the full value stored in case we want to calculate things with it later on - like the volume of a cylinder. | |||
On <code>results_page</code> we show the user the area of the circle, to 2 decimal places. | |||
<code> | == <code> default </code> == | ||
This | This is used to set an interaction element to a previously saved value. This is used in conjunction with the <code>save</code> command - see [[#save|<code>save</code>]] for an example. | ||
To recall information from the same page, use the [[#saveandload|<code>saveandload</code>]] command. | |||
== <code> divide </code> == | == <code> divide </code> == | ||
The symbol <code>/</code> can also be used. The command <code>divide</code> is used when performing calculations. | |||
'''Example 1''' | '''Example 1''' | ||
Line 361: | Line 514: | ||
<code> set score1 to (page1.interaction1 / page1.interaction2)</code> | <code> set score1 to (page1.interaction1 / page1.interaction2)</code> | ||
score1 would be the result of dividing the response given in | '''score1''' would be the result of dividing the response given in '''interaction1''' by the response given in '''interaction2'''. | ||
'''Example 2''' | '''Example 2''' | ||
Line 367: | Line 520: | ||
<code> set overallscore to (score1 / score2)</code> | <code> set overallscore to (score1 / score2)</code> | ||
In this example | In this example, '''overallscore''' is calculated by dividing '''score1''' by '''score2''', where '''score1''' and '''score2''' have already been calculated elsewhere in the logic. | ||
=E= | |||
== <code> else </code> == | |||
<code>else</code> is used only with <code>if</code>. It allows you to do something if a condition is Not met. For example: | |||
<code>if not(or(isempty(page1.q1),isempty(page1.q2))) set page1_complete to 1 | |||
else set page1_complete to 0</code> | |||
This page checks if both the interactions on page1 have been answered. If they have, page1_complete is set to 1. The <code>else</code> logic on the next line sets page1_complete to 0 if the interactions have not been answered. | |||
== <code> end </code> == | |||
Please see <code>begin</code> for details of how to use <code>end</code>. The <code>end</code> command is always used with the <code>begin</code> command. | |||
=F= | |||
== <code> for </code> == | |||
The <code>for</code> key command is used with the <code>save</code> and <code>graph</code> key commands. | |||
=G= | |||
== <code> getuserid </code> == | |||
This function gives you the database ID for a user, which is a number that is unique to each LifeGuide server. This number is automatically generated and can be used to uniquely identify a user without having to refer to their identifier (i.e. username). This number can also be included in your data export by ticking the '''User Number''' box when you export your data. | |||
'''Example 1''' | |||
<code>getuserid(username)</code> | |||
== <code> goto</code> == | |||
The <code>goto</code> command is always used with the <code>after</code> command. It tells the logic which page the user should '''goto''' after that line. See <code>after</code> for details. | |||
== <code> graph </code> == | |||
The <code>graph</code> 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. | |||
<code>graph value to "data variable determined on the graph interaction" for unique_identifier_for_the_end-user_e.g._a_username</code> | |||
Another line of logic is then needed for the page where the graph occurs. This will also always follow the same formula: | |||
<code>set pagename.graph-1 to graph "data variable determined on the graph interaction" for username</code> | |||
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 <code>set</code> key command for more information). | |||
<code>show progresschart | |||
graph progresschart.kg to "weight" for username</code> | |||
Later in the logic the following line is needed after the page where the graph occurs: | |||
<code>show weightgraph | |||
set weightgraph.graph-1 to graph "weight" for username</code> | |||
A full tutorial for using graphs will soon be available. | |||
=H= | |||
== <code> hasseen </code> == | == <code> hasseen </code> == | ||
<code>hasseen</code> is used to show end-users pages based on what they have or have not seen before. | <code>hasseen</code> is used to show end-users pages based on what they have or have not seen before. | ||
Tip - if you have more than one session in your intervention, we recommend that you use '''savevalue''' and '''loadvalue''' instead of hasseen as these values can be edited after your intervention has gone live (this is useful in case something goes wrong in your intervention). | |||
'''Example 1''' | '''Example 1''' | ||
Line 380: | Line 599: | ||
<code>show s1welcome if (not(hasseen (username, "s1welcome")))</code> | <code>show s1welcome if (not(hasseen (username, "s1welcome")))</code> | ||
<code>show s2welcome if (not(hasseen (username, "s2welcome")))</code> | <code>show s2welcome if (not(hasseen (username, "s2welcome")))</code> | ||
<code>show s3welcome if (not(hasseen (usernme, "s3welcome")))</code> | <code>show s3welcome if (not(hasseen (usernme, "s3welcome")))</code> | ||
This would mean that the first time they login they would see the | This would mean that the first time they login they would see the page '''s1welcome'''. The next time they log in, because they have already seen the '''s1welcome''' page, the logic will skip that line and show '''s2welcome''' because they have not yet seen the '''s2welcome''' page. | ||
'''Example 2''' | |||
The hasseen logic can also be used without <code>not</code>, to tailor the intervention for users. | |||
For example, you may want to show a page only if an end-user has seen a previous page. | |||
<code>show s1_feeback2 if (hasseen (username, "s1_feedback1")))</code> | |||
<code>show s1_feeback3 if (hasseen (username, "s1_feedback2")))</code> | |||
===Using hasseen in sessions=== | |||
You can use the hasseen logic in one of three ways: | |||
<code> show session2.interaction1 if (hasseen (username, "session1final"))</code> | |||
This will show the end-user '''interaction1''' if they have seen '''session1final''' in any session EXCEPT the one they are currently in (i.e. in previous sessions only). | |||
<code> show session2.interaction1 if (hasseen (username, "session1final", "true"))</code> | |||
Adding '''true''' to the hasseen command will show '''interaction1''' if the end-user has seen '''session1final''' in ANY session, INCLUDING the current one. | |||
<code> show session2.interaction1 if (hasseen (username, "session1final", "this"))</code> | |||
Adding '''this''' to the hasseen command will show '''interaction1''' if the end-user has seen '''session1final''' in the current session ONLY. | |||
== <code> hmacencode </code> == | |||
<code>hmacencode</code> is an advanced logic command that encrypts data. It is used to obscure data so that it cannot be read. You cannot decrypt anything encrypted using <code>hmacencode</code>. | |||
<code>set encoded to hmacencode("This message is encoded", "secret")</code> | |||
The primary use for <code>hmacencode</code> is to check that data passed from one intervention to another has not been corrupted. | |||
=I= | |||
== <code> if </code> == | |||
The <code>if</code> command is '''always''' used with another command (e.g. after, show). It is a conditional command so it should always be followed by a true or false statement (i.e. a statement that will be carried out if it is true OR a statement that will be carried out if it is false). | |||
== <code> isempty </code> == | == <code> isempty </code> == | ||
This command checks if | This command checks whether a response has been given to an interaction (i.e. if a response has not been given, the interaction '''isempty'''). | ||
'''Example1''' | '''Example1''' | ||
Line 393: | Line 659: | ||
<code>after page1 if (isempty (page1.interaction1)) goto page4</code> | <code>after page1 if (isempty (page1.interaction1)) goto page4</code> | ||
The end-user would be directed to page4 if they did not enter anything in interaction1 on page1. | The end-user would be directed to '''page4''' if they did not enter anything in '''interaction1''' on '''page1'''. | ||
'''Example2''' | '''Example2''' | ||
Line 399: | Line 665: | ||
<code>set none if (isempty (page1.interaction1))</code> | <code>set none if (isempty (page1.interaction1))</code> | ||
If the end-user does not enter anything in interaction1 on page1 | If the end-user does not enter anything in '''interaction1''' on '''page1''', the variable '''none''' will be set. | ||
=L= | |||
== <code> | == <code> load </code> == | ||
Please see the <code>save</code> command for more details. The <code>load </code> command is always used with the save command. | |||
<code> | == <code> loadvalue </code> == | ||
The '''loadvalue''' command is always used with the '''savevalue''' command. It loads the value that you have previously saved. Please see the '''savevalue''' command for more details. | |||
== <code> lessthan </code> == | == <code> lessthan </code> == | ||
This command | The symbol <code><</code> can also be used. | ||
This command is used when | |||
* performing calculations in the logic to check if one value is lower than another | |||
* comparing time to check if one time occurs before another time (e.g. comparing the current time to the time the previous session was completed to check that one week has passed. | |||
'''Example 1''' | |||
<code>set condition1 if (page1.interaction1 < page1.interaction2) </code> | <code>set condition1 if (page1.interaction1 < page1.interaction2) </code> | ||
'''Example 2''' | |||
<code>after login if (comparetimes (loadvalue(username, "session1_time"), currenttime(), "seconds" ) < 86400)</code> | |||
== <code> lessthanequal </code> == | == <code> lessthanequal </code> == | ||
This command | The symbol <code> <= </code> can also be used. | ||
This command is used in the same way as '''lessthan'''. It is used when: | |||
* performing calculations in the logic to check if one value is lower than another | |||
* comparing time to check if one time occurs before another time (e.g. comparing the current time to the time the previous session was completed to check that one week has passed. | |||
'''Example 1''' | |||
<code>set condition1 if (page1.interaction1 <= page1.interaction2) </code> | <code>set condition1 if (page1.interaction1 <= page1.interaction2) </code> | ||
'''Example 2''' | |||
<code>after login if (comparetimes (loadvalue(username, "session1_time"), currenttime(), "seconds" ) <= 86400)</code> | |||
=M= | |||
== <code> makenewuser </code> == | == <code> makenewuser </code> == | ||
The <code>makenewuser</code> | The <code>makenewuser</code> command is used to set up a new user for an intervention. for the end-user using a username (or e-mail address) and password. | ||
'''Example''' | '''Example''' | ||
Line 429: | Line 723: | ||
<code>show signup</code> | <code>show signup</code> | ||
<code> | <code>makenewuser(signup.signup_username, signup.signup_password)</code> | ||
In the example above, the information the end-user enters into the interactions <code>signup_username</code> and <code>signup_password</code> is used to create a user account. | |||
The <code>makenewuser</code> command not only creates the new intervention user but it also <i>signs them in at the same time</i>. There is no need to use <code>authenticateuser</code> afterwards. | |||
'''Important:''' the password interaction should always be set to a 'password' interaction type in the properties panel. If it is not set correctly, the password will be visible while you type it and will not be securely encoded when it is saved. This will result in users being unable to log on. | |||
== <code> midnight </code> == | |||
<code> midnight()</code> is similar to <code>currenttime()</code>, but gives the time at midnight earlier today. It is used to set a function for a specific time, for example, you could send an email to an end-user at 7am one week after registering as in the example below. | |||
<code>set delay7am to + (midnight(), 25200, (-1 * currenttime()))</code> | |||
This sets a variable called delay7am to the time at midnight plus 25200 minus the time now. | |||
For example, on 2/9/2016 at 10:30am, this would be 1472774400 + 25200 + (-1 X 1472812200) = -12600 | |||
This logic can be set anywhere in your logic file, but ideally place it at the start of the intervention file with other 'set' logic or immediately before the <code>sendemail</code> logic. | |||
'''delay7am''' can be replaced with a word of your choice. '''25200''' is the number of seconds since midnight (in this case 25200 = 7 hours = 7am). | |||
Your email logic will then look similar to this: | |||
<code> sendemail (append(username,"welcome_email"),username,"You have successfully registered to Stress Less", append("Dear ", loadvalue (username, "firstname"), "\n\n", welcome), (delay7am+604800)) </code> | |||
You will need to add at least one day (in seconds) to delay7am, as if the time is set after 7am, delay7am will be a negative number. In the above example, 1 week is added. | |||
Please note that you will have to take in to consideration time differences in the UK between GMT and BST, and also time differences between the UK and other countries if you are using this function. | |||
== <code> morethan </code> == | == <code> morethan </code> == | ||
This command | The symbol <code> > </code> can also be used. | ||
This command is used when performing calculations in the logic to check if one value is higher than another. | |||
'''Example 1''' | |||
<code>set condition2 if (page1.interaction1 > page1.interaction2) </code> | <code>set condition2 if (page1.interaction1 > page1.interaction2) </code> | ||
'''condition2''' will be set if the value selected for '''interaction1''' is greater than the value selected for '''interaction2'''. | |||
== <code> morethanequal </code> == | == <code> morethanequal </code> == | ||
This command | The symbol <code> >= </code> can also be used. | ||
This command is used when performing calculations in the logic to check if one value is more than or equal to another. | |||
'''Example 1''' | |||
<code>set condition2 if (page1.interaction1 >= page1.interaction2) </code> | <code>set condition2 if (page1.interaction1 >= page1.interaction2) </code> | ||
'''condition2''' will be set if '''interaction1''' is greater than or equal to '''interaction2'''. | |||
== <code> multiply </code> == | == <code> multiply </code> == | ||
The symbol <code> * </code> may also be used. | |||
This command is used when performing calculations to multiply one value by another. It may be taken from: | |||
* an end-user's response to an interaction | |||
* calculations performed elsewhere in the logic | |||
'''Example 1''' | '''Example 1''' | ||
<code>set score1 to (page1.interaction1 * page1.interaction2)</code> | <code>set score1 to (page1.interaction1 * page1.interaction2)</code> | ||
This is taken from an end-user's response to an interaction. The response to '''interaction1''' is multiplied by the response to '''interaction2''' and set as '''score1'''. | |||
'''Example 2''' | '''Example 2''' | ||
<code> set overallscore to (score1 * score2) </code> | |||
<code> | This is taken from a calculation performed elsewhere in the logic ('''score1''' and '''score2''' have been '''set''' previously in the logic). '''score1''' is multiplied by '''score2''' and set as '''overallscore''' | ||
=N= | |||
== <code> named </code> == | |||
This command will 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 <code>named</code> 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 1''' | |||
<code>show page1</code> | |||
[etc, etc] | |||
<code>show page1 named page2</code> | |||
[etc, etc] | |||
<code>show page1 named page3</code> | |||
== <code> not </code> == | == <code> not </code> == | ||
The <code>not</code> command is used to | The <code>not</code> command is used to form the opposite of statement. | ||
'''Example 1''' | '''Example 1''' | ||
Line 467: | Line 826: | ||
<code>set condition1 if (not (page1.interaction1 = "yes"))</code> | <code>set condition1 if (not (page1.interaction1 = "yes"))</code> | ||
'''condition1''' would be set for this user if they did not select '''yes''' for interaction1. We can then use this condition to tailor the rest of the intervention. | |||
'''Note''': | '''Note''': When using '''not''' with interactions, do not confuse <code>not</code> with <code>isempty</code>. The command <code>not</code> is used to refer to a specific response to an interaction that has not been chosen. <code>isempty</code> is used to refer to an interaction that an end-user has not answered. | ||
<code>not</code> and <code>isempty</code> can be used together to refer to an interaction that is not empty (i.e. something has been entered) | <code>not</code> and <code>isempty</code> can be used together to refer to an interaction that is not empty (i.e. something has been entered): | ||
'''Examples 2 and 3:''' | |||
<code> after page1 if (not (isempty (page1.interaction1))) goto page5</code> | <code> after page1 if (not (isempty (page1.interaction1))) goto page5</code> | ||
Or | Or: | ||
<code> set condition1 if (not (isempty (page1.interaction1)))</code> | <code> set condition1 if (not (isempty (page1.interaction1)))</code> | ||
=O= | |||
== <code> or </code> == | |||
Also written as ||. | |||
The <code>or</code> command is used in the same way as the <code>and</code> command. It can be used to check if a user has responded in a particular way to an interaction (or number of interactions): | |||
'''Example 1''' | |||
<code> show page1 | |||
after page1 if (or (page1.interaction1 = "none", page1.interaction1 = "sometimes")) goto page3</code> | |||
This will show '''page3''' if '''none''' or '''sometimes''' is selected as the response to '''interaction1''' on '''page1'''. | |||
'''Example 2''' | |||
<code>savevalue(username, "sport", "cardio") if (or( page1.interaction1 = "running", page2.interaction2 = "swimming"))</code> | |||
This will save the variable '''sport''' if '''running''' is selected for '''interaction1''' on '''page1''' OR if '''swimming''' is selected for '''interaction2''' on '''page2'''. | |||
=P= | |||
== <code> patternmatch </code> == | == <code> patternmatch </code> == | ||
The <code>patternmatch</code> command is used when users are required to enter a specific combination of characters into a text entry interaction, e.g. a study code. The logic <code>patternmatch(characters,interactionname)</code> will check if the characters entered by the user, match the characters that you have pre-defined. | |||
<code>Patternmatch</code> uses "Regular Expressions" to define a pattern of characters. Some basics are described below but for more detailed information, you can find guides to "Regular Expressions" on the Internet. | |||
{| class="wikitable" | |||
!Character !! Example !! Comment | |||
|- | |||
|a | |||
|a | |||
|match a single lower-case character. Can be any character except <code>.?+*[]\^$()|{}</code> | |||
|- | |||
|A | |||
|A | |||
|match a single upper-case character. | |||
|- | |||
|abc | |||
|abc | |||
|match the exact sequence of characters | |||
|- | |||
|. | |||
|a | |||
|. means any character | |||
|- | |||
|a? | |||
|a | |||
|? means zero or one of the preceding character | |||
|- | |||
|a* | |||
|aaa | |||
| * means any number of the preceding character | |||
|- | |||
|a+ | |||
|aaaa | |||
| + means one or more of the preceding character | |||
|- | |||
|[abc]+ | |||
|cab | |||
|[] means any character between the brackets | |||
|- | |||
|[^abc]+ | |||
|fed | |||
|^ in a [] means none of the characters between the brackets | |||
|- | |||
|[0-9] | |||
|1 | |||
|match any number between this range | |||
|- | |||
|[A-Z] | |||
|LIFEGUIDE | |||
|match any uppercase letter between this range | |||
|- | |||
|[a-z] | |||
|lifeguide | |||
|match any lowercase letter between this range | |||
|- | |||
|[A-Za-z]+ | |||
|LifeGuide | |||
|Any uppercase or lowercase letters | |||
|- | |||
|a(bc)+d | |||
|abcbcbcd | |||
|() groups things together | |||
|- | |||
|ab|cd | |||
|cd | |||
|| means 'or' | |||
|} | |||
'''Example 1''' | |||
This function may be useful if you have assigned each participant in your study a different code which they will need to enter in order to take part. This will ensure that only users who have been invited to use the intervention can gain access to it. To do this, you will need to write an error message on the page which contains your text entry interaction e.g. | |||
<code> Show nomatch if( not( patternmatch( “study[0-9][0-9]id[0-9][0-9]”, password ) ) ) </code> | |||
In this example, the error message named '''nomatch''' will be shown to users if they enter a string of characters in the text entry interaction named '''password''' which does not fit with the pattern specified in the square brackets. | |||
The string of characters needed in this example is '''studyxxidxx''', where '''x''' is any number between '''0 and 9'''. | |||
See also [[Adding Error Messages]] (example 7). | |||
'''Example 2''' | |||
The <code>patternmatch</code> function could also be used to direct users to specific conditions, sections or pages within an intervention e.g. | |||
<code> show page1 if (patternmatch(“[0-9][0-9]a[0-9][0-9]”, interaction1)) </code> | |||
<code> show page2 if (patternmatch(“[0-9][0-9]b[0-9][0-9]”, interaction1)) </code> | |||
In this example, if users enter the string xx'''a'''xx, where x represents a number between 0 and 9 they will see '''page 1''' of the intervention. If they enter the string xx'''b'''xx they will see '''page 2''' of the intervention. | |||
Instead of 0-9, you could use [a-z], which means the user will need to enter any letter between a and z in the alphabet. You could also specify [a-z0-9] – this will mean the user will need to enter either a letter or a number. | |||
NB The <code> patternmatch </code>function is '''case sensitive'''. If you specify '''[a-z]''', the user will need to enter a '''lowercase''' letter. If you specify '''[A-Z]''', the user will need to enter an '''uppercase''' letter. If you specify '''[a-zA-Z]''' the user may enter '''either an uppercase or a lower case letter'''. | |||
[[Category: patternmatch]] | |||
== <code> printtime </code> == | == <code> printtime </code> == | ||
The <code>printtime</code> | This command can be used to instruct the intervention to display a particular time or date to the user. It can display the time in many different ways, using letters to display them. | ||
The letters that can be used to display time are: | |||
{| class="wikitable" | |||
|- | |||
! Letter !! Description !! Example | |||
|- | |||
| G || Era designator || AD | |||
|- | |||
| y || Year in two digits || 01 | |||
|- | |||
| yyyy || Year in four digits || 2001 | |||
|- | |||
| M || Month in year || 7 | |||
|- | |||
| MMMM || Month in year || July | |||
|- | |||
| d || Day in month || 10 | |||
|- | |||
| h || Hour in A.M./P.M. || (1~12) 12 | |||
|- | |||
| H || Hour in day || (0~23) 22 | |||
|- | |||
| m || Minute in hour || 30 | |||
|- | |||
| s || Second in minute || 55 | |||
|- | |||
| E || Day in week || Tues | |||
|- | |||
| EEEE || Day in week || Tuesday | |||
|- | |||
| D || Day in year || 360 | |||
|- | |||
| F || Day of week in month || 2 (second Wed. in July) | |||
|- | |||
| w || Week in year || 40 | |||
|- | |||
| W || Week in month || 1 | |||
|- | |||
| a || A.M./P.M. marker || PM | |||
|- | |||
| k || Hour in day (1~24) || 24 | |||
|- | |||
| K || Hour in A.M./P.M. (0~11) || 10 | |||
|} | |||
For digits, e.g. minutes, '''use the number of letters for the number of digits you want to display'''. For example, '''9:01:07''' should be written as <code>h:mm:ss</code> | |||
''Advanced users, please see more options on [http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html#month Java SimpleDateFormat].'' | |||
<code>printtime</code> cannot be used to display the difference between 2 times if the difference is greater than 1 day. To display the difference between 2 times, use <code>comparetimes</code> (see [[#comparetimes]], Example 2). | |||
'''Example 1''' | |||
This example shows how you can use the <code>printtime</code> and <code>currenttime</code> functions to display the time/date a user is shown a specific page of the intervention: | |||
<code>show welcome</code> | |||
<code>set welcome.time to printtime (currenttime (), "H:m d-M-y")</code> | |||
In this example, the word 'time' on the page called 'welcome' has been set as a variable. This logic tells the intervention to display the hour, minute, day, month, and year at which the user is shown the page named 'welcome' in place of the word 'time'. | |||
'''Example 2''' | |||
This example shows you how to add words into <code>printtime</code> and store the result as a user variable. | |||
<code>set midnighttext to printtime (currenttime(), "'When you registered, it was 'H'hrs and 'm' minutes and 's' seconds since midnight'") | |||
savevalue(username, "midnighttext", midnighttext)</code> | |||
To add words and values in between the printtime special letters, use single quotes. Any printtime output can be stored or saved as a user variable, but numbers will always be stored as text and cannot be used in calculations. | |||
'''Example 3''' | |||
This example shows how you can use the <code>printtime</code> function to display particular times or dates that you have saved in your intervention logic, such as the time/date a user signed up for the intervention and the time/date they logged back into the intervention. | |||
<code>show signup</code> | |||
<code>after signup if (and (makenewuser (signup.name, signup.password), savevalue(signup.name, “currentlogintime”, currenttime()))) goto welcome</code> | |||
The first part of this logic tells the intervention to set up an account for the user using the username (signup.name) and password (signup.password) they created (see [[makenewuser]]). The second part of this logic uses the <code>currenttime</code> function to instruct the intervention to save the time/date a user signed up to the intervention as the variable <code>"currentlogintime"</code>. | |||
<code>show welcome</code> | |||
<code>set welcome.signuptime to printtime(loadvalue(signup.name, "currentlogintime"), "H:m d-M-y")</code> | |||
This logic tells the intervention to display the time/date a user signed up to the intervention on the page named 'welcome' in place of the word 'signuptime'. | |||
<code>show login</code> | |||
<code>after login if (and(savevalue(login.name, "lastlogintime", loadvalue(login.name, "currentlogintime")), savevalue(login.name, "currentlogintime", currenttime()))) go to loginhistory</code> | |||
This first part of this logic uses the previously created variable <code>"currentlogintime"</code> to create a new variable called <code>"lastlogintime"</code> – the time at which the user first signed up to the intervention <code>("currentlogintime"</code>) now becomes the time at which they last logged in to the intervention <code>("lastlogintime"</code>). | |||
The second part of this logic uses the <code>currenttime</code> function to re-create a new <code>"currentlogintime"</code> variable. Instead of saving the time at which the user first signed up for the intervention this variable now saves the time the user logged back into the intervention. | |||
<code>show loginhistory</code> | |||
<code>set loginhistory.lastlogintime to printtime (loadvalue(login.name, "lastlogintime"), "H:m d-M-y")</code> | |||
<code>set loginhistiry.currentlogintime to printtime (loadvalue(login.name, "currentlogintime"), "H:m d-M-y")</code> | |||
This logic tells the intervention to display the time a particular user first signed up to the intervention <code>("lastlogintime"</code>) and the time they logged back into the intervention <code>("currentlogintime"</code>) in place of the words ‘lastlogintime’ and ‘currentlogintime’. | |||
'''Example 4''' | |||
In this example, a time that was saved in a previous session is loaded and 1 week (in seconds) added to it: | |||
<code>savevalue (username, "goaltime", midnight())</code> | |||
<code>show examplepage</code> | |||
<code>set examplepage.weeklater to printtime((loadvalue(username,"goaltime")+delay), "E, d/M/y")</code> | |||
The output of this might be '''Tue, 09/08/2016''', a week after the time that the goal was set. | |||
=R= | |||
== <code> randomnumber </code> == | == <code> randomnumber </code> == | ||
Line 490: | Line 1,092: | ||
This command allows you to randomise your users into different groups and always follows the same formula: | This command allows you to randomise your users into different groups and always follows the same formula: | ||
<code> after page1 if (randomnumber (lowestvalue , highestvalue) = value) goto page3</code> | <code> after page1 if (randomnumber (lowestvalue , highestvalue) = </code>value) <code> goto page3</code> | ||
For example: | For example: | ||
Line 506: | Line 1,108: | ||
== <code> replaceall </code> == | == <code> replaceall </code> == | ||
This command | This command replaces text in a string (a string is a variable that you create - it appears in blue in the logic file). | ||
'''Example 1''' | |||
<code>replaceall ("c", "b", "caked car")</code> | |||
This would replace all the '''c's''' in the string to '''b's'''. So this would change '''caked car''' to '''baked bar'''. | |||
'''Example 2''' | |||
This example shows a workaround for showing responses to a single-choice interaction back to the user. A workaround is needed because the '''Unique Response Name''' (not the Response text) is saved and shown to the user when a single-choice drop-down interaction is used. | |||
<code>savevalue (username, "s1_home", replaceall("_", " ", s1_whattodo1.home)) if (or( s1_fatigue.home = "Other_aspects_of_home_life", s1_fatigue.home = "I_find_it_hard_doing_things_around_the_house",s1_fatigue.home = "I_cannot_get_out_and_about_the_way_I_used_to" ))</code> | |||
This example is specific to a drop-down single-choice interaction, where you want to show the response selected for the interaction '''home''' on page '''s1_fatigue''' back to the end-user. All of the '''_''' in each '''Unique Reponse Name''' in the interaction will be replaced with a space, which you can show back to your user. | |||
You can then use feedback boxes and a container to show the responses on a later page: | |||
<code>show s1_fatigue2.home1 if (s1_fatigue.home = "Other_aspects_of_home_life") | |||
show s1_fatigue2.home2 if (s1_fatigue.home = "I_find_it_hard_doing_things_around_the_house") | |||
show s1_fatigue2.home3 if (s1_fatigue.home = "I_cannot_get_out_and_about_the_way_I_used_to")</code> | |||
'''home1''' is a feedback textbox which will be shown on '''s1_fatigue2''' if '''Other_aspects_of_home_life''' was chosen for the interaction '''home''' on page '''s1_fatigue'''. | |||
== <code> resetpassword </code> == | == <code> resetpassword </code> == | ||
This command allows users to reset their password if they forget it. A new password will be emailed to them and they can use it to login. You can create additional pages to allow users to change their password to a personal and memorable one when they next login. | |||
'''Example 1''' | |||
<code>after resetpass if (resetpassword(resetpass.email)) goto resetpass_confirm </code> | |||
This logic will change a user's password if they enter a registered email address into the text-entry box called '''email''', and will show them the '''resetpass_confirm''' page. | |||
Please see the '''Changing and resetting users passwords''' tutorial intervention on the LifeGuide Community Website for a demo showing how this logic is used. | |||
== <code> round </code> == | |||
The <code>round</code> command rounds a number to the nearest whole number. For example, 5.49 rounds down to 5 and 5.5 rounds up to 6. This is useful if you want to calculate values and then present them to the user based on a quiz score. If you want to round a number to multiple decimal places, you should use the <code>decimalplaces</code> command. | |||
'''Example 1''' | |||
In this example we calculate 100 divided by 3 (33.333333). When we display it to the user on <code>examplepage</code> we want it to display 33. | |||
<code>set exactthird to (100/3) | |||
set approxthird to round(exactthird) | |||
show examplepage | |||
set examplepage.number to approxthird</code> | |||
'''Example 2''' | |||
In this example we collect the scores from a 3 item true/false quiz and present the scores as a percentage. | |||
<code> | |||
show exp | |||
if exp.question1="true" set q1 to 1 | |||
if exp.question1="false" set q1 to 0 | |||
if exp.question2="true" set q2 to 0 | |||
if exp.question2="false" set q2 to 1 | |||
if exp.question3="true" set q2 to 1 | |||
if exp.question3="false" set q2 to 0 | |||
set totalscore to (sum(q1,q2,q3)) | |||
set scorepercent to ((totalscore/3)*100) | |||
set scoreround to round(scorepercent) | |||
show results_page | |||
set results_page.score to scoreround | |||
</code> | |||
First we grade the quiz by giving each question a score of 1 (correct) or 0 (wrong). | |||
We then add together the scores using <code>sum</code>. | |||
To calculate the percentage, we divide the total by three and multiply by 100. | |||
We then round the number and display it to the user on the <code>results_page</code>. | |||
'''Example 3''' | |||
In this example we round a large number to the nearest hundred. | |||
<code>set largenumber to 1234567 | |||
set roundnumber to round(largenumber/100) | |||
set largenumbertwo to (roundnumber*100)</code> | |||
This takes the number 1,234,567 then divides it by 100, (12,345.67). | |||
This number is then rounded to 12,346. | |||
The new number is then multiplied by 100 giving 1,234,600. | |||
=S= | |||
== <code> save </code> == | |||
The <code> save </code> key command allows you to save the responses that an end-user enters on a page. This can then be loaded using the <code> load </code> 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: | |||
<code> show page1</code> | |||
<code> save page1 for username</code> | |||
Then, later on in the logic (either in the same session or a later session) the following logic would be used: | |||
<code> show page20</code> | |||
<code> set default page20.interaction2 to load page1.interaction1 for username</code> | |||
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. | |||
== <code> saveandload </code> == | |||
This command is used after a page that contains interactions. If an end-user clicks on a '''next''' button on that page and then returns to it, the page will automatically show them the responses they entered the last time they saw that page. | |||
'''Example 1''' | |||
<code>show page1 | |||
saveandload page1 for username</code> | |||
Any interaction on page1 will be saved and then loaded each time the end-user comes back to that page. | |||
== <code> set </code> == | |||
The <code>set</code> 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 <code>save</code> will need a username to be set. This will need to be done at the start of your logic file. | |||
<code>Set username to login.loginuname</code> | |||
This will set the variable '''username''' to whatever the end-user enters into the interaction uniquely named '''loginuname''' (usually an email address) on the login page. The word '''username''' can then be used any time throughout the logic to refer to the text an end-user entered into that interaction. | |||
'''Example 2''' | |||
You can '''set''' timings in your logic. Setting timings means you can change the timings for testing and change them back again to real-time easily, and it reduces the likelihood of mistakes being made. | |||
In this example, '''twelvemonth''' has been set to the number of seconds in 12 months: | |||
<code>set twelvemonth to "31536000"</code> | |||
You can then use this in your login logic as follows: | |||
<code>after login if (comparetimes(loadvalue(username,"baselinetime"), currenttime(),"seconds") >= twelvemonth) goto studyfinished </code> | |||
The above logic will show the page '''studyfinished''' if it has been more than 12 months since '''baselinelinetime'''. | |||
'''Example 3''' | |||
You can '''set''' text such as an email address to avoid having to type it out each time, e.g. the study coordinator's email address: | |||
<code>set studyemail to "study@soton.ac.uk" </code> | |||
This logic should appear near the top of your logic file. An advantage to using this function this way is that if you decide to change the study coordinator's email address, you only have to change it once (where you '''set''' it). | |||
You can also '''set''' the text and timings in emails: | |||
<code>set 3monthemail to "Thank you for taking part in The Reactivate Study. It is now time to complete your 3 month questionnaire. Your answers are very important to us. Please use the following link to login:\n\nwww.webaddress.co.uk\n\nIf you have any questions about the study, or no longer wish to participate, please contact us on study@soton.ac.uk\n\nFrom The Reactivate Team."</code> | |||
<code>set oneday to "86400" | |||
set oneweek to "604800"</code> | |||
The advantages to setting text in emails are: | |||
* They can be changed easily as you only have to change one line instead of multiple lines throughout your logic. It's common to overlook vital lines if you have many lines of logic and setting text reduces the likelihood of mistakes being made. | |||
* The lines are easy to find as they are placed at the top of the logic file. | |||
Please see the command <code>sendemail</code> for more information on how to write email logic. | |||
'''Example 4''' | |||
The <code>set</code> 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. | |||
<code>show page1</code> | |||
<code>set condition1 to and (page1.chooseoptions contains "optiona", page1.chooseoptions contains "optionc")</code> | |||
<code>after page1 if condition1 goto page3</code> | |||
So in example 2, the variable '''condition1''' is set if end-users select '''optiona''' and '''optionc''' 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 5''' | |||
In this example, the <code>set</code> 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 | |||
<code>set exercisescore to (page1.dailyexercise * 5)</code> | |||
== <code> saveuniquevalue </code> == | |||
The '''saveuniquevalue''' function is used in the same way as the '''savevalue''' function. The only difference is that with '''saveuniquevalue''', if the value entered by an end-user is not unique, the function will return a 'false' input, and you can use this to stop end-users continuing with the intervention until they have entered a value which is unique and you can send the study coordinator an email to alert them of this. | |||
'''Example 1''' | |||
To save and check a variable entered by an end-user is unique: | |||
<code>saveuniquevalue(username, "studyid", page1.interaction1)</code> | |||
'''Example 2''' | |||
If an end-user has entered a response that is not unique, you can allow them to continue with the intervention and send an email to the study coordinator. | |||
<code> after registration if (and(not(saveuniquevalue(username, "studyid", registration.interaction1)), sendemail( append(username,"not_unique"), "study@soton.ac.uk", "Participant - not unique", append("Participant ", loadvalue (username, "idnumber"), "has entered information that is not unique."),10) )) goto registrationfinish </code> | |||
For more information on saveuniquevalue [[How to check whether users have entered a unique value, e.g. Study ID code|please click here]] | |||
[[Category: saveuniquevalue]] | |||
== <code> savevalue </code> == | == <code> savevalue </code> == | ||
The '''savevalue''' command saves a variable that can be loaded again in later sessions. It is used if users have to create an account to access your intervention and you want to save information to a user. | |||
It can be used to: | |||
* create a variable and save it to a user | |||
* save a response a user has given to an interaction | |||
* save the time | |||
* save a questionnaire or session as 'complete' | |||
'''Example 1 - Create and save a text variable''' | |||
<code>savevalue(username, "group", "web_support")</code> | |||
This will save the variable '''web_support''' for a username. '''group''' will be the column heading in your data in the '''User data''' sheet. | |||
When loading this value later in your logic, you will use the command <code>loadvalue</code>, and the variables you have created - '''group''' and '''web_support''': | |||
<code>after page5 if (loadvalue(username, "group") = "web_support") goto page10</code> | |||
'''Example 2 - Create and save a numeric variable''' | |||
<code>savevalue(username, "work", 1)</code>. | |||
This will save '''1''' for the variable '''work'''. '''work''' will be the column heading in your data in the '''User data''' sheet. | |||
You can use this to show feedback on a page in another session: | |||
<code>show s1area.summary if (loadvalue (username, "work")>0) </code> | |||
This logic will show the feedback '''summary''' on page '''s1area''' if the variable '''work''' is more than '''0'''. | |||
'''Example 3 - Save a response a user has given to an interaction''' | |||
<code>savevalue(username, "s1_fatigue", page1.interaction1)</code> | |||
This will save the response given to '''interaction1''' on '''page1''' to the variable '''s1_fatigue''' for the username. | |||
To load this later in your logic, you would use the variable name '''s1_fatigue''': | |||
<code>set page5.fatigue_score to loadvalue (username,"s1_fatigue")</code> | |||
This will load the variable '''s1_fatigue''' and will show it in the text box '''fatigue_score''' on '''page5'''. For this to function correctly, '''fatigue_score''' needs to be [[How to set text as a printed variable| set as a printed variable]]. | |||
'''Example 4 - Save the time''' | |||
<code>savevalue(username, "s1_time", currenttime())</code> | |||
This will save the current time as '''s1_time'''. | |||
You can load this later in your logic to ensure that end-users do not see session 2 until 1 week later: | |||
<code>after login_successful if (comparetimes(loadvalue(username, "s1_time"), currenttime(), "seconds" ) > 604800) goto s2_welcome</code> | |||
'''Example 5 - Save a questionnaire or session as complete''' | |||
<code>savevalue(username, "baselinecomplete", "yes")</code> | |||
This will create the variable '''baselinecomplete''' and will save '''yes'''. In this example, you can use a number instead of '''yes''': | |||
<code>savevalue(username, "baselinecomplete", "1")</code> | |||
You can load this in your logic to check that an end-user has completed their baseline questionnaire: | |||
<code>after login_successful if (and( hasseen(username, "qintro"), (isempty(loadvalue(username, "baselinecomplete"))) )) goto q_notcomplete </code> | |||
This will show the page '''q_notcomplete''' if the end-user has seen '''qintro''', but the variable '''baselinecomplete''' is empty (because the baseline questionnaire has not yet been completed). | |||
== <code> sendemail </code> == | == <code> sendemail </code> == | ||
This is the command for setting up e-mails to send out to | This is the command for setting up e-mails to send out to end-users at specific points in the intervention. The function for sending out an e-mail always uses the same basic formula: | ||
<code>after pagename1 if sendemail(append(username,"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</code> | |||
'''Example 1''' | |||
<code>sendemail (append(username,"welcome_email"),username,"You have successfully registered to Stress Less", append("Dear ", loadvalue (username, "firstname"), "\n\n", welcome), 10)</code> | |||
<code> | In this example, the first part of the logic ,<code>(append(username,"welcome_email")</code>, is the unique name of the email. The '''append''' function joins the '''username''' to the name of the email ('''welcome_email''') to make sure that every email is unique. If the append function is not used, every email will be called '''welcome_email''' and only the first one will be unique - the other emails will not be unique and will not be sent out. | ||
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. | 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. | ||
Line 539: | Line 1,434: | ||
* there is a restriction for how long a text message can be | * there is a restriction for how long a text message can be | ||
<code>after page1 if | <code>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</code> | ||
'''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. | '''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. | ||
== <code> stringlength </code> == | == <code> stringlength </code> == | ||
This command tells the intervention how many characters a user has entered into a free text interaction. | |||
This can be useful if you want your users to create usernames that are a specific number of characters. | |||
To use this function you will need to write an error message: | |||
<code>show namemessage if (stringlength (username) < 5)</code> | |||
In this example, the error message called “namemessage” will be shown to users if they have entered less than 5 characters in the interaction called “username”. | |||
[[Category:Stringlength]] | |||
[[Category:Error Messages]] | |||
== <code> sum </code> == | == <code> sum </code> == | ||
Please see <code>add</code> | |||
== <code> show </code> == | |||
The <code>show</code> command is the first logic command you will need to know. It is also probably the most common one that you will use. | |||
This command shows each of the pages you have created. Pages will be shown in the order they are written 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''' | |||
<code>show page1 | |||
show page2 | |||
show page3 | |||
show page4</code> | |||
In the example above, the end-user will be shown the page named ‘page1’. When they click on the next button on '''page1''', they will see the page called ''page2’''. This is followed by ‘''page3’'' and finally ‘''page4’''. | |||
'''NB Before you can preview your intervention, you will need to have the '''show''' 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''' command once for each page. However, you can re-show the same page to users - see the <code>named</code> command above for more details. | |||
You can also reshow pages to your end-user by using a jump button on a previous page. | |||
=T= | |||
== <code> timesincelogin </code> == | == <code> timesincelogin </code> == | ||
This command can be used to show users how much time has passed since they last logged into the intervention. | |||
'''Example''' | |||
Using the <code> timesincelogin </code> 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: | |||
<code> show </code> 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: | |||
<code> set </code> username <code> to </code> login.name | |||
<code> if </code> (<code>not</code>(<code>isempty</code> (signup.name))) <code> set </code> username <code> to </code> 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 [[1.12 set]]) | |||
'''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 <code> timesincelogin </code> command. | |||
<code> set </code> time.secs to <code> timesincelogin </code> (username, <code> "seconds"</code>) | |||
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. | |||
== <code> to </code> == | |||
The <code>to</code> key command is used with the <code>set</code> key command to set variables. | |||
=U= | |||
== <code> urlencode </code> == | |||
<code> urlencode(string) </code> | |||
This is an a function for advanced users. It returns a URL encoded version of a string and should be used only when creating a dynamic URL (i.e. using a variable). It is used when the variable might contain non alphanumeric characters. It converts a string into the correct format to prevent usual characters from breaking the link. This is because certain characters (such as ? and &) have special functions when included in a URL and have to be encoded in a different format (e.g. the & symbol gets converted to %26). | |||
URL encoding is common and you will find more information here: http://en.wikipedia.org/wiki/Percent-encoding |
Latest revision as of 10:49, 13 July 2018
A quick reference guide to LifeGuide logic. For more detailed information, please refer to the How to... Guide.
It is important to insert Next buttons on your pages (instead of Jump buttons) whenever possible in order for your logic to work correctly. If you show a page and have a vital line of logic written after you show that page (such as randomisation or saving logic), or have error messages on that page, your intervention will not work correctly if you use a Jump button - you will jump to another page and skip parts of the logic in your logic file and Error Messages section.
A
add
This may also be written as sum or +. The add command is used when performing calculations in the logic. It is used to add together more than two values.
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)
For simple addition or subtract calculations +
and -
can be used normally.
For example:
set score to (100 - page1.interaction1)
Make sure you leave a space between the numbers/variables and the subtraction symbol.
after
The after command is used after a page to perform functions that relate to that page.
It is likely that you will use this command quite regularly in your intervention logic. The most common way of using the after command is with the if and goto commands, e.g.
show page1
after page1 if (any_commands_you_want_to_relate_to_this_page) goto page3
Example 1
after page1 if (page1.interaction1 = "yes") goto page3
show page 2
show page3
In the above example, the end-user will be directed to page3 if they have answered yes to interaction1 on page1. If they answer no to interaction1, they will be directed to the next line of logic and will see page2.
NB If you use the after
command with the goto
command, the page that you goto should NOT be the next page shown in your logic, it should be a page further down in your logic as in the example above.
As will be seen throughout this dictionary, any command can be used with the after command.
and
Can also be written as &&.
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 page6 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.
Example 2
after login_successful if (and( not(hasseen(username, "q_demographics")), (isempty (loadvalue(username, "baselinecomplete"))) )) goto q_intro
End-users will be shown q_intro if they have not seen page q_demographics and if the variable baselinecomplete is empty (i.e. the variable baselinecomplete hasn't been saved because the end-user hasn't finished the baseline questionnaire).
append
The append
command allows you to attach logic commands together, and/or to attach a variable to a string (a string is something that you create - a sequence of characters between quotation marks, e.g. "session1".
append
is most often used with the logic commands sendemail
and cancelemail
Example 1
sendemail (append(username,"user_reg1"), username, "StressLess - Session 1 is ready", append("Dear ", loadvalue (username, "personsname"), "\n\n", reg_part1, reg_part2), 10)
In this example, append is used to attach:
- a username (which has been set in a previous part of the logic) to the unique name of the email message:
append (username,"user_reg1")
- a user's name to the text used in an email message (the append function here allows the content of the email message to be made of different parts):
append ("Dear ", loadvalue (username, "personsname"), "\n\n", reg_part1, reg_part2)
The \n\n in the logic above means a new line in the email message content.
Example 2
cancelemail (append("user_regs2rem", username), username)
In this example, append is used to attach:
- a username to the unique name of the email message:
append ("user_regs1", username)
Example 3
Append is not only useful for emails. It can be used to combine interactions and other parts of text and save values. For example:
set fullname to append(registration.firstname, " ",registration.surname)
savevalue(username,"fullname", fullname)
This code takes the interaction items "firstname" and "surname" from the registration page and combines them into a fullname.
Important: When you use append in this way, make sure you add a string i.e. a letter, number or space in quotation marks like "a" or it may not work!
Example 4
In this example, we add information to a previously saved value:
savevalue(username, "oldgoals","RESULTS_") if isempty(loadvalue(username,"oldgoals"))
set oldgoals to loadvalue(username,"oldgoals")
savevalue(username, "oldgoals", (append(oldgoals,"_", printtime(currenttime(),"dMy"),"_", goalsetpage.newgoal)))
First, we create the variable "oldgoals" and save it if it doesn't exist. We then set oldgoals to load this value. Lastly, we save the value oldgoals again, appending the old value of "oldgoals", adding the date the new value is being added and adding the value of the newgoal set on the page "goalsetpage". Underscores are used to separate the data and make it more readable. This will create a user variable like this, that gets longer over time:
"RESULTS_181016_firstgoal_191016_secondgoal_221016_thirdgoal"
authenticateuser
This is important logic for ensuring that a user is registered with the intervention and is written directly after the show login logic. This logic should be used with the makenewuser
logic function, which creates a new user.
The authenticateuser
command can be used in the logic (intervention.lgil) file or in the Error Message logic.
Example 1
show login
after login if (authenticateuser (login.username, login.password)) goto login_confirmation
show login_fail
show login_confirmation
The logic in this example is written in the logic file. The details that the end-user enters into the username and password interactions on the login page will be used to check they are a registered user. If they are not a registered user, they will be shown the login_fail page.
Example 2
show err1 if (isempty(username))
show err2 if (not(authenticateuser(username, password)))
The logic in this example is written in the Error Messages tab of a page. The details that the end-user enters into the username and password interactions on the login page will be used to check they are a registered user. If they are not a registered user, they will be shown the error message err2 and will not be able to proceed to the next page.
B
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
andend
- 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.
The 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 section relieve. The final end
will end the section stress.
C
cancelemail
Used to cancel an email that has been set up earlier in the logic.
You may want to:
- cancel emails to end-users (e.g. if you set up email reminders for end-users to login to upcoming sessions, you will need to cancel them if they login before the email is due to be sent.
- cancel emails to the study coordinator (e.g. if you set up email reminders to notify the study coordinator when end-users do not complete study questionnaires, you will need to cancel them if they complete the questionnaires.
This command uses the same basic formula:
cancelemail (append(username, "unique_email_name", e-mail address))
Example 1
cancelemail(append(username, "email_session2r"), username)
This will cancel the email email_session2r for an end-user. The append function links an end-user's username to the name of the email (email_session2r) to give each email a unique name.
Example 2
cancelemail(append(username,"q1_notcomplete"), "study@test.ac.uk")
This will cancel the email q1_notcomplete that was due to be sent to study@test.ac.uk. The append function links an end-users username to the name of the email (q1_notcompleteto) to give each email a unique name.
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
Enables end-users to change their password.
Please see the LifeGuide Community Website for a tutorial intervention that shows how to create the pages and write the logic for this.
Example 1
after passworddetails if changepassword (username, passworddetails.old, passworddetails.new) goto confirmchange
This will allow a password to be changed if the old password is correctly entered into the interaction called old on page passworddetails, and a new password is entered into the interaction called new on page passworddetails.
checkemailvalidity
Checks that the e-mail address a user has entered contains an @ symbol.
This command is used with an error message and is written in the Error Messages tab (please refer to Adding Error Messages for information about writing error messages).
Example 1
show invalidemail if (not (checkemailvalidity (email)))
invalidemail is the name of an 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 a user has entered begins with +44 or '0.
This command is used with an error message (please see Adding error messages for more information.
Example 1
show invalidnumber 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 error messages to check the correct numbers are entered for international numbers.
checkuserenabled
checkuserexists
This command checks whether an email address or username has already been registered with the intervention (i.e. if the details that have been entered are already registered with another user). This command is often used with an error message (please see the How to guide for details on how to write error messages)
Example 1
show registeredemail if (checkuserexists (email))
In this example registeredemail is the name of the error message that would show if a user enters an email address that has already been registered in the text box called email.
comparetimes
This command can be used to compare two points in time. It can also be used to convert a number of seconds to days, hours, minutes and seconds (see Example 2).
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 text-entry interactions to allow end-users to enter their email address and password)
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 currenttime), 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.
Example 2
In this example we use comparetimes
to convert the difference between two times to weeks, days, hours, minutes and seconds to tell the user how long they need to wait before features of the intervention are unlocked. In this example, we display the time until Christmas 2016.
set timenow to (currenttime())
set christmas to (1482624000)
set weeks to (comparetimes(timenow,christmas,"weeks"))
set days to (comparetimes(timenow,christmas,"days"))
set hrs to (comparetimes(timenow,christmas,"hours"))
set mins to (comparetimes(timenow,christmas,"minutes"))
set days2 to (days - (weeks*7))
set hrs2 to (hrs - (days*24))
set mins2 to (mins - (hrs*60))
set secs to ((christmas - timenow) - (mins*60))
This logic first uses comparetimes
to set variables - the time between now and Christmas in weeks, days, hours and minutes. However, we want to display the time between now and Christmas as a whole, not the total number of days, total number of hours, total number of minutes and total number of seconds.
We need to set the number of days to the total number of days minus the days in the weeks that we have already counted, so that the number of days is less than 7. We do the same for hours and minutes.
For seconds, we simply calculate the difference between christmas and now and subtract the total number seconds in minutes that we have already set. You don't need to use comparetimes
for calculating the difference in seconds as currenttime
is already in seconds.
To display the time between now and Christmas on a page, the following logic can be used:
show intro
set intro.hrs to hrs2
set intro.mins to mins2
set intro.secs to secs
set intro.days to days2
set intro.weeks to weeks
contains
Used with multiple-choice interactions. It is used to show tailored information based on a specific response an end-user has given.
Example 1
after page1 if (page1.exercise contains "none") goto page4
In this example, the end-user will be directed to page4 if they had selected none to the interaction exercise on page1.
Example 2
after page1 if (or( page1.exercise contains "1day", page1.exercise contains "2days" )) goto page4
An end-user will be shown page4 if they selected 1day or 2days to the interaction exercise on page1.
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
This command instructs the intervention logic to load or save the time as it is at that particular moment.
The currenttime
function can be used to create new variables which save the time at which users completed a particular session of the intervention.
1. In your logic, you will first need to create a new variable (e.g. “username”) which will tell the intervention which particular user a time is being saved 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”, “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 1.12 set)
2. Using the “username” variable you have just created, you can then save the time at which each user completes a particular section of your intervention, in this case ‘session 3’:
show session3
after session3 if ( savevalue ( username, “session3time”, currenttime ( ) ) )goto session3end
show session3end
Here, the logic instructs the intervention to save the time at the particular moment a user completes the session 3 page. The saved time is represented as a new variable called "session3time".
3. The currenttime
function can also be used as a comparison or reference point. This is particularly useful if you want to put time controls on when users can access particular sessions of the website (see also 2.12 comparetimes):
after mainpage if ( comparetimes ( loadvalue ( username, "session3time" ), currenttime ( ), "minutes" ) >= 120 ) goto session4
This line tells the intervention that the user can continue to session 4 of the intervention if it has been at least two hours since they completed session 3
after mainpage if ( comparetimes ( loadvalue ( username, "session3time" ), currenttime ( ), "minutes" ) <= 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 hours since they completed session 3. Users are directed to a “waitpage” instead.
You may have noticed that the currenttime
function is always followed by (). These empty brackets tell the intervention that currenttime
should act as a logic function rather than an intervention variable that you have created yourself.
D
decimalplaces
This command will round a number to a specified number of decimal places. For example, it would round 6.6666666 to 6.67 if 2 decimal places was selected or 6.6667 for 4 decimal places. If you want to round a number to 0 decimal places (i.e. you want a whole number), the simpler round
command can be used.
You cannot use decimalplaces
to abbreviate whole numbers to a number of significant figures (e.g. setting 1,234,567 to 1,234,600) by asking for a negative number of decimal places; a negative number of decimal places will be treated as 0 decimal places. This can be done using round
(see example 3 of round
).
Example 1
In this example we shorten a long decimal number to 4 decimal places.
set numberpi to decimalplaces(3.1415926,4)
This will set the value of numberpi
to 3.1416.
Example 2
In this example we calculate the area of a circle and return the answer to 2 decimal places.
show circle_page
set cradius to circle_page.radius
set pi to 3.14159
set carea to ((cradius*cradius)*pi)
set careashort to decimalplaces(carea,2)
show results_page
set results_page.circle to careashort
Firstly we get the radius from the user's interaction on circle_page
.
Then we set the value of pi.
Then we calculate the area of the circle using the formula area=pi*(radius*radius).
We then shorten the value back to 2 decimal places. We still have the full value stored in case we want to calculate things with it later on - like the volume of a cylinder.
On results_page
we show the user the area of the circle, to 2 decimal places.
default
This is used to set an interaction element to a previously saved value. This is used in conjunction with the save
command - see save
for an example.
To recall information from the same page, use the saveandload
command.
divide
The symbol /
can also be used. The command divide
is used when performing calculations.
Example 1
set score1 to (page1.interaction1 / page1.interaction2)
score1 would be the result of dividing the response given in interaction1 by the response given in interaction2.
Example 2
set overallscore to (score1 / score2)
In this example, overallscore is calculated by dividing score1 by score2, where score1 and score2 have already been calculated elsewhere in the logic.
E
else
else
is used only with if
. It allows you to do something if a condition is Not met. For example:
if not(or(isempty(page1.q1),isempty(page1.q2))) set page1_complete to 1
else set page1_complete to 0
This page checks if both the interactions on page1 have been answered. If they have, page1_complete is set to 1. The else
logic on the next line sets page1_complete to 0 if the interactions have not been answered.
end
Please see begin
for details of how to use end
. The end
command is always used with the begin
command.
F
for
The for
key command is used with the save
and graph
key commands.
G
getuserid
This function gives you the database ID for a user, which is a number that is unique to each LifeGuide server. This number is automatically generated and can be used to uniquely identify a user without having to refer to their identifier (i.e. username). This number can also be included in your data export by ticking the User Number box when you export your data.
Example 1
getuserid(username)
goto
The goto
command is always used with the after
command. It tells the logic which page the user should goto after that line. See after
for details.
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.
H
hasseen
hasseen
is used to show end-users pages based on what they have or have not seen before.
Tip - if you have more than one session in your intervention, we recommend that you use savevalue and loadvalue instead of hasseen as these values can be edited after your intervention has gone live (this is useful in case something goes wrong in your intervention).
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 page s1welcome. The next time they log in, because they have already seen the s1welcome page, the logic will skip that line and show s2welcome because they have not yet seen the s2welcome page.
Example 2
The hasseen logic can also be used without not
, to tailor the intervention for users.
For example, you may want to show a page only if an end-user has seen a previous page.
show s1_feeback2 if (hasseen (username, "s1_feedback1")))
show s1_feeback3 if (hasseen (username, "s1_feedback2")))
Using hasseen in sessions
You can use the hasseen logic in one of three ways:
show session2.interaction1 if (hasseen (username, "session1final"))
This will show the end-user interaction1 if they have seen session1final in any session EXCEPT the one they are currently in (i.e. in previous sessions only).
show session2.interaction1 if (hasseen (username, "session1final", "true"))
Adding true to the hasseen command will show interaction1 if the end-user has seen session1final in ANY session, INCLUDING the current one.
show session2.interaction1 if (hasseen (username, "session1final", "this"))
Adding this to the hasseen command will show interaction1 if the end-user has seen session1final in the current session ONLY.
hmacencode
hmacencode
is an advanced logic command that encrypts data. It is used to obscure data so that it cannot be read. You cannot decrypt anything encrypted using hmacencode
.
set encoded to hmacencode("This message is encoded", "secret")
The primary use for hmacencode
is to check that data passed from one intervention to another has not been corrupted.
I
if
The if
command is always used with another command (e.g. after, show). It is a conditional command so it should always be followed by a true or false statement (i.e. a statement that will be carried out if it is true OR a statement that will be carried out if it is false).
isempty
This command checks whether a response has been given to an interaction (i.e. if a response has not been given, the interaction isempty).
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, the variable none will be set.
L
load
Please see the save
command for more details. The load
command is always used with the save command.
loadvalue
The loadvalue command is always used with the savevalue command. It loads the value that you have previously saved. Please see the savevalue command for more details.
lessthan
The symbol <
can also be used.
This command is used when
- performing calculations in the logic to check if one value is lower than another
- comparing time to check if one time occurs before another time (e.g. comparing the current time to the time the previous session was completed to check that one week has passed.
Example 1
set condition1 if (page1.interaction1 < page1.interaction2)
Example 2
after login if (comparetimes (loadvalue(username, "session1_time"), currenttime(), "seconds" ) < 86400)
lessthanequal
The symbol <=
can also be used.
This command is used in the same way as lessthan. It is used when:
- performing calculations in the logic to check if one value is lower than another
- comparing time to check if one time occurs before another time (e.g. comparing the current time to the time the previous session was completed to check that one week has passed.
Example 1
set condition1 if (page1.interaction1 <= page1.interaction2)
Example 2
after login if (comparetimes (loadvalue(username, "session1_time"), currenttime(), "seconds" ) <= 86400)
M
makenewuser
The makenewuser
command is used to set up a new user for an intervention. for the end-user using a username (or e-mail address) and password.
Example
show signup
makenewuser(signup.signup_username, signup.signup_password)
In the example above, the information the end-user enters into the interactions signup_username
and signup_password
is used to create a user account.
The makenewuser
command not only creates the new intervention user but it also signs them in at the same time. There is no need to use authenticateuser
afterwards.
Important: the password interaction should always be set to a 'password' interaction type in the properties panel. If it is not set correctly, the password will be visible while you type it and will not be securely encoded when it is saved. This will result in users being unable to log on.
midnight
midnight()
is similar to currenttime()
, but gives the time at midnight earlier today. It is used to set a function for a specific time, for example, you could send an email to an end-user at 7am one week after registering as in the example below.
set delay7am to + (midnight(), 25200, (-1 * currenttime()))
This sets a variable called delay7am to the time at midnight plus 25200 minus the time now.
For example, on 2/9/2016 at 10:30am, this would be 1472774400 + 25200 + (-1 X 1472812200) = -12600
This logic can be set anywhere in your logic file, but ideally place it at the start of the intervention file with other 'set' logic or immediately before the sendemail
logic.
delay7am can be replaced with a word of your choice. 25200 is the number of seconds since midnight (in this case 25200 = 7 hours = 7am).
Your email logic will then look similar to this:
sendemail (append(username,"welcome_email"),username,"You have successfully registered to Stress Less", append("Dear ", loadvalue (username, "firstname"), "\n\n", welcome), (delay7am+604800))
You will need to add at least one day (in seconds) to delay7am, as if the time is set after 7am, delay7am will be a negative number. In the above example, 1 week is added.
Please note that you will have to take in to consideration time differences in the UK between GMT and BST, and also time differences between the UK and other countries if you are using this function.
morethan
The symbol >
can also be used.
This command is used when performing calculations in the logic to check if one value is higher than another.
Example 1
set condition2 if (page1.interaction1 > page1.interaction2)
condition2 will be set if the value selected for interaction1 is greater than the value selected for interaction2.
morethanequal
The symbol >=
can also be used.
This command is used when performing calculations in the logic to check if one value is more than or equal to another.
Example 1
set condition2 if (page1.interaction1 >= page1.interaction2)
condition2 will be set if interaction1 is greater than or equal to interaction2.
multiply
The symbol *
may also be used.
This command is used when performing calculations to multiply one value by another. It may be taken from:
- an end-user's response to an interaction
- calculations performed elsewhere in the logic
Example 1
set score1 to (page1.interaction1 * page1.interaction2)
This is taken from an end-user's response to an interaction. The response to interaction1 is multiplied by the response to interaction2 and set as score1.
Example 2
set overallscore to (score1 * score2)
This is taken from a calculation performed elsewhere in the logic (score1 and score2 have been set previously in the logic). score1 is multiplied by score2 and set as overallscore
N
named
This command will 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
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 1
show page1
[etc, etc]
show page1 named page2
[etc, etc]
show page1 named page3
not
The not
command is used to form the opposite of statement.
Example 1
set condition1 if (not (page1.interaction1 = "yes"))
condition1 would be set for this user if they did not select yes for interaction1. We can then use this condition to tailor the rest of the intervention.
Note: When using not with interactions, do not confuse not
with isempty
. The 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):
Examples 2 and 3:
after page1 if (not (isempty (page1.interaction1))) goto page5
Or:
set condition1 if (not (isempty (page1.interaction1)))
O
or
Also written as ||.
The or
command is used in the same way as the and
command. It can be used to check if a user has responded in a particular way to an interaction (or number of interactions):
Example 1
show page1
after page1 if (or (page1.interaction1 = "none", page1.interaction1 = "sometimes")) goto page3
This will show page3 if none or sometimes is selected as the response to interaction1 on page1.
Example 2
savevalue(username, "sport", "cardio") if (or( page1.interaction1 = "running", page2.interaction2 = "swimming"))
This will save the variable sport if running is selected for interaction1 on page1 OR if swimming is selected for interaction2 on page2.
P
patternmatch
The patternmatch
command is used when users are required to enter a specific combination of characters into a text entry interaction, e.g. a study code. The logic patternmatch(characters,interactionname)
will check if the characters entered by the user, match the characters that you have pre-defined.
Patternmatch
uses "Regular Expressions" to define a pattern of characters. Some basics are described below but for more detailed information, you can find guides to "Regular Expressions" on the Internet.
Character | Example | Comment |
---|---|---|
a | a | match a single lower-case character. Can be any character except .?+*[]\^$()|{}
|
A | A | match a single upper-case character. |
abc | abc | match the exact sequence of characters |
. | a | . means any character |
a? | a | ? means zero or one of the preceding character |
a* | aaa | * means any number of the preceding character |
a+ | aaaa | + means one or more of the preceding character |
[abc]+ | cab | [] means any character between the brackets |
[^abc]+ | fed | ^ in a [] means none of the characters between the brackets |
[0-9] | 1 | match any number between this range |
[A-Z] | LIFEGUIDE | match any uppercase letter between this range |
[a-z] | lifeguide | match any lowercase letter between this range |
[A-Za-z]+ | LifeGuide | Any uppercase or lowercase letters |
a(bc)+d | abcbcbcd | () groups things together |
ab|cd | cd | | means 'or' |
Example 1
This function may be useful if you have assigned each participant in your study a different code which they will need to enter in order to take part. This will ensure that only users who have been invited to use the intervention can gain access to it. To do this, you will need to write an error message on the page which contains your text entry interaction e.g.
Show nomatch if( not( patternmatch( “study[0-9][0-9]id[0-9][0-9]”, password ) ) )
In this example, the error message named nomatch will be shown to users if they enter a string of characters in the text entry interaction named password which does not fit with the pattern specified in the square brackets.
The string of characters needed in this example is studyxxidxx, where x is any number between 0 and 9.
See also Adding Error Messages (example 7).
Example 2
The patternmatch
function could also be used to direct users to specific conditions, sections or pages within an intervention e.g.
show page1 if (patternmatch(“[0-9][0-9]a[0-9][0-9]”, interaction1))
show page2 if (patternmatch(“[0-9][0-9]b[0-9][0-9]”, interaction1))
In this example, if users enter the string xxaxx, where x represents a number between 0 and 9 they will see page 1 of the intervention. If they enter the string xxbxx they will see page 2 of the intervention.
Instead of 0-9, you could use [a-z], which means the user will need to enter any letter between a and z in the alphabet. You could also specify [a-z0-9] – this will mean the user will need to enter either a letter or a number.
NB The patternmatch
function is case sensitive. If you specify [a-z], the user will need to enter a lowercase letter. If you specify [A-Z], the user will need to enter an uppercase letter. If you specify [a-zA-Z] the user may enter either an uppercase or a lower case letter.
printtime
This command can be used to instruct the intervention to display a particular time or date to the user. It can display the time in many different ways, using letters to display them.
The letters that can be used to display time are:
Letter | Description | Example |
---|---|---|
G | Era designator | AD |
y | Year in two digits | 01 |
yyyy | Year in four digits | 2001 |
M | Month in year | 7 |
MMMM | Month in year | July |
d | Day in month | 10 |
h | Hour in A.M./P.M. | (1~12) 12 |
H | Hour in day | (0~23) 22 |
m | Minute in hour | 30 |
s | Second in minute | 55 |
E | Day in week | Tues |
EEEE | Day in week | Tuesday |
D | Day in year | 360 |
F | Day of week in month | 2 (second Wed. in July) |
w | Week in year | 40 |
W | Week in month | 1 |
a | A.M./P.M. marker | PM |
k | Hour in day (1~24) | 24 |
K | Hour in A.M./P.M. (0~11) | 10 |
For digits, e.g. minutes, use the number of letters for the number of digits you want to display. For example, 9:01:07 should be written as h:mm:ss
Advanced users, please see more options on Java SimpleDateFormat.
printtime
cannot be used to display the difference between 2 times if the difference is greater than 1 day. To display the difference between 2 times, use comparetimes
(see #comparetimes, Example 2).
Example 1
This example shows how you can use the printtime
and currenttime
functions to display the time/date a user is shown a specific page of the intervention:
show welcome
set welcome.time to printtime (currenttime (), "H:m d-M-y")
In this example, the word 'time' on the page called 'welcome' has been set as a variable. This logic tells the intervention to display the hour, minute, day, month, and year at which the user is shown the page named 'welcome' in place of the word 'time'.
Example 2
This example shows you how to add words into printtime
and store the result as a user variable.
set midnighttext to printtime (currenttime(), "'When you registered, it was 'H'hrs and 'm' minutes and 's' seconds since midnight'")
savevalue(username, "midnighttext", midnighttext)
To add words and values in between the printtime special letters, use single quotes. Any printtime output can be stored or saved as a user variable, but numbers will always be stored as text and cannot be used in calculations.
Example 3
This example shows how you can use the printtime
function to display particular times or dates that you have saved in your intervention logic, such as the time/date a user signed up for the intervention and the time/date they logged back into the intervention.
show signup
after signup if (and (makenewuser (signup.name, signup.password), savevalue(signup.name, “currentlogintime”, currenttime()))) goto welcome
The first part of this logic tells the intervention to set up an account for the user using the username (signup.name) and password (signup.password) they created (see makenewuser). The second part of this logic uses the currenttime
function to instruct the intervention to save the time/date a user signed up to the intervention as the variable "currentlogintime"
.
show welcome
set welcome.signuptime to printtime(loadvalue(signup.name, "currentlogintime"), "H:m d-M-y")
This logic tells the intervention to display the time/date a user signed up to the intervention on the page named 'welcome' in place of the word 'signuptime'.
show login
after login if (and(savevalue(login.name, "lastlogintime", loadvalue(login.name, "currentlogintime")), savevalue(login.name, "currentlogintime", currenttime()))) go to loginhistory
This first part of this logic uses the previously created variable "currentlogintime"
to create a new variable called "lastlogintime"
– the time at which the user first signed up to the intervention ("currentlogintime"
) now becomes the time at which they last logged in to the intervention ("lastlogintime"
).
The second part of this logic uses the currenttime
function to re-create a new "currentlogintime"
variable. Instead of saving the time at which the user first signed up for the intervention this variable now saves the time the user logged back into the intervention.
show loginhistory
set loginhistory.lastlogintime to printtime (loadvalue(login.name, "lastlogintime"), "H:m d-M-y")
set loginhistiry.currentlogintime to printtime (loadvalue(login.name, "currentlogintime"), "H:m d-M-y")
This logic tells the intervention to display the time a particular user first signed up to the intervention ("lastlogintime"
) and the time they logged back into the intervention ("currentlogintime"
) in place of the words ‘lastlogintime’ and ‘currentlogintime’.
Example 4
In this example, a time that was saved in a previous session is loaded and 1 week (in seconds) added to it:
savevalue (username, "goaltime", midnight())
show examplepage
set examplepage.weeklater to printtime((loadvalue(username,"goaltime")+delay), "E, d/M/y")
The output of this might be Tue, 09/08/2016, a week after the time that the goal was set.
R
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 replaces text in a string (a string is a variable that you create - it appears in blue in the logic file).
Example 1
replaceall ("c", "b", "caked car")
This would replace all the c's in the string to b's. So this would change caked car to baked bar.
Example 2
This example shows a workaround for showing responses to a single-choice interaction back to the user. A workaround is needed because the Unique Response Name (not the Response text) is saved and shown to the user when a single-choice drop-down interaction is used.
savevalue (username, "s1_home", replaceall("_", " ", s1_whattodo1.home)) if (or( s1_fatigue.home = "Other_aspects_of_home_life", s1_fatigue.home = "I_find_it_hard_doing_things_around_the_house",s1_fatigue.home = "I_cannot_get_out_and_about_the_way_I_used_to" ))
This example is specific to a drop-down single-choice interaction, where you want to show the response selected for the interaction home on page s1_fatigue back to the end-user. All of the _ in each Unique Reponse Name in the interaction will be replaced with a space, which you can show back to your user.
You can then use feedback boxes and a container to show the responses on a later page:
show s1_fatigue2.home1 if (s1_fatigue.home = "Other_aspects_of_home_life")
show s1_fatigue2.home2 if (s1_fatigue.home = "I_find_it_hard_doing_things_around_the_house")
show s1_fatigue2.home3 if (s1_fatigue.home = "I_cannot_get_out_and_about_the_way_I_used_to")
home1 is a feedback textbox which will be shown on s1_fatigue2 if Other_aspects_of_home_life was chosen for the interaction home on page s1_fatigue.
resetpassword
This command allows users to reset their password if they forget it. A new password will be emailed to them and they can use it to login. You can create additional pages to allow users to change their password to a personal and memorable one when they next login.
Example 1
after resetpass if (resetpassword(resetpass.email)) goto resetpass_confirm
This logic will change a user's password if they enter a registered email address into the text-entry box called email, and will show them the resetpass_confirm page.
Please see the Changing and resetting users passwords tutorial intervention on the LifeGuide Community Website for a demo showing how this logic is used.
round
The round
command rounds a number to the nearest whole number. For example, 5.49 rounds down to 5 and 5.5 rounds up to 6. This is useful if you want to calculate values and then present them to the user based on a quiz score. If you want to round a number to multiple decimal places, you should use the decimalplaces
command.
Example 1
In this example we calculate 100 divided by 3 (33.333333). When we display it to the user on examplepage
we want it to display 33.
set exactthird to (100/3)
set approxthird to round(exactthird)
show examplepage
set examplepage.number to approxthird
Example 2
In this example we collect the scores from a 3 item true/false quiz and present the scores as a percentage.
show exp
if exp.question1="true" set q1 to 1
if exp.question1="false" set q1 to 0
if exp.question2="true" set q2 to 0
if exp.question2="false" set q2 to 1
if exp.question3="true" set q2 to 1
if exp.question3="false" set q2 to 0
set totalscore to (sum(q1,q2,q3))
set scorepercent to ((totalscore/3)*100)
set scoreround to round(scorepercent)
show results_page
set results_page.score to scoreround
First we grade the quiz by giving each question a score of 1 (correct) or 0 (wrong).
We then add together the scores using sum
.
To calculate the percentage, we divide the total by three and multiply by 100.
We then round the number and display it to the user on the results_page
.
Example 3
In this example we round a large number to the nearest hundred.
set largenumber to 1234567
set roundnumber to round(largenumber/100)
set largenumbertwo to (roundnumber*100)
This takes the number 1,234,567 then divides it by 100, (12,345.67).
This number is then rounded to 12,346.
The new number is then multiplied by 100 giving 1,234,600.
S
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 command is used after a page that contains interactions. If an end-user clicks on a next button on that page and then returns to it, the page will automatically show them the responses they entered the last time they saw that page.
Example 1
show page1
saveandload page1 for username
Any interaction on page1 will be saved and then loaded each time the end-user comes back to that page.
set
The set
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 (usually an email address) on the login page. The word username can then be used any time throughout the logic to refer to the text an end-user entered into that interaction.
Example 2
You can set timings in your logic. Setting timings means you can change the timings for testing and change them back again to real-time easily, and it reduces the likelihood of mistakes being made.
In this example, twelvemonth has been set to the number of seconds in 12 months:
set twelvemonth to "31536000"
You can then use this in your login logic as follows:
after login if (comparetimes(loadvalue(username,"baselinetime"), currenttime(),"seconds") >= twelvemonth) goto studyfinished
The above logic will show the page studyfinished if it has been more than 12 months since baselinelinetime.
Example 3
You can set text such as an email address to avoid having to type it out each time, e.g. the study coordinator's email address:
set studyemail to "study@soton.ac.uk"
This logic should appear near the top of your logic file. An advantage to using this function this way is that if you decide to change the study coordinator's email address, you only have to change it once (where you set it).
You can also set the text and timings in emails:
set 3monthemail to "Thank you for taking part in The Reactivate Study. It is now time to complete your 3 month questionnaire. Your answers are very important to us. Please use the following link to login:\n\nwww.webaddress.co.uk\n\nIf you have any questions about the study, or no longer wish to participate, please contact us on study@soton.ac.uk\n\nFrom The Reactivate Team."
set oneday to "86400"
set oneweek to "604800"
The advantages to setting text in emails are:
- They can be changed easily as you only have to change one line instead of multiple lines throughout your logic. It's common to overlook vital lines if you have many lines of logic and setting text reduces the likelihood of mistakes being made.
- The lines are easy to find as they are placed at the top of the logic file.
Please see the command sendemail
for more information on how to write email logic.
Example 4
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 "optionc")
after page1 if condition1 goto page3
So in example 2, the variable condition1 is set if end-users select optiona and optionc 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 5
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)
saveuniquevalue
The saveuniquevalue function is used in the same way as the savevalue function. The only difference is that with saveuniquevalue, if the value entered by an end-user is not unique, the function will return a 'false' input, and you can use this to stop end-users continuing with the intervention until they have entered a value which is unique and you can send the study coordinator an email to alert them of this.
Example 1
To save and check a variable entered by an end-user is unique:
saveuniquevalue(username, "studyid", page1.interaction1)
Example 2
If an end-user has entered a response that is not unique, you can allow them to continue with the intervention and send an email to the study coordinator.
after registration if (and(not(saveuniquevalue(username, "studyid", registration.interaction1)), sendemail( append(username,"not_unique"), "study@soton.ac.uk", "Participant - not unique", append("Participant ", loadvalue (username, "idnumber"), "has entered information that is not unique."),10) )) goto registrationfinish
For more information on saveuniquevalue please click here
savevalue
The savevalue command saves a variable that can be loaded again in later sessions. It is used if users have to create an account to access your intervention and you want to save information to a user.
It can be used to:
- create a variable and save it to a user
- save a response a user has given to an interaction
- save the time
- save a questionnaire or session as 'complete'
Example 1 - Create and save a text variable
savevalue(username, "group", "web_support")
This will save the variable web_support for a username. group will be the column heading in your data in the User data sheet.
When loading this value later in your logic, you will use the command loadvalue
, and the variables you have created - group and web_support:
after page5 if (loadvalue(username, "group") = "web_support") goto page10
Example 2 - Create and save a numeric variable
savevalue(username, "work", 1)
.
This will save 1 for the variable work. work will be the column heading in your data in the User data sheet.
You can use this to show feedback on a page in another session:
show s1area.summary if (loadvalue (username, "work")>0)
This logic will show the feedback summary on page s1area if the variable work is more than 0.
Example 3 - Save a response a user has given to an interaction
savevalue(username, "s1_fatigue", page1.interaction1)
This will save the response given to interaction1 on page1 to the variable s1_fatigue for the username.
To load this later in your logic, you would use the variable name s1_fatigue:
set page5.fatigue_score to loadvalue (username,"s1_fatigue")
This will load the variable s1_fatigue and will show it in the text box fatigue_score on page5. For this to function correctly, fatigue_score needs to be set as a printed variable.
Example 4 - Save the time
savevalue(username, "s1_time", currenttime())
This will save the current time as s1_time.
You can load this later in your logic to ensure that end-users do not see session 2 until 1 week later:
after login_successful if (comparetimes(loadvalue(username, "s1_time"), currenttime(), "seconds" ) > 604800) goto s2_welcome
Example 5 - Save a questionnaire or session as complete
savevalue(username, "baselinecomplete", "yes")
This will create the variable baselinecomplete and will save yes. In this example, you can use a number instead of yes:
savevalue(username, "baselinecomplete", "1")
You can load this in your logic to check that an end-user has completed their baseline questionnaire:
after login_successful if (and( hasseen(username, "qintro"), (isempty(loadvalue(username, "baselinecomplete"))) )) goto q_notcomplete
This will show the page q_notcomplete if the end-user has seen qintro, but the variable baselinecomplete is empty (because the baseline questionnaire has not yet been completed).
sendemail
This is the command for setting up e-mails to send out to end-users at specific points in the intervention. The function for sending out an e-mail always uses the same basic formula:
after pagename1 if sendemail(append(username,"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 1
sendemail (append(username,"welcome_email"),username,"You have successfully registered to Stress Less", append("Dear ", loadvalue (username, "firstname"), "\n\n", welcome), 10)
In this example, the first part of the logic ,(append(username,"welcome_email")
, is the unique name of the email. The append function joins the username to the name of the email (welcome_email) to make sure that every email is unique. If the append function is not used, every email will be called welcome_email and only the first one will be unique - the other emails will not be unique and will not be sent out.
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
This command tells the intervention how many characters a user has entered into a free text interaction.
This can be useful if you want your users to create usernames that are a specific number of characters.
To use this function you will need to write an error message:
show namemessage if (stringlength (username) < 5)
In this example, the error message called “namemessage” will be shown to users if they have entered less than 5 characters in the interaction called “username”.
sum
Please see add
show
The show
command is the first logic command you will need to know. It is also probably the most common one that you will use.
This command shows each of the pages you have created. Pages will be shown in the order they are written 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 be shown the page named ‘page1’. When they click on the next button on page1, they will see the page called page2’. This is followed by ‘page3’ and finally ‘page4’.
NB Before you can preview your intervention, you will need to have the show 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 command once for each page. However, you can re-show the same page to users - see the named
command above for more details.
You can also reshow pages to your end-user by using a jump button on a previous page.
T
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 1.12 set)
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.
to
The to
key command is used with the set
key command to set variables.
U
urlencode
urlencode(string)
This is an a function for advanced users. It returns a URL encoded version of a string and should be used only when creating a dynamic URL (i.e. using a variable). It is used when the variable might contain non alphanumeric characters. It converts a string into the correct format to prevent usual characters from breaking the link. This is because certain characters (such as ? and &) have special functions when included in a URL and have to be encoded in a different format (e.g. the & symbol gets converted to %26).
URL encoding is common and you will find more information here: http://en.wikipedia.org/wiki/Percent-encoding