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

  • 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

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

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

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.

Multi-value fields

It is also possible to define multi-value fields within WikiDB. For example, if you had a Student table you might want to be able to specify that an individual student is taking multiple courses. This is analogous to a many-to-many relationship in a standard relational database.

In WikiDB, this is not done as part of the table definition, but as part of the data. Any field in any row of any table may be specified such that it contains multiple values.

The syntax for multiple values is to wrap the set of values in braces. Wherever you might specify a single value (as per the above descriptions) you can instead specify multiple values.

Example 1 - Field/value mode
<data table="Students">
Name = John
Course = {English, Geography, French}
YearGroup = 2A
</data>
Example 2 - Multi-line mode
<data table="Students" fields="Name,Course,Supervisor">
John, {English, Geography, French}, Dr. Lucas
Jane, {Physics, Mathematics}, Dr. Aponsa
</data>

Multi-value fields can be queried just like any other field and all values for the record will be checked when the criteria is applied. This means that expressions such as Course = 'English' AND Course = 'French' will find all records which include both of these values. In addition, specifying a multi-field value as part of the sort will sort the values for each row accordingly (e.g. specifying a sort that includes "Course DESC" would result in John's courses being listed as "Geography, French, English". If a sort is not specified, they will be listed in the order entered.

Note that a multi-value field with a single element is treated the same as a single-value field (i.e. "English" and "{English}" are identical) and an empty multi-value field is treated the same as an empty field (i.e. "" and "{}" are identical).

Dealing with edge-cases

Because the multi-value field syntax is invoked by a value that starts with a {, field values that start with a brace must be represented in multi-value format. For example, to represent the value {Value starting with a brace, you would place it into a multi-field value, like this: {{Value starting with a brace}.

Similarly, because } indicates the end of a multi-value field, it is not possible to include values ending in braces as part of a multi-value field in multi-line mode. Closing braces have no special meaning outside of a multi-value field, so these are safe if they are the only value (but, this is not possible if it also starts with a brace). Alternatively, if that is not possible, you can use field/value mode, as in this mode the closing brace will only end the value list if it is the last character on the line.

There is no way to override the use of braces to delineate multi-value fields.

Display options

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

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>