Feature Update – *page, *startup, and using Airtable with *service

Here’s what’s new:

Put a whole lot of questions, and whatever else, all on one *page

You asked for it, and now it’s here! The ability to do something like…


You can put heaps of questions all on one page, and the regular things that can go on a page, such as text, headers, images, videos, etc., can be added before, between, or after questions. 

This keyword is great for creating user “preference” pages or pairing related quiz questions.

Simply add the *page keyword, and indent whatever you want included on that page below.

GuidedTrack will automatically insert a page break just before your *page keyword and on the bottom of it if there isn’t one there already (in the form of a “Next” button”). You can also add your own buttons before *page or as the last thing indented beneath page.
 

Add content and/or code that launches at every *startup of your program

The new feature *startup (an attribute of the new keyword *events) 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:

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 they would have the last_load variable, so the *if is triggered and the time_elapsed variable is defined, which lets us know how much time has passed since users last opened the program.

Once the content from *startup is complete, the program would then start from the position the user last left off on when they exited their 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…

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, *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 in use. 

In the future, the *events keyword will have additional, innovative uses that allow you to detect other important activities of your users. For now, *startup is the only keyword it supports. 
 

Use Airtable as a *service

Airtable is a user-friendly database system that you can use like a spreadsheet as needed.

Some reasons it could come in handy:

  • Storing custom information (one row per user) that can be checked by someone else in real time (like looking at a spreadsheet, such as a professor quickly checking which students have finished a test).
  • Storing information that will be shared across users (i.e. multiple users will need access to the same information, such as a dataset from a study).
  • Storing information created by one user that is accessible to another user, like a high score in a game.
  • Storing a list of things that each user gets only one of (which is then deleted from the spreadsheet once a user has gotten one, for instance unique coupon codes).

Here we explain how to set it up to use with *service, how to add entries to your database (i.e. spreadsheets) from GuidedTrack, and also how to look up (i.e. check) entries in the spreadsheet.

1. To set up Airtable
Go to Airtable.com, create an account, then create a new workspace. You want to avoid using spaces or special characters in the title of your workspace or in any of its tabs (sheets).
 
2. To integrate a GuidedTrack program with Airtable
Go to the Services tab under Settings, and create a new Service as follows:
(Click the image for a zoomed-in version).

 

Note that the URL will be different for you, based on your unique Airtable account. In order to get the proper link, go to your Airtable’s API page (we can’t include the link, since that page is unique to your account, but you can find it pretty easily).

 
Also note that you need to find your Airtable API key, which you can access from your Airtable account. (It will likely begin with “key” and then have a random string of case-sensitive letters/numbers.) Note than in this part of GuidedTrack, you need to type “Bearer” before your key.
 
3. To ADD entries to Airtable from a GuidedTrack program
Use and modify this code based on your own Airtable tab name, column headings, and GuidedTrack variables:
 
Note that under *path, you’ll include the name of the sheet/tab in your Aitrable database you want to add to (the example here is called AccessCodes).
 
 
In this example, the spreadsheet columns are AccessCode, UserType, GroupName and AdminEmail—as partially shown here:
Inline image 3
 
See how the code above sends two variables that have been defined in the GuidedTrack program, named accessCode and adminEmail.

Note however, that for POST requests, any variable in GuidedTrack that isn’t text (e.g., a number, a list) won’t get passed properly to your Airtable spreadsheet, and the entire POST will fail but it won’t give you any error message. The way to fix it is to pass your variables within quotes. For example:

Lastly, in our example the variable “posted” was created beneath *success and *error so that you can confirm in the csv of your program whether your attempt to send data to Airtable was met with success or not. You could also let users know the outcome, with something like the following:

 
4. To CHECK entries in Airtable from a GuidedTrack program
Use and modify this code based on your sheet name, the column you wish to check, and the GuidedTrack variable it pairs with:
Inline image 4
Note that under *path, you’ll include the name of the sheet/table in your Airtable database you want to check (just like with adding entries, in this case “AccessCodes” is the name of the sheet). Then, the filterByFormula code tells Airtable what to look up. In this case, we are looking up all entries that have the field AccessCode (singular unlike the plural sheet name, which is also the first column in the screenshot above) equal to the variable tocheck (which was defined in GuidedTrack). Here’s a super handy tool for creating a URL that gets exactly the data you need.
 
Airtable retrieves the records in a funky way—it’s a list of a list of a list. So, to give an example, this is how you would extract the other fields: