Another common use-case that we get asked about a lot involves automatically calculating dates. These calculations can have a few different results, and this post will document a few of the most common ones.
All of these examples will be using the time command. We'll also look at the datetimediff function for figuring out the length of a time shift.
The basics for the {time} command
The time command has 3 primary portions to it, which may be written like this: {time: YYYY-MM-DD; at=2023-02-20; shift=+1D}. Those 3 portions are:
-
{time: YYYY-MM-DD}: Out of the 3 portions of the time command, this is the only portion that is always required. Tis is the opening of the time command as well as the format which the time will be displayed when the snippet is used. Almost any format of date is supported. In this example, I am using YYYY-MM-DD. Using the time command with only this portion will always display today's date and/or time.
-
at=specific_time: the at= setting lets you choose a specific date to display. As noted above, without the at= setting, the time command will always display today's date and/or time. at= lets you specify a different date or time to display. For instance, at the time of writing this post {time: YYYY-MM-DD} will display 2023-02-20, but {time: YYYY-MM-DD; at=2016-11-06} would always display 2016-11-06.
-
shift=set_shift_amount: The shift setting will adjust the date by a specified amount. For instance, {time: YYYY-MM-DD; shift=+3D} will results in the date 3 days from now. This can be very powerful when combined with the at= setting. Subsequent examples will demonstrate that. Multiple shifts can be combined together as well, for behavior such as "the next Saturday that happens after 3 weeks from today".
Calculating a date in the future
Let's say you want to tell someone that you'll follow up with them in 3 days, but don't always want to calculate what day that would be. The shift setting can accomplish that for us:
I will look into your question and get back to you in 3 days, which is {time: MMMM, Do; shift=+3D}.
I could also use the shift to skip weekends if I wanted to say 6 business days instead:
I will look into your question and get back to you in 6 business days, which is {time: MMMM, Do; shift=+6D(skip=SAT, SUN)}.
Using at= to set an anchor date, and then calculating other dates from there
Using the at= setting, I can calculate a shifted date from any date as the anchor, instead of always relying on today.
Let's say I'm going to ship a package in 2 days, and I want to tell someone that if they haven't received it 7 days later they should reach back out to me. Here's two different ways I could do that:
Setting the shipping date as a variable
Your items will ship in 2 days, on {=shippingdate}. If you haven't received your package by {time: YYYY-MM-DD; at={=shippingdate}; shift=+1W}, please follow back up with me for an update.
{shippingdate={time: YYYY-MM-DD; shift=+2D}}
Using a formdate field to manually select the shipping date
Your item will ship in 2 days, on {formdate: YYYY-MM-DD; name=shippingdate}. If you haven't received your package by {time: YYYY-MM-DD; at={=shippingdate}; shift=+1W}, please follow back up with me for an update.
Sometimes, dates will be in different formats and you'll need to format the date appropriately for your at= setting to work appropriately. You can use the pattern= setting to tell the time command what format your at= date is in so it's recognized:
In this example, I'll receive an error because the format of the date used in my at= setting isn't recognized.
{time1={time: dddd, MMMM, Do; shift=-3W}}{=time1}
{time: YYYY-MM-DD; at={=time1}}
Here's the same command but using pattern= setting so my at= setting's date is recognized. pattern= tells the time command what format the at= setting's time is written in. This does not effect the output of the time command, which is still controlled by the formatting at the start of the command:
{time: YYYY-MM-DD; at={=time1}; pattern=dddd, MMMM, Do}
Calculating amounts of time between any two dates
The function datetimediff can be used to calculate the difference between two dates. It is formatted as follows:
{=datetimediff(first_date, second_date, "D")}, with "D" being the time period in which the difference is measured. D could be replaced with W for weeks, M for months (m for minutes), Q for quarters, and Y for years.
Select the first date: {formdate: YYYY-MM-DD; name=date1}
Select the second date: {formdate: YYYY-MM-DD; name=date2; default={time: YYYY-MM-DD; shift=+1D}}
{difference=datetimediff(date1, date2, "D"); trim=left}
Using datetimediff, I can determine that these two dates are {=difference} days apart.
{if: difference<0}The second date selected is prior to the first date selected{elseif: difference>0}The second date selected is after the first date selected{else}Both selected days are the same{endif}
There are additional items about the time command not covered in this post that can be found in our documentation, like locales or datetimeparse. This is just a small hint of what the very powerful time command can do.
In this post