Extension:DataInvoker

DataInvoker is an extension that introduces new parser functions which allow retrieving data from a database.

Installation
Please cut and paste the code found below and place it in. Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php.

To install this extension, add the following to LocalSettings.php:

Configuration parameters
Note: These parameters should be put in LocalSettings.php.

There are currently 4 configuration parameters for this extension. They are:
 * $wgDataInvokerHostName - String that indicates the host name of the database connection. Default value is.
 * $wgDataInvokerUserName - String that specifies the username of the database connection. Default value is.
 * $wgDataInvokerPassword - String that specifies the password of the database connection. Default value is.
 * $wgDataInvokerDatabase - String that specifies the name of the database being connected to. Default value is.

Reference
DataInvoker currently introduces 4 new parser functions allowing data retrieving.

Usage
DataInvoker retrieves data by doing a query to the database and caching the result temporarily, then reading data from the cache and outputing them. doquery and rawquery do the database query, retrieve a row, and store the result into a temporary cache with a handle. Then getdata can be used to read data from the cached results by a key (column name) and a certain handle. When necessary, use escapestr to escape a string for safe SQL execution with rawquery.

#doquery:
Does a query to the database and stores the result in a temporary cache. Other than the first parameter (table_name), all parameters are optional.
 * table_name
 * The name(s) of the table to retrieve data from. If there are multiple tables, use commas to separate them - although retrieving data from multiple tables isn't fully tested yet and might not work.


 * column_name
 * The name(s) of the columns from which the fields are wanted in the result output. If there are multiple columns, use commas to separate them. If all columns of a table is wanted, use an asterisk (*). Default value is *.


 * match_column and match_value
 * Indicates that the match_column column of the retrieved result rows must be match_value. If omitted (or empty), no matching pattern is required for the retrieved rows.


 * order_by
 * Sorts the retrieved rows by the order_by column(s). If there are multiple columns to sort by, use commas to separate them - although sorting by multiple rows isn't fully tested yet and might not work. If omitted (or empty), no sorting is done to the retrieved rows.


 * order
 * Specifies the way the rows are ordered by order_by. Possible values are ASC (in ascending order), or DESC (in descending order). Default value is ASC.


 * row_number
 * When multiple rows are retrieved and they all match the matching pattern defined by match_column and match_value</tt> (if any), only the row_number</tt>th row will be output. Default value is 1</tt>. Must be a positive integer.


 * handle_name
 * The name of the handle by which to store the result to the cache. This is a classifier of the result which can be referred to by #getdata: later. When this is omitted, the result is stored with the handle _unnamedHandleN, when the stored result is the Nth (counting from 0) without a specified handle name.

#rawquery:
Does a raw SQL query to the database and stores the result in a temporary cache. The second and third parameter can be omitted.
 * query_string
 * The raw SQL query string. Must start with the characters, or  , or  , etc.


 * row_number
 * When multiple rows are retrieved, only the row_number</tt>th row will be output. Default value is 1</tt>. Must be a positive integer.


 * handle_name
 * The name of the handle by which to store the result to the cache. This is a classifier of the result which can be referred to by #getdata: later. When this is omitted, the result is stored with the handle _unnamedHandleN, when the stored result is the Nth (counting from 0) retrieved result without a specified handle name.

#getdata:
Reads the data cache and outputs the value.
 * column_name
 * Required. The name of the column to retrieve data from.


 * handle_name
 * Optional. The handle of the cached result. When omitted, it is defaulted to the last stored result.


 * suppress_error
 * Optional, Boolean. Whether to suppress the errors in case one occurs. Default value is false</tt>.

#escapestr:
Escapes the given string by adding slashes (\) in front of apostrophes ('). This can be useful when used in conjunction with #rawquery: (#doquery: automatically escapes the strings).
 * string
 * Required. The string to escape.

Acknowledgments
Thanks go to those guys at the #mediawiki IRC channel who helped me with this. They include Werdna, MinuteElectron, Duesentrieb, and Dantman. Thanks again!

Under Development
This extension is still under development; it might be a little unstable since it hasn't undergone strict testing, and it is still too simple at the current stage. It lacks more functionality and I'm aware of the situation; you are welcome to give suggestions in the talk page.

Trivia
Invoker is a hero in the game DotA Allstars, who has the game's most unique skillset and requires a lot of skills to play.

Changelog

 * v0.3b
 * New parameter for getdata suppress_error
 * New exception class DIError
 * v0.3a Added a new parser function escapestr
 * v0.3
 * New parser functions doquery and rawquery
 * Changed the way retrieving data works; now getdata no longer directly does a query, but retrieve data from the cached query results from either doquery or rawquery.