TB Wiki

Login

DocTables

Problem importing plugins
TBWiki includes a feature for very easy creation and editing of simple databases. These are referred to as "tables".

no macro 'TableOfContents' found

Table Data [edit section]

Table data is stored in regular tbwiki pages. [FIXTHIS - maybe change this to a database directory?], or it can be parsed from an external source. For data in tbwiki pages, you can edit the data in a table via the normal tbwiki page editor, or using table forms.

There are several types of tables, which vary depending on their storage format:

  • MoinMoin - db_type="moinmoin"
    • data is in a separate page (or block on a page), and is specified in MoinMoin syntax (using double vertical bars to delimit fields)
  • attribute files - db_type="attr_files"
    • multiple files, with one table record per file
    • data values for the record (field values) are listed as name-value pairs
  • inline - db_type="inline"
    • places the data in moin-moin format inline in the same processor block used to declare the table
  • parsed data files - data db_type="match_spec"
    • data is parsed from an external source using a "match_spec"
    • this uses the data_scan module
    • this is currently a read-only data source (no record editing allowed)
  • test data - db_type="test_data"
    • this is a special set of test data internal to the table.py module. It is used for testing only.

MoinMoin Tables [edit section]

MoinMoin tables are stored in a single file. The records are stored one per line, with the field names in the first row of the table, and the record_ids in the first column of the table.

Sample source spec: source_spec=PhoneDatabase

||Name||Phone||
||Tim ||555-1212||
||Nadine||444-2323||

Attribute files [edit section]

Attribute files are a collection of files, each containing a single record, where the fields for each record are stored as name-value pairs.

Dample source spec: source_spec=Book.*

Any file starting with "Book" would be considered a record in the table.

Attributes are listed in the file as name=value pairs. Values can be single-line or multi-line. Multi-line values are

The first attribute of the record have the name: 'record', which should correspond to a unique identifier for records in this table. Internally, this is referred to as the record_id.

The names in the records are NOT required to be perfectly consistent between records. That is, one record may have a 'phone' attribute, while others do not. For purposes of display and editing, the set of fields for the tables is the union of all fields encountered in all records in the set of files in the database.

Inline Tables [edit section]

Inline tables are stored inline on a regular tbwiki page. They currently only support moinmoin table syntax, and can be either named or unnamed.

An inline table is embedded inside a #!Table processor block, and each line of the table has fields separated by double vertical bars.

Here's an example:

{{{#!Table
||Name||Job||
||Tim||engineer||
||Fred||pilot||
}} }

Only one unnamed table may be used on a single wiki page.

Multiple named tables may be used on a wiki page. A named table uses a block with a name.

{{{BlockName
<data>
}} }

Also, the table processor declaration can include a block name:

{{{#!Table:BlockName
<data>
}} }

Parsed data Tables [edit section]

Using the scan_data module, you can parse data from multiple sources.

These can be tbwiki pages, local files, or web pages.

Parsing data from external web pages (scraping them) may introduce long delays in displaying a table.

Here is a sample table declaration for the FIXTHIS list for the tbwiki software:

{{{#!Table
source_spec=/home/tbird/work/tbwiki/cgi-bin/.*[.]py$:/home/tbird/work/tbwiki/cgi-bin/plugins/.*[.]py$
match_spec="""
record_start=.*FIXTHIS
description=.*FIXTHIS[ -]*(.*)$
file=%(basename)s
line_no=%(line_no)s
"""
cols=file:line_no:description
sortby=file:alpha,line_no:int
}} }

source_spec [edit section]

For the source_spec, if there is a leading slash, the spec indicates local files (in the server file system). (This is a huge security issue!)

If there is no leading slash, the spec indicates pages in the tbwiki data area. This spec can contain wildcards. (At least, trailing wildcards.) If the spec contains a colon, ':', then the first part is the page name and the second part is a block name. If the table name is '#', then the current page is used as the page name.

If the string starts with "http", then it indicates a URL for a web page from which the data is loaded.

match_spec [edit section]

A match_spec is used to describe the regular expressions which are used to gather the record fields and values from the data.

The match_spec is a specified with a set of lines, one-per regular expression, enclosed in triple-quotes (three double-quotes in a row).

To identify the beginning of each record, the "record_start=" special variable is used.

Named fields are parsed according to the regular expressions given in the match_spec.

By default, each record will have the named fields, and those will be displayed in the resulting table. Each record also has a 'record_id' field, which will have the same value as the first field listed in the match_spec.

See DocWebSed for details about pattern matching and regular expressionsthat are supported by the data_scan module.

basename and

line_no are special values which hold the name of the file being read and the line_no in the data where the record_start is found. These can be assigned to arbitrary field names for the record, and used in the table.

Declaring a Table [edit section]

Table data is stored in one or more files (or parsed from some other source). To show a view of a table on a page, you create a table declaration, usually with a processor block:

Macro Syntax [edit section]

Here is a sample macro referencing a simple table:
{{Table(Table1Data)}}

Processor Syntax (with examples) [edit section]

