GuidedTrack Docs

Switching Users Around Multiple Saved Positions🔗

The keyword *switch is for the rare program that keeps track of the user's position in multiple places at once, allowing them to switch back and forth, or apps that have multiple distinct sections that you want to be able to switch the user back and forth between easily.

For example, let's again say you have a program that teaches the finery of dog fashion design. There are 10 scintillating lessons, but the user is allowed to take them in any order, and they can pause one lesson to switch over to another and then switch back again to finish the earlier lesson up later.

In this scenario, you could use the *switch keyword, and your program could look something like the following.

Here's a sample program that includes the lessons themselves and a *navigation item to help users return to the "home" program (defined after this program):

-- An example first lesson program.
-- (Here *navigation is used to help users get around)
*navigation
	Switch lessons
		*switch: My program home screen
			*reset

*header: Lesson 1: History of canine accoutrements
*button: Begin
The pampered pooches of ancient Egypt...

And here's the separate program called "My program home screen":

-- An example "home" program that helps users *switch around.
Hey there future furball fashionista!

*question: Which lesson do you want?
	Lesson 1
		*switch: My program lesson 1
	Lesson 2
		*switch: My program lesson 2
	Lesson 3
		*switch: My program lesson 3
	Etc.

Above, the user might start in the lesson 1 program, but a navigation placed at the top can be clicked to *switch them to an organizing "home" screen, where they can select a different lesson to *switch into. From there, they can *switch into any of the other lessons, or back again into session 1.

How switch works🔗

*switch: The name of the program to switch to
	*reset

As soon as the user encounters a *switch command, they are immediately transferred to a different section of your program (and any text that might've been on the screen prior to the *switch is not shown, so it's best to have *switch after a *button or page break).

There are two ways to switch:

1. *switch with a *reset keyword indented below, which will send users to the start of the named program and any previous progress in that program is wiped out
2. *switch without a *reset attribute, which will send users to their last position within the named program (unless it's their first time running the named program, in which case they'll just start at the beginning of it)

In our example program, when users *switch to the "home" program, the *reset attribute ensures they start off at the top of that program. When they *switch to a lesson, though, there's no *reset attribute, so they'll start off wherever they were when they last switched out.

What switches or changes with *switch?🔗

The features below do not persist as a switch is made (so they will disappear from the screen, if present, and will reappear only if they were previously present on the program being switched into):

• *progress
• *maintain
• *navigation

Any points accumulated stay on the screen between switches. Variables can also be shared across programs navigated to via *switch.

In a program like our example above, we would have to put a *navigation (to help users return to the home page) at the top of each lesson, since *navigation is not something that persists between switches!

What happens at the end of the program the user switched into?🔗

You'll need to control what should happen when a user reaches the end of a program they've switched into. GuidedTrack's natural response when there's no further content to display is to assume user's entire run is finished (i.e., the next time the user opens the program it'll be as if a "Reset everything" has occurred).

For example, at the end of our lesson 1 program, we could include the following to control what should happen next:

>> lesson1 = "done"

Yeah you did it! You mastered 5,000 years of canine couture!
*button: Bring me to the home screen

*switch: My program home screen
	*reset

Once lesson 1 is complete, the user will be directed to the home screen. If we wanted to prevent users from starting lesson 1 over, the variable lesson1 that's been added (stored with the value "done"), could be used to remove this lesson from a list of lessons available to complete.

To sum up: whenever a section reaches its end, use *switch to bring the user somewhere else.

Why is *switch superior here to *program?🔗

Switching around willy-nilly would be hard to pull off with the *program keyword alone. The *program keyword runs one program that yearns to be finished, returning the user back to the program that contained the *program keyword. You cannot create a loop where two programs continuously call each other via *program, as GT would grow wearisome and possibly crash.

When a *switch is used, it is not necessary for the user to ever return to the program that called the *switch. Two or more programs could continuously switch back and forth, and GuidedTrack would be completely chill about the whole thing.

In short:

• *program is most useful for running a program until it completes, automatically continuing on from there when done and/or returning to an outer program.
• *switch is most useful when switching between various programs with no intention of returning, or when pausing the current program until *switch is used to come back and continue.

What are some other times *switch would be useful?🔗

*switch might also be useful if:

• your app has a "Home" or "Main Menu" where users can adjust settings, or could potentially get several subprograms deep into alternative content, and you want to quickly *switch users back into the main thing they were doing
• your app has "Toolbox" or "Homework" sections that users can play around in, and you want to keep track of users' progress in the various tools
• you're developing a traditional app that has a persistent navigation bar, where clicking each navigation icon takes you to a different section of the app via *switch (Note that you'll have to create the *navigation again at the start of each section, since navigation does not persist across sections.)
• a *program you call may not run to completion