From: Tim Wood Date: Wed, 21 Dec 2011 17:56:01 +0000 (-0800) Subject: Adding documentation for moment.fn.calendar X-Git-Tag: 1.3.0~21 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0aa17277c53d8ca46eab6716b4be709ac9718bc1;p=thirdparty%2Fmoment.git Adding documentation for moment.fn.calendar #102 --- diff --git a/site/docs/index.html b/site/docs/index.html index 5fc8d52b7..adb4d4785 100644 --- a/site/docs/index.html +++ b/site/docs/index.html @@ -1,4 +1,4 @@ -Moment.js Documentation

Moment.js Documentation

A lightweight javascript date library for parsing, manipulating, and formatting dates.

Where to get it

Github

Production Version 1.2.03.1kb minified & gzippedDevelopment Version 1.2.021.2kb full source + comments

You can also clone the project with Git by running:

git clone git://github.com/timrwood/moment

npm

npm install moment

Where to use it

Moment was designed to work in both the browser and in NodeJS. All code will work in both environments. All unit tests are run in both environments.

In NodeJS

var moment = require('moment');
+Moment.js Documentation
Moment.js Documentation
A lightweight javascript date library for parsing, manipulating, and formatting dates.
Where to get it
Github
Production Version 1.2.03.1kb minified & gzippedDevelopment Version 1.2.021.2kb full source + comments
You can also clone the project with Git by running:
git clone git://github.com/timrwood/moment
npm
npm install moment
Where to use it
Moment was designed to work in both the browser and in NodeJS. All code will work in both environments. All unit tests are run in both environments.
In NodeJS
var moment = require('moment');
 moment().add('hours', 1).fromNow(); // "1 hour ago"
 
In the browser
<script src="moment.min.js"></script>
 moment().add('hours', 1).fromNow(); // "1 hour ago"
@@ -53,7 +53,7 @@ moment().milliseconds() === new Date().getMilliseconds();
 
var date = new Date(2010, 1, 14, 15, 25, 50, 125);
 moment(date).format("dddd, MMMM Do YYYY, h:mm:ss a"); // "Sunday, February 14th 2010, 3:25:50 pm"
 moment(date).format("ddd, hA");                       // "Sun, 3PM"
-
TokenOutput
Month
M1 2 ... 11 12
Mo1st 2nd ... 11th 12th
MM01 02 ... 11 12
MMMJan Feb ... Nov Dec
MMMMJanuary February ... November December
Day of Month
D1 2 ... 30 30
Do1st 2nd ... 30th 31st
DD01 02 ... 30 31
Day of Year
DDD1 2 ... 364 365
DDDo1st 2nd ... 364th 365th
DDDD001 002 ... 364 365
Day of Week
d0 1 ... 5 6
do0th 1st ... 5th 6th
dddSun Mon ... Fri Sat
ddddSunday Monday ... Friday Saturday
Week of Year
w1 2 ... 52 53
wo1st 2nd ... 52nd 53rd
ww01 02 ... 52 53
Year
YY70 71 ... 29 30
YYYY1970 1971 ... 2029 2030
AM/PM
AAM PM
aam pm
Hour
H0 1 ... 22 23
HH00 01 ... 22 23
h1 2 ... 11 12
hh01 02 ... 11 12
Minute
m0 1 ... 58 59
mm00 01 ... 58 59
Second
s0 1 ... 58 59
ss00 01 ... 58 59
Timezone
z or zz (lowercase)EST CST ... MST PST
Z-07:00 -06:00 ... +06:00 +07:00
ZZ-0700 -0600 ... +0600 +0700
Localized date format
L07/10/1986
LLJuly 10 1986
LLLJuly 10 1986 8:30 PM
LLLLSaturday, July 10 1986 8:30 PM
To escape characters in format strings, you can use a backslash before any character. NOTE: if you are using a string literal, you will need to escape the backslash, hence the double backslash below.
moment().format('\\L'); // outputs 'L'
To escape multiple characters, you can wrap the characters in square brackets.
moment().format('[today] DDDD'); // 'today Sunday'
While these date formats are very similar to LDML date formats, there are a few minor differences regarding day of month, day of year, and day of week.
For a breakdown of a few different date formatting tokens, see this chart of date formatting tokens.
To compare moment.js date formatting speeds against other libraries, check out http://jsperf.com/date-formatting .
+
TokenOutput
Month
M1 2 ... 11 12
Mo1st 2nd ... 11th 12th
MM01 02 ... 11 12
MMMJan Feb ... Nov Dec
MMMMJanuary February ... November December
Day of Month
D1 2 ... 30 30
Do1st 2nd ... 30th 31st
DD01 02 ... 30 31
Day of Year
DDD1 2 ... 364 365
DDDo1st 2nd ... 364th 365th
DDDD001 002 ... 364 365
Day of Week
d0 1 ... 5 6
do0th 1st ... 5th 6th
dddSun Mon ... Fri Sat
ddddSunday Monday ... Friday Saturday
Week of Year
w1 2 ... 52 53
wo1st 2nd ... 52nd 53rd
ww01 02 ... 52 53
Year
YY70 71 ... 29 30
YYYY1970 1971 ... 2029 2030
AM/PM
AAM PM
aam pm
Hour
H0 1 ... 22 23
HH00 01 ... 22 23
h1 2 ... 11 12
hh01 02 ... 11 12
Minute
m0 1 ... 58 59
mm00 01 ... 58 59
Second
s0 1 ... 58 59
ss00 01 ... 58 59
Timezone
z or zz (lowercase)EST CST ... MST PST
Z-07:00 -06:00 ... +06:00 +07:00
ZZ-0700 -0600 ... +0600 +0700
Localized date format
LT8:30 PM
L07/10/1986
LLJuly 10 1986
LLLJuly 10 1986 8:30 PM
LLLLSaturday, July 10 1986 8:30 PM
To escape characters in format strings, you can use a backslash before any character. NOTE: if you are using a string literal, you will need to escape the backslash, hence the double backslash below.
moment().format('\\L'); // outputs 'L'
To escape multiple characters, you can wrap the characters in square brackets.
moment().format('[today] DDDD'); // 'today Sunday'
While these date formats are very similar to LDML date formats, there are a few minor differences regarding day of month, day of year, and day of week.
For a breakdown of a few different date formatting tokens, see this chart of date formatting tokens.
To compare moment.js date formatting speeds against other libraries, check out http://jsperf.com/date-formatting .
 
