| Back to Contents List |
|
(New in version 5.0)
AscToHTM has the ability to detect and analyse tables. However, if you
want to convert a file containing multiple tables, or to convert
multiple files containing a variety of tables, it may be useful to create
a "Table Definition File" (TDF). In this file you can define multiple table
types, and each type can be associated with a particular structure and
a particular format.
By associating a table type with a structure, you are telling the software how the table is laid out, thereby simplifying it's task, and reducing the likelihood of analysis errors.
By associating a table type with a format, you can control various aspects of how the final table looks.
Using TDF files you can
You can see An example TDF file
Contents of this section
Loading the Table Definition File
Defining a Table Type
TDF line: Table typeDefining a Table Structure
TDF line: Must contain
TDF line: Use Structure
TDF line: Use Format
TDF line: Table structureDefining a Table Format
TDF line: Layout
TDF line: Table formatDefining table alarms
TDF line: Column names
TDF line: Column format
TDF line: Caption
TDF line: Column alignments
TDF line: Column headers
TDF line: Column widths
TDF line: CSS ID
TDF line: Table colour
TDF line: Border colour
TDF line: Colour data rows
TDF line: Border size
TDF line: HTML attributes
TDF line: HTML cell attributes
TDF line: Show columns
TDF line: HTML fragments
TDF line: alarmDefining table graphs and barcharts
TDF line: BarchartLocating data in a table
TDF line: Table DataAn example TDF file
All the table definition information should be placed in a "Table Definitions File" (TDF). By convention this file should have a ".inc" extension, but this isn't a requirement.
To have the file loaded, you will need to set a policy line in your policy file of the form
[config files]
Definitions file : table_definitions.inc
This will normally appear in the "[config files]" section of your policy file, but again this isn't strictly necessary.
Once this option appears in your policy file, the table definitions file will be loaded before the conversion process starts. During the conversion each table that is found will be tested against the known table types, and if a match is made, any associated structure and formatting will be applied.
You can select the Style Definition File that you want from the Config File locations menu option.
Whenever the software identifies a candidate table, it will check against the Table Definitions File (TDF) to see if this is a table of a known type. If it is, it will apply any defined structure or formatting for that type to the candidate table.
Table types are defined by having a series of table type sections something like the following in your definition file
table type : Rank
must contain : Rank ROC5 ROC10 ROC21
use format : format_rank
use structure : structure_rank
Each table type section starts with the table type line, and is followed by a number of additional definition lines that apply to this table type.
Each table type section must contain at least one "identifier" line. Identifier lines are those that specify conditions by which tables of this type can be identified.
The identifier line(s) specify conditions that are used to test each table to see if it could be of this type. Commonly the test is a search for text that is present in the header of all tables of this type.
If multiple table type sections are defined, then the first table type whose identifiers match the table is used, so the ordering of table type sections within the definition file can be important.
For example :-
table type : type_1
must contain : Rank
...
table type : type_2
must contain : date Rank
...
In the above example any table that contains a line of text containing "date rank" would match both table types. Since type_1 is listed first, all such tables would be treated as type_1. In this case it would be better to define type_2 first as below
table type : type_2
must contain : date Rank
...
table type : type_1
must contain : Rank
...
With the above definitions, a table containing "date rank" would be assigned to type_1, one which simply contained "rank" would be type_2
The presence of a "table type" line in the definition file marks the start of a new table type definition. The line has the format
table type : <type_name>
where <type_name> is the a unique name for this type of table, and shouldn't contain any spaces.
The "must contain" line is an identifier line. That is it is a condition applied against a candidate table to see if it matches this table type.
The line has the format :
must contain : <text_to_be_matched>
The candidate table is tested line-by-line, so the text to be matched must be wholly contained within one line of the source text. When testing the match expression the case of the text being tested is ignored, and all multiple white space is treated as a single space. So the match text "Date rank" will match the word "date" followed by any number of spaces and tabs, followed by "rank".
A good use of this line would be to match the know headers in a table, e.g.
must contain : Date Temperature Max Min
would match a table with headers "Date", "temperature", "MAX" and "MIN" if they were in that order, regardless of the spacing.
The "use structure" line specifies that if a table matches the identifying conditions for this table type, then it's structure should be interpreted according to the rules specified in the named table structure section.
This line has the form
use structure : <structure_name>
where <structure_name> is the name of a table structure section defined elsewhere in the definition file. The <structure_name> should contain no spaces.
The same structure may be shared by multiple table types, that is several table type sections could all end up having the same "use structure" line.
If the <structure_name> given doesn't match a structure defined elsewhere in the definition file, then the software will report this error each time it matches a table of this type and then fails to locate the named structure. That is it gives a runtime error, rather than reporting the error when the definition file is loaded.
See Defining a table structure
The "use format" line specifies that if a table matches the identifying conditions for this table type, then it should be formatted according to the rules specified in the named table format section.
This line has the form
use format : <format_name>
where <format_name> is the name of a table format section defined elsewhere in the definition file. The <format_name> should contain no spaces.
The same format may be shared by multiple table types, that is several table type sections could all end up having the same "use format" line.
If the <format_name> given doesn't match a format defined elsewhere in the definition file, then the software will report this error each time it matches a table of this type and then fails to locate the named format. That is it gives a runtime error, rather than reporting the error when the definition file is loaded.
Table structures are defined by having a table structure section something like the following in your definition file
table structure : Percent_funds
Layout : 6,31,41,51,61,71,81
Each table structure section starts with the table structure line, and is followed by layout line.
The presence of a "table structure" line in the definition file marks the start of a new table structure definition. The line has the format
table structure : <structure_name>
where <structure_name> is the a unique name for this structure, and shouldn't contain any spaces. The <structure_name> is the name used in any "Use structure" statement in a table type section.
The Layout line in a table structure section describes how the matched table should be interpreted into columns. The format of the Layout line is the same as that used by the TABLE_LAYOUT pre-processor command.
Layout : 6,7,39,51,61,71,80
For example the above line specifies the data comes in 6 columns which end at the column positions 7, 39, 51.. etc
Table formats are defined by having a table format section something like the following in your definition file
table format : Rank
column names : ,,,ROC5,ROC10,ROC21
caption : Rankings
table colour : #E1D1C1
border colour : #E2E2E2
Colour data rows : Yes
border size : 2
HTML attributes : onmouseover='click'
HTML cell attributes : nowrap
show columns : no,no,no,,,,,,,,
The presence of a "table format" line in the definition file marks the start of a new table format definition. The line has the format
table format : <format_name>
where <format_name> is the a unique name for this format, and shouldn't contain any spaces.
The <format_name> is the name used in any "TDF line: Use Format" statement in a table type section.
The "Column Names" line allows you to give each column a name. This name should be unique, and can be referenced in more advanced configuration lines.
The "Column Format" line specifies how cells in a particular column should be formatted. The format of this line is as follows
column format : name=<name> css_id=<id> barchart=<chartname> alarms=<alarm_list>
where
name (mandatory). The unique name given to this column format.
This is used to match the name listed for the column in the
column names line.css_id (optional). The CSS class ID to be added to cells in this
column of the tablebarchart (optional). Identifies the name of any barchart
to be used to display data in this column.alarms (optional). Identifies the name of any alarms
to be applied against data in this column.
The "Caption" line allows you to add a caption to any table that matched the table type conditions.
The "Column alignments" line allows you to define the alignment of each column.
The format is
column alignments : "<alignment_1>","<alignment_2>",...
where alignment is LEFT,RIGHT,CENTER. If a value is omitted, the software will automatically calculate the best alignment for the column.
The "Column headers" line allows you to define the headers to put at the top of the each column.
The format is
column headers : "<heading_1>","<heading_2>",...
If you want a heading to break over several lines, insert the text "\n" wherever you want a line break.
The "Column widths" line allows you to define the width of each column in pixels or as a percentage.
The format is
column widths : "<width_1>","<width_2>",...
If a value is omitted, the software will normally leave the width unspecified allowing the browser to fit the data in the bets way it can.
This specifies the CSS_ID to be added to the <TABLE> tag of the matching table. If omitted, each table will be given a unique name in the form "table_1", "table_2" etc.
Format
CSS ID : <ID_value>
The "Table Colour" line allows you to specify a background colour for the table.
The "Border Colour" line allows you to specify a border colour for the table.
The "Colour data rows" line allows you to specify that odd and even rows of the table should be coloured differently to allow the table to be more easily understood.
Format
colour data rows : <yes/no>
The "Border size" line allows you to specify a border colour for the table.
The "HTML attributes" line only applies to HTML generation by AscToHTM
This line has the same effect as that described for the policy line Default TABLE html attributes policy, namely it will define attributes to be added to the <TABLE> tag.
Note that this will apply only to the tables which match this definition, whereas that policy will apply to all tables. Where both are defined, the matching TDF line will override any default value.
The "HTML cell attributes" line only applies to HTML generation by AscToHTM
This line has the same effect as that described for the policy line Default TABLE html cell attributes policy, namely it will defined attributes to be added to the cell tags <TH> and <TD> in any matching table.
Note that this will apply only to the tables which match this definition, whereas that policy will apply to all tables. Where both are defined, the matching TDF line will override any default value.
Format is
show columns : <yes_no>,<yes_no>,...
where <yes_no> is either "yes" or "no" or blank. If blank it's taken to be "yes" for all columns
This line specifies whether or not each column should be included in the output. If your table has been exported in CSV format from a spreadsheet it may contain "work" columns that you don't want shown. This option allows you to specify that.
Format is
HTML fragments : <header_fragment_name>,<footer_fragment_name>
This line identifies HTML fragments to be used as alternatives for the TABLE_HEADER and TABLE_FOOTER HTML fragments. This allows you to define custom HTML fragments to be output either before or after the matching table type. If you don't want to supply both header and footer, then leave the unwanted fragment name blank.
See Table fragments
It's possible to define "alarm" conditions on cells in a given column of the table. These alarm conditions test the value in the cell against a "comparison value". Various "types" of comparison are possible.
The "comparison value" can either be a fixed value (i.e. the same for all cells in the column), or a value taken from a cell in a different column in the same row. For example you could define an alarm for any value in the column greater than 100, or for any cell whose value exceeded the value in column 2 of the same row.
Any cell that matches the alarm criteria is said to be "in alarm". Cells that are in alarm have their output modified in a number of ways, including having a different CSS ID applied to the cell and having extra attributes added to the cell's tag. In this way you are able to customize the appearance and behaviour of any cell that meets your "alarm" conditions.
Alarms are defined by alarm lines in the TDF file.
To identify that an alarm should be applied to a cell, add the desired alarm names to the alarms attribute of the TDF line: column format definition for the relevant column.
The "alarm" line specifies how cells in a particular column should be tested for being "in alarm". Cells that are in alarm can have a number of formatting options applied to them, to make them stand out in the HTML.
The format is as follows (shown here over two lines for convenience)
alarm : name=<name> type=<type> column_value=<colum_no> value=<value>
alarm_color=<html_color> cellatts="<cell_attributes>" CSS_ID=<id>
where
name (mandatory). The unique name given to this column format.
This is used to match the name listed for the column in the
column names line.type (mandatory). The type of comparison being made between
the cell value and comparison value. Options arelt numerically less than
le numerically less than or equal to
eq numerically equal to
ne numerically not equal to
ge numerically greater than or equal to
gt numerically greater thaneqs text strings are the same
nes text strings are not the samecolumn_value (optional). Column number to get comparison value from.
When specified the value in this column in the current row
will be used for the comparison.value (optional). Fixed comparison value. alarm_color (optional). If the cell is configured to display a
barchart, then this is the colour the barchart should
be when the cell is "in alarm"cellatts (optional). When the cell is in alarm, this identifies any
HTML attributes you want added to the alarm cell's tag.CSS_ID (optional). When the cell is in alarm, this identifies any
CSS ID to be added to the cell's tag. This will replace any
CSS ID that the cell would have acquired from the column
definition. This would allow you to define in your style
sheet how alarm cells should be formatted.
Note, the "comparison value" will be determined by the values of column_value or value, only one of which should be supplied.
The "in alarm" status is determined by comparing the cell's value with the comparison value according to type.
The "in alarm" response is configured by the alarm_color, cellatts and CSS_ID attributes. You should specify at least one of these, but are free to specify more than one should you want.
Using a barchart definition, it's possible to get the numbers in a column displayed as a series of bargraphs where each bargraph is proportional to the size of the value in the cell.
For example the TDF lines
column format: name=mom barchart=mom_bar alarms=negative
barchart : name=mom_bar origin=0 width=200 color=green
alarm : name=negative type=le Value=0.0 alarm_color=red
Will help turn this table :-
-4 days -3 days -2 days -1 day Today MOM
-------- -------- -------- -------- -------- --------
ABC CLOSED Scudde 71.32 73.36 75.11 78.60 79.97 6.07
DEFGH ABPrice Small 72.82 72.18 71.18 72.20 71.90 2.39
IJKLM Sit Trucking 69.96 69.74 66.52 64.58 65.48 4.74
NOPQR ABPrice Emerg 88.95 87.24 85.23 82.00 83.27 -4.52
STUVW Fidelity Cont 68.95 69.27 66.91 67.59 66.67 -1.72
XYZAB IntlFunds AB: 72.15 70.69 71.78 70.44 68.88 -2.41
CDEFG IntlFunds CD: 67.65 67.38 66.42 66.91 65.16 0.05
HIJKL JafSoft Micro 74.10 72.26 70.17 68.72 65.77 -4.97
MNOPQ IntlFunds EF: 70.14 69.80 68.36 68.57 66.82 -0.61
into the following (only visible in the HTML version)
| -4 days | -3 days | -2 days | -1 day | Today | MOM | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ABC | CLOSED Scudde | 71.32 | 73.36 | 75.11 | 78.60 | 79.97 |
|
|||||
| DEFGH | ABPrice Small | 72.82 | 72.18 | 71.18 | 72.20 | 71.90 |
|
|||||
| IJKLM | Sit Trucking | 69.96 | 69.74 | 66.52 | 64.58 | 65.48 |
|
|||||
| NOPQR | ABPrice Emerg | 88.95 | 87.24 | 85.23 | 82.00 | 83.27 |
|
|||||
| STUVW | Fidelity Cont | 68.95 | 69.27 | 66.91 | 67.59 | 66.67 |
|
|||||
| XYZAB | IntlFunds AB: | 72.15 | 70.69 | 71.78 | 70.44 | 68.88 |
|
|||||
| CDEFG | IntlFunds CD: | 67.65 | 67.38 | 66.42 | 66.91 | 65.16 |
|
|||||
| HIJKL | JafSoft Micro | 74.10 | 72.26 | 70.17 | 68.72 | 65.77 |
|
|||||
| MNOPQ | IntlFunds EF: | 70.14 | 69.80 | 68.36 | 68.57 | 66.82 |
|
In which column 5 has it's data shown as a number of bargraphs, zeroed on 0.0, with negative values changed to alarm states and shown in red.
The "barchart" line specifies how cells in a particular column should have their data represented by a bargraph.
The format is as follows (shown here over two lines for convenience)
barchart : name=<name> min=<value> max=<value> width=<size> origin=<value>
bgcolor=<html_colour> color=<html_colour> value_location=<position>
null_value=<value> null_display=<option>
where
name (mandatory). The unique name given to this column format.
This is used to match the name listed for the column in the
column names line.min (optional). The minimum value to show on the bargraph. If omitted
the minimum value seen in the column of data will be used.max (optional). The maximum value to show on the bargraph. If omitted
the maximum value seen in the column of data will be used.width (optional). The width (in pixels) that the bargraph should be.
If omitted, the default value will be 200.origin (optional). A data value taken to be an "origin" for the bargraph.
Any values less than this will be shown as a negative bar to the
left, any values greater than this will be shown as a positive bar
to the right. If omitted, the origin will be set to the bargraph's
"min" value so that all bargraphs point to the right.bgcolor (optional). The background colour for the bargraph. This is the
colour used for that part of the bargraph that doesn't correspond
to the data value. If omitted, the background will be transparent,
allowing the background colour of the table cell, table or HTML
page to show through.color (optional). The colour for the active part of the bargraph, i.e.
that part that represents the data value itself. If omitted the
default colour will be "blue".value_location (optional). Determines where the cell value should be placed
relative to the barchart. The options areleft - value is placed to the left
right - value is placed to the right
middle or center - value is placed on the bar itself
none - value is not displayedThe default value is "left", and if an origin is specified
then this is ignored an "left" is used instead.null_value (optional). Specifies a "null" value, that is a value in the
cell that indicates this value is not valid. This can be useful
for example when showing instrument readings to indicate am
"out of service" value. Cells whose data indicates a null value
will not have a bargraph shown, they will instead display the
null_display value.null_display (optional). Where a cell matches the supplied null_value, this
specifies the text that should be shown in the cell in place of
the bargraph.
It's possible to define table data lines, which specify a row and column of a table from which to extract a data value. This value is then made available in an appropriate VARIABLE tag, allowing the extracted data to be displayed elsewhere in the document.
Here's a real-life example:-
A customer had data tables exported from an application recording temperatures in a number of device names. The data was exported from an Excel spreadsheet and consisted of a series of rows showing time, and the temperature.
What they didn't have was a nice table header, but they could get their application to stick the device name into each row of the table as an extra column.
Using a table data line as follows
table data : name=device_name row=2, col=1
allowed them to define a TABLE_HEADER HTML fragment as follows
$_$_DEFINE_HTML_FRAGMENT TABLE_HEADER
<H2>Here are the results for device [[VARIABLE device_name]]</H2>
$_$_END_BLOCK
This HTML fragment was then output before the table, but used the "device_name" extracted from the table. Finally to hide the added column all that was needed was a TDF line: show columns line as follows
show columns : no, yes, yes
In this particular case the user also made full use of the barchart feature and alarms feature to represent the temperatures graphically, and to show through use of colour those that were out of spec.
The "table data" line specifies in item of data that may be extracted from a table of known structure. The value extracted can then be accessed in any subsequent VARIABLE tag, and in particular in a VARIABLE tag placed into either the TABLE_HEADER or TABLE_FOOTER HTML fragments.
The format is as follows:
| table data : | name=<name> row=<number> col=<number> | ||||||
| where | |||||||
| name | (mandatory). | The | unique | name | given to this table data | ||
| item. | |||||||
| row | (mandatory). | The | row number of | the cell to extract the | |||
| data from. | |||||||
| col | (mandatory). | The | column | number | of the cell to extract the | ||
| data from. | |||||||
The example TDF file shown below is meant to work on a text file that contains the following table
-4 days -3 days -2 days -1 day Last MOM
-------- -------- -------- -------- -------- --------
ABC CLOSED Scudde 71.32 73.36 75.11 78.60 79.97 6.07
DEFGH ABPrice Small 72.82 72.18 71.18 72.20 71.90 2.39
IJKLM Sit Trucking 69.96 69.74 66.52 64.58 65.48 4.74
NOPQR ABPrice Emerg 88.95 87.24 85.23 82.00 83.27 -4.52
STUVW Fidelity Cont 68.95 69.27 66.91 67.59 66.67 -1.72
XYZAB IntlFunds AB: 72.15 70.69 71.78 70.44 68.88 -2.41
CDEFG IntlFunds CD: 67.65 67.38 66.42 66.91 65.16 0.05
HIJKL JafSoft Micro 74.10 72.26 70.17 68.72 65.77 -4.97
MNOPQ IntlFunds EF: 70.14 69.80 68.36 68.57 66.82 -0.61
First the TDF file identifies the table type as follows
table type : 4day
must contain : -4 days -3 days -2 days -1 day Last Mom
use format : Format_4day
use structure : Struct_4day
The must contain line matches the heading line in the table (since the spacing is ignored). Once this connection is made, the software knows which structure and format to use.
The table structure is defined as follows:
table structure : Struct_4day
Layout : 8, 6,20,30,40,50,60,70,80
In this the layout identifies the table has 8 columns, and where these start and end. The software could have auto-detected this structure, but by supplying a layout the possibility of errors or ambiguities is eliminated.
The formatting of this table is fairly complex. The table represents a series of stock price movements, and the user wants to apply an external JavaScript to make this table sortable by clicking on the column headings. For this to work the table has to have a CSS class of "sortable" and to have some JavaScript events defined. The data columns have to have unique CSS IDs so that data in the same column can be identified by the script.
The table formatting definition starts as follows
column names: ,,-4days,-3days,-2days,-1day,Last,Mome
column format : name=-4days css_id=-4days alarms="green,yellow,red"
column format : name=-3days css_id=-3days alarms="green,yellow,red"
column format : name=-2days css_id=-2days alarms="green,yellow,red"
column format : name=-1day css_id=-1day alarms="green,yellow,red"
column format : name=Last css_id=Last alarms="green,yellow,red"
column format : name=Mom css_id=Mom alarms="Mom_green,Mom_red"
The column names names the columns, but only the data columns, as the first two columns don't contain numeric data. The various column format defines the formats for each line. In this case this consists of giving each column a different CSS ID, and defining some alarm conditions.
All bar the last column get three alarms defined to turn the cell green, yellow or red, whereas the last column gets just two - also green and red, but on different conditions). These alarm names are indicative of what should be done, but are only names in this case.
The alarms themselves are defined as follows
alarm : name=red type=lt Value=50.0 alarm_color=red cellatts='bgcolor="ffa7a7"'
alarm : name=yellow type=ge Value=50.0 alarm_color=yellow cellatts='bgcolor="ffffa7"'
alarm : name=green type=ge Value=65.0 alarm_color=green cellatts='bgcolor="a7ffa7"'
alarm : name=Mom_red type=le Value=0.0 alarm_color=red cellatts='bgcolor="ffa7a7"'
alarm : name=Mom_green type=gt Value=0.0 alarm_color=green cellatts='bgcolor="a7ffa7"'
In this example each alarm is triggered by comparing the numerical value to some limit, and then adding cell attributes and alarm colours when the alarm triggers.
Finally the line
HTML attributes : class="sortable" onMouseover="changeto(event, 'white')" onMouseout="changeback(event, '')"
specifies the necessary HTML attributes to add to the <TABLE> tag for the external sorting JavaScript to locate and work on the table.
All put together the TDF file looks like this
! ! Stocks and shares table ! !- define table type "4day" ! table type : 4day must contain : -4 days -3 days -2 days -1 day Last Mom use format : Format_4day use structure : Struct_4day ! !- structure of table type "4day" ! table structure : Struct_4day Layout : 8, 6,20,30,40,50,60,70,80 ! !- formatting of table type "4day" ! table format : Format_4day ! !- only care about the numerical columns. No need to name the others column names: ,,-4days,-3days,-2days,-1day,Last,Mome ! each column gets a CSS_ID and several alarm conditions applied column format : name=-4days css_id=-4days alarms="green,yellow,red" column format : name=-3days css_id=-3days alarms="green,yellow,red" column format : name=-2days css_id=-2days alarms="green,yellow,red" column format : name=-1day css_id=-1day alarms="green,yellow,red" column format : name=Last css_id=Last alarms="green,yellow,red" column format : name=Mom css_id=Mom alarms="Mom_green,Mom_red" ! ! alarm conditions. ! Red turns cell red if value is very low ! yellow turns cell yellow if value is low ! green turns cell green is value is above acceptable minimum ! alarm : name=red type=lt Value=50.0 alarm_color=red cellatts='bgcolor="ffa7a7"' alarm : name=yellow type=ge Value=50.0 alarm_color=yellow cellatts='bgcolor="ffffa7"' alarm : name=green type=ge Value=65.0 alarm_color=green cellatts='bgcolor="a7ffa7"' alarm : name=Mom_red type=le Value=0.0 alarm_color=red cellatts='bgcolor="ffa7a7"' alarm : name=Mom_green type=gt Value=0.0 alarm_color=green cellatts='bgcolor="a7ffa7"' ! HTML attributes added to <TABLE> tag. In this case the table is marked ! as sortable and gets a couple of mouse events. An external JavaScript module ! contains code to sort columns by clicking on the header. That script requires ! the table to be labelled as "sortable" and for sortable columns to all have the ! same CSS ID on the cells (achieved via the "column format" definitions above. ! HTML attributes : class="sortable" onMouseover="changeto(event, 'white')" onMouseout="changeback(event, '')"
 |
Converted from
a single text file by
AscToHTM © 1997-2004 John A Fotheringham |  |