Events and Triggers 🔗
Events are things that happen in the program that would alter the normal navigation. When an event is triggered, the GuidedTrack code underneath it gets run immediately — putting on hold whatever was happening in the navigation.
Currently, GuideTrack events can be launched with a matching JavaScript event or when a user returns to an unfinished run of a program.
Running a block of code when the user returns to a program using
*startup
🔗
The feature
*startup
is an attribute of the keyword
*events
that can be handy when you have a program that users may return
to more than once. It offers a block of code that will run FIRST
each time a user loads your program, irrespective of their
position when they last closed the program.
*startup
is great if:
- You have a program you're continuously updating and you need to add the newest variables for users with older runs.
-
You want to
*trigger
some event whenever someone returns to the program (e.g. using*trigger
to send usage data to Google Analytics). -
You need to check how long it's been since the last time the
user started the program, and if it's been a while, bring them
to a different place than if they were using the program
recently (i.e. using
*goto
with the*reset
attribute, explained below).
The below example covers the third use case. To begin, here's a way you can check how long it's been since a user was last in your program:
*events
*startup
*if: last_load
>> time_elapsed = calendar::now - last_load
>> last_load = calendar::now
Above, we're first checking if the user has ever activated the
variable
last_load
. If it's their first time, then the
*if
is ignored and the variable
last_load
is activated immediately after. If it's the user's second or
more time in this program, then the
last_load
variable is already defined; so the
*if
is triggered and the
time_elapsed
variable is defined, which lets us know how much time has passed
since the user last opened the program.
Once the content from
*startup
is complete, the program would then start from the user's last
position (when they exited their previous run), even if that
position is buried deeply within your program.
With
*startup
, though, you can also change where the returning user will
return to. For example, if it's been a few days since the user
opened your program, you could make them start it over from the
beginning. The
*reset
option lets us reset the user's position and place them
elsewhere:
*events
*startup
*if: last_load
>> time_elapsed = calendar::now - last_load
*if: calendar::now + time_elapsed > calendar::now + 3.days
*goto: beginning
*reset
>> last_load = calendar::now
*label: beginning
Let's get started!
The
*reset
option exits the user out of any programs they may have been
running (via
*program
keywords) and then takes them via
*goto
to a
*label
of your choosing on your main program page.
In this case,
*reset
will send any users who've been out of the program for more than
3 days to the "beginning" label that we've put at the start of
the program. The
*reset
attribute ensures users smoothly exit out of any subprograms
they may have been in, ensuring your main program has full
control.
Within
*startup
or any
custom event
,
*goto
is only allowed if it has a
*reset
attribute, because a regular
*goto
will not exit users out of subprograms they were previously in
the middle of, which may cause unexpected behaviors.
It's important to also note that page breaks are not allowed
within
*startup
. This is intentional, as things could quickly become mucky and
complex if users were to refresh the screen while within content
of a
*startup
, or if
*back
buttons were enabled.
Sending data from JavaScript to a GuidedTrack program using
*events
🔗
Custom events are a super powerful tool that allows you to control the program navigation using events and send data from JavaScript to GuidedTrack.
This feature is only for when embedding your program on a website and you will need to have a working knowledge of HTML and JavaScript. 🔗
Here is a simple program that uses custom events:
*events
loadFinalPage
{it["message1"]} {it["message2"]}
*goto: final_page
*reset
Page 1/3
*button: Next
Page 2/3
*button: Next
*label: final_page
Page 3/3
*button: Quit
The program above has an event called "loadFinalPage". In order to trigger this event, you would have a script in the page where the program is embedded that would look like this:
jQuery(window).trigger("loadFinalPage", {
message1: "Going to last page",
message2: "because a button was clicked",
})
Note that the event's name in the JavaScript code must match the name in your program!
When the JavaScript event occurs, the GuidedTrack code under the
event runs immediately. Note also how the JavaScript code passes
an association of data that gets stored in the association
it
so that you can read this data from within the program. So, if
the event "loadFinalPage" is triggered as shown above, the
sample program will display "message1" and "message2" and then
go to the label "final_page" no matter where the navigation was
at that point.
Notice that the keyword
*goto
has
*reset
indented underneath — just like in
*startup
*events
. Your program will throw an error if you don't
*reset
when redirecting to a point of your program from an event. And
also, just like in
*startup
, page breaks are not allowed in these type of events.
You can create as many custom events as you like! For example:
*events
*startup
--Code that runs when a user loads the program
event1
--Code to run when event1 is triggered
event2
--Code to run when event2 is triggered
Note that
*startup
is the
only
event name prefixed by an asterisk (
*
). That's because it's a special, reserved event name, and the
*startup
event is automatically triggered by GuidedTrack itself. Custom
events, though,
cannot
have names prefixed with an asterisk, and those events must be
triggered manually (either from JavaScript or by using
*trigger
).
Next: Experiments