Extension:DataTable
From MediaWiki.org
 Release status: beta |
|
|---|---|
| Implementation | Tag, Parser function, Database |
| Description | store data in a table and retrieve it on other pages |
| Author(s) | RV1971 Talk |
| Version | 0.3 (2007-10-10) |
| MediaWiki | >=1.9.0 |
| Download | Extension:DataTable/Source Extension:DataTable/ChangeLog |
| Hooks used | |
Contents |
[edit] Motivation
At work I administer a MediaWiki installation which contains, among others, a history of days where new software versions were will be released to production. For each release, there is a page describing the steps which were done / will be done; furthermore there is an overview page listing all releases in tabular form. The single pages and the overview page share some data like release date, status, affected component, summary. Obviously I want to update these data in one place only, as they may change frequently (for instance the date of a planned release).
There are some extensions which could be used for such a task to a limited extent. For instance, with recent versions of Extension:DynamicPageList, you could enter the data in each detail page and display it in a master page.
However, this (and other extension which might be used for such a purpose) is not that straightforward, and from a performance point of view it would be inadequate to manage large amounts of data. Therefore I wrote a new extension, borrowing the basic idea of the Tasks Extension: a tag is provided which displays data and at the same time saves it to a database table, so that it can be retrieved on other pages.
[edit] How to Install the DataTable Extension
- Apply the SQL script to create a new table in your database.
- Save the extension source code as a file extensions/DataTable/DataTable.php.
- Add the following line to your LocalSettings.php:
require_once( "extensions/DataTable/DataTable.php" );
[edit] Usage
[edit] Storing Data
To store data, you use the datatable tag. Each line within the tag corresponds to a record with fields separated by pipe characters. The parser is sufficiently intelligent so that you can use links or parametrized templates and similar staff within a field, even if this contains pipe characters. If a line starts with #, the rest of the line is passed verbatim to the MediaWiki parser for display.
In the simplest case, data is displayed just in a normal table. For instance, you can set up a list of important pages with some attributes like this:
<datatable table=demo>
#{|
#|-
{{PAGENAME}}|interesting page|extension description
[[Manual:Contents|Manual]]|very interesting page|manual page
#|}
</datatable>
will display
| this page | interesting page | extension description |
| Manual | very interesting page | manual page |
and save the data in your database table.
If you only want to save the data without any display, you can provide the parameter display=no in the datatable tag.
For fancier formatting, you can provide a parameter template=some_template. Then, the template will be invoked for each record, with the fields as template parameters. Note that the template does not need to create tabular output, it can just do anything with the data. You can also use this as a comfortable way to display a series of template invocations without saving the data to the database. In that case, just omit the table parameter.
You can have several datatable tags on a page storing data in the same table or in different tables. You can also have datatable tags on different pages storing data to the same table. The way the extension works is fairly simple: each time a page is saved, all data from this page which was previously stored in the database table is erased, and then all data defined on the new version of this page is saved. Furthermore, if a page is deleted from MediaWiki, the corresponding data is erased as well.
[edit] Retrieving Data
To retrieve data, there is a new parser function data whose syntax is as follows:
{{#data: table|columns|template|condition|sort|p1|p2|p3|p4}}
You will not always need to supply all these parameters. Evaluation of this function works as follows:
- The extension performs a select distinct of the given columns from the given table which satisfy the given condition (if any) and sorts the result as indicated (if any). Columns in the condition and the sort specification are simply called c1, c2, c3, .... If no columns are specified, all columns are taken.
- If no template is indicated, all rows found are displayed separated by semicolon, with field separated by comma. Normally this is useful only when retrieving a single column from a single row.
- If a template is specified, it is invoked for each row with the selected columns as parameters. Furthermore, the contents of p1, p2, ... are passed to the template as named parameters p1, p2, ....
You might consider using the StackFunctions Extension to use the query results in more sophisticated ways.
[edit] Notes
- Currently there is no hook when importing pages into MediaWiki. Therefore, after importing pages with Special:Import which contain datatable tags, you must edit and save each single page.
- If you retrieve data on the same page where it is stored, changes will not immediately be visible after saving. This is because the data in the database is updated after the page has been rendered for output. To see the changes, you need to purge the page after saving.
