Arithmetic and Formatting in Date Variables (New)

Date variables can be manipulated in order to move the date, or to change the way the date is displayed.

For example, when using the value of a variable like  {cardduedate} , you may want to shift the value by a few days or weeks, or display it in another timezone such as GMT.

You can use all of the operations described here with date variables, due date variables, and dates contained in custom fields.


Adding or subtracting from a date variable value

You can add or subtract from the value of a date variable by using the format shown by these examples:

{date-7d} is the date seven days ago.

{cardduedate+2d} is two days after the card is due.

{{%Start Date}+6w} is six weeks after the date in custom field Start Date.

You can also add or subtract minutes (e.g.  {time+30min} ), hours (e.g. {cardduedate-2h} ), months (e.g. {{%Start Date}+3m}), years( {{%Start Date}+1y} ), and working days (e.g.: {date+5wd} ).

Regarding working days, note that  {date+1wd} is not the next working day, but the date after a working day has passed.

It's a subtle distinction that only matters if the date falls on a weekend: Saturday + 1 working day is Tuesday.

To obtain the next working day, use the following syntax:  {datelong+0wd}. To obtain the previous working day, use the following syntax: {datelong-0wd}


Changing parts of a date value

Changing the day of the week

{date=0wd} is the Sunday of the current week.

{date=1wd} is the Monday of the current week.

etc... (here,  wd stands for "day of the week" instead of "working day")

Changing the day of the month

{date=1d} is the first day of the current month

{date=15d} is the fifteenth day of the current month

etc...

{date=31d} is the last day of the current month, regardless of how long the month is.

Combining date adjustments

You can combine both adjustment operations to reach out to other weeks or months, e.g.:

{date-1w=1wd} is the Monday of last week.

{date+3m=31d} is the last day of the month three months from now.


Changing the timezone

Butler supports common abbreviations for timezone specification (e.g. PST, EDT, GMT,...):

{{%Start Date}@HKT} (Hong Kong)

You can also specify the full timezone name:

{date@Australia/Sydney} 

A list of timezones can be found in  this Wikipedia article.

Timezone changes can be combined with adjustment operations, e.g.:

{cardduedate+5wd@PST} is the date in 5 working days from now in Pacific Time.


Formatting

The value of the date can also be formatted by specifying a pattern after ~, e.g.

{date~dddd, MMMM Do YYYY, h:mm:ss a}

Will format the date like:  

Thursday, May 31st 2018, 12:00:00 am

The format specification comes from the moment.js library, which is used to perform the formatting. See  https://momentjs.com/docs/#/displaying/ for details.

This can be very useful to generate list or card names. Here's a more complex example:

The following command automatically moves cards to a list depending on the value of a custom field called "Start Date".

when custom field "Start Date" is set by anyone, move the card to list "Week {{%Start Date}=1wd~MMM D} - {{%Start Date}=5wd~MMM D}"

The lists will be created automatically if not existing, with names formatted like:

Week May 28th - Jun 1st

Nested Custom Field Variables (Advanced)

You can use the value of a custom field to specify the parameters for date arithmetic or formatting operations, e.g.:

{{%Start Date}+wd@