General Configuration

Date Formats

This tutorial explains how dates are formatted in Confluence...

There are several places where dates are used in Confluence such as the General Configuration settings (which set the default formats for dates and times) and various macros including the chart macro, date-data macro and page-info macro.

All dates and times are stored in the same way, however they can be displayed in many different formats. To set the format, you use a "date pattern" which is a series of characters that define where particular pieces of information are shown, for example:

Using date patterns, you can format dates and time in almost any concievable way.

Date and time formats are specified by date and time pattern strings. Within date and time pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted as pattern letters representing the components of a date or time string.

Text can be quoted using single quotes (') to avoid interpretation. Two single quotes together ('') results in a single quote (') being displayed.

All other characters are not interpreted; they're simply copied into the output string during formatting or matched against the input string during parsing.

Pattern Letters

Case Senstitive! The characters used in the date patterns are case sensitive. For example, "m" (minute) and "M" (month) are obviously very different things.

Presentation

As you'll see from the table above, each character has a designated "presentation" that defines how it will look when output. Different presentations have different special properties as listed below...

Note:
When using macros such as the chart macro, date patterns can also be used to parse dates in tables, etc. Parsed dates sometimes have slightly different settings and are detailed at the end of each presentation type.

Text

If the number of pattern letters is 4 or more, the full form is used; otherwise a short or abbreviated form is used if available as shown in the examples below:

For parsing, both forms (three letter abbreviation and full day name) are accepted, independent of the number of pattern letters.

Number

The number of pattern letters defines the minimum number of digits, and shorter numbers are zero-padded to ensure the desired number of digits as shown in the example below:

For parsing, the number of pattern letters is ignored unless it's needed to separate two adjacent fields.

Month

If the number of pattern letters is 3 or more, the month is interpreted as Text; otherwise, it is interpreted as a Number.

Year

If the number of pattern letters is 2 digits, the last two digits of the year are shown, otherwise it is treated as a Number.

For parsing, if the number of pattern letters is more than 2, the year is interpreted literally, regardless of the number of digits. So using the pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D.

For parsing with the abbreviated year pattern ("y" or "yy"), it must interpret the abbreviated year relative to some century. It does this by adjusting dates to be within 80 years before and 20 years after the time the current year (usually).

For example, using a pattern of "MM/dd/yy" and a SimpleDateFormat instance created on Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964.

During parsing, only strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that isn't all digits (for example, "-1"), is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC.

General Time Zone

Time zones are interpreted as Text if they have names:

As shown in the last example, if a time zone does not have a name, a GMT offset will be shown in the format:

For example: GMT-8:00

RFC 822 Time Zone

An IETF RFC 822 time zone always shows the offset from Greenwich Mean Time.

If the number of pattern characters is 3 or less, an offset in the form hhmm is given. If the number of pattern characters is 4 or more, an offset in the form hh:mm is given.

Delimiter

A delimiter is used to display text when formatting a date/time string, for example:

The text at will be treated as literal.

Without the quotes, the a would be treated as the AM/PM marker:

Because additional letters may have specific meaning assigned to them in later versions, you should always enclose Literal text in Delimiters.

Quote

Obviously, there may be occasions when you want to display a quote - to do this, simply place two quotes together:

Literal

Literal text is not processed - it is merely output when formatting and when parsing it is skipped.

Any text can be made literal by using Delimiters as stated above.

Any character that does not have any special meaning (i.e. not a letter of the alphabet), such as a colon (:), is also treated as literal text.

See Also

• SimpleDateFormat – Java's date utility classes are generally used for formatting dates in Confluence.
• Joda Time – Another library that's used in several 3rd party macros.