Saucy: doc

2021-02-01T03:06:13Z

doc

New page

'''Date table sorting''' is used to correctly sort and display dates in a sortable table.

Template [[wp:Template:Date table sorting|copied from Wikipedia]]. Additional documentation is available there.

==What it solves==
Dates in their customary formats, if simply treated as alphanumeric text strings, sort in nonsensical ways:
*1 September 1998 sorts alphanumerically before 5 March 1967, because ''1'' is less than ''5'';
*February 5, 1922 sorts alphanumerically before January 3, 1922, because ''F'' comes before ''J''.
Use of the YYYY-MM-DD format would solve this problem, but with minor exceptions that format is not used in articles.

This template automatically attaches a "hidden key" to dates, causing them to sort correctly while still being displayed in one of the customary display formats such as ''February 5, 1922'' or ''5 Feb 1922''.

==Parameters==
===Dates===
{|class=wikitable
|-
|+The year, month and day can either be entered separately or as a single date.
|-
! style="width: 50%;" |{{Date table sort|''year''|''month''|''day''|''BC''}}
! style="width: 50%;" |{{Date table sort|''date''}}
|- style="vertical-align:top;"
|
* 1st parameter – Year (optional if month is given)
** Positive number (1 to 999,999,999,999) represent years AD or BC (dependant on the fourth parameter).
** Negative numbers (−1 to −999,999,999,999) represent years BC (without the fourth parameter).
** Year numbers must not contain commas or other formatting.
* 2nd parameter – Month (optional if the day is not given either)
** Full month name – e.g. February
** Abbreviated month name – e.g. Feb
** Month number – (either zero-padded or not) e.g. 2 or 02
* 3rd parameter – Day (optional)
** Day number – (either zero-padded or not) e.g. 7 or 07
* 4th parameter – (optional)
** May be BC, AD, BCE or CE
** Used with a positive year number
|
* 1st parameter – the full date
** By default YYYY-MM-DD format becomes month-day-year format and DD-MM-YYYY format becomes day-month-year while other formats remain in the order they are input.
** Abbreviated months are accepted and are abbreviated in the output.
** Capitalisation and comma mistakes are corrected.
** A single number is interpreted as a year, otherwise the date is parsed by the module. The following formats are accepted:
*** YYYY-MM-DD
*** DD-MM-YYYY
*** DD Month YYYY
*** Month DD, YYYY
*** YYYY-MM
*** DD Month
*** Month DD
*** Month YYYY
*** YYYY
*** Month
** Day and month numbers may be 1 or 2 digits, and year numbers may only be 3 or 4 digits. If you need to input a number less than 1000, use leading zeroes (e.g. "0700").
** BC years can only be parsed if the date is only the year number.
** If you need to include the day or month for BC years or years greater than 9999, you must use separate parameters for year, month and day.
|}

==TemplateData==
<templatedata>
{
"params": {
"1": {
"label": "Full date or year",
"description": "Full date if second to fourth parameters are not specfied, otherwise year. Full date can be either in \"YYYY-MM-DD\", \"DD-MM-YYYY\", \"DD Month YYYY\", \"Month DD, YYYY\", \"YYYY-MM\", \"DD Month\", \"Month DD\", \"Month YYYY\" or \"Month\" format. Year is either a positive number or a negative number. If fourth parameter is not specified negative numbers are interpreted as years of BC era. Parameter is optional if the second parameter is specified.",
"example": "\"1893\", \"-89\", \"-10000\", \"Oct\", \"February 1767\", \"12 Aug 1987\", \"July 1, 1867\", \"25 October\", \"Jan 1\", \"2014-12-09\"",
"type": "string"
},
"2": {
"label": "Month",
"description": "Full or abbreviated month name or alternatively, a month number which can be zero-padded. Parameter is optional if the third parameter is not specified.",
"example": "February, Feb, 2 or 02",
"type": "string"
},
"3": {
"label": "Day",
"description": "Day, optionally zero-padded",
"example": "7 or 07",
"type": "number"
},
"4": {
"label": "Era",
"description": "BC, AD, BCE or CE. Takes effect only if the first parameter is a positive number.",
"type": "string"
},
"format": {
"label": "Format",
"description": "Controls the output format. Can be \"dmy\", \"dm\", \"mdy\", \"md\", \"my\", \"d\", \"m\", \"y\" or \"hide\".",
"type": "string"
},
"abbr": {
"label": "Abbreviation",
"description": "Abbreviates the month name",
"example": "on",
"type": "string",
"default": "off"
},
"addkey": {
"label": "Additional sort key",
"description": "Adds another sort key to resolve conflicts between rows with the same date",
"example": "3",
"type": "number"
},
"nowrap": {
"label": "Wrapping",
"description": "To turn off the suppression of word wraps, use the \"off\" parameter",
"example": "off",
"type": "boolean",
"default": "off"
}
},
"description": "Date table sorting is used to correctly sort and display dates in a sortable table."
}
</templatedata>

==Notes==
===Sorting for incomplete dates===
;Whole months or years: A whole year or month (and year) is sorted according to its first day.
;Missing years: If the year is not specified, the date will be sorted as if the year were the current year.
;Blank dates: For no date input at all, the maximum possible sort key is used, so the entry will sort last.

===Error handling===
Errors are tracked in [[:Category:Date table sorting templates with errors]].

===Calendar choice===
The template is not capable of distinguishing Julian and Gregorian calendar dates. Also, it is not capable of taking a date in one calendar as input and outputting a date in the other calendar. Thus, to insure proper sorting, editors must either use one calendar for all dates, or pick a specific changeover date (for example, deciding that 4 October 1582 is Julian and all later dates are Gregorian); this would be done on an article-by article basis. Editors are also responsible for explaining to the reader whether the visible dates are Julian or Gregorian, if there is any possibility of confusion.

===Linking===
The template formerly linked dates automatically, with <code>link=off</code> used to suppress linking. In accordance with current guidelines linking of dates is no longer supported and instances of <code>link=off</code> should be removed.

Template:Date table sort/doc - Revision history

Saucy: doc