Here is a sample processor syntax for a simple table (with data specified in an external file (another page):

{{{#!Table
source_spec=Table1Data
}} }

Here is the sample processor syntax for a multi-file table:

{{{#!Table
source_spec=bug_.*
}} }

You can also specify data in a named block on either the current page or another page:

{{{#!Table
source_spec=#:DataBlock1
}} }

{{{#!Table
source_spec=DataPage:DataBlock1
}} }

Table processing attributes [edit section]

Table attributes are specified as name/value pairs, using standard syntax (use triple-quotes for multi-line values).

Here are some of the attributes you can use with the Table processor:

  • source_spec - specifies the source of the data
  • match_spec - used only for parsed-data tables
    • see below
  • cols - specify the columns of the table to output (and their order)
    • e.g. cols=field2:field1:field4
  • sortby - specify the sort order for displayed records
    • multiple fields can be specified, along with their sort type
    • e.g. sortby=age:int,name:alpha
    • sort types are: alpha (default), int, rev_alpha (reverse alpha), rev_int
  • field - specify field type information (multiple declarations allowed)
    • these are specified as one or more "field=" statements, using standard attribute syntax
    • each "field=" line begins a new field type declaration
    • see below for details
  • row_filter - specify an expression used to filter records in the table
    • right now, only equality can be tested in a row filter
    • ex: row_filter=name=Tim
  • add_form - specify a form used for adding a new record to the table
  • conf - specify the configuration in a separate block
    • see below for details
  • query - specify a block containing query attributes
    • Usually, this specifies a block of configuration information, along with a row-filter, to generate a particular view of the data
    • see below for details

field attributes [edit section]

You can specify the attributes of individual fields, so that TBWiki can process them properly (generate appropriate default forms, and display the values properly).

field attributes are:

  • field - specify the name of the field for which attributes are being declared
  • type - specify the type of the field
    • possible types are: Text, Textarea, Select, Checkbox, Radio
  • possible_values - list of possible values for the field
    • specified with a multi-line value, one value per line
  • colors - list of expressions used to define the background color for a field, based on the field
    • specified as a list of expressions which are matched against the field value
    • each color expression consists of a python expression using the term 'value', a colon, then a color to use if that expression is true
    • colors can be color names or hex triples
    • expressions can include boolean operators (not, and, or)
    • ex: (int(value)<20):blue - show a blue cell for items with value<20
    • ex: """(value=="good"):green - show "good" cells in green and "bad" cells in red (value=="bad"):ff0000"""
    • ex: (int(value)>5 and int(value)<10):00ffff - show particular values in yellow

field attribute samples [edit section]

Field types and possible values:
{{{SampleDataConf
field=Summary
type=Text
field=Description
type=Textarea
field=Done
type=Select
possible_values="""Yes
No"""
field=Happy
type=Checkbox
field=OS
type=Radio
possible_values="""Linux
BeOs
DOS
Windows"""
}} }

Color Expressions:

{{{#!Table
source_spec=#:ReactorTable
field=reactor_temperature
colors="""(int(value)<10):ffffd0
(int(value)>=10 and int(value)<50):ffff80
(int(value)>500):ffd0d0"""
}} }

Configuration blocks [edit section]

You can specify several "configuration" attributes of a table, and use them repeatedly (i.e. from different processor blocks), using the "conf=" attribute:

Query blocks [edit section]

You can specify a "query" block, which has a set of table attributes (usually including a row_filter) to show a subset of the data. These can be referenced via a URL, to show different views of the same data.

Views [edit section]

To show a table on a page, you use the table processor, which has the format:
{{{#!Table
<source spec>
}} }
You can also specify view a

Custom forms and views [edit section]

You can create custom views of table data, by creating a view file.

View [edit section]

To create a custom view for a record, ...

Add Form [edit section]

To create a custom form to add a record, for an attribute file database, create a file with the same prefix as the database, and the ending 'AddForm'.

Possible custom form names:

  • BookAddForm
  • BookEditForm
  • PhoneDatabaseAddForm
  • PhoneDatabaseEditForm

Ex: To create a custom add form for the Book.* database, create a page called "BookAddForm". In this file, put HTML (FIXTHIS - should allow tbwiki markup also) to display the form. Whereever you want the form input element for a field of the record, you can place a python named string format item.

Here is an example showing fields in an HTML table.

<table>
<tr>
<td>User name:</td><td> <font color=red>&lt;missing data value for key "record_idField"&gt</font></td>
</tr><tr>
<td>Phone number:</td><td> <font color=red>&lt;missing data value for key "phoneField"&gt</font></td>
</tr><tr>
<td>Description:</td><td> <font color=red>&lt;missing data value for key "descriptionFieldTextarea"&gt</font></td>
</tr><tr>
<td><font color=red>&lt;missing data value for key "ok_flagFieldCheckbox"&gt</font> Is OK?</td>
</tr>
</table>
<font color=red>&lt;missing data value for key "SaveButton"&gt</font> <font color=red>&lt;missing data value for key "CancelButton"&gt</font><br>

Field format strings for edit forms [edit section]

Field format strings are python named format strings. The name of the python variable consist of the field name, followed by "Field", followed by the type of form element to display.

If no type is specified, a single-line text entry box is used.

Possible types are:

  • Text
  • TextArea
  • Checkbox
  • Select
  • Radio

If something besides one of these types is specified, it is used as the INPUT field type in the HTML file element.

Special form elements [edit section]

The following are special form elements that can be placed anywhere in the form specification:
  • SaveButton - this shows the button to submit the form data
  • CancelButton - this cancels the operation and doesn't save the form data

Things to Describe [edit section]

  • sequencing of records
  • filtering
  • sorting
  • views

TBWiki engine by Tim Bird