duration filter

In the Nunjucks templates of JMWE to create, manipulate and format durations, JMWE uses the duration objects of the Moment.js library. All the functions provided by the library, that are available to your Nunjucks templates through the duration filter, return a Moment.js duration object. A Moment.js duration object is an object that represents the length of time in milliseconds, and can easily be manipulated and formatted for display. Refer to the official documentation for more information about Moment.js.

On this page:

Duration creation

duration

Description:

Creates a Moment.js duration object from a duration number, or a string representing a duration. This duration object can then be used with the other duration filters. It returns a number representing the specified duration in the specified unit. If not specified, and the input is a number, it will be interpreted as a number of milliseconds.

Syntax:

{{ NumberOrString | duration([unit] }}

Parameters:

ParameterDescription
unitThe unit of the duration number. One of secondsminuteshoursdaysweeksmonthsyears. If not specified, and the input is a number, it will be interpreted as a number of milliseconds. 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.

Examples:

FormatOutput
{{ 3 | duration("minutes") }}3
{{ "2:30:00" | duration }}9000000
{{ {days:2,hours:12} | duration }}
216000000

2} | duration

Duration formatting

You might want to display duration in a specific format. Momentjs provides some methods to display duration in different formats. 

humanize

Description:

Formats a Moment.js duration object into a user-friendly string. To format it in a specific locale (language), use the duration("locale") filter first. It applies to a Moment.js duration object, as returned by the duration([unit]) filter. 

Syntax:

{{ durationObject | duration("humanize" [,relative]) }}

Parameters:

ParameterDescription
relativeIf true, the duration will be formatted as a relative duration from now (e.g. 3 hours ago). Default is false.

Examples:

FormatOutput
{{ 3 | duration("hours") | duration("humanize") }}3 hours
{{ 3 | duration("hours") | duration("humanize", true) }}in 3 hours
{{ -3 | duration("hours") | duration("humanize", true) }}3 hours ago
{{ issue.fields.created | date("diff") | duration | duration("humanize", true) }}3 months ago

locale

Description:

Specifies a locale to use for a subsequent duration("humanize") filter.

Syntax:

{{ durationObject | duration("locale", locale) }}

Parameters:

ParameterDescription
localeA two-letter locale identifier, such as en or fr

Examples:

FormatOutput
{{ 2 | duration("hours") | duration("locale", "fr") | duration("humanize") }}2 heures
{{ 1 | duration("minutes") | duration("locale", "es") | duration("humanize") }}
un minuto

Duration calculations

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

add

Description:

Adds time to a Moment.js duration.

Syntax:

{{ durationObject | duration('add' , amount [, unit ] ) }}

Parameters:

ParameterDescription
amountThe amount of time to add. Can be a number or another Moment.js duration object
unitThe unit of the amount parameter. One of secondsminuteshoursdaysweeksmonthsyears. If not specified, and the amount parameter is a number, it will be interpreted as a number of milliseconds. 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.

Examples:

InputDetailsOutput

{{ 3 | duration("days") | duration("add", 6, "days") }}

Returns the duration in milliseconds.
777600000
{{ 3 | duration("hours") | duration("add", -6, "hours") | duration("humanize", true) }}The number can be negative. Apply the duration("humanize") filter to display the duration as a relative time.
3 hours ago
{{ 5 | duration("months") | duration('add' , {months:2, days:3}) | duration ("humanize") }}You can also pass them in object literal7 months
{{ issue.fields.timeoriginalestimate | duration | duration("add",1,"hours") }}Add an hour to the Original estimate of the issue. 

Duration in milliseconds. For example 14400000 when the Original estimate is 3 hours

{{ issue.fields.timeestimate | duration | duration("add",issue.fields.timespent) | duration("humanize", true)) }}Adds the Remaining estimate and the Time Spent on the issue.

Duration as a relative time. For example in 4 hours when the Remaining estimate is 3 hours and Time Spent is 1 hour.

subtract

Description:

Subtracts time from a Moment.js duration.

Syntax:

{{ durationObject | duration('subtract' , amount [, unit ] ) }}

Parameters:

ParameterDescription
amountThe amount of time to subtract. Can be a number or another Moment.js duration object
unitThe unit of the amount parameter. One of secondsminuteshoursdaysweeksmonthsyears. If not specified, and the amount parameter is a number, it will be interpreted as a number of milliseconds. 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.

Examples:

InputDetailsOutput

{{ 3 | duration("days") | duration("subtract", 6, "days") }}

Returns the duration in milliseconds.
-259200000
{{ 3 | duration("days") | duration("subtract", -6, "days") | duration("days") }}The number can be negative. Apply the duration filter to display the duration in days.9
{{ 5 | duration("months") | duration('subtract' , {months:2, days:3}) | duration ("humanize", true) }}You can also pass them in object literal
in 3 months
{{ issue.fields.timeoriginalestimate | duration | duration("subtract",1,"hours") }}Subtracts an hour to the Original estimate of the issue. Duration in milliseconds. For example 

7200000 when the Original estimate is 3 hours

{{ issue.fields.timeestimate | duration | duration("subtract",issue.fields.timespent) | duration ("humanize", true) }}Subtracts the Remaining estimate and the Time Spent on the issue.Duration as a relative time. For example

in 2 hours when the Remaining estimate is 3 hours and Time Spent is 1 hour.

get

Description:

Returns a part of the Moment.js duration (milliseconds, seconds, minutes, ...)

Syntax:

{{ durationObject | duration([unit]) }}

Parameters:

ParameterDescription
unitThe unit of the number to return. One of secondsminuteshoursdaysweeksmonthsyears. 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.

Examples:

InputOutput

{{ 3 | duration("hours") | duration("get", "hours") }}

3
{{ "2:30:00" | duration | duration("get", "minutes") }}30
{{ issue.fields.timeestimate | duration | duration("get", "hours") }}Hours in the Remaining Estimate of the issue

as

Description:

Converts a Moment.js duration into a number of milliseconds, or seconds, or minutes, ...

Syntax:

{{ durationObject | duration([unit]) }}

Parameters:

ParameterDescription
unitThe unit of the number to return. One of secondsminuteshoursdaysweeksmonthsyears. 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.

Examples:

InputOutput

{{ 3 | duration("hours") | duration("as", "minutes") }}

180
{{ "2:30:00" | duration | duration("as", "minutes") }}
150
{{ issue.fields.timeestimate | duration | duration("as", "hours") }}Remaining Estimate of the issue in hours