Date manipulation in WCTL

For the most part, date manipulation in Webcrossing scripting is more familiar and intuitive in Server-Side Javascript (SSJS). The Date object has a full suite of getters and setters, objects can be directly compared using the < = > operators, and Webcrossing extends the object with the dateFormat() method that makes it easy to present a date in any format. But there are always cases where you're doing layouts in WCTL and it may be inconvenient to do the mode switch into JS. (There's also a tiny performance penalty for doing so, insignificant in all but the highest-traffic sites.) WCTL has directives for comparing and manipulating dates, but since it is an untyped language - basically, everything is a string except when it's a string treated like an integer - it may strike you as a giant kludge. Nevertheless, its date-manipulation routines are powerful and useful once you get accustomed to the weirdness.

The basis to WCTL date manipulation is a string in the format Y4-M2-D2-H4.I2.S2[.L3], for example 2011-06-23-15.05.00 to represent today at five minutes past three in the afternoon. You can optionally add another three digits to represent milliseconds. Note that month, day, hour, minute, second must all be two digits; note hours, minutes, and seconds delimited by a dot instead of a colon; note that the month index is 1-based instead of 0-based as in Javascript. This format string is referred to as a dateObject or dateObj, and this is the only format that WCTL recognizes as a date. All of the directives discussed here use a dateObj.

To compare dates, there are .dateEqual, .dateLessThan, and .dateGreaterThan. All three use the syntax

%% date1.dateLessThan(date2) %%

where both date1 and date2 are dateObj-format strings. In this example, the directive evaluates to 1 if date1 is before date2, 0 otherwise. Similarly,

%% date1.dateDeltaSeconds(date2) %%

evaluates to the seconds elapsed from date1 to date2. If the former is after the latter, the value is negative.

To alter a dateObj string you can use .dateSetHours, .dateSetMinutes, .dateSetSeconds in the format

%% dateString.dateSetHours(int) %%

Where int is the hour (0-23) or in the other functions the minute or second (0-59). How, you may ask, do you set the year, month, or day? There are no dedicated directives for that purpose; instead you must use string manipulation to parse out and replace those numbers.

For raw numbers there are %% milliseconds %% that evaluates to the elapsed milliseconds since the most recent midnight, server time, and %% secsFrom1970 %% that evals to the elapsed seconds since the midnight before January 1, 1970. Less well-known is the directive %% sexFrom1970 %% that will reveal an interesting fact about the past 41 years of the user's personal life.

Finally, %% date %% and %% time %% are synonyms; both return the current time in the site's default format (set in the Control Panel). If you call them with dateObj (the literal string) as an argument, the return value is in dateObj format.