WikiDB/Tutorial

From TestWiki
Jump to: navigation, search

Step 1 - Defining Data

Suppose you have a standard infobox, say Template:Infobox company. You use it in a page by entering the following syntax:

{{Infobox company
 |name=Microsoft
 |founded=1492
 |revenue=$8
 }}

Which gives the following result:

Microsoft

Year founded: 1492
Annual Revenue: $8

In order to add this data to the Companies table, you simply replace the above syntax with the following:

<data table="Companies" template="Infobox company">
name=Microsoft
founded=1492
revenue=$8
</data>

This generates exactly the same output:

Microsoft

Year founded: 1492
Annual Revenue: $8

...BUT it also adds data to the Companies table. It doesn't matter that we haven't defined a Companies table. The table exists because the data exists. If we want to define it formally we can (as you will see later) but we don't have to.

Data can be defined on any page in the wiki, and more than one row of data can be defined in a page. You get to group data with content, and still have it displayed in a standard format within the page.

You can omit the template parameter altogether, and the data will not be displayed on the page at all (though it will still be added to the appropriate table), or you can use the special "default" template to display the data in a standard format, as follows:

name founded revenue
Apple 1984 $7.42


Now, follow this link to Table:Companies. This will take you to the edit page for the table definition (please don't edit it, as it will spoil this tutorial - feel free to experiment elsewhere on the wiki!). If you look at the tabs at the top of the page you will see 'table definition' and 'data'. Select 'data' and you will see that even though the table definition doesn't exist (as indicated by the red link) you are still able to view any data that has been defined.

To help you administer the wiki, Special:EmptyTables lists any empty tables, and Special:UndefinedTables lists tables that have data but no definition.

Step 2 - Defining A Table

Now we are going to try setting up a table definition, using the following data:

 Row #1: 
     Company name=Microsoft, 
     Founded= 1492, 
     Location=Seattle, 
     Annual revenue=$8
 Row #2: 
     Founded=April 2005, 
     Revenue=$7.42, 
     Company name=Apple, 
     Logo=Image:Apple logo.png
 Row #3: 
     Name=Intel, 
     Founded=USA, 
     Logo=Image:Intel_logo.jpg

The data is defined using data tags, but I have not supplied a template, so they are hidden from view. (You have to edit this wiki page to see the code.)

Take a look at the definition of the table Table:Companies2 and at the effect this has on its data.

You can see that the defined and undefined fields are separated out, and that data (e.g. Company name) is modified according to the field definitions. Unlike a normal database, changing the table definition does not alter the stored data, except in the way that it is displayed. In true wiki-way, both data and definition are editable separately, with any changes to either becoming visible as soon as the page is saved.

Step 3 - Fixing errors

In the above example, you may have noticed that there were two fields 'Name' and 'Annual revenue' which should have been 'Company name' and 'Revenue' respectively. In this case you can either go and fix each record, or define aliases for the incorrectly named fields.

I have defined the same data for Table:Companies3 (definition) (data), which has aliases in place. Take a look and see what a difference it makes.

Step 4 - Retrieving data

Finally, you can pull data from the table for use within a page. This is the least well-implemented part of the extension at the moment, but I can give you some examples already. Each example shows the syntax entered, followed by the output it generates. All are drawn from Table:Companies3

<repeat table="Companies3"></repeat>
Company name Logo Founded Location Revenue
Intel File:Intel logo.jpg USA    
Microsof   1492 Seattle $8
Apple File:Apple logo.png April 2005   $7.42


<repeat table="Companies3" sort="Revenue"></repeat>
Company name Logo Founded Location Revenue
Intel File:Intel logo.jpg USA    
Apple File:Apple logo.png April 2005   $7.42
Microsof   1492 Seattle $8


<repeat table="Companies3" criteria="Name!=Microsoft" sort="Logo desc"></repeat>
Company name Logo Founded Location Revenue
Intel File:Intel logo.jpg USA    
Apple File:Apple logo.png April 2005   $7.42


If you include some wiki text inside the repeat tag, then instead of outputting in the default format as above, the contents are repeated for each row. Within the contents you can use {{{FieldName}}} to refer to a field in the returned row, and this will be replaced by the value of that field. Aliases are properly expanded so {{{Name}}} is equivalent to {{{Company name}}}. Here is an example:

'''ANNUAL REVENUE:'''
 <repeat table="Companies3" sort="Revenue DESC"># '''{{{Company name}}}''': {{{Revenue}}}
 </repeat>

ANNUAL REVENUE:

  1. Microsof: $8
  2. Apple: $7.42
  3. Intel:


At the moment it's still quite primitive, but this is being worked upon.

Closing comments

This extension is still in its infancy, as is this tutorial. There are plenty of features yet to be added and no doubt a load of bugs to be ironed out. I would appreciate any feedback you have at this stage though, and feel free to use this wiki to experiment with the extension (though I would appreciate it if you didn't play with any of the tables used in this example).