This documentation can be downloaded as part of the documentation set in .zip format
2.1 Conversion of plain text tables3 Controlling the conversion process
2.1.1 Overview2.2 Conversion of delimited tables
2.1.2 Correcting mistakes
2.1.2.1 Getting the detection of tables right2.1.3 Tips and tricks
2.1.2.2 Getting the preformatted text correctly recognised as tables
2.1.2.3 Getting the column structure correct
2.1.2.4 Getting the table header correct
2.1.2.5 Getting the cell COLSPAN correct
2.1.2.6 Getting the table formatting right
2.1.3.1 Use white space
2.1.3.1 switch on borders
2.1.3.2 Use the BEGIN_TABLE / END_TABLE tags to delimit the table
2.1.3.3 Use the LAYOUT tag to specify the column positions
2.2.1 Specifying a delimited table2.3 Conversion of user tagged tables
2.2.1.1 Tab-delimited data2.2.2 Embedding a regularly updated table in an otherwise static page
2.2.1.2 Comma-delimited data
2.2.3 Handling quotation marks and commas
2.2.4 Handling multiple lines
2.2.5 Specifing a table heading
2.2.5.1 Using the TABLE_HEADER_ROWS command
2.2.5.2 Adding a line to separate the header from the data
2.3.1 BEGIN_USER_TABLE ... END_TABLE
2.3.2 COLUMN_DETAILS
2.3.3 NEW_ROW
2.3.4 NEW_CELL
2.3.5 Cell contents
3.1 Using policy filesAppendix A - Policies
3.2 Using pre-processor commands
3.3 Using a table definition file
3.3.1 Loading the table definitions file
3.3.2 Defining a table type
3.3.2.1 Table type3.3.3 Defining a table structure
3.3.2.2 Must contain
3.3.2.3 Use format
3.3.2.4 Use structure
3.3.3.1 Table structure3.3.4 Defining a table format
3.3.3.2 Layout
3.3.4.1 Table format3.3.5 Defining a column format
3.3.4.2 Column names
3.3.4.3 Caption
3.3.4.4 Table colour
3.3.4.5 Border colour
3.3.4.6 Colour data rows
3.3.4.7 Border size
3.3.4.8 HTML attributes
3.3.4.9 HTML cell attributes
3.3.4.10 Show columns
3.3.4.11 Table css_id
3.3.6 Defining Cell Alarms
3.3.7 Defining barcharts for numerical columns
3.3.8 Defining custom table headers and footers
3.3.9 Defining table data
JafSoft's text conversion utilities convert plain ASCII fiels into richer formats such as HTML (AscToHTM) or RTF (AscToRTF). These converters include the ability to detect and convert tables within the text into suitably formatted tables in the output.
Table conversion is a useful aspect of the file conversion, and over the years the functionality has been greatly increased in this area in response to user requirements. The converters can now convert tables in a variety of forms, and accept varying levels of user guidance as to how the table is structured.
At the same time a large number of formatting options give the user control over how the table will appear in the final document.
This manual describes the table handling available in JafSoft products. It is divided into sections as follows
- Getting the structure of the table correct
- Controlling the conversion process
- Using policy files and policies
- Using directives in the source text
- Using a table definition file
Appendices
The converters can create tables from three different types of text
Here's an overview of how the software detects a table in a plain text document, and then works out it's structure. This will give you a feel for the complexity of the issues that need to be addressed.
The software first looks for pre-formatted regions of text. It does this by
2) Each time a heavily formatted line is encountered an attempt is made
to extend the preformatted region by "rolling it out" to adjacent, not so clearly formatted lines
3) This "roll out" process is stopped whenever it encounters a line that is
clearly not part of the formatted region. This might be a section heading or a set of multiple blank lines (the default is 2).
Once a preformatted region is identified, analysis is performed to see whether this is a table, diagram, code sample or something else. This decision depends on
4) The mix of "graphics" characters ('|','-','+','=','*' etc) as opposed
to "text" characters
If nothing fits then this text is output "as normal", except that the line structure is preserved to hopefully retain the original meaning.
If the software decides a table is possible, it
Once a tentative set of column boundaries has been identified, the following steps are repeated
Finally, having settled on a column structure the software
Once all these calculations have been performed the software
Naturally any one of the automatic steps described in 2.1.1 can go wrong, leading to less than perfect results. Happily the software provides many different ways in which you can correct errors. You can use "policies" passed in a policy file, or "tag directives" added to your source to tell the program how to modify it's analysis of the source text. For fuller description of these techniques read controlling the conversion process
The software first looks for regions of pre-formatted text. The problems here are usually either that the software is detecting pre-formatted text where it shouldn't, or isn't detecting a large enough region when it should.
Stop the detection of pre-formatted text
Lines with lots of horizontal white space or "table characters" (such as "|". "-". "+") are all candidates for being pre-formatted, especially where several of these lines occur.
This often causes people's .sigs from email to be placed in a table-like structure.
"Look for preformatted text" : no
"Minimum automatic <PRE> size" : <n>
Where <n> is the smallest number of lines that you will allow to be regarded as a region of preformatted text
Make the detected regions larger or smaller
Having detected some preformatted lines, the software tries to "roll out" this region to adjacent lines, i.e. to include them in the region even if, by themselves, they don't appear heavily formatted. If this goes wrong you will either get lines included in the table that shouldn't be there, or you will find lines left out of the table that should be in it. In this last case you may find that a large table is treated as two or more independent tables, with "normal" lines inbetween.
There are a number of actions you can take.
"Table extending factor" : <n>
Where <n> is 1-10. The higher the value, the more likely a table is to include adjacent lines. A value of 10 will include everything up to the next page break or heading.
$_$_BEGIN_TABLE
...
table lines
...
$_$_END_TABLE
This unambiguously tells the software where your table is (and that it is a table as opposed to anything else). If you can edit your source text then this is best solution.
Once a preformatted region is identified, analysis is performed to see whether this is a table, diagram, code sample or something else. This can occasionaly go wrong, the commonest mistake being that ascii art and tables can get confused.
Solutions include :-
"Look for diagrams" : no
"Expect code samples" : no
If you don't want pre-formatted text output as tables, use the policy
"Attempt TABLE generation" : no
Preformatted text will be output in non-proprtional font (<PRE> in HTML)
???
Here's a diagram...
$_$_BEGIN_DIAGRAM
+-----------+ +-------------+
+ nice box +-------->+ another box +
+-----------+ +-------------+
$_$_END_DIAGRAM
here's some code
$_$_BEGIN_CODE
for (int i=0; i<Max; i++) {
print("some more code lines");
}
$_$_END_CODE
here's a table
$_$_BEGIN_TABLE
start time total
---------------------
10:00 124
11:00 81
$_$_END_TABLE
This is probably the single most difficult thing that the software attempts. It works well on larger tables with nice regular columns of data. It works worst on smaller tables with large amounts of free-form text. It can also have real problems with the complex table headers often found in reports where some headers will span multiple columns
When the analysis of the table columns has has gone wrong :-
If all this fails you can explicitly tell the software what the table layout
is. You can do this in two ways
$_$_BEGIN_TABLE
$_$_TABLE_LAYOUT 3, 9,17,27
Basic Dimensions
Hole No. X Y
-------------------------
1 3.2500 5.0150
2 1.2500 3.1250
etc.....
$_$_END_TABLE
In this case the TABLE_LAYOUT states there are three columns with the boundaries at character positions 9, 17 and 27. In a large table of this type this would probably be auto-detected, but if there were only 1 or 2 lines of data, the analysis might go wrong. Tagging the as above would eliminate this ambiguity
The software will usually automatically detect the heading is there is a "line" under it like so
Basic Dimensions
Hole No. X Y
-------------------------
1 3.2500 5.0150
2 1.2500 3.1250
etc.....
Alternatively you can tell the program how many lines of header there are in
the source. You can do this in two ways
$_$_BEGIN_TABLE
$_$_TABLE_HEADER_ROWS 2
Basic Dimensions
Hole No. X Y
1 3.2500 5.0150
2 1.2500 3.1250
etc.....
$_$_END_TABLE
In this case the TABLE_HEADER_ROWS states there are 2 lines of text to be included in the header (if the header had been underlined, this would be 3 to include the underlining itself)
The COLSPAN applied to a cell depends on whether or not data is deemed to straddle a column boundary position. In this the calculation of the correct column structure and the boundary positions is crucial, so you should first check that the columns structure is correct. (See Getting the column structure correct)
Even if the column structure is right, the COLSPAN values can still be wrog sometimes, especially in spanned headers. Basically if you have a space where the column gap is expected the text will be split into cells, if you don't then the text will be placed in a cell with a COLSPAN value that spans several cells.
For example
| space aligns with column "gap", text will be split into 2 cells
v
Basic Dimensions
Hole No. X Y
-------------------------
1 3.2500 5.0150
2 1.2500 3.1250
etc.....
In this case you'd get "Basic" in column 1 and "Dimensions" spanning columns 2 and 3. If you edit this slightly as follows then the "Basic Dimensions" will span all 3 columns
| space no longer aligns with "gap". A COLSPAN=2 cell is created
v
Basic Dimensions
Hole No. X Y
-------------------------
1 3.2500 5.0150
2 1.2500 3.1250
etc.....
It's a bit of a black art.
Sometimes when the table is wrong, it's a good idea to set the BORDER size to 0 (again via the policy options) to make things look not so bad. It's a fudge, but a useful one to know.
Once the table structure has been correctly calculated, you will want to ensure that it is formatted as you would want. Formatting is mostly achieved though passed in policies and tags added to teh source files.
For a fuller description read the chapter Formatting the output of the table
White space can be useful in making a table structure less ambiguous to the software in a number of ways
While trying to fine tune the conversion, and to see just how the software has laid out the table, switch on borders. This can be done using the "default TABLE border size" policy. Once you are happy with te structure you can delete this policy from your policy file (which will allow borders to be auto-detected), or switch the policy off should you want.
If the software wrongly calculates the extent of a table, use the "BEGIN/END_TABLE" tags to explicitly delimit the table in the source document.
See Getting the preformatted text correctly recognised as tables
If the software wrongly calculates the column structure of a table, it may be simpler just to tell the software how the table is laid out by adding "LAYOUT" tags to the source document.
See Getting the column structure correct
As well as converting plain text tables, the software can also converted delimited data into tabular format. The options are less flexible here, but this is the best method to use if you are converting data exported from a spreadsheet.
In each case the table will be created row-by-row from each input line in the source text. The delimiter character will be used to divide the input into cells. COLSPAN and ROWSPAN are not supported in this format.
The software supports two types of delimiter, tabs and commas
Tab-delimited data should be placed between "BEGIN/END_DELIMITED_TABLE" commands as follows
$_$_BEGIN_DELIMITED_TABLE
...
<lines of comma-delimited text>
...
$_$_END_DELIMITED_TABLE
Comma-delimited data should be placed between "BEGIN/END_COMMA_DELIMITED_TABLE" commands as follows
$_$_BEGIN_COMMA_DELIMITED_TABLE
...
<lines of comma-delimited text>
...
$_$_END_COMMA_DELIMITED_TABLE
If you want to create an output file that consists of a regularly updated table inside an otherwise static format, one tip is to use the "INCLUDE" command as follows
This is text before the table
$_$_BEGIN_COMMA_DELIMITED_TABLE
$_$_INCLUDE <name_of_data_file>
$_$_END_COMMA_DELIMITED_TABLE
This is text after the table
In the above example the source text contains text before and after the table, as well as the commands to delimit the table itself. The actual data is contained in the file whose name is specified on the INCLUDE statement.
In this way you can regularly export your spreadsheet into a CSV file, and create a template that "includes" the CSV file into the source file that you then convert to get the results file.
If your data contains quotation marks or commas, then the data value should be placed in double quotes. Commas can then be left "as is", but double quotation marks must be doubled up.
For example
"This contains a comma, and a double quotation mark """
becomes
This contains a comma, and a double quotation mark "
At present there is no was of sepcifying multiple lines of text inside a single cell in a delimited table.
There are two ways of specifying that a delimited table has a heading. the first is by using the "TABLE_HEADER_ROWS" command, and the second is by adding a line near the top
As with all tables, you can use the "TABLE_HEADER_ROWS" directive to specify how many input rows are header rows as follows
$_$_BEGIN_COMMA_DELIMITED_TABLE
$_$_TABLE_HEADER_ROWS 2
,"No." ,"Running"
Date,"sold","Total"
1-Jan-2003, 2, 2
...
... more data lines
...
$_$_END_COMMA_DELIMITED_TABLE
If a "line" is detected in the table near the top (in the first few lines) this will be taken as a separator between the table header and the data rows.
For example in the following, the row of dashes at row three marks lines 1 and 2 as header lines that will be placed in bold and marked up accordingly
$_$_BEGIN_COMMA_DELIMITED_TABLE
,"No." ,"Running"
Date,"sold","Total"
1-Jan-2003, 2, 2
...
... more data lines
...
$_$_END_TABLE
In addition to converting plain text files, and sets of delimited data into tables, the software also supports a method of explicitly tagging the input as to how it should be placed in a table.
This may seem extreme, as the point of the converters is to generate the desired markup as save work, but there are a couple of situations in which this approach can be useful.
Here's a sample of a user-tagged table (with blank lines added for clarity) :-
$_$_BEGIN_USER_TABLE C,1 in
$_$_COLUMN_DETAILS 1,,,L, 2in
$_$_COLUMN_DETAILS 2,,,C, 1 ins
$_$_TABLE_BORDER 1
$_$_NEW_ROW HEAD
$_$_NEW_CELL
Substance (units)
$_$_NEW_CELL
Year
Sampled
$_$_NEW_ROW DATA
$_$_NEW_CELL
Alpha emitters (pCi/L)
$_$_NEW_CELL
1999
$_$_NEW_ROW DATA
$_$_NEW_CELL
Asbestos (MFL)
$_$_NEW_CELL
1993
$_$_END_TABLE
Here's how this table appears when converted into the current format
| Substance (units) |
Year Sampled |
|---|---|
| Alpha emitters (pCi/L) |
1999 |
| Asbestos (MFL) |
1993 |
To identfy a section of a source file as a user table, it must be enclosed in the BEGIN_USER_TABLE..END_TABLE commands as follows
$_$_BEGIN_USER_TABLE <arguments>
...
<other commands to layout the table>
...
$_$_END_TABLE
The BEGIN_USER_TABLE line can take arguments as follows
$_$_BEGIN_USER_TABLE <alignment>,<margin>
| where | |
| <align> |
The alignment of the table. This can be L(eft), R(ight) or C(enter) |
| <margin> | The margin to be applied to the table. This consists of a number and a unit. Recognised units include points ("pts" or "pt"), inches ("ins" or "in") and centimetres ("cm"). In HTML generation these margins will be approximate only |
After the BEGIN_USER_TABLE line will appear a number of COLUMN_DETAILS lines. These are optional, but if present they give details of the characteristics of each column in the table as follows :-
$_$_COLUMN_DETAILS <col_no>,<align>,<width>
where
<col_no>
This is the column number, starting at 1
<align>
This is the alignment of data in this column.
If omitted this will be auto-detected, but you can
choose to set it to L(eft), R(ight) or C(enter)
<width> The width of the column. If omitted the width will
be caluculated. As with the <margin> on the tabe
the width can be specified in points, inches or
centimetres. If a width is set too narrow, it may
be ignored.
Each new row is identifies by the present of a NEW_ROW command on a line by itself. The format is
$_$_NEW_ROW <row_type>
where
<row_type> This is the row type. Options include HEAD This is a header row
DATA This is a data row
LINE This is a line in the tableThe type may be omitted, in which case the default
is "DATA"
except when the NEW_ROW is a "LINE", this command should be followed by a series of NEW_CELL commands and theit matching cell data - normally one per column.
Except for "LINE" rows, each new cell in a row identifies by the present of a NEW_CELL command on a line by itself. The contents of the cell follow on subsequent lines until either another NEW_CELL, NEW_ROW or END_TABLE command is encountered.
The format of the NEW_CELL command is
$_$_NEW_CELL
At present the NEW_CELL command doesn't take any arguments.
Anything following a NEW_CELL command up until the next NEW_CELL, NEW_ROW or END_TABLE commands will be added into the current cell. The line structure will be preserved, so that if you have three lines of text following a NEW_CELL command, this will appear as a cell in the table with three lines of data in it.
The alignment of the cell will normally be that of the column the cell is in. This will either have been calculated automatically for the column as a whole, or will be value passed in via the matching COLUMN_DETAILS line, earlier in the table definition.
- use of policies - in policy file - in sourec directives - global or per table
- use of directives
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. In this files 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. For example in HTML you can associate CSS styles with columns, allowing tables of a known type to have their columns formatted through an external stylesheet.
Other advanced features are available. For example in HTML it is possible to define alarm conditions to apply to cells in a column, and for the different alarm states to alter the apparance of the cell.
All the table definition information should be placed in a "Table Definitions file". 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.
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.
NOTE: At present the only identifier line supported is the "must contain" line
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 contaiu : 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 contaiu : 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.
NOTE: AT present only one "must contain" line per table type is supported
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.
NOTE: This may change in later versions
The "use structure" line specifies that if a table matches the identifying conditions for this table type, then it's structure should be interpretted 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.
NOTE: This may change in later versions
See Defining a table structure
table structure : Percent_funds
Layout : 6,31,41,51,61,71,81
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.
???
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 "Use format" statement in a table type section.
???
???
???
???
???
???
???
???
???
???
column format : name=ROC5 css_id=ROC5 alarms="ROC_red,ROC_green"
column format : name=ROC10 css_id=ROC10 alarms="ROC_red,ROC_green"
column format : name=ROC21 css_id=ROC21 alarms="ROC_red,ROC_green"
???
alarm : name=ROC_red type=LE value=0.0 alarm_color=red cellatts='BGCOLOR="#
alarm : name=ROC_green type=gt value=0.0 alarm_color=green cellatts='BGCOLOR="#
???
???
!- Graph definition. define --------------------------------------------------
! - graph min/max,
! - graph width (in pixels),
! - location of value relative to graph (left, right, center, none)
! - colour of graph
! - bg colour of graph
!
! simple graph defn
!
Barchart : name=GRAPH_1 width=200 value_location=left color=green null_value=491 null_display="no data"
???
table data : name=Unit_id row=1 col=1
???
Table formatting options
There are several options for controlling the formatting of the table.
These include
table css_id
column names
Show columns
Note some of the table format commands depend on the table analysis correctly identifying the columns in your table. If the columns are not correctly identified, then the formats will be applied to the wrong part of the table. See ???
table css_id
Format is
table css_id : <CSS_ID>
The value supplied is used as the CSS ID for the output table. This allows you to attach a stylesheet to the particular table layout. If this line is not present, then the software will generate a unique ID for each table of the type "table_<nn>", where <nn>=1,2,3...
column names
Format is
column names : <format_1>,<format_2>,....
where <format_1> etc are the name of column formats defined elsewhere in the file by a "Column Format" line. Commas are used to separate the names of the formats used for each column.
Formats may be omitted for some columns, and the same format may be used for multiple columns, so the following are both valid
column names : ,,,,temperature,,
column names : date,date,,temperature,,
There should only be one "columm formats" line for each "table format", although this can be omitted.
Show columns
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".
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.
Column formatting
Column formats are each defined by a sinmgle line in the definition file.
These formats do not belong to any one table format, and may be referenced
by multiple table formats, or multiple times by a single table format.
The format is
- column format
- name=<name> css_id=<id> alarms=<alarm_list> barchart=<bar_name>
Where
<name>
Required. Unique name for the column format.
This is used by table formats to identify which
column format(s) are to be used.
<css_id>
Optional. If present this is the root CSS ID
for cells in the column. Cells in the header (<TH>)
will be assigned the CSS ID "<css_id>_HEAD" while
cells in the main body (<TD>) of the table will be
given the ID "<css_id>", unless they are in an
alarm state which has it's own CSS ID.
<alarms>
Optional. A comma-separated list of Alarms that
the data cells in this column should be tested against.
If multiple alarms are to be tested, they should be
listed in quotes, and in order of precidence.
<barchart> Optional. If present this is the name of a barchart
definition to be applied to the numerical data cells
in this column.
Cell Alarms
Cells in a column can be tested against one or more alarm conditions,
according to the list given in the "alarms" attribute of the corresponding
"column format" line. The precedence order is the order the alarms are named
int the "column format" line.
the format for an Alarm definition is
- alarm
- name=<name> type=<comparison> css_id=<ID> value=<value> column_value=<column_no> alarm_color=<html_color> cellatts=<html_cell_attributes>
where
- name
- Required. This is the unique name by which the alarm condition will be reffered to in "Column Format" lines
- type
- Required. Comparison type. This identified how the cell contents are to be compared to the reference value. Options include
| lt | less than | |||
| gt | greater than | |||
| le | less than or equal to | |||
| ge | greater than or equal to | |||
| eq | equal to | |||
| ne |
not equal to |
|||
| eqs | equal to (string comparison) | |||
| nes |
not equal to (string comparison) |
- css_id
- Optional. When present, this is the CSS ID to be applied to any cell that matches this condition. This will override any column CSS ID, and so allow a stylesheet to be created which highlights those cells in an alarm state.
- cellatts
- Optional. When present, this defines any HTML cell attributes to be added to the <TD> tag for any cell matching the condition. This could be used as an alternative to CSS (not recommended ???
Using Barcharts
For columns of numerical data it is possible to have this displayed
in barchart form, with each cell showing a bar whose size is proporiotnal
to the value in the cell. If alarms are defined for the cell, then
then barchart will take on any alarm colour when the cell's contents
match the alarm condition.
the format is :-
- Barchart
- name=<name> min=<value> max=<value> origin=<value> width=<pixel_value> colour=<HTML_Colour> bgcolor=<HTML_colour> value_location=<alignment>
where
name Required. Unique name by chich this barchar
can be referred to in "column format" statementsMin, Max Optional. The minimum and maximum values at the
extremes of the barchart. If omitted the software
will automatically calculate the min and max value
for the column. If any values in the column lie
outside the specifies range, this will be automatically
extended to cope.origin Optional. Specifies an "origin" for the barchart.
Values less than this will be shown as barcharts
going to the left, those greater as barcharts to
the right, If omitted, the origin is set to
the min value, so that all barcharts draw to the left.
If you set a value greater than the max, then all
mars will be drawn to the right from.width Optional. The pixel width for the barchart. The
barchart is if omitted the default width is 200color Optional. The HTML colour to be used for the barchart
the default is "blue"bgcolor Optional. The HTML colour to be used for the barchart
background. The default is blank, indicating that
the background of the document should be used.value_location Optional. Specifies where the numerical value should
be displayed relative to the barchart. Options areleft
Value is displayed to the left of the barright
Value is dispalyed to the rightof the barcenter, middle
Value is displayed in the bar itself. If necessary
the bar will be widened. You may have difficulty
reading the text, and if an origin is specified then
this option will be switched to "left"none
The value isn't displayed, only the barchartnull_value If present any cell containing this text value will
be deemed to be "null" and won't get a barchart, nor
contribute to any limit calculations.null_display If any cell is deemed to be "null" by matching the
"null_value" then this value will be displayed
instead of a barchart.
Defining custom table headers and footers
You can customise the HTML put out before and after a table by using the
"HTML fragments" feature (described in the Tag manual). You can do
this by naming the fragments to be put out before and after the table
Format:-
HTML fragments : <before_fragment_name>, <after_fragment_name>
The statement is a comma separated list fo the before and after fragment names, values can be omitted, so for example
HTML fragments : ,table_trailer
will add the fragment "table_trailer" after the table.
HTML fragments like this can be particularly when combined with "Table data" definitions. These define how to extract data from certain cells in the table.
For example the HTML Fragment
$_$_DEFINE_HTML_FRAGMNET TABLE_HEADER
<H1>Report for customer customer</H1>
$_$_END_BLOCK
will create a heading with the variable "customer" in it. If the Table Data definition
Table Data : name=customer row=2 col=1
then the value in row 2, column 1 would be copied into the "customer" variable, which would then be output in the table header/
Extracting Table data
The Table Data definition identifies data that can be extractfrom the table
itself. The main purpose of this is to allow the data to then be used in any
HTML fragments, particularly those associated with the table header and footer
Format:-
table data : name=<name> row=<row_no> col=<col_no>
where
- name
- Required. The name given to the data item. This should be unique, and will be the name assigned to the VARIABLE tag that will display the extracted data.
row, col Required. The row and column number that the data is to be
extracted from.
???
???
????
 |
Converted from a single text file by AscToHTM © 1997-2003 John A. Fotheringham |  |