NAME
Parse::Dia::SQL::Output::HTML - Create HTML documentation.
SYNOPSIS
use Parse::Dia::SQL;
my $dia = Parse::Dia::SQL->new(file => 'foo.dia', db => 'html'[, format=>{formatfile}]);
print $dia->get_sql();DESCRIPTION
This sub-class creates HTML formatted database documentation.
HTML formatting is controlled by templates selected with the optional format parameter which supplies a format file. See "HTML formats" for more.
The generated HTML is intended to be useful rather than beautiful.
This sub-class follows the same structure as the rdbms output sub-classes with the intent of maintaining consistency, even though this give less than optimum efficiency.
new
The constructor.
Object names in HTML have no inherent limit. 64 has been arbitrarily chosen.
get_sql
Return all sql documentation.
First build the data structures:
schema create
view create
permissions create
inserts
associations create (indices first, then foreign keys)Then generate the output:
html start
html comments
body start
generate main html
body end
html end_get_preamble
HTML Header
_get_comment
Comment for HTML Header
get_smallpackage_pre_sql
HTML Body start
get_smallpackage_post_sql
HTML Body close
_get_postscript
HTML close
_get_create_table_sql
Extracts the documentation details for a single table.
get_schema_drop
Do nothing
get_view_drop
Do nothing
_get_fk_drop
Do nothing
_get_drop_index_sql
Do nothing
get_permissions_create
Permissions are formatted as {type} {name} to {list of roles} where:
type is the operation GRANT, REVOKE etc
name is the permission name SELECT, INSERT etc
list of roles is the set of datbase roles affected.
Warning
Permissions are at best lightly tested (ie potentially buggy)
get_permissions_drop
Do nothing
_get_create_association_sql
Extracts the documentation for table relationships.
_get_create_index_sql
Extracts the documentation for table indices.
generate_html
Do the output
set_html_template
Set up the formatting template
Template elements use {placeholders} to identify how the document should be built.
HTML Formats
The default format may be all you need. If you want to create different HTML formats for different uses, create a format file with template elements defined between {def:element} and {/def:element} markers. You only need to define those elements that you want to be different from the defaults.
Any text outside the {def:element} and {/def:element} is ignored, so you can add comments without affecting the output.
Any \n literals in the format file are replaced with newlines; although newlines in the generated HTML typically have no effect on the layout, they can make the output easier for humans to read.
Template elements
htmlpreamble
The start of the html document.
Placeholders: filename
Default: <html><head>\n<title>Database documentation: {filename}</title>
htmlcomment
A generated comment at the start of the html document. This is the standard comment at the start of the SQL script.
Placeholders: htmlcomment
Default: \n<!-- {htmlcomment} -->\n
htmlstartbody
The start body html tag.
Default: <body>
htmlendbody
The end body html tag.
Placeholders: gentime
Default: <p style="font-size:75%">Generated at {gentime}.</p></body>
htmlend
The end html tag.
Default: </html>
tablelist
The bit at the top of the page which lists all the tables. Each is formatted with "tablelistitem", separated by "tablelistsep".
Placeholders: tablelist (the assembled list of table), filename
Default:
<h1>Data Dictionary for {filename}</h1>
<h2\>List of Tables</h2>
{tablelist}
<hr width='80%'/>tablelistitem
An individual element (table) in the table list
Placeholders: tablename, tablecomment
Default: <a href='#{tablename}'>{tablename}</a>
tablelistsep
Separator between individual elements in the table list.
Default: ,
tablestart
Introduction to the table details
Default: <h2>Table details</h2>
table
Details of one table.
Placeholders: tablename, comment, refto, refby, tablerowdata, autoupdate, indices, permissions.
Default:
<h3>Table: {tablename}<a name='{tablename}'/></h3>
{comment}
{refto}
{refby}
<table border='1' cellspacing='0' cellpadding='1'>
<tr><td>Field</td><td>Type</td><td>Default</td><td>Description</td></tr>
{tablerowdata}
</table>
{autoupdate}
{indices}
{permissions}
<hr width='80%'/>tablekeyrow, tablerow
Details of an individual field (column) from the (table) in the table detail.
tablekeyrow is used for primary key fields, tablerow for other fields.
Placeholders: name, type, default, comment.
Default tablekeyrow: <tr><td><b>{name}</b></td><td>{type}</td><td>{default}</td><td>{comment}</td></tr>
Default tablerow: <tr><td>{name}</td><td>{type}</td><td>{default}</td><td>{comment}</td></tr>
tablecomment
Table comments/description.
Placeholders: comment
Default: <p>{comment}</p>
tablecommentlist
Table comments/description in a list context
Placeholders: comment
Default: {comment}
autoupdate
Auto update code, if used.
Placeholders: autoupdate
Default: <p>Automatically set:{autoupdate}</p>
refby, refto
References by - a list of tables that refer to this one via foreign keys.
References to - a list of tables to which this table refers via foreign keys.
The whole section is omitted if there are no references (including any static text).
Placeholders: refbylist, reftolist respectively.
Default: refby <p>Referenced by: {refbylist}</p>
Default: refto <p>References: {reftolist}</p>
refbyitem, reftoitem
A single item in the reference by list
Placeholders: tablename, key, fk, action, refname
Here tablename is the other table, key is the field in this table, fk is the field in the other table, action in the action on update/delete (such as cascade or update) and refname is the name of the constraint.
Default: <a href='#{tablename}'>{tablename}</a>
refbysep, reftosep
Separator between references.
Default: ,
indices
List of indices on this tables.
The whole section is omitted if there are no indices (including any static text).
Placeholders: indexlist
Default: <h4>Indices</h4><p>{indexlist}</p>
indexitem
A single item in the index list
Placeholders: tablename, columns, comment, type, indexname
Here tablename is the indexed (ie current) table, columns is the set of columns in the index, comment is the index comment if any, type is 'unique' (or blank) and indexname is the name of the index.
Default: {indexname}: {type} on {columns} {comment}
indexsep
Separator between indices.
Default: <br\>
permission
A list of permissions granted on this table.
Placeholders: permissionlist
Default: <h4>Permissions</h4><p>{permissionlist}</p>
permissionitem
A single permission in the list
Placeholders: permission
Default: {permission}
permissionsep
Separator between permissions.
Default: <br/>
fieldblank
Replacement character(s) for blank values. Default value is empty.
Sample format file
This format file generates vertical lists of tables and references rather than single paragraph, comma separated lists (which is the default).
{def:tablelist}
<h1>List of Tables</h1>
<table border='1' cellspacing='0' cellpadding='2'>
<tr><td><b>Name</b></td><td><b>Description</b></td></tr>
{tablelist}
</table>
<hr width='80%'/>
{/def:tablelist}
{def:tablelistitem}<tr><td><a href='#{tablename}'>{tablename}</a></td><td>{tablecomment}</td></tr> {/def:tablelistitem}
{def:tablelistsep}\n{/def:tablelistsep}
{def:refby}<p><b>Referenced by:</b> <br/>{refbylist}</p>{/def:refby}
{def:refbyitem}{fk}=<a href='#{tablename}'>{tablename}</a>.{key} {action}{/def:refbyitem}
{def:refbysep} <br/>{/def:refbysep}
{def:refto}<p><b>References:</b> <br/>{reftolist}</p>{/def:refto}
{def:reftoitem} {fk}=<a href='#{tablename}'>{tablename}</a>.{key} {action}{/def:reftoitem}
{def:reftosep}<br/>{/def:reftosep}
# Comments don't matter
{def:permission}<h4>Permissions</h4><p>{permissionlist}</p>{/def:permission}
{def:permissionitem}{permission}{/def:permissionitem}
{def:permissionsep}<br/>{/def:permissionsep}Note that comments or other text outside the {def:} The other template elements are the same as the default.
TODO
Things that might get added in future versions:
Better templating mechanism.
Views are not currently documented.
Bugs etc