GuidedTrack Docs

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).