Extension:DataTable/Main
Contents |
[edit] Motivation
In my company, our MediaWiki 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 MW: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 from 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] Installation
- See Extension:DataTable/Install when you install DataTable for the first time.
- See Extension:DataTable/Upgrade when you upgrade an existing DataTable installation.
- See Extension:DataTable/Parameters for a complete list of parameters you might choose to customize in your LocalSettings.php.
- See Extension:DataTable/ChangeLog for all the change history.
[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 parameterized templates and similar stuff within a field, even if this contains pipe characters.
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">
<head>
! Page
! Rating
! Type
</head>
{{FULLPAGENAME}}|interesting page|extension description
[[MW:Manual:Contents|Manual]]|very interesting page|manual page
</datatable>
will display
| Page | Rating | Type |
|---|---|---|
| this page | interesting page | extension description |
| Manual | very interesting page | manual page |
and save the data in your database table.
Use of the <head> tag causes DataTable to automatically generate open-table and close-table wikitext around your data. If you do not need a headline, you can insert an empty <head> tag. If you only want to save the data without any display, you can provide the parameter display="no" in the <datatable> tag (which is not a good idea in most cases since it makes it difficult to understand the way your page works). You can specify class='wikitable sortable' or similar things in the <datatable> tag to specify a css class for the table.
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. The template does not need to create tabular output, it can just do anything with the data; if you don't want to create a table, do not include a <head> tag. You can also use the <datatable> tag as a comfortable way to display a series of template invocations (tabluar or not) without saving the data to the database. In that case, just omit the table parameter.
Instead of specifying a template name, you can provide template code just after the <datatable> tag between <template> … </template> tags; this is a handy solution if you need the template just for one table. However, the template is not exactly parsed like a real template so that parameters like {{{1}}} as well as template invocations and parser functions work, but parameters with defaults like {{{1|foo}}} don't.
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 or imported, all data from this page which was previously stored in the database table is deleted, 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 deleted as well.
[edit] Retrieving Data
Conceptually I find it easier to store data than to retrieve it, because the data to store is simply provided in a record structure which is saved 1:1 in the database, while there are many ways to make use of the data later. I do not consider the facilities provided so far as an optimal solution. Suggestions are welcome.
[edit] Parser function
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, joined with the >page table, which satisfy the given condition (if any) and sorts the result as indicated. 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 sort is specified, the value of DataTable::$mDefaultSort is used; it defaults to c1, c2, c3 and can be customized in LocalSettings.php.
- If no template is provided, all rows found are displayed separated by the value of DataTable::$mDefaultRecordSep (default <br/>), with fields separated by the value of DataTable::$mDefaultFieldSep (default comma). Both and can be customized. Typically this is useful only when retrieving a single column from a single row, or for debugging purposes. If you leave the template and the columns entry empty, nothing will be displayed, but the data will be stored for later access by #lastdata: (see below). This is useful when you know that you will retrieve exactly one record and you want to do something with the data without writing an extra template.
- If a template is specified, it is invoked for each row with the selected columns as parameters. Furthermore, the contents of p1, p2, p3, p4 are passed to the template as named parameters p1, p2, p3, p4.
To access again the last record of data that has been fetched without performing a new database query, you can write
{{#lastdata:}} (get first column)
{{#lastdata: c2}} (get second column)
and so on. As the data is now joined with data in the page table, you can also get information about the page where data was entered. For instance
the last record was entered on [[{{ns:{{#lastdata:page_namespace}}}}:{{#lastdata:page_title}}|this page]]
Similarly, if you use #data: with a template, in the template you can say
entered [[{{ns:{{{page_namespace}}}}}:{{{page_title}}}|here]]
You might consider using the StackFunctions Extension to use the query results in more sophisticated ways.
[edit] Tag
As an alternative to the #data: parser function, a <data> tag is also provided. It accepts named parameters corresponding to the positional parameters of #data:, namely table, columns, template, condition, sort, p1, p2, p3, p4.
The main purpose of using the tag instead of the parser function is that instead of referencing a template, you can write template code in the tag content which is is then used basically the same way as the <template> tag within the <datatable> tag. A <head> tag within the <data> tag and a class parameter are supported and work the same way as for the <datatable> tag.
If you do not need the template code anywhere else, this can be simpler and easier to read than the solution with the #data: parser function and an additional template page. However, there are limits:
- While a page using the <data> tag can be transcluded into another page, its result cannot be used as a template parameter.
- The condition parameter is expanded by the DataTable extension using $parser->replaceVariables(), but as of MediaWiki 1.15 this does not replace any template variables contained in it. In other words, it just replaces magic words and parser functions. Since the most frequent case of retrieving data in a template is to select rows based on template parameters, this is actually of little use at present; the remaining use case is a template selecting rows based on {{PAGENAME}} and similar magic words. MediaWiki 1.16 might offer more flexibility here.
[edit] Special page
The extension creates a new special page, Special:DataTablePages which shows a list of all tables in use together with a list, for each table, of pages contributing to the table. If the name of a table is given as a subpage, e.g. Special:DataTablePages/My_Table, only a list of pages contributing to My_Table is shown. The special page is embeddable so that you may include sonething like {{Special:DataTablePages/My_Table}} in any of your pages to create a list of pages contributing to this table.
When you click on the table My_Table, the special page Special:DataTableData/My_Table is opened and shows the contents of the table.
[edit] Notes
- 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.
