View source for Template:Dts/doc

{{Documentation subpage}}
<!-- EDIT TEMPLATE DOCUMENTATION BELOW THIS LINE -->
{{High-use|20200+}}
{{Mbox|type=content|text=Please check that you do actually need this template before using it. Default date sorting does not work for spelled-out month–year or year–month combos and dates before the year 100, but it works in most other circumstances. Furthermore, this template litters the [[devmo:Web/API/Node/textContent|text content]] of tables, and <code>data-sort-value</code> should generally be preferred. For more information, see {{Section link|Help:Sorting|Date sorting problems}}.}}
{{COinS safe|n}}
{{lua|Module:Dts}}

'''Dts''' (date time sorting) is used to correctly sort and display dates in a sortable table (see [[Help:Sorting]]).

==What it solves==
Dates in their customary formats, if simply treated as alphanumeric text strings, sort in nonsensical ways:
*1 August 2013 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 (see [[WP:DATEFORMAT]]).

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%;" |{{tlf|dts|''year''|''month''|''day''|''BC''}}
! style="width: 50%;" |{{tlf|dts|''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 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.
|}


{| class="wikitable sortable"
|+ Examples
!input style
!input code
!hidden sort key
!visible output
{{dts/testcases/row|span=3|a={{tlf|dts|''year''}}|1893}}
{{dts/testcases/row|-89}}
{{dts/testcases/row|-10000}}
{{dts/testcases/row|a={{tlf|dts|''month''}}|Oct}}
{{dts/testcases/row|a={{tlf|dts|''month year''}}|February 1767}}
{{dts/testcases/row|a={{tlf|dts|''day month year''}}|12 Aug 1987}}
{{dts/testcases/row|a={{tlf|dts|''month day, year''}}|July 1, 1867}}
{{dts/testcases/row|a={{tlf|dts|''day month''}}|25 October}}
{{dts/testcases/row|a={{tlf|dts|''month day''}}|Jan 1}}
{{dts/testcases/row|a={{tlf|dts|''YYYY-MM-DD''}}|2014-12-09}}
{{dts/testcases/row|span=3|a={{tlf|dts|''year''|''month''}}|1990|10}}
{{dts/testcases/row|1980|Dec}}
{{dts/testcases/row|1970|August}}
{{dts/testcases/row|span=2|a={{tlf|dts|''year''|''month''|''day''}}|2024|Jun|12}}
{{dts/testcases/row|-204|11|22}}
{{dts/testcases/row|span=2|a={{tlf|dts|''year''|''month''|''day''|''era''}}|44|3|15|BC}}
{{dts/testcases/row|94|Oct|17|AD}}
{{dts/testcases/row|a={{tlf|dts||''month''}}||May}}
{{dts/testcases/row|a={{tlf|dts||''month''|''day''}}||Sep|12}}
|}

===Formatting===
Using <code>format</code> produces a format that depends on, but is not necessarily equal to the format of the supplied date. The <code>format</code> parameter can take nine values.

{|class="wikitable sortable"
|+ Examples
|-
!value
!function
!input code
!hidden sort key
!visible output
{{dts/testcases/row|span=3|a=&nbsp;|b=format depends on the input|26 Jan 1788}}
{{dts/testcases/row|March 12, 1557}}
{{dts/testcases/row|1975-02-13}}
{{dts/testcases/row|span=2|a=<code>dmy</code>|b=displays the date in day-month-year format|Sep 13, 1888|format=dmy}}
{{dts/testcases/row|1983-01-03|format=dmy}}
{{dts/testcases/row|span=2|a=<code>dm</code>|b=displays only the day and month in day-month format|Feb 26, 1788|format=dm}}
{{dts/testcases/row|2020-10-15|format=dm}}
{{dts/testcases/row|span=2|a=<code>mdy</code>|b=displays the date in month-day-year format|August 31, 1901|format=mdy}}
{{dts/testcases/row|2006-11-08|format=mdy}}
{{dts/testcases/row|span=2|a=<code>md</code>|b=displays only the day and month in month-day format|26 Jun 1988|format=md}}
{{dts/testcases/row|2002-02-27|format=md}}
{{dts/testcases/row|a=<code>my</code>|b=displays only the month and year in month-year format|16 November 1488|format=my}}
{{dts/testcases/row|a=<code>d</code>|b=displays only the day|6 July 1666|format=d}}
{{dts/testcases/row|a=<code>m</code>|b=displays only the month|1980-02-12|format=m}}
{{dts/testcases/row|a=<code>y</code>|b=displays only the year|-26|Jan|18|format=y}}
{{dts/testcases/row|a=<code>hide</code>|b=hides the date|15 October 1800|format=hide}}
|}

===Abbreviation===
There are two ways of abbreviating the month name.
# Directly input an abbreviated month name.
# Use the <code>abbr=on</code> parameter.

{|class="wikitable sortable"
|+ Examples
|-
!abbreviation method
!input code
!hidden sort key
!visible output
{{dts/testcases/row|span=4|a=none|2000-01-01}}
{{dts/testcases/row|2000|1|1}}
{{dts/testcases/row|1 January 2000}}
{{dts/testcases/row|2000|January|1}}
{{dts/testcases/row|span=2|a=abbreviated input|1 Jan 2000}}
{{dts/testcases/row|2000|Jan|1}}
{{dts/testcases/row|span=4|a=<code>abbr{{=}}on</code>|1 January 2000|abbr=on}}
{{dts/testcases/row|2000|January|1|abbr=on}}
{{dts/testcases/row|2000-01-01|abbr=on}}
{{dts/testcases/row|2000|1|1|abbr=on}}
|}

===Additional sort key===
In case two dates in a table are identical they may be ordered using the <code>addkey</code> parameter.

{|class="wikitable sortable"
|+ Examples
|-
!input code
!hidden sort key
!visible output
{{dts/testcases/row|2010-10-10|addkey=3}}
{{dts/testcases/row|2010-10-09}}
{{dts/testcases/row|2010-10-10|addkey=1}}
{{dts/testcases/row|2010-10-10}}
{{dts/testcases/row|2010-10-10|addkey=4}}
{{dts/testcases/row|2010-10-11}}
{{dts/testcases/row|2010-10-10|addkey=2}}
|}

===Wrapping===
To turn off the suppression of word wraps, use the <code>nowrap=off</code> parameter.

==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===
Entering an invalid date format will (generally)<!--It's not quite perfect.--> produce an error message such as the one below.
<blockquote>{{dts|35 June 1900}}</blockquote>

Errors are tracked in [[:Category:Dts 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. Transclusions using the {{para|link}} parameter are tracked in [[:Category:Dts templates with deprecated parameters]].

==See also==
* {{tim|dts}}, since on Meta e.g. 09999 9999 induces numeric sort mode, "&" is prefixed to force string sort mode.
* {{tl|sort}}, sorting by a specified key (also good for complicated numbers, e.g. scientific notation)
* {{tl|sortname}}, full name sorting (using "last name, first name" as default sort key)
* {{tl|tts}}, for sorting times in result tables of athletic events (only needed in certain cases - see template documentation)
* {{tl|mss}}, for sorting times in tables of eclipses
* {{tl|nts}}, for numbers

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Sorting templates|Dts]]
[[Category:Date mathematics templates]]

}}</includeonly>