Parse::Dia::SQL::Output::HTML - Create HTML documentation.
use Parse::Dia::SQL; my $dia = Parse::Dia::SQL->new( file => 'foo.dia', db => 'html' [ , htmlformat => {formatfile} ] ); print $dia->get_sql();
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.
The constructor.
Object names in HTML have no inherent limit. 64 has been arbitrarily chosen.
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
HTML Header
Comment for HTML Header
HTML Body start
HTML Body close
HTML close
Extracts the documentation details for a single table.
Do nothing
Permissions are formatted as {type} {name} to {list of roles} where:
{type} {name} to {list of roles}
type is the operation GRANT, REVOKE etc
type
GRANT
REVOKE
name is the permission name SELECT, INSERT etc
name
SELECT
INSERT
list of roles is the set of datbase roles affected.
list of roles
Permissions are at best lightly tested (ie potentially buggy)
Extracts the documentation for table relationships.
Extracts the documentation for table indices.
Do the output
Set up the formatting template
Template elements use {placeholders} to identify how the document should be built.
{placeholders}
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.
{def:element}
{/def:element}
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.
\n
The start of the html document.
Placeholders: filename
Default: <html><head>\n<title>Database documentation: {filename}</title>
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
The start body html tag.
Default: </head><body>
The end body html tag.
Placeholders: gentime
Default: <p style="font-size:75%">Generated at {gentime}.</p>
The end html tag.
Default: </html>
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%'/>
An individual element (table) in the table list
Placeholders: tablename, tablecomment
Default: <a href='#{tablename}'>{tablename}</a>
Separator between individual elements in the table list.
Default: ,
,
Introduction to the table details
Default: <h2>Table details</h2>
Details of one table.
Placeholders: tablename, comment, refto, refby, tablerowdata, autoupdate, indices, permissions.
<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%'/>
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>
Table comments/description.
Placeholders: comment
Default: <p>{comment}</p>
Table comments/description in a list context
Default: {comment}
Auto update code, if used.
Placeholders: autoupdate
Default: <p>Automatically set:{autoupdate}</p>
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>
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.
Separator between references.
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>
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}
Separator between indices.
Default: <br\>
<br\
A list of permissions granted on this table.
Placeholders: permissionlist
Default: <h4>Permissions</h4><p>{permissionlist}</p>
A single permission in the list
Placeholders: permission
Default: {permission}
Separator between permissions.
Default: <br/>
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.
Things that might get added in future versions:
Views are not currently documented.
Bugs etc
To install Parse::Dia::SQL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Parse::Dia::SQL
CPAN shell
perl -MCPAN -e shell install Parse::Dia::SQL
For more information on module installation, please visit the detailed CPAN module installation guide.