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' [ , htmlformat => {formatfile} ]
);
print $dia->get_sql();
DESCRIPTION¶
This sub-class creates HTML formatted database documentation.
HTML formatting is controlled by templates selected with the optional
htmlformat 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
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.
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: </head><body>
htmlendbody
The end body html tag.
Placeholders: gentime
Default: <p style="font-size:75%">Generated at
{gentime}.</p>
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.
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:
Views are not currently documented.
Bugs etc
