Here are some notes on table internals

{{TableOfContents}}

= classes =
== table_class ==
A table consist of a instance of table_class with the following attributes:
 * .records - a map of actual records of the database
 * header_record - a record with header values for the fields
 * .source_spec - indicates the origin of the data
 * .field_list - a list of records containing information about the fields in the db
 * col_names - a map of column names
 * row_names - a map of row names
 * row_output_list - list of record_ids for rows to show
 * row_filter - 
 * col_output_list - list of col_names for columns to show
 * page_name
 * conf
 * rmap
 * num_fields
 * message - a message to print out, for debugging or errors
 * conf - the database configuration
   * see below
 * handler - the io handler for the database
   * see below
 * req = the request that fetched this database
 * data_dir = the directory where the data was read from (e.g. data or admin or backup)

=== table_conf_class ===
Has all kinds of configuration information (the raw text) for a class:
 * conf_spec
 * source_spec
 * row_filter
 * cols
 * sortby
 * row_output_list
 * query
 * query_list
 * sort_col_list
 * add_form
 * edit_form
 * show_header
 * show_record
 * show_footer
 * field_spec
 * field_db - map of attributes for the fields in the database
   * a field_db element (field record) can have the following attributes:
     * type
     * possible_values
     * color_list

methods:
 * __init__
 * set_color_lists
 * get_conf - get the configuration.  This is a merge of the base conf and the dynamic conf
 * 

The base conf is read from a block on the page, and the dynamic conf is read
from the URL.  This allows things like a base configuration specifying the
field types, while the dynamic conf specifies the sortby order (or some other complex query, like from a query form.

table_class methods:

 * __init__
 * add_or_edit_numbered_record
 * remove_numbered_record
 * set_col_output_list
 * set_row_filter
 * filter_match
 * add_to_message
 * html_string - main routine to render the table to HTML
 * get_default_edit_form_spec
 * show_record_edit_form
 * show_edit_table_form
 * get_default_line_edit_form_spec
 * show_edit_table_in_place_form
 * edit_link
 * show_query_form

== form_fields_generator_class ==
The form_fields_generator_class is used to create an instance of a
form_fields_generator.  This is used with a form_spec to create
an actual form.  It generates the correct HTML for each field, on
the fly, by acting like a map where the string substitutions in
the form get converted into appropriate HTML input elements.

== io_handle_* classes ==
These classes handle I/O operations for the different types of databases
supported:
 * test
 * moin_file
 * moin_in_page (inline in table block or named block)
 * attr_files
 * parsed_files

An io_handler instance has the following attributes:
 * req - the request used to fetch the database
 * tb - the table instance
 * data_dir - the directory used to read the data from
 * source_spec

The io_handle_base class is a stub class, with methods for:
 * read - read the whole database
 * get_record - (does not appear to be used)
 * add_record - (does not appear to be used)
 * update_record - (does not appear to be used)
 * remove_record - remove an individual record
 * write - write the whole database (not used?? see save_table_data)

Different classes implement these methods, according to the database type.

== class capture_stderr ==
In order to capture errors, a class is used to grab the errors and put
them in a buffer.  This is to capture exceptions and put them in the
message log, in case of unhandled error conditions.


= global routines =
 * print_error
 * generate_field_input - used to generate an input field for a form element
 * value_trans
 * parse_attrs - given a block of data, create a map with key-value pairs
 * rec_sort - used to sort records (according to 'sortby' setting)
   * cmp_rev(), cmp_int(), cmp_rev_int()
 * set_sort_col_list
 * gen_row_output_list - generate a default row output list, based on the sortby spec.  The list is ordered and filtered.
 * setup_conf_and_db - set up configuration and source_spec, possibly reading from multiple blocks (table block, data block, conf block)
 * macro_get_table
 * get_table - an action?
 * add_record_form - an action in the table module
 * query_form - an action in the table module
 * edit_table - an action in the table module
 * edit_table_in_place
 * parse_moin_table
 * read_page_or_block
 * parse_attrdb_data
 * read_attrdb_file
 * get_filelist
 * db_from_attrdb_files
 * db_from_parsed_files
 * save_attrs_to_file
 * save_attrdb
 * remove_attrdb
 * convert_table_to_dict
 * render_moin_table
 * get_table_type - examines source_spec and conf, to determine the type of
 database to handle
 * get_table_data
 * save_table_data - routine that implements save of data based on data type
   * this appears to be a hold-over from before the implementation of the
   io_handler_class
   * currently, the write() io_handlers call save_table_data
 * action - multiplexor for table sub_actions, from the set:
   * add_record
   * remove_record
   * edit_record_form
   * edit_record
   * save_all
   * add_column - not implemented
   * edit_column - not implemented
   * remove_column - not implemented
   * query


= Table Processor =
The table processor has the following actions:

 * Table - main routine to return a table (from get_table() above)
 * add_record_form
 * query_form
 * edit_table - 
 * edit_table_in_place -
 * action - process form actions (sub_actions)
   * this performs some action, like processing a form or operation, then
   sets a results message, and then shows the page (with results, hopefully).

= Notes =
A table configuration can have the following attributes:
 * conf=
 * query=
 * source_spec=
 * and all the fields shown in the table_conf_class list
   * these are read like a map into the conf's attributes as strings directly from the configuration block
 * a list of field attributes (in attrdb format, with 'field' as the record indicator)

The conf and query lines can "chain" to other blocks, so that a multiple
"Views" can be constructed from the same data.

For example, a table could be defined like:

{{{
{{ {Data
||foo||bar||baz||
||1  ||yes ||5||
||3  ||no  ||100||

}} }
}}}

{{{
{{ {#Conf1
source_spec=#:Data
sortby=bar,int
field=bar
possible_values="""yes
no"""
field=baz
color_list="""(int(value))<50:red
(int(value)<100:yellow"""
}} }
}}}

{{{
{{ {#Query1
col_list=foo,baz
filter=foo=1
}} }
}}}

{{{
{{ {!#Table
conf=#:Conf1
query=#:Query1
}} }
}}}

source_specs indicate the source and type of data for the database:
 * test_data = use the special built-in test data (read-only)
 * endswith '.*' = attr_files
 * startswith '#' = inline
 * startswith '_inline_' = inline
 * config has 'match_spec' = parsed
 * otherwise it's a moinmoin db in a file

sortby can have the following types:
 * alpha
 * rev_alpha
 * int
 * rev_int