Male user:TheDJ/tables
Template:H:h
Tables can be made Template:Mlw via client-side JavaScript with class="sortable" (in combination with the usual formatting: class="wikitable sortable"). This works in MediaWiki 1.9 and above, which is installed in all Wikimedia projects.
A sortable table is identified by the arrows in each of its header cells. Clicking them will cause the table rows to sort based on the selected column, in ascending order first, and subsequently toggling between ascending and descending order. Links and other wiki-markup are not possible in headers.
JavaScript[edit]
The JavaScript code jquery.tablesorter.js (source) of the tablesorter is loaded by the ResourceLoader. Some sites may have a page MediaWiki:Common.js which adds and overrides some code.
Sort modes[edit]
The way items are sorted depends on the data type of the item currently in the first row. To determine the data type, multiple cells are tested and the most appropriate format is chosen. Mismatches are possible, but can be easily corrected by manually specifying data-sort-type inside the header of the respective row:
{|class="wikitable sortable"
! data-sort-type="date" | Date!!Name!!Height
|-
|01.10.1977||Smith||1.85
|-
|11.6.1972||Ray||1.89
|-
|1.9.1992||Bianchi||1.72
|}
The following (case-insensitive) values are valid for data-sort-type:
- text
- number
- IPAdress
- currency
- url
- isoDate
- usLongDate
- date
- time
Tags such as span or sup are ignored when determining data type.
Dates[edit]
Various date formats are supported, including those with localized month names. On the German Wikipedia, "16. März 2010" is correctly sorted as 2010-03-16
Most other numerical formats are supported as well, including those with different separators (such as . , ' or / ); On English Wikipedias dates are treated as US-Dates (eg. month-day-year) per default.
Numbers[edit]
The script can recognize numbers with different decimal separators (. and ,) as well as e/E numbers.
Text[edit]
Text is sorted in ASCII order (Any accented/special characters follow after the basic latin alphabet). This can be changed site wide by posting code like the following inside the common.js:
mw.config.set('tableSorterCollation', {'ä':'ae', 'ö' : 'oe', 'ß': 'ss', 'ü':'ue'});
Afterwards, all 'ä' will be sorted as if they were an ae etc.
Partial list showing the default order: !"#$%&'()*+,-./09:;<=>?@[\]^_'az{|}~é—
Examples[edit]
|
|
|
|
|
|
|
|
|
The example with "a" gives alphabetic sorting; that with "e" ditto, the data are not mistaken for numbers in scientific format.
|
|
|
|
The first example demonstrates that text is positioned at zero, and that e.g. e3 for 1000 is not allowed; use 1e3 instead. It also shows that "-" should be used, not "−".
The second example shows that expressions are not sorted according to their evaluated value, but according to the first number.
The third example shows that a percentage is accepted for numeric sorting mode, but ignored in the actual sorting, so if a column contains percentages, all numbers have to be written as a percentage.
The fourth example shows again that "ca. 12" sorts at 0, as opposed to 12 with some text after it, which sorts at 12. In case such an element arrives at the top of a column, it causes alphabetic sorting mode.
Additional features[edit]
Excluding the last row from sorting[edit]
Sometimes it is helpful to exclude the last row of a table from the sorting process.
This can be achieved by declaring the last row as a footer
Wiki markup
{|class="wikitable sortable"
!Name!!Surname!!Height
|-
|John||Smith||1.85
|-
|Ron||Ray||1.89
|-
|Mario||Bianchi||1.72
|-
! !!Average:||1.82
|}
What it looks like in your browser
| Name | Surname | Height |
|---|---|---|
| John | Smith | 1.85 |
| Ron | Ray | 1.89 |
| Mario | Bianchi | 1.72 |
| Average: | 1.82 |
Excluding the first row from sorting[edit]
The same can be applied for first rows as well, by declaring them as header using the same exclamation mark notation.
Making a column unsortable[edit]
If you want a specific column not to be sortable, specify class="unsortable" in the attributes of its header cell.
Wiki markup
{|class="wikitable sortable"
!Numbers!!Alphabet!!Dates!!Currency!!class="unsortable"|Unsortable
|-
|1||Z||02-02-2004||5.00||This
|-
|2||y||13-apr-2005||||Column
|-
|3||X||17.aug.2006||6.50||Is
|-
|4||w||01.Jan.2005||4.20||Unsortable
|-
|5||V||05/12/2006||7.15||See?
|-
!Total: 15!!!!!!Total: 29.55!!
|-
|}
What it looks like in your browser
| Numbers | Alphabet | Dates | Currency | Unsortable |
|---|---|---|---|---|
| 1 | Z | 02-02-2004 | 5.00 | This |
| 2 | y | 13-apr-2005 | Column | |
| 3 | X | 17.aug.2006 | 6.50 | Is |
| 4 | w | 01.Jan.2005 | 4.20 | Unsortable |
| 5 | V | 05/12/2006 | 7.15 | See? |
| Total: 15 | Total: 29.55 | Original example |
Correcting a wrongly parsed cell[edit]
Sometimes the value of a cell is not correctly parsed or one wants to sort the row in a special way. (e.g. a cell containing 'John Doe' should actually be sorted as 'Doe' and not as 'John')
This can be easily achieved by manually setting
data-sort-value
Note, however, that this will not work on Wikimedia Foundation wikis, which strip all "data-*" attributes.
Wiki markup
{|class="wikitable sortable"
!Name and Surname!!Height
|-
|data-sort-value="Smith"|John Smith||1.85
|-
|data-sort-value="Ray"|Ian Ray||1.89
|-
|data-sort-value="Bianchi"|Zachary Bianchi||1.72
|-
!Average:||1.82
|}
What it looks like in your browser
| Name and Surname | Height |
|---|---|
| John Smith | 1.85 |
| Ian Ray | 1.89 |
| Zachary Bianchi | 1.72 |
| Average: | 1.82 |
Keeping some rows together[edit]
data-sort-value can be used to keep certain rows together. The original mutual order of these rows is preserved.
Example where this is the case for the rows about the Netherlands:
| Country/province | Capital |
|---|---|
| France | Paris |
| Netherlands | Amsterdam |
| South Holland | The Hague |
| U.K. | London |
Special dates[edit]
For years BC we can use, for example, !9937-09-23 for -0062-09-23 (subtract the year number BC from 10000, or the absolute value of the astronomical year from 9999).
If a table column contains any or all incomplete dates, this will not cause sorting problems. If only a year and month are given, that incomplete date is positioned alphabetically before the first day of the month in question. Likewise, if only a year is given, the date is positioned before the first month or day given for that year.
Use of #time[edit]
Using parser function #time we can put <span style="display:none">&{{#expr:3e11+{{#time:U|..}}}}</span> in front of the displayed date. This works in the range 1 Jan 111, 00:00:00 through 31 Dec 9999, 23:59:59 for the proleptic Gregorian calendar. The added value makes all values positive and the same length (if scientific format would show up an additional step is needed to prevent this). The "&" forces string sort mode.
Dates and times can be entered in any php date/time format. Note that when we have just a year, a month (typically Jan) must be added in the hidden part.
Example using Help:Sorting/date:
To use dates before the year 111, add a multiple of 400, e.g. 6000, to all years, this effectively shifts the range to 1 Jan -5889, 00:00:00 through 31 Dec 3999, 23:59:59, without changing the calendar.
See also:
Secondary sortkey[edit]
The sorting algorithm employed is a Template:Mlw: If a column contains a value multiple times then sorting the column preserves the order of the rows within each subset that has the same value in that column (Template:Mlw). Thus sorting based on a primary, secondary, tertiary, etc. sortkey can be done by sorting the least-significant sortkey first, etc.
First click on column Text and then, while holding the shift-key, on Numbers, you'll see that the ordering is on Numbers (1), Alphabet (2).
| Numbers | Text | Dates | Currency | More text |
|---|---|---|---|---|
| 4 | a | 01.Jan.2005 | 4.20 | row 1 |
| 5 | a | 05/12/2006 | 7.15 | row 2 |
| 1 | b | 02-02-2004 | 5.00 | row 3 |
| 1 | a | 02-02-2004 | 5.00 | row 4 |
| 2 | x | 13-apr-2005 | row 5 | |
| 2 | a | 13-apr-2005 | row 6 | |
| 3 | a | 17.aug.2006 | 6.50 | row 7 |
| 3 | z | 25.aug.2006 | 2.30 | row 8 |
| 3 | z | 28.aug.2006 | 5.50 | row 9 |
| 3 | z | 31.aug.2006 | 3.77 | row 10 |
| 3 | z | 01.sep.2006 | 1.50 | row 11 |
| Bottom |
Cell spanning multiple rows/cells[edit]
Cells which are spanning more than one row are treated as if it were multiple cells with the same value.
Example:
| Date | Name | Height |
|---|---|---|
| 01.10.1977 | Smith | 1.85 |
| 11.6.1972 | Adams | |
| 1.9.1992 | Bianchi | 1.72 |
Javascript sorting may not work properly on tables with cells extending over multiple rows and/or columns (however, sorting of columns up to and including the first with colspan does not seem to be affected). Also, while cells can be empty, they should not be missing at the end of a row. In these cases sometimes the table gets messed up when attempting to sort, while other times some of the sorting buttons work while others don't.
Colspan workaround[edit]
To allow sorting, the formal number of cells in each row should be equal (if not all columns are made sortable this should apply at least for the number of cells up to and including the last sortable column). However, with a CSS hack the number of cells shown in a row can differ from the formal number of cells. For example, two formal cells can be shown as one by specifying a width for the first column, shifting the contents of the second cell to the left, increasing its width by the same amount, and hiding the cell border that would normally be visible. Hidden sortkeys can be used to control, for sorting with respect to each column, how this row should be sorted.
Example:
| Country | Capital |
|---|---|
| France | Paris |
| U.K. | London |
This can be combined with the method of "keeping some rows together" demonstrated above. For an example of an application of this, consider a table of three columns where the third column would make the table too wide, such as a column of miscellaneous details. These details can be put in separate rows, each staying below the corresponding row when the table is sorted.
Example:
| Country | Capital |
|---|---|
| France | Paris |
| U.K. | London |
| Germany | Berlin |
A table row template makes this technique less cumbersome to apply, see e.g. w:List of furry conventions, w:Template:Furry-con-list-start and w:Template:Furry-con-list-entry.
Controlling sorting and display[edit]
Text undesired for sorting but needed for display:
- In numeric sorting mode, the sorting will still work properly even though the cell (except the cell of the first data row) contains text after numbers (e.g. "200 approx"). Empty cell is treated as "zero" when sorting numerically. See e.g. Help:Sorting/countries. However bear in mind that the cell of the first data row will change accordingly after sorting. If that cell no longer contains number only after sorting, the sorting mode will change. For example, if the cell of the first data row becomes "200 approx" after sorting, this will make the sorting mode alphabetic.
- In date sorting mode, this text needs to be put in a separate column; in the case of a cell containing a range of dates or numbers (e.g. from .. to ..), text in surplus of what is required for sorting is put in the extra column. If the first part of the text is used for sorting, then the extra column needs to be the following one; conversely, if the last part of the text is used for sorting, then the extra column needs to be the previous one; depending on the table format, this dividing of an item over two cells may look ugly.
- In alphabetic sorting, any footnotes etc. do not require a separate column; they can simply be put at the end of the element.
Static column[edit]
A static column, e.g. with row numbers, can be obtained with two side-by-side tables with for each row the same height set in both tables:
|
|
The style can be adjusted to make it appear as a single table. If for some row the height of that row is too small for the text in a cell on one of the sides, the browser increases it, and there is no longer a match.
Default order[edit]
It is not possible to make a table appear sorted by a certain column without the user clicking on it. By default, the rows of a table always appear in the same order as in the wikitext. If you want a table to appear sorted by a certain column, you must sort the wikitext itself in that order; see the next section for one way to do this.
Sorting the wikitext of a table[edit]
Sorting the wikitext itself, thus creating a new default sort order, can be done semi-automatically by making an auxiliary sortable table where each row is rendered as the wikitext for the corresponding row of the original table. Applying the JavaScript sorting as desired, the result can be copied to provide the sorted wikitext for the original table.
Example:
Original table:
| demo |
|---|
| 9 |
| 12 |
| 11 |
Auxiliary table:
| aux |
|---|
| |- | 9 |
| |- |12 |
| |- |11 |
After copying the rendered text to the edit box, to provide the body of the table syntax (between the header part and the closing line), this renders as a new table, sorted by default:
| demo |
|---|
| 9 |
| 11 |
| 12 |
The auxiliary table can be kept, to be reused in case one later (or on another page) wants to use another column for determining the default order, or wants to change between ascending and descending.
Basic alphabetic sorting order[edit]
| demo |
|---|
| ! |
| " |
| # |
| $ |
| % |
| & |
| ' |
| ( |
| ) |
| * |
| + |
| , |
| - |
| . |
| / |
| 0 |
| 9 |
| : |
| ; |
| < |
| = |
| > |
| ? |
| @ |
| [ |
| \ |
| ] |
| ^ |
| _ |
| ` |
| A |
| Z |
| a |
| z |
| A1 |
| Z1 |
| a1 |
| z1 |
| { |
| | |
| } |
| ~ |
| — |
| É |
| é |
| É1 |
| é1 |
The two-character entries such as A1 demonstrate that A and a are at the same position.
This is not a fully alphabetic sort order: letter case is first folded to lowercase using a basic 1-to-1 conversion table (limited to the Basic Multilingual Plane of Unicode, and whose coverage and completeness still depends on browser versions and on their current implementation of the versioned Unicode Character Database), but letters with diacritics (and all other digits, symbols or special whitespaces or format control characters) will still sort according to the binary encoding of the casefolded letter, using the binary order of the UTF-16 code units (exposed and seen in Javascript through the parsed HTML DOM), but not the binary order of UTF-8 code units in the HTML page, and not of codepoints as one could also expect for encoded characters in supplementary planes).
In addition, no normalization of the Unicode text is being performed (so canonically equivalent strings, that should compare equal or with only very minor binary difference, may sometimes compare very far away, with completely different strings interleaved between them). For this reason, MediaWiki pages should always be encoded with their text in the Normalized Form C (preComposed), as recommended in the HTML standards.
As of today, an UCA-based sort is still not implemented in the client-side Javascript code, but some wikis are implementing a limited form of multilevel collation using custom basic replacement rules tuned for specific languages.
Server issue[edit]
It has been observed that the MediaWiki code on the server replaces a regular space before "!" by a non-breaking space  , affecting the sorting order. To avoid this, this blank space can be coded as  , or the exclamation mark may be surrounded by <nowiki> and </nowiki> tags. This is to comply with French typographic rules, where exclamation marks (and a few other punctuations) must be preceded (or sometimes followed) by a space (preferably narrow) which must still be unbreakable when it is effectively needed and present, the substitution being performed as an convenient editing facility of the Wiki code for cases that are very frequent within many texts.
Persistent sort states using cookies[edit]
Adding this snippet to your MediaWiki:Common.js page will make the sortable tables remember their columns sort states in a cookie so they look the same next time the page is visited. Each sortable table must have a unique id attribute for its state to be stored in the cookie.
addOnloadHook( function() {
jQuery('.sortable').each( function() {
var id = jQuery(this).attr('id');
document.shCookie = getCookie('sortheader-'+id);
document.sortheaderId = 0;
jQuery('#'+id+' a.sortheader').each( function() {
var id = jQuery(this).parent().parent().parent().parent().attr('id');
var sh = document.sortheaderId++;
if( sh+100 == document.shCookie ) { ts_resortTable(this); ts_resortTable(this); }
if( sh == document.shCookie ) { ts_resortTable(this); sh += 100; }
jQuery(this).bind('click', {id: id, sh: sh}, function(e) {
setCookie('sortheader-'+e.data.id, e.data.sh, 1);
e.data.sh += e.data.sh < 100 ? 100 : -100;
});
});
});
});
function setCookie(c_name,value,exdays) {
var exdate=new Date();
exdate.setDate(exdate.getDate() + exdays);
var c_value=escape(value) + ((exdays==null) ? "" : "; expires="+exdate.toUTCString());
document.cookie=c_name + "=" + c_value;
}
function getCookie(c_name) {
var i,x,y,ARRcookies=document.cookie.split(";");
for (i=0;i<ARRcookies.length;i++) {
x=ARRcookies[i].substr(0,ARRcookies[i].indexOf("="));
y=ARRcookies[i].substr(ARRcookies[i].indexOf("=")+1);
x=x.replace(/^\s+|\s+$/g,"");
if (x==c_name) return unescape(y);
}
}
The getCookie and setCookie functions are those recommended by W3C from W3Schools.
See also[edit]
- Template:Ml
- Template:Tiw - sorting a table by a date column, while following w:Wikipedia:Manual_of_Style_(dates_and_numbers)#Dates_containing_a_month_and_a_day for display
- w:Category:Sorting templates
- Template:Tim - shows buggy date sorting when some or all dates are linked
- Help:Table
- wikibits.js - contains, among other things, the sorting code
- changes regarding sorting:
- Sep 2008: allow negative numbers and scientific notation in determining numeric sort mode
- Nov 2007 allow multiple commas in numbers - from [1]
- Feb 2007 allow pound and euro in currency sort mode
- Jan 2007 sorttable.js merged into wikibits.js
- for older revisions see the revision history of sorttable.js
- Template:Mlm page overriding function ts_parseFloat(num) and function ts_resortTable(lnk) on Meta with improved versions
- page overriding function ts_parseFloat(num); adaptation to decimal comma
- changes regarding sorting:
- bugzilla:2001 - resolved feature request
- bugzilla:8063 - request to enable sorting of numbers with a point as thousands separator
- bugzilla:8115
- http://www.kryogenix.org/code/browser/sorttable/ - explanation of the original version of the code by Stuart Langridge; an improvement in the MediaWiki version is that tables no longer need to have an id.
- http://blog.webkist.com/archives/000043.html
- http://www.joostdevalk.nl/code/sortable-table/
- w:Wikipedia:Wikipedia Signpost/2007-01-02/Technology report
- Template:Tiw
- mw:Extension:Sort2
- mw:Extension:Sort
- w:User:TimR/Tables
Examples elsewhere:
- w:Ranked list of Dutch provinces
- w:List of countries by GDP estimates for 2006 (nominal)
- w:List of countries by GDP (PPP), 2006
- w:List of longest reigning current monarchs - date columns are sortable for people with "no preference" for date formatting, and for people with preference [[YYYY-MM-DD]].
- Pokémon table - prefixes numbers with "#" to have them before "-".
- Nuclear power by country (Featured List)
- w:Desert Island Discs: castaways' choices
- zh:秘鲁行政区划 (Subdivisions of Peru) for sorting of Chinese (CJK)
- w:Standard electrode potential (data page)