moment.js template helpers and computed property macros for Ember
- Installing
- Upgrading
- Usage
- Computed Property Macros
- Helpers
- ES6 Moment
- Configuration Options
- Frequently Asked Questions
- Docs to add
ember install ember-moment
It's advisable to run ember g ember-moment
between upgrades as dependencies may have been added, removed, or upgraded between releases. Please try this, along with clearing node_modules
and bower_components
before reporting issues after upgrading.
Ships with the following computed property macros: duration
, humanize
, locale
, tz
, format
, calendar
, moment
, toNow
, fromNow
. They can be used individually or composed together.
Computed Property Macro Documentation
Parameters | Values |
---|---|
<date> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
Returns a Moment.
Example
Parameters | Values |
---|---|
<date> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
Returns a Moment with utc mode set.
Example
Parameters | Values |
---|---|
<date> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
outputFormat |
An optional date/time String output format, defaults to moment.defaultFormat which you must explicitly define |
<inputFormat> |
An optional date/time String input format |
Formats a <date>
to an optional outputFormat
from an optional inputFormat
. If the inputFormat
is not provided, the date String
is parsed on a best effort basis. If the outputFormat
is not given the global moment.defaultFormat
is used. Typically, outputFormat
and inputFormat
are given. See momentjs#format
.
NOTE: for all other helpers, the input format string is the second argument.
Example
Parameters | Values |
---|---|
<dateA> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
<dateB> |
An optional value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...), defaults to now |
hideAffix |
An optional Boolean to hide the relative prefix/suffix or not. |
hideSuffix |
Deprecated An optional Boolean to hide the relative suffix or not. It was only available for moment-from and will be removed in 8.0.0 |
Returns the time between <dateA>
and <dateB>
relative to <dateB>
. See momentjs#from
.
Note that moment-from-now
is just a more verbose moment-from
without dateB
. You don't need to use it anymore.
Examples
Parameters | Values |
---|---|
<dateA> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
<dateB> |
An optional value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...), defaults to now |
hideAffix |
An optional Boolean to hide the relative prefix/suffix or not. |
hidePrefix |
Deprecated An optional Boolean to hide the relative prefix or not. It was only available for moment-to and will be removed in 8.0.0 |
Returns the time between <dateA>
and <dateB>
relative to <dateA>
. See momentjs#to
.
Note that moment-to-now
is just a more verbose moment-to
without dateB
. You don't need to use it anymore.
Examples
Parameters | Values |
---|---|
<number> |
Any value(s) interpretable as a duration by moment (typically a Number in milliseconds) |
<units> |
An optional String to specify the units of <number> (typically 'seconds' , 'minutes' , 'hours' ...) |
Returns a Duration automatically humanized. See momentjs#duration
.
Examples
Parameters | Values |
---|---|
<dateA> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
<dateB> |
An optional value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) used as a reference, defaults to now |
<formatHash> |
An optional output format hash, defaults to {} |
Returns the time between <dateA>
and <dateB>
relative to <dateB>
in a way that is different from moment-from
and customizable via <formatHash>
. See momentjs#calendar
.
Examples
Parameters | Values |
---|---|
<dateA> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
<dateB> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
precision |
An optional unit of measurement, defaults to 'milliseconds' |
float |
An optional Boolean to get the floating point result, rather than the integer value |
Returns the difference in precision
units between <dateA>
and <dateB>
with floating point accuracy if float
is true
. See momentjs#diff
.
Examples
Parameters | Values |
---|---|
<date> |
An optional value interpretable as a date/time by moment (a date String or a Moment or a Date ...). Defaults to value of moment() |
<number> |
Any value(s) interpretable as a duration by moment that is the amount of the precision you want to add to the date provided |
precision |
An optional unit of measurement, defaults to 'milliseconds' |
Mutates the original moment by adding time. See momentjs#add
.
Examples
Parameters | Values |
---|---|
<date> |
An optional value interpretable as a date/time by moment (a date String or a Moment or a Date ...). Defaults to value of moment() |
<number> |
Any value(s) interpretable as a duration by moment that is the amount of the precision you want to subtract from the date provided |
precision |
An optional unit of measurement, defaults to 'milliseconds' |
Mutates the original moment by removing time. See momentjs#subtract
.
Examples
Parameters | Values |
---|---|
<dateA> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
<dateB> |
An optional value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...). If not given, <dateA> becomes now and <dateB> becomes <dateA> |
precision |
An optional String unit of comparison precision, defaults to 'milliseconds' |
Returns a Boolean
that indicates if <dateA>
is respectively before/after/the same/same or before/ same or after <dateB>
to the precision
level. See momentjs#queries
.
Examples
Parameters | Values |
---|---|
<date> |
Any value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
<dateA> |
A boundary value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...) |
<dateB> |
An optional boundary value(s) interpretable as a date/time by moment (a date String or a Moment or a Date ...). If not given <date> is assigned now, <dateA> is assigned <date> and <dateB> is assigned <dateA> . |
precision |
An optional String unit of comparison precision, defaults to 'milliseconds' |
inclusivity |
An optional String indicating inclusivity of the boundaries, defaults to () |
Returns a Boolean
that indicates if <date>
is between <dateA>
and <dateB>
to the precision
level and with boundary inclusions specified by inclusivity
. See momentjs#is-between
.
Examples
Returns the present Moment.
Examples
Parameters | Values |
---|---|
<timestamp> |
An integer Number or String value representing the number of seconds since the Unix Epoch (January 1 1970 12AM UTC) |
Returns a Moment corresponding to the <timestamp>
.
Examples
All helpers accept the following optional named arguments (even though they are not always applicable):
Parameters | Values |
---|---|
locale |
An optional String locale, to override the default global moment.locale |
timeZone |
An optional String time zone, defaults to moment.timeZone (the default time zone) |
interval |
An optional interval Number of milliseconds when the helper should be recomputed |
allow-empty |
An optional Boolean to ignore the Invalid date output when knowingly passing null , undefined , or '' , defaults to false |
Note that interval
does not recompute the value of the helper parameters, unless it is
part of a helper that is a value in which case it is useful for "live" updating as time elapses.
Warning: allow-empty
is currently inconsistent and should not always be trusted.
Examples
This addon provides the ability to import moment as an ES6 module.
import moment from 'moment';
You can optionally include the Moment Timezone package in your config/environment.js
like so:
// config/environment.js
module.exports = function() {
return {
moment: {
// Options:
// 'all' - all years, all timezones
// 'subset' - 2012-2022, all timezones
// 'none' - no data, just timezone API
includeTimezone: 'all'
}
}
};
Your application may require a default format other than the default, ISO 8601. For example, you may want dates to fallback on the localized shorthand format L
by default.
// config/environment.js
module.exports = function() {
return {
moment: {
outputFormat: 'L'
}
}
};
If you need to change the default format during runtime, use the service API. Doing so will cause the moment-format helper instances to re-render with the new default format.
// app/controller/index.js
export default Ember.Controller.extend({
moment: Ember.inject.service(),
actions: {
changeDefaultFormat() {
this.set('moment.defaultFormat', 'MM.DD.YYYY');
}
}
})
If null
, undefined
, or an empty string are passed as a date to any of the moment helpers then you will get Invalid Date
in the output. To avoid this issue globally, you can set the option allowEmpty
which all of the helpers respect and will result in nothing being rendered instead of Invalid Date
.
// config/environment.js
module.exports = function() {
return {
moment: {
allowEmpty: true // default: false
}
}
};
// config/environment.js
module.exports = function(environment) {
return {
moment: {
// To cherry-pick specific locale support into your application.
// Full list of locales: https://github.com/moment/moment/tree/2.10.3/locale
includeLocales: ['es', 'fr-ca']
}
};
// config/environment.js
module.exports = function(environment) {
return {
moment: {
includeLocales: true
}
};
NOTE: English is bundled automatically, no need to add en
in includeLocales
Alternatively, you can copy all of moment's locale files into your dist
directory.
// config.environment.js
module.exports = function(environment) {
return {
moment: {
// This will output _all_ locale scripts to assets/moment-locales
// this option does not respect includeLocales
localeOutputPath: 'assets/moment-locales'
}
};
This allows you to load them on demand when you need them:
Ember.$.getScript('/assets/moment-locales/fr.js');
// app/routes/applicaton.js
export default Ember.Route.extend({
moment: Ember.inject.service(),
beforeModel() {
this.get('moment').setLocale('es');
}
});
// app/routes/applicaton.js
export default Ember.Route.extend({
moment: Ember.inject.service(),
beforeModel() {
this.get('moment').setTimeZone('America/Los_Angeles');
}
});
Invalid Date
is being rendered into the DOM, how do I avoid this?
An invalid date string is being passed into momentjs and/or the input string format was omitted.
If you are knowingly passing null, undefined, or an empty string and want to ignore the output of Invalid Date
then pass the option allow-empty=true
to the helper (all helpers accept this property)