Dates

Table of Contents

• Date-Producing Macros

  • Optional Date-Macro Parameters
  • Formatting Keywords
  • Formatting Codes
  • Language Codes
  • Examples

• Date-based Conditional Macros

Date-Producing Macros

There are a number of macros that return displayable dates (for email, html, xml, etc.).

• msgCreationDate
• msgModificationDate
• msgCustomField (for date fields)
• pageModified
• pageCreated
• weblogTimestamp

All of these macros work basically the same way. We'll use #msgCreationDate in our samples, but remember that you can use the same approach with most of the date macros.

Optional Date-Macro Parameters

While different date macros have different parameters depending on what they're used for, all of the date macros have three optional parameters in common.

• format

  This determines the format of the date and time that will be returned by the macro. It's extremely flexible, allowing virtually any date format, but it's also very easy to use because the most common options can be specified with a keyword instead of a rather cryptic date-formatting string.

  More information, including a complete reference to the formatting codes, can be found below.

• timezoneName

  The name of the timezone is a short string like "GMT" or "EDT". It's only used if you've specified a format which includes the timezone.

• lang

  "lang" allows you to localize your dates to the formats of any of a number of different languages. The default is "EN," for English, but you can also use "DE" for German and "FR" for French. Other localizations will be available soon.

Formatting Keywords

The format string can contain either a single keyword, or one or more formatting codes. The keyworlds represent pre-written format strings, localized for each different language's standard way of displaying dates and times.

The following are the keywords recognized by Conversant's date formatter.

abbrev	Abbreviated name of the day, abbreviated name of the month, day of the month, and the full year.
date	Numerical month, day, and year.
default	Combination of "date" and "time", separated by a semicolon and a space.
long	Full name of the day, full name of the month, day of the month, and full year.
longWithTime	Everything in "long" plus a space and everything in "time."
netstandard	Returns a date in the standard format for the internet. Mon, 10 Jun 2002 01:47:25 GMT
short	Same as "date"
time	Hour, minute, and am/pm designation.
timeWithSecs	Hour, minute, seconds, and am/pm designation.

Formatting Codes

The format string can contain either a single keyword (as described above) or any of the following formatting codes. These codes each insert a specific part of a date, and anything which returns text (instead of a number) will use a localized version as specified by the "lang" parameter.

2-9	Pads any numerical value with n zeroes, to guarantee that a certain number of characters are always used. The numbers are special codes, and must appear after the % but before one of the other codes.
%a	abbreviated weekday names: "Thu"
%A	complete weekday names: "Thursday"
%b	abbreviated month names: "Aug"
%B	complete month names: "August"
%c	localized date and time, default format
%d	day of the month, as a number (1-31)
%H	the hour on the 24-hour clock (0-23)
%I	the hour on the 12-hour clock (1-12)
%j	day of the year as a number (0-366)
%m	month as a number (1-12)
%M	minute as a number (1-59)
%p	localized version of "AM" or "PM"
%S	second as a number (0-59)
%U	week of the year as a number, for weeks starting on Sundays (0-53)
%w	day of the week as a number (1-7)
%W	week of the year as a number, for weeks starting on Mondays (0-53)
%x	localized standard date format
%X	localized standard time format
%y	two-digit year as number (00-99)
%Y	four digit year as number: 1972
%z	name or abbreviated name of the timezone, as provided in parameter, or empty string if not provided
%%	a single %

Language Codes

Dates can be localized by including the lang parameter. The value of this parameter is just a two-letter code specifying a region.

Being "localized" means two things: names of months and days will be displayed in the specified language, and the keywords produce dates which are formatted according to localized customs.

en	English (typically American English) This is the default, used if the lang attribute is not present.
fr	French
de	German

Examples of Format Strings in Macros

The following examples show use of the formatting strings with two of Conversant's date macros.

• Keyword

  <!--#msgCreationDate format="long"-->

  » Friday, March 1, 2002

• Hyphenated Date

  <!--#msgCreationDate format="%Y-%m-%d"-->

  » 2002-6-9

• Decimal Date, Fixed Width

  <!--#msgCreationDate format="%Y.%2m.%2d"-->

  » 2002.06.09

• Day of the Year with Arbitrary Text

  <!--#msgCreationDate format="Day %j of '%y"-->

  » Day 160 of '02

• French - Long Date and Time

  <!--#msgCreationDate format="longwithtime" lang="fr"-->

  » lundi 10 juin 2002 11:08 AM

Date-based Conditional Macros

This section not yet written.