Difference between revisions of "WikiDB/Configuration settings"
m (+ TOC, as we are below the threshold for it to be automatically displayed.) |
(→$wgWikiDBNamespaces: Rewritten to be clearer and to mention the new simpler syntax for single-namespace setups.) |
||
Line 5: | Line 5: | ||
'''Default value:''' ''empty array'' | '''Default value:''' ''empty array'' | ||
− | + | This setting defines the namespace(s) within your wiki that will be used to store table definitions. This is a required setting - without it, the WikiDB extension will have no effect. | |
− | + | A table namespace is a namespace where the structure of individual tables is defined, meaning that they have an [[WikiDB/Syntax#Table definitions|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. | |
− | + | The setting can be defined in two ways. If you just need a single namespace, you can simply assign the namespace number to the variable directly: | |
− | + | <php>$wgWikiDBNamespaces = 100;</php> | |
− | When you refer to a table within the wiki, you may omit the namespace (e.g. you can just use | + | If, however, you want more than one table namespace to be defined then you need to use an array format. This is the same format as is used by the built-in MediaWiki <code>[[mw:Manual:$wgNamespacesWithSubpages|$wgNamespacesWithSubpages]]</code> setting, 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! |
+ | |||
+ | <php> | ||
+ | $wgWikiDBNamespaces = array( | ||
+ | 100 => true, | ||
+ | 102 => true, | ||
+ | ); | ||
+ | </php> | ||
+ | |||
+ | In order for a table namespace to be created, you will also need to add the namespace and its talk page to the [[mw:Manual:$wgExtraNamespaces|$wgExtraNamespaces]] array. You need both settings - <code>$wgExtraNamespaces</code> tells MediaWiki that the namespace exists, and <code>$wgWikiDBNamespaces</code> tells WikiDB to use this namespace as a table namespace. For an example of how this looks, see the [[WikiDB/Installation#Define table namespaces|installation]] page. | ||
+ | |||
+ | === The default table namespace === | ||
+ | |||
+ | When you refer to a table within the wiki, you may omit the namespace (e.g. you can just use <code>Countries</code> instead of <code>Table:Countries</code>) and in these situations the default table namespace will be assumed (whether or not there is a defined table with this name in that namespace). | ||
+ | |||
+ | If you only have one table namespace, then this is the default, and you effectively never need to specify it. If you have multiple namespaces, the default namespace is the first entry in the <code>$wgWikiDBNamespaces</code> array. | ||
+ | |||
+ | For example, assume that you have two table namespaces <code>ProjectTable</code> and <code>UserTable</code>, with <code>ProjectTable</code> being defined first in the array. If you add some data as follows: <code><data table="Languages"></code> it will be added to the table <code>ProjectTable:Languages</code>, because <code>ProjectTable</code> is the default DB namespace. To add it to <code>UserTable:Languages</code> you would need to use the full name: <code><data table="UserTable:Languages"></code>. | ||
== $wgWikiDBMaxRefreshRate == | == $wgWikiDBMaxRefreshRate == |
Latest revision as of 12:41, 31 March 2019
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.
Contents
$wgWikiDBNamespaces[edit]
Default value: empty array
This setting defines the namespace(s) within your wiki that will be used to store table definitions. This is a required setting - without it, the WikiDB extension will have no effect.
A table namespace is a namespace where the structure of individual tables is defined, 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.
The setting can be defined in two ways. If you just need a single namespace, you can simply assign the namespace number to the variable directly:
$wgWikiDBNamespaces = 100;
If, however, you want more than one table namespace to be defined then you need to use an array format. This is the same format as is used by the built-in MediaWiki $wgNamespacesWithSubpages
setting, 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!
$wgWikiDBNamespaces = array( 100 => true, 102 => true, );
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.
The default table namespace[edit]
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 there is a defined table with this name in that namespace).
If you only have one table namespace, then this is the default, and you effectively never need to specify it. If you have multiple namespaces, the default namespace is the first entry in the $wgWikiDBNamespaces
array.
For example, assume that 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[edit]
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[edit]
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.