Note: Baron Schwartz wrote a pretty cool date formatter that caches formatting functions to avoid expensive regex or string splitting. It's so much faster than any of the other libraries, that it's best to compare it on its own, rather than pollute the "best of the uncompiled" formatting libs.
Here's the moment.js vs xaprb performance tests, and here is the
 article describing his methods.
Time from another moment
Another common way of displaying time, sometimes called timeago, is handled by moment.fn.from.
 
var a = moment([2007, 0, 29]);
@@ -82,8 +82,13 @@ start.from(end, true); // "5 days"
 trueas the second parameter, you can get the value without the suffix.
 
moment([2007, 0, 29]).fromNow();     // 4 years ago
 moment([2007, 0, 29]).fromNow(true); // 4 years
-
Difference
To get the difference in milliseconds, use moment.fn.diff like you would use moment.fn.from.

-
var a = moment([2007, 0, 29]);
+
Calendar time
Calendar time is displays time relative to now, but slightly differently than moment.fn.from.
+
moment.fn.calendar will format a date with different strings depending on how close to today the date is.
+
Last weekLast Monday 2:30 AM
The day beforeYesterday 2:30 AM
The same dayToday 2:30 AM
The next dayTomorrow 2:30 AM
The next weekSunday 2:30 AM
Everything else7/10/2011
These strings are localized, and can be customized with moment.calendar or 
+moment.lang.
+
Difference
To get the difference in milliseconds, use moment.fn.diff like you would use 
+moment.fn.from.
+
var a = moment([2007, 0, 29]);
 var b = moment([2007, 0, 28]);
 a.diff(b) // 86400000
 
To get the difference in another unit of measurement, pass that measurement as the second argument.
var a = moment([2007, 0, 29]);
@@ -125,6 +130,14 @@ moment([2011, 2, 14]).isDST(); // true, March 14 2011 is DST
         PM : 'PM',
         pm : 'pm'
     },
+    calendar : {
+        sameDay: "[Ajourd'hui à] LT",
+        nextDay: '[Demain à] LT',
+        nextWeek: 'dddd [à] LT',
+        lastDay: '[Hier à] LT',
+        lastWeek: 'dddd [denier à] LT',
+        sameElse: 'L'
+    },
     relativeTime : {
         future : "in %s",
         past : "il y a %s",
@@ -212,6 +225,15 @@ moment(1316116057189).fromNow(); // il y a une heure
     pm : 'pm',
     PM : 'PM'
 };
