Extension:TableData

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
OOjs UI icon advanced.svg
Table Data
Release status: beta
Implementation Tag
Description Provides a tabledata tag for formatting data as a table.
Author(s) Daniel Friesen (Dantmantalk)
License GPL2+
Download Template:WikimediaDownload/svn
Translate the TableData extension if it is available at translatewiki.net
Check usage and version matrix.

TableData implements a <tabledata> tag. This tag can take data input in a variety of forms such as csv and tab separated data and will output a simple table based on this data. This table can be fully formatted and customized using templates, when using a full set of templates you technically don't actually even need to output a table.

The input format parsing is extensible, other extensions can add other formats, json, yaml, whatever, as long as they output the correct data. All data is expected to define a list of headings and output rows using those headings as keys. In csv and separated data the first row is considered the definition of the headers.

Usage[edit]

The extension is used via <tabledata></tabledata> tags in articles. The contents of these tags is the data you are making a table out of. Each tabledata tag must define the format that the data is in. The header, row, and footer attributes can optionally define the name of a template to use to format the header, individual rows, and the footer.

Examples[edit]

This defines a simple table with no borders:

<tabledata format=csv>
Format,1,2,3,4
Numeric,1,2,3,4
Alphabet,A,B,C,D
Roman,I,II,III,IV
</tabledata>

The result would be something like this:

Format 1 2 3 4
Numeric 1 2 3 4
Alphabet A B C D
Roman I II III IV

To add any special formatting one would define templates to use to format the table:

<tabledata format=csv header=Header row=Row footer=Footer>
Format,1,2,3,4
Numeric,1,2,3,4
Alphabet,A,B,C,D
Roman,I,II,III,IV
</tabledata>

This would instead output template inclusions to Template:Header Template:Row and Template:Footer to format the table.

Formats[edit]

The extension contains two formatters by default, you define which format parser to use with the format= attribute to the tabledata tag:

format=csv
The csv format expects comma-separated values formatted data with a comma as a separator and php's default handling of " as an enclosure and \ as an escape.
format=separated
The separated data format expects an extra separator attribute to be defined.
Valid separators are:
space
Single spaces (not multiple)
tab
A single tab (not multiple)
whitespace
Multiples of any whitespace such as spaces and tabs
comma
Commas ",". Note that this is not the same as csv which uses a csv parser that supports quoting commas inside values you cannot quote or escape commas in the separated format
colon
A single colon ":"
semicolon
A single semicolon ";"

Templates[edit]

The header, row, and footer attributes can be used to define the name templates to use to format the header, individual rows, and the footer of the table (or something else if you decide to override them all and output something different).

Typically you should define a simple table header in the header:

{| ...
!| [...]

And inside of the row template define a table row:

|- [...]
|| [...]

The footer should contain a table end:

|}

If you are just customizing the formatting of the table you usually don't need to override the footer, unless you are creating something other than a table, or want to add table headers to the footer.

Parameters[edit]

Each of these templates are passed a number of parameters to allow them to output and format the data.

The table data of a row is passed into the row template in parameters named by the header they are associated with. So in the above examples the value of the Format column for a row would be included into the template using a {{{Format}}}. Additionally the row template can output the number of the current table row using {{{#}}} the value of this number starts at 1 for the first row.

For all templates, the header, footer, and row templates the names of the headers are included inside of {{{#1#}}} parameters where {{{#1#}}} is the first header, {{{#2#}}} is the second, and so on.

Note that because the names of headers are passed as arguments to the row template it becomes possible to hack in generic formatting templates (with a limited number of columns) by using a trick like {{{ {{{#1#}}} }}} to output the contents of the first header and so on.

This template setup makes table data based tables very flexible. You can define fairly generic table formats to be used for data by using the {{{#1#}}} parameters to output header names, and the {{{ {{{#1#}}} }}} trick to output table cells in header order. Or for more complex data you can define custom header, row, and footer templates with header names hardcoded in the templates and use the headers inside of the data table to define a clean set of parameters that the data should be exposed to the row templates with to make custom formatted data that previously took a lot of direct template inclusions much simpler.

Beta[edit]

There are one or two things not yet implemented in the extension.

  • A hook to allow extensions to define parsers for new input data formats.
  • The CSV parser needs some extra code to be compatible with php < 5.3 which does not have str_getcsv but has fgetcsv.

Alternatives[edit]