grail.misc.htmlgen module

Version: 16.2

Table of Contents

Description

Very simple HyperText Markup Language (HTML) generator.

Look to this module as the future location for making composing HTML documents easier. Currently this module only contains the building blocks, which do not really make composition easier.

The HTML Quick Reference [1] provides a useful reference for more information about what it is that this module's functions actually generated.

Importing the grail.htmlgen Module

A lot of functions in this module have very short (and probably common) names, for instance b() may be easily confused with a variable called b. For this reason is is recommend that your import should be,

from grail.misc import htmlgen

Not the simpler,

from grail.misc.htmlgen import *

Which will pollute your namespace unnecessarily.

Example of Generating a HTML Document

The following code example illustrates how you can go about composing an HyperText Markup Language (HTML) document. You have know a few little things about HTML, but basically the current incarnation of this module just saves you the effort of having to manage all the HTML tags.

print "creating 'test.html'...",
head = head(title("Test document"))
body = body(aname("top", h1("This is a test document.")),
                            "This is a test string",
                            ahref("test.html#top", "top"),
                            "And here is a hyper link to ",
                            ahref("http://www.google.ca", "google"),
                            bgcolor="#ebebeb")
HTMLDoc("test.html").generate(head, body)
print "...done."

Classes

HTMLDoc Class

class HTMLDoc(path)

Basic document generation tool.

Takes a set of strings (otherwise known as contents), and writes to the file specified by the path. The contents are wrapped like,

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
contents...
</html>

Note

This does not open a physical file handle to to the path. That is only done when the generate() method is executed.

generate(*contents)

Actually writes the contents out to the file.

Argument:
*contents : variable argument list
An arbitrarily long list of strings that will be put together to generate the final HTML document.

HTMLStream Class

class HTMLStream(stream)

You do not want to send the output directly to a file via the HTMLDoc class, then you want to use the stream object. The stream object will write the contents out the given stream.

The stream can be another file, a cStringIO object or just sys.stdout.

generate(*contents)

Writes out the contents out to the stream.

Argument:
*contents : variable argument list
An arbitrarily long list of strings that will be put together to generate the final HTML document.

Table Class

class Table()

Helps to simplify generating a HTML table of data.

As a somewhat contrived example, consider working with a pointlist, and you want to generate an html table with pointnumber, x, y, and z columns. You would do it like this,

table = htmlgen.Table()
table.setheader(0, "Point number")
table.setheader(1, "X")
table.setheader(2, "Y")
table.setheader(3, "Z")
for i in range(len(pointlist)):
   x, y, z = pointlist[i]
   table.setcell(i+1, 0, str(i+1))  # since i starts at 0.
   table.setcell(i+1, 1, str(x))
   table.setcell(i+1, 2, str(y))
   table.setcell(i+1, 3, str(z))

# this generates the <table>...</table> HTML.
html = table.generate()

The HTML TABLE element will have a summary attribute of "" applied to the table if no attribute is supplied. This is in accordance with the WC3 specification for TABLE elements.

generate()
Returns a HTML string of the data inserted into the table. Use this string as an argument to your HTMLDoc class.
setcell(row, column, *components, **kws)

Set the contents of a cell in the table.

Arguments:
row
Row number.
column
Column number.
components
Such as headers, javascripts, text.
*kws : keyword dictionary
Keywords applicable to the <td> tag, for example, align or bgcolor.
setheader(column, *components, **kws)

Set the contents of the header.

Arguments:
column
Column number.
components
Such as headers, javascripts, text.
*kws : keyword dictionary
Keywords applicable to the <th> tag, for example, align or bgcolor.
setheaderattr(**kws)
Allows set attributes for all headers.
setrowattr(row, **kws)

Allows you set an attribute for a row.

Arguments:
column
Column number.
components
Such as headers, javascripts, text.
*kws : keyword dictionary
Keywords applicable to the <tr> tag, for example, align or bgcolor.
settableattr(**kws)

Allows you to set attributes at the table level.

Arguments:
*kws : keyword dictionary
Keywords applicable to the <table> tag, for example, align or bgcolor.

Functions

ahref(link, name, **kws)
Returns <A href=link key=value key=value...>name</A>.
aname(tag, name)
Returns <A name=tag>name</A>.
body(*components, **kws)

Returns <BODY key=value key=value...>components</BODY>.

Keywords are applied as parameters to the BODY tag. For example the following call,

body(h1("Test"), bgcolor='ebebeb')

Will return,

<BODY bgcolor='ebebeb'><H1>Test</H1></BODY>
br()
Returns a <BR /> tag.
div(class_, *contents)
Returns <DIV class=class_>contents</DIV>.
h1(s)
Returns <H1>s</H1>.
h2(s)
Returns <H2>s</H2>.
h3(s)
Returns <H3>s</H3>.
h4(s)
Returns <H4>s</H4>.
h5(s)
Returns <H5>s</H5>.
head(*components)

Returns <HEAD>components</HEAD>.

Typical components include: title, javascript, style.

html(*components)

Returns <HTML>components</HTML>.

Typical components include: head, body.

Note

The HTMLDoc class wraps your contents with the HTML tag.

javascript(*functions)
Returns <SCRIPT language=javascript><!-- functions --></SCRIPT>.
p(*contents)
Returns <P>contents</P>.
pre(*contents)
Returns <PRE>contents</PRE>.
style(*contents)

Returns <STYLE>contents</STYLE>.

The contents are inserted in between the style tag. Contents can be multiple lines, and in the future there will be additional tags for composing contents.

table(*rows, **kws)

Returns <TABLE key=value key=value>rows</TABLE>.

You have to compose the rows with the tr() function. This is one of the hardest ways to build a table, and is only really good for simple table layouts.

td(*items, **kws)

Returns <TD key=value key=value...>items</TD>.

The return value is supplied to the tr() function.

th(*items, **kws)

Returns <TH key=value key=value...>items</TH>.

The return value is typically supplied to the tr() function.

title(s)
Returns <TITLE>s</TITLE>.
tr(columns, **kws)

Returns a <TR key=value key=value...>columns</TR>.

These are supplied to the table() function. The columns are generated using the td() function.

Data

BR
The <BR> tag doesn't typically take attributes so it is available via a straight constant.
[1]University of Miami. HTML Quick Reference. 1998. 2 June 2004. <http://www.it.miami.edu/classes/documents/BegHTML/htmllist.html>
View document source. Generated on: 2024-04-16 17:27 UTC.