WikiDB/Configuration settings

From TestWiki
< WikiDB
Revision as of 13:02, 24 August 2013 by HappyDog (Talk | contribs) (+ TOC, as we are below the threshold for it to be automatically displayed.)

Jump to: navigation, search

This page describes the settings that you may use to configure WikiDB. They should be set in LocalSettings.php, either before or after including the main WikiDB.php script. If you do not explicitly set a value for any of these settings, then the default value will be used, as described.

$wgWikiDBNamespaces

Default value: empty array

Whilst you technically don't need to set this setting, if you don't set it then you might as well not install WikiDB at all!

The format of the array is the same as the built-in MediaWiki setting $wgNamespacesWithSubpages, except in this case the array indicates any namespaces that should be treated as table namespaces. Note that you should *not* define talk namespaces as table namespaces!

A table namespace is a namespace where table definitions are stored, meaning that they have an enhanced syntax available to them in order to make these definitions, plus extra interface features such as the 'data' tab. On most wikis only a single table namespace will be required, but it should be noted that you may define as many table namespaces as you like. This could be useful if your wiki is used for several different projects that you want to keep separate, or if you want to grant users different rights for different namespaces. However, in most situations a single table namespace will be enough.

Note that in order for a table namespace to be created, you will also need to add the namespace and its talk page to the $wgExtraNamespaces array. You need both settings - $wgExtraNamespaces tells MediaWiki that the namespace exists, and $wgWikiDBNamespaces tells WikiDB to use this namespace as a table namespace. For an example of how this looks, see the installation page.

When you refer to a table within the wiki, you may omit the namespace (e.g. you can just use 'Countries' instead of 'Table:Countries') and in these situations the default table namespace will be assumed (whether or not the named table is defined in that namespace). The default namespace is the one defined first in the $wgWikiDBNamespaces array. For example, say you have two table namespaces 'ProjectTable' and 'UserTable', with 'ProjectTable' being defined first in the array. If you add some data as follows: <data table="Languages"> it will be added to the table "ProjectTable:Languages", because "ProjectTable" is the default DB namespace. To add it to "UserTable:Languages" you would need to use the full name: <data table="UserTable:Languages">.

$wgWikiDBMaxRefreshRate

Default value: 100

In order to enable proper type-specific filtering/sorting of data, WikiDB formats the submitted data prior to storage, based on the field's type, as given in the table definition. Undefined fields are considered to be of type 'wikistring' and are stored as literal strings. However other data types may be stored differently. For example, numeric fields are stored in such a way that they sort numerically (i.e. 1, 2, 5, 10, 15, 20) rather than alphabetically (e.g. 1, 10, 15, 2, 20, 5). What this means is that whenever a table definition is changed, all existing data needs to be updated so that it is formatted according to the new definition.

In order to avoid having to update the all data in one go, and thus potentially bring the wiki to it's knees, WikiDB instead marks all rows in the table as stale, and then updates a batch of rows on each page request

This variable controls the maximum number of stale rows to refresh on each page view (i.e. the batch size) and can either be set to a specific number of rows, or to one of the following constants:

WIKIDB_DisableAutoRefresh
Disables the auto-refresh completely (e.g. because you are running RefreshStaleData.php via a regular cron job).
WIKIDB_RefreshAll
Updates all stale rows (if there are any) on every page request, so there is never any stale data.

The optimum value for this setting will depend on how many visitors your wiki gets, how large your tables are (in terms of numbers of rows), how often your table definitions change and how important it is that the sorting/filtering of data is correct. The default has been chosen as a good average-case value, but you may need to customise this to suit your circumstances, and modify it further as your circumstances change.

$wgWikiDBDefaultClasses

This setting defines the class string that will be applied to the <table> tag for any data tables generated by WikiDB. By default, this is set to "wikitable", which is a class built-in to MediaWiki for formatting tables nicely. However, you can over-ride this to add additional/alternative classes if you want.

Note that, regardless of this setting, all tables will also have the "WikiDBDataTable" class added to them, so we have a consistent class name always available to JavaScript code.