Date manipulation is one of those development hurdles that we all must jump at one point in our career, and great tools go a long way in taming the beast.
The Moment.js library is that tool for JavaScript developers.
Since discovering Moment.js, an open source project, I’ve used it religiously to simplify validation, parsing and manipulation of dates on the client-side.
In this tutorial, I’ll help you get up and running with this ultra-useful JavaScript date library.
What is Moment.js?
Moment.js is a free and open source JavaScript library that removes the need to use the native JavaScript Date object directly. The library is a wrapper for the Date object (in the same way that jQuery is a wrapper for JavaScript) making the object a whole lot easier to work with.
The problem with JavaScript’s Date object isn’t the functionality it brings; it’s just extremely cumbersome to use as a developer. If you want to do complex parsing, validation and displaying of dates, you’ll end up writing a lot of code.
Moment.js also extends native JavaScript date capabilities with a variety of features, such as relative time, calendar time, durations and multi-language support. It has a seemingly endless list of plugins that allow for additional features like time-zone support, recurrence and Twitter integration.
Tutorial Information
In this tutorial, we’re going to take a look at Moment.js. The following are the things we’ll tackle.
Referencing Moment.js and displaying basic date outputs
Displaying formatted dates
Parsing dates
Detecting invalid dates
Correcting invalid dates
Adding and subtracting dates
There are demo pages for almost all the sections of this tutorial that demonstrate the code being discussed.
Alternatively, you can download all the demo files associated with this tutorial as a ZIP archive.
Download All Demo Files
Let’s dive in.
Referencing Moment.js and Displaying Basic Outputs
To get started, you’ll need to download Moment.js and reference it in your HTML document. You can also find the library at cdnjs.com (a public CDN for open source projects). Just search for the library using the term "moment.js".
The first thing we’re going to do in this tutorial is to reference the Moment.js library.
Then, to make sure it’s working properly, we’re going to instantiate a moment object and a JavaScript Date object, and then output their values.
The following shows you how to reference the Moment.js library in your HTML documents, as well as how to instantiate and display the values of the moment object and the JavaScript Date object.
View Demo 1
At this point, the code-lengths of both the moment and native Date object look on par.
Displaying Formatted Dates
Things between moment and JavaScript Date quickly change, however, when we want to output even a simple, human-readable date display with the format of ‘Y-m-d’ (e.g. ’2014-7-1′).
Using JavaScript Date, this would be our code.
Moment.js makes our code terser.
View Demo 2
You’ll notice we had to add a lot of set-up code for our specific date format output in the native solution, and only a simple method called .format() in the Moment solution.
The string argument that we passed into .format(), which is 'YYYY-M-D', is the format that we’re asking the Moment.js library to return the date in. The Moment.js website has many format options conveniently listed in a table here:
http://momentjs.com/docs/#/displaying/format/
Now that we’re familiar with the process of displaying and formatting the current date, let’s move on.
Parsing Dates
The Moment initializer will take a parameter and set the Date object to that date.
One detail to note is there’s no standard that browsers adhere to when parsing dates. Fortunately, the Moment.js library provides additional parameters that allow us to specify the exact pattern we’re passing in to help us avoid cross-browser inconsistencies.
For consistency across all browsers and platforms, the above code should be parsed like the fowlloing.
View Demo 3
The Moment.js website has another table displaying the available parameters that we can use for parsing:
http://momentjs.com/docs/#/parsing/string-format/
As the value we’re parsing is rarely entered by hand, it’s important to know that we’re actually parsing a date value.
Consider the input '2014-14-14' — this is an impossible date. In this case the moment() function will actually return the string 'Invalid Date' if you try to parse it.
However, there are additional tools available to us for detecting and correcting an invalid date values.
Detecting Invalid Dates
To detect an invalid date, Moment.js provides us with the isValid() method. It returns a simple boolean value (true or false), enabling us to determine the next course of action in our code logic in case the date value is not a valid one.
The other detection method available is invalidAt(). This method is more specific, it will tell us where our date value is invalid. It will return an integer between 0 and 6, the meanings of which can be found in the following table.
Integer
Error location
0
Years
1
Months
2
Days
3
Hours
4
Minutes
5
Seconds
6
Milliseconds
So, in the example of '2014-14-14', the invalidAt() function would return 1 because 14 is an invalid month (only 1-12 are valid month values).
Correcting Invalid Dates
When would you ever be able to correct an invalid date? If you haven’t worked with dates at length before, this one might stump you. However, there are more variables at play than just the date itself: We must also consider how we’re getting the date and who is providing it.
Often, we ask people to enter dates and, despite our best efforts and flashy tooltips asking them to input in a specific date format like "d/m/y", they ignore our instructions and provide "m/d/y" anyways.
We can go back to the date-parsing call we made earlier and add a second parsing parameter (you can have more than two options) by passing in a string array of various possible date formats as a fallback.
Let’s use the date January 1, 2014 as our input example. We’ll input 14/1/2014 and 1/14/2014 expecting an input of D/M/YYYY.
View Demo 4
You’ll notice that with just one string argument, if the input doesn’t match, you will output 'Invalid Date'.
However, if you provide an array of string formats as the argument, the first parsing option that works will be used. This is great for removing or anticipating possible user errors.
Adding and Subtracting Dates
One of my favorite features in the Moment.js library is it conveniently has date-manipulation methods, such as .add() and .subtract().
For example:
View Demo 5
The Moment.js library will handle edge-cases elegantly. For example, using the native JavaScript Date object, adding one month to August 31 will result in October 1. This same operation performed by Moment.js will correctly produce September 30.
Conclusion
Moment.js is an excellent tool to have if you regularly end up working with client-side date parsing, formatting and validation. It has plenty to offer in terms of speeding up JavaScript development in this area. To see the project’s source code, head over to its GitHub repository. To learn more about its features, check out the official docs.
Related Content
Speed Up Your Web Development Workflow with Grunt
Top 10 Mobile Web Development JavaScript Frameworks
A Guide to the New HTML5 Form Input Types
About the Author
Bradley Holbrook is a senior software developer for Click4Time Software Inc. He has been designing and developing web applications for over 15 years. Connect with Bradley via email.
The post Working with JavaScript Dates Using Moment.js appeared first on Six Revisions.