BANAL version 0.03

Chapter 3: Advanced Topics

This chapter deals with fairly advanced topics including how the database (tables) files are setup and why certain design decisions were made.

3.1: How the Tax field behaves

The Tax field in the Charge table is specially treated when generating invoices. The value is split up (on the character '/') and each substring is checked for a TaxRate in the Categories table (it better have one).

This means that if you want a charge item to has both Provincial Sales Tax (PST) and the Goods & Service Sales Tax (GST) then you should use the value 'GST/PST' or 'PST/GST' in the Tax field. You also do not have to supply a total TaxRate for a combined Tax.

NOTE: The default Category data only has GST/PST.

3.2: Why Date fields are formatted as YYYY.MMDD

Dates are a pain. The reason we chose the YYYY.MMDD format for dates is simple. We wanted to be able to do numeric-style comparisons. With the date format as it is we are able to do searches on dates such as:

Date ge 1997 and Paid lt 1997.0401

This search (when used with the bk invoices command) will return a list of all invoices that were generated in 1997 or later and were paid before April 1st. If you can show us a date format that is able to do the same without lots of fussing and is also not error prone, please let me know.

3.3: BANAL Tables

The templates for the tables are in the templates directory and there is a script in bin called tablegen which will generate a working set of books from the templates and corresponding data. There are also some sample books in the sample directory including an empty set if you do not wish to generate your starting books.

Here are a couple of noteworthy pieces of information for people making or interested in BANAL tables:

  1. The first field in each file is a unique ID field. The field name is the same as the table's. The first character is uppercase and all other characters are lowercase.

  2. Any values with tabspaces (\t) or newlines (\n) will have them changed to the two character strings, '\T' and '\N', respectively. These strings will be changed back as needed (editting, running a transaction) but not when being listed.

  3. KEYWORDS are placed in the Field Description. These keywords are seperate from the rest of the description by the string '@@'. The current keywords are:

    • /^[A-Z][a-z]* ID/ means that this references an ID from another table. (NOTE: This is a regular expression)

    • CATEGORIZED means that valid values come from the Category table.

    • MULTILINE means that you may enter a value that spans multiple lines.

    • REQUIRED means that the field must be set when adding/editting.

    • YYYY.MMDD in the description means it is a date field.

The tables that are distributed with this version include:

3.3.1: Adding your own tables

You can easily add your own table by creating a RDB file in your books directory. The RDB file must start with a capital letter and be followed by lowercase letters (eg. Todo.rdb). The only mandatory field is the first one in a record. It must be the same name as the RDB file (without the .rdb extension - eg. Todo).

The next time you start the bkd server it will notice the new file and generate a modify and list command for it.

You can either copy an existing database and modify it as desired or you may copy a .tpl file in the templates directory and have tablegen generate your books (remember, you can include initial data in a .dat file).

Details on RDB template files and the RDB header can be obtained from the full RDB documentation.