+
Calendar
moment.calendar should have the following formatting strings.
+
moment.meridiem = {
+    lastDay : '[Yesterday at] LT',
+    sameDay : '[Today at] LT',
+    nextDay : '[Tomorrow at] LT',
+    lastWeek : '[last] dddd [at] LT',
+    nextWeek : 'dddd [at] LT',
+    sameElse : 'L'
+};
 
Ordinal
moment.ordinal should be a function that returns the ordinal for a given number.
 
moment.ordinal = function (number) {
     var b = number % 10;
diff --git a/sitesrc/docs.jade b/sitesrc/docs.jade
index 2d167ee3e..0d8eb9e27 100644
--- a/sitesrc/docs.jade
+++ b/sitesrc/docs.jade
@@ -75,6 +75,8 @@ block content
           a(href="#/display/from") Time from another moment
         li
           a(href="#/display/fromNow") Time from now
+        li
+          a(href="#/display/calendar") Calendar time
         li
           a(href="#/display/diff") Difference
         li
@@ -133,6 +135,8 @@ block content
           a(href="#/custom/relativeTime") Relative Time
         li
           a(href="#/custom/meridiem") AM/PM
+        li
+          a(href="#/custom/calendar") Calendar
         li
           a(href="#/custom/ordinal") Ordinal
     #docs
@@ -634,6 +638,9 @@ block content
             td
               b Localized date format
             td
+          tr
+            td LT
+            td 8:30 PM
           tr
             td L
             td 07/10/1986
@@ -769,10 +776,49 @@ block content
         | moment([2007, 0, 29]).fromNow(true); // 4 years
 
 
+      a(name="/display/calendar")
+      h3
+        span Calendar time
+      p Calendar time is displays time relative to now, but slightly differently than 
+        code moment.fn.from
+        | .
+      p 
+        code moment.fn.calendar
+        |  will format a date with different strings depending on how close to today the date is.
+      table
+        tr
+          td Last week
+          td Last Monday 2:30 AM
+        tr
+          td The day before
+          td Yesterday 2:30 AM
+        tr
+          td The same day
+          td Today 2:30 AM
+        tr
+          td The next day
+          td Tomorrow 2:30 AM
+        tr
+          td The next week
+          td Sunday 2:30 AM
+        tr
+          td Everything else
+          td 7/10/2011
+      p These strings are localized, and can be customized with 
+        a(href="#/custom/calendar") moment.calendar
+        |  or 
+        a(href="#/i18n/lang") moment.lang
+        | .
+
+
       a(name="/display/diff")
       h3
         span Difference
-            
To get the difference in milliseconds, use moment.fn.diff like you would use moment.fn.from.

+      p To get the difference in milliseconds, use 
+        code moment.fn.diff
+        |  like you would use 
+        code moment.fn.from
+        | .
       pre var a = moment([2007, 0, 29]);\n
         | var b = moment([2007, 0, 28]);
         | a.diff(b) // 86400000
@@ -926,6 +972,14 @@ block content
         |         PM : 'PM',
         |         pm : 'pm'
         |     },
+        |     calendar : {
+        |         sameDay: "[Ajourd'hui à] LT",
+        |         nextDay: '[Demain à] LT',
+        |         nextWeek: 'dddd [à] LT',
+        |         lastDay: '[Hier à] LT',
+        |         lastWeek: 'dddd [denier à] LT',
+        |         sameElse: 'L'
+        |     },
         |     relativeTime : {
         |         future : "in %s",
         |         past : "il y a %s",
@@ -1122,6 +1176,23 @@ block content
         |     PM : 'PM'
         | };
 
+
+      a(name="/custom/calendar")
+      h3
+        span Calendar
+      p
+        code moment.calendar
+        |  should have the following formatting strings.
+      pre moment.meridiem = {\n
+        |     lastDay : '[Yesterday at] LT',
+        |     sameDay : '[Today at] LT',
+        |     nextDay : '[Tomorrow at] LT',
+        |     lastWeek : '[last] dddd [at] LT',
+        |     nextWeek : 'dddd [at] LT',
+        |     sameElse : 'L'
+        | };
+
+
       a(name="/custom/ordinal")
       h3
         span Ordinal