GuidedTrack Blog

Recent Updates Page 11 Toggle Comment Threads | Keyboard Shortcuts

• 

  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.

   
• 

  Aislinn 10:54 am on January 10, 2017 Permalink  

  Feature Update – *until, *return, *countdown, new icons, and more! 

  Here’s what’s new: More to use with *icon Associations Help the user *return to their original position Specify that a recurring email should continue *until a certain date  Timers for questions

  More super awesome icons! What’s more fun than a good icon? Pretty much nothing. Except maybe cake. Definitely cake. And beer, and sleeping, and bicycles… But look – icons!! Icons were covered earlier, but the list of potential flare you can bedazzle your program with has now expanded. In addition to the bootstrap icons we mentioned… you can now find way more (675 to be exact!) icons here: http://fontawesome.io/icons/ To add either a glyphicon icon or a font awesome (fa) icon, you type *icon:, followed by the type of icon (glyphicon or fa), followed by a dash and the name provided on the site where you got it from. Like this: You can add icons to multiple choice or checkbox questions plus navigation options. Enjoy!

  Creating Associations Associations are sort of like neatly-organized collections that allows you to look stuff up fast. If you’re familiar with programming terms, these also go by the names “Hash tables,” “Associative arrays,” “Hash maps,” or “Dictionaries.” Here’s an example. Let’s say you have a terrible memory, and want to create a GuidedTrack program that can give you the birthday of any of your friends. You set things up so that all you have to do is type in their name, and their birthday pops up on the next screen. With that scenario, you might use an association to add all the starting data you have. Each entry in an association must include two things: A “key” (the term associated with each piece of data, in this case the name of your friend) Its value (such as the friend’s birthday). If you were a postal enthusiast, the keys of your next association might be thousands of zip codes, and the values might be the names of the town associated with each key/zip code. The code for associations is a little different, so to start, here’s an association with just one birthday entry in it: In this example, the name Justin is the key that you’ll use later to find the associated data, which in this case is Justin’s birthday, March 1, 1994. What’s perhaps most striking here is that you’ll use {curly braces} instead of [square brackets] to create the association. Also, the arrow ( -> ) is used to say something along the lines of “when I input this key, show me this thing right here.” The final program, once you’ve added more of your friends, might look like this: Each entry in the association is separated by a comma. You can then type the name of your friend, saving your selection as “friend”, and then, similar to the way you would show a specific position in a collection, you display that friend’s birthday by typing {friendsBirthday[friend]} You don’t always have to use a variable though to show items in an association. If you had Bieber fever, you could prominently display Justin’s birthday in your program by typing: While you could accomplish this same feat using collections and the *while keyword, associations make it much easier to look up values associated with other values. Adding or changing a single item in an association Once you’ve got a basic association set up, it’s easy to add or modify items. For example, let’s say you have an association of English words with their Polish translations. If you want to add a new word to this pre-existing association (which you’ve called polish_words), you can simply do the following: “tea” will be a new key added to the polish_words association, and “herbata” will be its value. Similarly, if you realized you misspelled something and need to replace the value for a given key, you can overwrite a key in similar fashion: If “cake” was already in the association, it’s value is replaced by “ciasto.” If it wasn’t in the association, then it’ll be added new. One more association example, for good measure If we revisit the earlier example about adding friends’ birthdays to an association, there’s another way we may want to organize lots of info we have about our friends. For example: In the above example, each friend has their own association, complete with different keys representing crucial details about them. The collection ‘myfriends’ contains all the associations. If you set things up this way, here’s a couple ways you could display data: The first line accesses the second association in the myFriends collection and displays the value to the key “name,” which is “Mariah.” The second line would display the key “Perfume” of friend3, which is the sensual “Eau de Gaga,” with its opulent woody-floral intensity. You could display all your friends’ signature scents, like so:

  Help the user *return to their original program There’s a new keyword that works particularly well when partnered with *navigation and at least one *program keyword, though it could have simpler use cases as well. This would be the *return keyword, which functions like a high-tech *goto. When users pass over the *return keyword, they go to the very end of the current program they’re in, which returns them to wherever they were prior to that. Here it is in a somewhat simpler form: (starting program): (Super Fun Exercise program): In the above example, users start the program, which then launches into the “Super Fun Exercise” program via the *proram keyword. Once there, they have a choice to “Play” or say “This is lame.” If they choose the latter, they immediately exit the Super Fun Exercise program via *return, and next see the text “Now we’ll do something else!” from the original program. If they instead choose “Play,” they’ll see the line “Let’s get ready to prancercise!” and any lines that follow. So why use *return when you could instead use a *goto keyword that could direct users to a *label at the end of a program? For one, laziness. You can now accomplish the same feat in one line of code instead of two. But suppose you didn’t actually know which program users were in? And suppose you instead wanted users to be able to exit out of the current program via an option in *navigation. Sounds weird right? Here’s an example to show you what I mean: ​ The *goto keyword does NOT work across programs, so trying to add it beneath this navigation option would be of no use. But no matter which tool users are randomized into, the *return keyword will bring them out of the tool, to the next line in the original program, which reads “Alright, that’s the end!” Of course, it doesn’t have to be the end here, you could allow users to return to the beginning to try a new tool, or your program could just continue going forward. Note: If one of the tool programs itself includes an additional *program keyword that leads to a program that would carry the user through two or more screens, and the user is in that second program, *return alone isn’t going to cut it. *return only exits the user back one program layer, not several. So keep that in mind if you end up using *return! It can be tricky to use if the user needs to exit out of a program within a program within a program!

  Specify that a recurring email should keep being sent *until a certain date Recurring emails were discussed last time, but since then there’s been a new keyword added to make them even more effective: *until If you’d like to send users the same email multiple times (every Wednesday, for example), but have a natural stopping point (after one month), *until is the keyword for you. Here’s how this works using the example from last time. Let’s say the user will be completing an intervention each day for seven days, and you want to send out a reminder each day to complete the task. You’ll can optionally add the *identifier keyword, (if you may want to cancel the email early later on). You’ll use the *every keyword, to specify how often the email should be sent out. You can use *until to specify that the email should stop after 7 days. The most an email can be repeated is once a day (not hourly, for example), and users are now given an option to opt out of your recurring email by clicking an automatic opt-out link that will occur at the bottom.

  Timers for questions Want to restrict how much time a user has to answer a certain question before they automatically advance to the next page? Enter *countdown When you use *countdown, you can set how many .seconds, .minutes, or even .hours a user has to complete your question. The time remaining even displays just above the question like this: When time is running out, the timer turns red: The code is pretty simple, here’s an example: All you really need to use timers is the *countdown keyword specifying how much time the user can have before the page automatically advances. But in this example, we also used the *save keyword to store the user’s response. We can find out if the user left the question blank by checking the .size of the variable (gets the character length of the response). If the size is 0, then the user didn’t get to type anything in before the question disappeared.