date filter

However, being strings, Jira date/time values aren't easy to work with. To manipulate and format dates and times in Nunjucks, JMWE uses the Moment.js library. All the functions provided by the library, which are available to your Nunjucks templates through the date filter, return a Moment.js date object. A Moment.js date object is an object that encapsulates the current date and time, as well as time zone information, and can easily be manipulated and formatted for display.  JMWE's  nowObj variable, which represents the current date and time, returns a Moment.js date object.

Refer to the official documentation for more information about Moment.js.

Converting a Jira date/time string to a Moment.js date object

You can convert a Jira date/time string to a Moment.js date object using the clone method of the Moment.js library. For example: 

"2018-02-14" | date("clone") returns a Moment.js date object.

When rendered in a {{...}} block, a Moment.js date object is output as a string representing the specified moment in milliseconds.

{{ "2018-02-14" | date("clone") }} outputs 1518566400000 

Converting a Moment.js date object to a Jira date/time string

You can convert a Moment.js date object to a string representing a date/time object using the date filter. For example: 

nowObj | date returns the current date/time as an ISO 8601-compliant string such as 2018-02-14T00:00:00Z.

To format a Moment.js date object to a more human-readable string, use the date(format) form of the filter.

Date calculations

You might want to manipulate a date before setting it to a field. For example, you might want to set the Original estimate to the difference of the Created and Due date. Below are some methods to help with these manipulations.

add

Description:

Adds time to a date.

Syntax:

{{ DATE | date('add' , Number , String) | date }}

{{ DATE | date('add' , Duration) | date }}

{{ DATE | date('add' , Object) | date }}

Examples:

Assuming {{ now }} is 2016-10-17T08:38:16.625Z

The shorthand keys are: 'y', 'Q', 'M', 'w', 'd', 'h', 'm', 's' and 'ms' for years, quarter, months, weeks, days, hours, minutes, seconds and milliseconds respectively.

When decimal values are passed for days and months, they are rounded to the nearest integer. Weeks, quarters, and years are converted to days or months, and then rounded to the nearest integer.

subtract

Description:

Subtracts time from a date.

Syntax:

{{ DATE | date('subtract' , Number , String) | date }}

{{ DATE | date('subtract' , Duration) | date }}

{{ DATE | date('subtract' , Object) | date }}

Examples:

 Assuming {{ now }} is 2016-10-17T08:41:47.658Z

The shorthand keys are: 'y', 'Q', 'M', 'w', 'd', 'h', 'm', 's' and 'ms' for years, quarters, months, weeks, days, hours, minutes, seconds and milliseconds respectively.

When decimal values are passed for days and months, they are rounded to the nearest integer. Weeks, quarters, and years are converted to days or months, and then rounded to the nearest integer.

startOf

Description:

Sets a date to the start of a unit of time.

Syntax:

{{ DATE | date('startOf' , String) | date }}

Examples:

 Assuming {{ now }} is 2016-10-17T08:41:47.658Z

The units of time that can be passed are:

endOf

Description:

Sets a date to the end of a unit of time.

Syntax:

{{ DATE | date('endOf' , String) | date }}

Examples:

 Assuming {{ now }} is 2016-10-17T08:41:47.658Z

The units of time that can be passed are:

clone

Description:

This method takes a date String as input and creates a Moment.js date object.

Syntax:

{{ DATE | date("clone") }}

Examples:

daysInMonth

Description:

daysInMonth() method can be used to display the number of days in the current month.

Syntax:

{{ DATE | date('daysInMonth') }}

Examples:

If the Due date is 24/Nov/16: {{ issue.fields.duedate | date('daysInMonth') }} will display 30

Date formatting

You might want to display a date in specific format after or before manipulating it. Momentjs provides some methods to display a date in different formats. 

format

Description:

This method takes a string of tokens and replaces them with the corresponding values. If the field (on which the method is applied) is invalid the result is an Invalid date string.

Syntax:

{{ DATE | date(format) }}

Examples:

List of tokens:

If you would like to add strings in format strings, you need to wrap the characters in square brackets. For example: {{ now | date ('[The issue was resolved on] Do MMMM YYYY dddd') }} will display, The issue was resolved on 14th October 2016 Friday.

tz

Description:

You can parse and display dates in any timezone. By default this method will print the date in the timezone of the current user (the user running the transition). See here for all the available functions.

The list of possible time zones is available here.

Syntax:

{{ DATE | date('tz') }}

Examples:

2017-07-21T06:26:46+02:00

2017 June 05

fromNow

Description:

fromNow() method can be used to display the time from now.

Syntax:

{{ DATE | date('fromNow') }}

Examples: If Due date is 24/Nov/16 and Created is 13/10/16

You can remove the suffix 'ago' by passing true to the method. For example: {{ issue.fields.duedate | date('fromNow' , true) }} will display: a month

The string displayed for each length of time is listed below: 

from x

Description:

from() method can be used to display the time from x (time other than now).

Syntax:

{{ DATE | date('from' , 'x') }}

Examples:

If you want to find the time from the Due date to the Created date:

{% set due = issue.fields.duedate %}
{% set cre = issue.fields.created %}
{{ due | date('from' , cre) }}

You can remove the suffix 'month' by passing true to the method: {{ due | date('from' , cre , true) }} will display: a month.

toNow

Description:

toNow() method can be used to display the time to now.

Syntax:

{{ DATE | date('toNow') }}

Examples:

If the Due date is 24/Nov/16, {{ issue.fields.duedate | date('fromNow') }} will display: a month ago

If the issue created date is 13/10/16, {{ issue.fields.created | date('fromNow') }} will display: in a day

The string displayed for each length of time is listed below: 

to x

Description:

to() method can be used to display the time to x (time other than now).

Syntax:

{{ DATE | date('to' , 'x') }}

Examples:

{% set due = issue.fields.duedate %}
{% set cre = issue.fields.created %}
{{ cre | date('to' , due) }}

The string displayed for each length of time is listed below: 

You can remove the suffix 'in' by passing true to the method: {{ cre | date('to' , due, true) }} will display: a month.

locale

Description:

This method takes a string representing a date, or a Moment.js date and sets the locale to use to format the date.

Syntax:

{{ DATE | date("locale") }}

Examples:

"2018-02-14T06:49:17Z" | date("locale") | date("LLLL") returns the full date in the current user's locale.

"2018-02-14T06:49:17Z" | date("locale", "fr") | date("LLLL") returns mercredi 14 février 2018 06:49