GuidedTrack Docs

Date/Time Features🔗

Save the Current Date/Time🔗

Sometimes you need to know the exact moment a user answered a question or reached a certain point in the program. Whatever the reason, you can now store the current date/time like this:

>> thisMoment = calendar::now

Just make a new variable and call it whatever you want (e.g. thisMoment or time1), and then set it to equal calendar::now.

If you want to store just the current time, or just the current date, you can do the following, respectively:

>> currentTime = calendar::time
>> dateAnswered = calendar::date

You can display these variables to the user just as you would any other variable, with {curly brackets}. A date and time combination (known as a _datetime*), a time, and a date display like this in GuidedTrack, respectively:

Add and Subtract Time🔗

What if you want to communicate with users about not only the current date/time, but dates in the past or future?

For example, if you want to remind the user to do something two weeks from now, you'll need to know what date that is.

You can create a new variable that takes the current time and adds to or subtracts from it, like so:

>> two_weeks_from_now = calendar::now + 2.weeks

In this example, you just come up with a name for your variable (e.g. two_weeks_from_now), and then assign to it the value of calendar::now (which gets the current date and time) + 2.weeks (which adds two weeks).

You could instead add 3.days, or 5000.seconds, as long as you add a period in between the number and the time unit.

Here are all the time units you can manipulate:

.seconds
.minutes
.hours
.days
.weeks
.months
.years

You can similarly add or subtract units like seconds, minutes, or hours from calendar::time (the current time), or days, weeks, etc., from calendar::date (the current date, without the current time).

You can also add or subtract from a datetime other than the present date and time.

For example, let's say your user will be working on a new habit for 21 days, starting on a day of their choosing, and you want them to mark their calendar when the 21 days is up.

You could do something like this:

*question: When are you going to start your new habit of being an abrasive jerk?
	*type: calendar
	*date: yes
	*save: habit_start

>> habit_check = habit_start + 21.days
Great! You'll start your new habit on {habit_start}.
After 21 days ({habit_check}), be sure to celebrate your progress!

In this example, you're not looking to add or subtract from calendar::now (the present time); you're adding or subtracting from a different calendar-based variable (habit_start).

Manually Entering a Date/Time🔗

You can include questions that asks users to enter a *date and/or *time, and 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:

>> bulgarian_independence_day = calendar::date({ "month" -> 3, "day" -> 3, "year" -> 1878 })

Or add just a time, specifying the hour and optionally the minute:

>> bedtime = calendar::time({ "hour" -> 23, "minute" -> 30 })

You can also create a variable that has both a date and a time:

>> game_time = calendar::date({ "month" -> 2, "day" -> 4, "year" -> 2018, "hour" -> 14, "minute" -> 00 })

An hour is required for a manually-specified calendar::time, and a year is required for a manually-specified calendar::date.

Time Durations🔗

You can subtract time to find durations. For example, consider the following example:

>> start_time = calendar::now

*question: Who are you, really?

>> end_time = calendar::now
>> time_duration = end_time - start_time

You answered that question in {time_duration}.

Above, the text will state that the question was answered in "x seconds" (where x is the number of seconds your user took in answering).

By default, whenever you calculate a time duration by substracting one time or date from another, the duration unit that will be used is seconds with three decimal places (up to the millisecond). Be aware that there is an estimated error of ± 10 ms in time durations measured this way due to the browser, device running your program, etc.

However, if you'd rather have minutes, hours, days, or any of the other time units mentioned above, you can do the following:

>> time_duration = time_duration.to("minutes")

In our example, if we had done the above before writing {time_duration}, the user would instead see "You answered that question in x minutes" (where x represents how long they spent answering).

Comparing durations🔗

You can also compare durations to see if one time is bigger than another. However, this gets a little tricky. Is 1.month > 30.days? Well that depends on the month. Is 365.days = 1.year? Normally it is, but not during a leap year.

Because some types of time are impossible to compare, to compare times you must first add them to a known time, such as this moment. For example, both of the following will work:

*if: calendar::date + 20.days < calendar::date + 1.month
	20 days from now is less than 1 month from now!

*if: calendar::now + savedTime < calendar::now + 3.hours
	{savedTime} from now is less than 3 hours from now!

The above examples work because, in the first example, if today were January 1st, GuidedTrack would add one month simply by making it February 1st. That's easier to compare than an unknown month length. By default, GuidedTrack requires that in order to compare any type of durations you first add them to a known time.