Difference between revisions of "WikiDB/Syntax"

Revision as of 02:44, 2 February 2011

This page describes the current syntax for all user input handled by the extension. Note that this is highly likely to change, but I shall endeavour to keep this page up-to-date with the current working version.

Table definitions

Within a DB namespace, the entire page is parsed as follows:

• All lines that begin with > (as the very first character) are treated as field definitions (see below).
• The rest of the page will be treated as standard wiki markup.

This means that you can include whatever you like along with your table definition, including images and links and even table data itself!

Field definitions

Each field row has the following syntax, where elements in square brackets are optional and whitespace may be omitted:

> FieldName [: Type [(TypeOptions)]] [LinkDetails] [-- Comment]

• FieldName - Required - The name of the field. Currently case-sensitive. May contain any characters that don't confuse the syntax (I will fill in the details about this later). Whitespace is trimmed from either end, but internal whitespace is preserved.
• Type - Optional - One of the defined Types. Must be preceeded by a colon to separate it from the name. If the specified type is not recognised then it is ignored.
• TypeOptions - Optional. Only valid if Type is defined - A comma-separated list of type options, surrounded in parentheses. The usage varies according to the Type.
• LinkDetails - Optional - Currently only used for aliases, but will also be used for foreign keys if they get implemented. A standard wiki link to the field name being aliased to, preceeded by #. E.g. use [[#Company name]] to make an alias for 'Company name'.
• Comment - Optional - A space for you to make notes about the field. Unlike notes elsewhere in the page, this comment is displayed at the top in the main table definition. Starts with two hyphens and runs to the end of the line.

Data tag

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="..." template="...">
  Field1=Value1
  Field2=Value2
  Any line without an equals sign is ignored.
</data>

The table attribute is required, and tells the extension which table the data belongs to. The table need not be defined on the wiki.

The template attribute is optional, and contains either "none" (in which case the data is not displayed), "default" (which outputs the data in a standard format) or the name of a template that has been defined on the wiki. This works the same as for standard templates, and each of the fields is passed to the template as named parameters. If this attribute is omitted, then "none" is assumed.

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="," template="...">
  Row1 Field1, Row1 Field2, Row1 Field 3, ...
  Row2 Field1, Row2 Field2, Row2 Field 3, ...
  == Headings are ignored ==
</data>

The table and template attributes work the same way as for field/value mode.

The fields attribute is a list of field names separated by commas. Note that the separator is always a comma, regardless of the value of the separator attribute.

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. Fields are separated by commas, unless you specify a different separator using the optional separator argument, in which case this will be used instead. Multi-character separators are allowed.

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.

Repeat tag

This tag allows you to query the data.

<repeat table="..." criteria="..." sort="...">Any old wiki text, with {{{variable}}} substitution.</repeat>

The table attribute is required, and defines where the data comes from. Again, the table does not need to be defined on the wiki - the tag will pull data for all rows that specified this table, even if the table does not exist.

The criteria is optional. Specifying this allows you to specify which records to return. Options are currently very limited, partly due to limitations of passing in an attribute. Currently you can provide a comma-separated list of "field=value" or "field!=value" pairs, which are ANDed together.

The sort contains a comma separated list of fields with an optional 'DESC' modifier (e.g. "Field1,Field2 DESC,Field3"). The rows are sorted by the fields in the order specified.

The text between the opening and closing tag will be repeated for each row returned by the query, and will be parsed as normal wiki text. {{{FieldName}}} will be replaced by the value of the field for the current row. Field aliases are resolved correctly, so if you defined 'name' as an alias for 'first name' then using either field will give the same result. If there is no text between the tags (or it just contains whitespace) then the data is output in a standard tabular format.