Tutorial

Working with dates

Handling dates in cplaceJS works a little different than working with plain Javascript date objects. cplace provides the Joda date library to scripts, which makes working with those data much more convenient. This is available in every cplaceJS script.

Here are some guidelines and tips to get you started and through most common situations when handling dates in cplaceJS.

Table of contents
  1. Creating a new date object and getting the current date
  2. Extracting date fields from date objects
  3. Formatting and displaying dates
  4. Calculating dates
  5. Things to avoid doing

Creating a new date object and getting the current date

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 DateTime object from a javascript date like

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.

Extracting date fields from date objects

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.

Formatting and displaying dates

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

Calculating dates

With joda it is also possible to easily calculate and compare dates. You can check how two dates are related by checking isBefore(DateTime) or isAfter(DateTime) like

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);

Things to avoid doing

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.

Also do not create DateTime objects from JS dates just for the sake of it like

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).