Parse::Dia::SQL::Output::HTML(3) 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

_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: </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.

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:

Views are not currently documented.

Bugs etc

LAST SEARCHED