WikiDB/Defining data

From TestWiki
Jump to: navigation, search

WikiDB is a tool to create and query database-like data from within your wiki.

This page describes how to add new data to your wiki.

Basic principles[edit]

  • You can create data anywhere on the wiki, simply by editing the page content to include a <data> tag (as described below).
  • You need to specify the name of a table into which the data will be placed, e.g. "People" or "Countries" so WikiDB knows where the data should go.
  • The table or fields that you use do not have to exist, but if it does then any data rules it defines will be applied to your data when it is displayed. However, the data you enter is never modified (except by subsequent page edits) and any changes to the table definition are reflected in the data in real-time.
  • Even if the data is sent to a table that doesn't exist it can still be viewed and queried, just as if the table did exist.

Creating data[edit]

Data is defined using the <data> tag. There are two ways of using this tag - field/value mode or multi-line mode.

Field/value mode[edit]

This method defines a single row of DB data per tag. The tag's contents consist of multiple lines, each of which is a fieldname/value pair (if it contains an = sign) or a comment (if it doesn't).

<data table="...">
  Field1=Value1
  Field2=Value2
  Any line without an equals sign is ignored.
</data>

Multi-line mode[edit]

In multi-line mode, you define the field names in the fields attribute, and then each line is a comma-separated list of values.

<data table="..." fields="Field1,Field2,Field3,..." separator=",">
  Row1 Field1, Row1 Field2, Row1 Field 3, ...
  Row2 Field1, Row2 Field2, Row2 Field 3, ...
  == Headings are ignored ==
</data>

Each line in the tag's contents is treated as a row of data, except for blank rows or MediaWiki headings (e.g. == Heading ==) which are ignored. The fields attribute defines the names of the fields that appear in each row, in the form of a comma-separated list

In the body of the tag, each row consists of field values separated, usually, by commas. If a row has fewer fields than are defined in the fields attribute then the remaining fields are left blank. If it has additional fields, then they are ignored.

As you may have field values that need to contain commas, it is possible to specify an alternative separator via the separator attribute (which is optional). Multi-character separators are allowed. Note that the separator does not affect the way the fields attribute is defined - this always uses a comma as the separator.

Display options[edit]

When you define data in your page, you are essentially instructing WikiDB to place the data into the specified table, so unless you specify otherwise, this won't result in any content being output within the page itself.

However, WikiDB provides an optional template attribute which can be used to output the contents of the tag directly into the page at the point the tag appears. This attribute can be set to one of the following values:

  • "none" means the data is not displayed - this is the default, and never needs to be explicitly specified.
  • "default" means the data is output in a standard tabular format provided by WikiDB.
  • Any other value is treated as the name of a template that has been defined on the wiki. This template will be expanded once per row of data. It works the same as for standard templates, and each of the fields is passed to the template as a named parameter.

For example, if you define data like this:

<data table="People" fields="Name,Age" template="People">
  John, 42
  Kate, 37
</data>

then as well as adding the data to the 'People' table, you would get output equivalent to the following wiki code:

[[Template:People|Name=John|Age=42]]
[[Template:People|Name=Kate|Age=37]]

Defining data using templates[edit]

As well as using templates to display data defined in a <data> tag, it is also possible to do this the other way round, and define data using templates.

Imagine you have a template called [[Template:People]] which is defined as follows:

* {{{Name}}} is {{{Age|an unknown number of}}} years old.

which you include in your wiki articles in the standard way, like this:

{{Name|John|42}}
{{Name|Kate|37}}

By simply updating your template, as follows, this data will now also be added to a queryable table on your wiki:

* {{{Name}}} is {{{Age|an unknown number of}}} years old. <data table="People" fields="Name,Age">{{{Name}}},{{{Age}}}</data>