---
name: "Parse::Dia::SQL::Output::HTML"
section: "3pm"
platform: "linux"
package: "libparse-dia-sql-perl"
version: "0.31-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Parse::Dia::SQL::Output::HTML"
---

# Parse::Dia::SQL::Output::HTML(3pm)

Create HTML documentation.

## 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

### \_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