GuidedTrack Blog

Updates from Aislinn Toggle Comment Threads | Keyboard Shortcuts

• 

  Aislinn 9:04 pm on February 9, 2018 Permalink  

  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 Add content and/or code that launches at every *startup of your program Use Airtable as a *service in your program

  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:   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: 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:

   

   
• 

  Aislinn 5:13 pm on December 29, 2017 Permalink  

  Feature Update – *service and manually entered dates/times 

  Here’s what’s new: Use *service to embed outside apps and other tools Create dates and times manually

  Use *service to embed outside apps and other tools There’s a lot that GuidedTrack can do, but now the possibilities are nearly endless. Show your users the current weather, generate a random image of a kitten, provide recipes and currency conversions, add job searching from Indeed, and the list goes on. If a person or company offers a web API for it, then you can most likely add it to your GuidedTrack program! For instance, the Mashape Marketplace is a database chock-full of public and private APIs that can be easily added to GuidedTrack. Search the marketplace for an app that interests you, and when you find one, create an account (it’s free to join) and follow the steps below. Beyond Mashape, you can add APIs from just about any other source, as long as they’re compatible with basic authentication or custom headers over HTTP (about 90% of APIs out there will fit these restrictions). There are two parts to adding a *service: setting it up in the settings page, and adding the GuidedTrack code. Part 1: Setting up the Settings page In this example, we’ll walk you through adding an from the Mashape Marketplace. Other types of services may require somewhat different steps. Be sure to read the documentation for any API you want to use in order to understand how it works. 1. Create an account on the Mashape Marketplace, if you haven’t already done so. 2. Click on “Default Application” from your dashboard. 3. In the top-right, you’ll see a button that says “Get the Keys.” Click this button: 4. You’ll see a modal appear with your api key, which is a long string of letters and numbers. Copy this somewhere safe. 5. In GuidedTrack, in the program you want to use, navigate to​ the “Settings” page, and the “Services” tab, and click on “New Service”​: 6. The name we’ll use for this service is “Random quotes”. It could be anything at all — it doesn’t need to match the Mashape API name, as this name is just used to identify it within the context of your GuidedTrack program. 7. We need to get the URL to make a request to Mashape, so go to the page for the API you want. In this example, we’ll go to the page for the “Random quotes” api​. 8. Where it says “Endpoint Definition”, there’s a URL that we can point our requests to. You’ll notice on the right-hand side for this example there are actually two Endpoint Definitions. One says “POST” and the other says “GET”. There are a few different kinds of requests you can make to APIs; the most common are GET, POST, PUT, and DELETE. Different APIs will support different ones. Here’s roughly what each of these mean: GET – read a resource POST – create a new resource PUT – update an existing resource DELETE – delete an existing resource In this case, we want GET because we want to read a quote from the API, so copy the URL for GET into the GuidedTrack form: 9. For the last part, we need to provide a way to prove that we have permission to make this request. Mashape doesn’t authenticate requests via username/password, so we’ll leave those fields blank. Instead, we include the API key (the one you copied earlier) in a custom header. Click on “Add Header” to create one. Custom header is an extra piece of information that gets sent along with every request this service makes; headers are used for lots of different things, and even among websites that use them for authentication, the name of the header can vary. 10. In the case of Mashape, ​the header name that we send the key in is “X-Mashape-Key”. So we’ll fill in the key and value for the header like so: 11. Once that’s done, click “Save”, and you’ll be ready to write your GT code! Part 2: Adding GuidedTrack Code To make a request to the Random Quotes API, we can use this GuidedTrack code: 1. First, we add the *service keyword and include the name we gave to our service, in this case we called it “Random quotes”. 2. The keyword *path is used when your service has multiple locations within the same domain. This is just like a website URL: when we defined the service we gave it a base URL, and now we want to specify which part of the site to go to. In this case, all requests to the Random Quotes API go to the same place as the URL specified on the Services page (i.e. the URL in the settings: https://andruxnet-random-famous-quotes.p.mashape.com/), so we just write “/” to indicate we’re looking for this base URL. (if there was a hypothetical API we wanted at https://andruxnet-random-famous-quotes.p.mashape.com/romance-quotes, then our path would be “/romance-quotes”) 3. We use “*method: GET” to indicate what kind of request we’re making. 4. The *send keyword is used to send an association of data (your “request”) to the server that hosts the API (e.g. Mashape). This data will tell the server what you want it to do or what information you want it to send back. In the documentation for the Random Quotes API, it tells us that it supports two different fields: “cat” to indicate which category of quote (“movies” or “famous”), and “count” to indicate how many quotes to return. In this example, we want to specify that we want one quote from a movie {“count” -> 1, “cat” -> “movies”}   (the API site also says we can leave out the “count” and it will retrieve just a single quote, but we’re keeping it here for the sake of the example). 5. Lastly, we use *success and *error to get certain information about what happened (the result, or the data you’re interested in). Each of these can be given a block of GuidedTrack code that it will display in the case where the request succeeds or fails, respectively. There are a few restrictions on what can be indented under a *success or *error block; by and large the guiding principle is that it shouldn’t be anything that breaks the page or messes with the program flow, so no *question, *button, or *goto. The other thing to know about *success and *error is that inside of each of them you get access to the special “it” variable. This is a temporary variable that can only be used inside of the block, which holds the response the server sends back. It’s usually in the form of an association. It’s important to save the important pieces of this variable as something else so that you don’t lose it if you plan to use it later on. For instance, in our example we had a line that said >> quote = it[“quote”]. That way we can store the output of the quote as the “quote” variable and use it elsewhere. We had a similar variable to store the movie name. As a result of what was typed in the *success block, the user might see something like this: While you can theoretically save the entire output by assigning “it” to a new variable, this is not necessarily a good idea because the output may store a lot of information you are not interested in, which you don’t want to become a permanent part of your GuidedTrack program’s data.

  Create dates and times manually You can include questions that asks users to enter a *date and/or *time, and now you can also include your own manually entered dates/times. This is useful if you plan to show the same date over and over and want to store it as a variable, or for adding or subtracting the time or date the user entered with one of your own. You can add a simple date, like the one below, using an association to define the year and optionally, the day and month: Or add just a time, specifying the hour and optionally the minute: You can also create a variable that has both a date and a time: An hour is required for a calendar::time type of manually added time while a year is required for a calendar::date type of variable.

   
• 

  Aislinn 10:44 am on July 28, 2017 Permalink  

  Feature Update – *trigger, scales for *answers, version control, email settings, and more! 

  Here’s what’s new: Easily add a scale to *answers and make questionnaire creation a breeze Control “who” your emails appear to come from Enable version control-useful for multi-day programs Create a fancy JavaScript event using *trigger  Start the user’s run at a custom *label using URL parameters Hide points

  Add a scale to *answers and make questionnaire creation a breeze Particularly if you’re a researcher, you may have a lengthy questionnaire where the same answer options are repeated over and over (“So true of me”, “So not true of me”). Likewise, the number of points assigned to each answer option may be consistent across questions. You could copy and paste your scale beneath each question, but that could get tedious. Instead, you can also use *answers with a scale. Here’s an example of how it works: In the above, “Adventurousness Scale,” several questions use the same “YES!!!” to “eff no” answer options. But here’s how you simplify adding the scale to *answers: First, you define a variable (e.g. “answerScale”) that contains a collection with several smaller collections. Each smaller collection looks like this: [“text of answer option”, point value associated with that answer] (e.g. [“YES!!!”, 4 ]). Second, if you have any other scales for other questions, you may wish to create more variables, such as one that includes a reverse scoring of the typical answer options, if needed (like the “reverseScale” in this example). Third, you add “*answers: yourScaleVariable” beneath each question that relies on that scale. The points assigned to each answer won’t be visible on the user’s screen, but they will be in the csv of the data. In the csv, you’ll see a column with each full question, and beneath the column will be the point values of all the responses you’ve collected (rather than the typical text-version of the responses). This will make analyzing your data much easier! Note: the text-version of the user’s answer response will not be saved ANYWHERE! The csv only stores the numeric value of the response, as does the *save keyword. Of course, if you really needed to, later on you could look up the point value in the CSV and check the GuidedTrack code to see what answer it corresponds to. If you wish to add up a total score, or do other mathematical tricks, you can add a *save keyword plus a unique variable to each question. As mentioned, these variables will save the numeric value of the selected response, rather than the response text. At the end of the program, you can add code like >>totalScore=variable1+variable2+etc. to get a variable of the total score.

  Control “who” your emails appear to come from There’s a new setting that allows you to control the “from” name when you send emails via your GuidedTrack program. This is not the email address your email is from, but rather the name of who it comes from, which many email providers display prominently. Here’s how to activate it: From the “Settings” tab, enter what you’d like the “Email display name” to be. For example, if you made a program about cats that emails the user at some point, you may want the email to be from “Mr. Whisklypuffs.” Without the display name, your email will appear to be from the name of your program plus some randomly generated letters and numbers. Later, the “Public name” will be the name of your program as it’s displayed in the iPhone or Android app store (when that soon becomes a thing) and eventually as the title of the tab that your program is running within.

  Enable version control Enabling version control is a great idea for programs that will need live updates while multiple people are taking them (over multiple days). It ensures that the program version people began with will be the version they continue with indefinitely, so that new changes you’ve made don’t accidentally make a muck of their progress. Here’s the scenario: You have this amazing program that allows people to track the firmness, dexterity, sweat control, and length of their handshakes. You think it’ll greatly help people master the art of a truly impeccable digit delivery. You anticipate that people will use your program over the course of several weeks as their limp noodles firm up. Here’s the thing, within a couple weeks you have a few hundred palm perfectors, but you’ve thought of a new handshaking aspect you’d like for people to be able to track – the webby-to-webby touch. However, if you just throw in new changes to your program now, it could disrupt the progress of the people currently in the program (perhaps they wouldn’t have important variables from your revised intro quiz, or their current place in the program could have disappeared). That’s where version control comes in. By going to Versioning from the Settings tab, you can set the version to be “Consistent” for active users as opposed to “Always latest” As GuidedTrack advances further, there will be an option to safely migrate your existing users to the new version, but for now, this is your best bet to ensure complete smoothness as your program reaches new heights.

  Create a JavaScript event using *trigger *trigger is used to run JavaScript that is sitting within the HTML file that a GuidedTrack program is embedded in. Hence, it enables GuidedTrack programs to effectively do anything JavaScript can do, as long as you put the appropriate JavaScript within the HTML file that the GuidedTrack is embedded in. This feature is for those who are embedding their programs on other websites, and it’s best for those who have a working knowledge of HTML and JavaScript (or at minimum who feel comfortable enough copying and pasting JavaScript obtained through other sources). So in other words, be warned that this section gets quite technical! The *trigger command is used to “trigger” JavaScript code to run on the current page. For example, it could trigger the sending of data to external sources, such as Google Analytics for tracking activity in your program. In it’s simplest form, it looks something like this: Above, “quizEnd” is the name we chose to give to our triggering event, and on the website that’s embedding our program there will be JavaScript code matching this name that will be actively listening for this event to be called. When the website notices this event, it will grab the JavaScript code from the *send keyword and do with it as you’ve commanded (for example, perhaps sending the accompanying data from your program to an external source that you’ve specified). The data used with the *send function is always written in the form of an association, with a name or description of the data on the left of the “->” accompanied by its value to the right. For a simple example of how you might *trigger a Google Analytics event, you could do the following: There would also be JavaScript on your website that included this along with other JavaScript: // Include the following on the page that embeds the program inside of a <script>…</script> tag $(window).on(“finished”, function() { ga(“send”, “event”, “progress”, “view”, “page”, “end”); }); Here’s a more complex example of using *trigger with Google Analytics: And here’s a description of what you’d put in the JavaScript on your website: // The first parameter to the event handler is the event itself // The data sent along with the event is the second parameter (data) $(window).on(“analytics”, function(event, data) { ga(“send”, “event”, data.category, data.action, data.label, data.value); }); To get the above example to work, you’d also have to include in the HTML page the JavaScript that Google provides to activate Analytics and the Google Analytics function that’s being used. Here are a few more ideas of ways to use *trigger, with more detailed versions of the JavaScript code that gets added to the website.

  Start the user’s run at a custom *label using URL parameters You may have a reason for starting some new users further along in your program. Now you can give users a custom link to your program that includes the *label of where they should begin. For example, let’s say you have a training program that teaches basic and advanced skills in hobbyhorsing, the dramatic trending sport where (mostly) young girls leap over hurdles and gallop around tight corners, all while skillfully controlling a wooden stick attached to a stuffed horse head. You know that some of your users will be of a more advanced skill-level, and therefore, will need to skip the kiddy stuff. After the beginner lessons in jumps, dressage, and keeping your hobby-horse well-groomed, you’ve added a *label: advancedTechniques just before the extreme stuff begins. To provide professional users a link that will automatically start them there, you’d simply add the following to the end of your URL: https://www.guidedtrack.com/programs/programID/run#advancedTechniques Users clicking that link will start at *label: advancedTechniques instead of the beginning. As another example, let’s say there’s a menu at the beginning of your program and you’d like returning users, those coming to finish the program later on, to begin at *label: mainmenu instead of wherever they may have left off. You can easily share a link to your program that’s something like this: https://www.guidedtrack.com/programs/programID/run#mainmenu The *label/URL parameter trick only works for a *label that’s within your starting program (it won’t work for a program that’s linked to within your program using *program).

  Hide the user’s points When you give users points, they appear in the top-right of the screen, but they don’t have to stay there forever. Hiding points is a breeze. The points are no longer visible to the user, though they haven’t been erased completely. They’ll still display the correct total if you decide to add them on the screen again later.