Here are some guidelines and tips to get you started and through most common situations when handling dates in cplaceJS.
Table of contents
- Creating a new date object and getting the current date
- Extracting date fields from date objects
- Formatting and displaying dates
- Calculating dates
- Things to avoid doing
Creating a date object with Joda is as easy as creating any other date object - you just call the constructor
var date = new DateTime();
and you got yourself a
DateTime object of the current date and time.
If you want to create an object from a given point in time you can use the constructor overload like this:
year day minute | | | var cplaceDay = new DateTime(2019, 11, 13, 12, 0); | | month hour
If really necessary you can even create a
var jsDate = new Date(); // some logic which requires a JS date ... var dateFromAttribute = new DateTime(jsDate.getTime());
however in most cases you should not find yourself in a situation where that is actually necessary. See here for more on that topic.
Note that also calling the
get() method on a date attribute will also provide a DateTime object.
It is possible to extract specific date fields from a
DateTime object, eg. the year or month by using the
appropriate methods. There are multiple possibilities to access the date fields whereas the noted alternatives
will probably be the ones you'll use most, just because they're more convenient to type:
var dateTime = new DateTime(2019, 11, 13, 0, 0); var year = dateTime.year().get(); // -> 2019 var yearAlt = dateTime.getYear(); var month = dateTime.monthOfYear().get(); // -> 11 var monthAlt = dateTime.getMonthOfYear(); var dayOfMonth = dateTime.dayOfMonth().get(); // -> 13 var dayOfMonthAlt = dateTime.getDayOfMonth();
this is a great and handy way to access specific parts of a date to check against any condition, e.g. "Change the color of a report element to icy blue when the date is in a winter month". However this should not be used to dis- and reassemble dates for display or further calculation!
For further information on which fields can be accessed see the official joda-time api documentation.
To format a date use the
toString(String) method with the desired pattern string as the parameter.
For detailed explanation of supported symbols see the documentation for DateTimeFormat.
An kind of everyday example may be
var dateToFormat = new DateTime(2019, 8, 14, 0, 0); var formattedDate = dateToFormat.toString('EEEE, dd MMMM yyyy'); // -> Wednesday, 14 August 2019
With joda it is also possible to easily calculate and compare dates.
You can check how two dates are related by checking
var cplaceDay = new DateTime(2019, 11, 13, 13, 0); var christmas = new DateTime(2019, 12, 24, 18, 0); var release4_56 = new DateTime(2019, 5, 29, 0, 0); var cplaceDayBeforeChristmas = cplaceDay.isBefore(christmas); // -> true var release4_56AfterChristmas = release4_56.isAfter(christmas); // -> false
It is also possible to add and substract intervals from dates:
var date = new DateTime(); var theDayAfterTomorrow = date.plusDays(2); var tenThousandBC = date.minusYears(12000);
These methods will not mutate the original date, but rather create a new instance of DateTime with the calculated date set. This is similiar to the following which also won't alter the date object, but create a new one with the appropiate date field set to the given value:
var now = new DateTime(); var startOfCurrentMonth = now.dayOfMonth().setCopy(1);
Of course the general rule of keeping code clean, readable and understandable applies here as well, but we want to give some guidelines which practises you should try to avoid as they are unnessecarily complicated thus hard to understand and/or perform badly.
Do not convert different date types. Stick to one type instead. There usually should not be any reason to convert a DateTime to JS date or vice versa:
var date = page.get('cf.tutorial.date'); var parsedDate = new Date(date.getMillis()); var year = parsedDate.getYear(); var month = parsedDate.getMonth(); var day = parsedDate.getDay(); // ...
Instead just use the DateTime object and work with that - the api should be able to provide everything needed. This way your code stays easier to read and understand and you prevent unnessecary operations.
var dateTime = new DateTime(new Date().getTime()); // or var date = new Date(); var otherDateTime = new DateTime(date.getTime());
as this is redundant. In that case just use the default constructor (
new DateTime() ) of DateTime. Only do
this if it is really necessary to use a native JS date (which is probably very unlikely but still might occur).