Difference between revisions of "WikiDB/Configuration settings"

From TestWiki
Jump to: navigation, search
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''
  
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! 
+
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.
  
The format of the array is the same as the built-in MediaWiki setting [[mw:Manual:$wgNamespacesWithSubpages|$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 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 likeThis 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.
  
A table namespace is a namespace where table definitions are stored, 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' tabOn 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 waysIf you just need a single namespace, you can simply assign the namespace number to the variable directly:
  
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 [[mw:Manual:$wgExtraNamespaces|$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 [[WikiDB/Installation#Define table namespaces|installation]] page.
+
<php>$wgWikiDBNamespaces = 100;</php>
  
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: <code>&lt;data table="Languages"></code> 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: <code>&lt;data table="UserTable:Languages"></code>.
+
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 itIf 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>&lt;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>&lt;data table="UserTable:Languages"></code>.
  
 
== $wgWikiDBMaxRefreshRate ==
 
== $wgWikiDBMaxRefreshRate ==

Latest revision as of 11: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.

$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.