============================= ``grail.misc.htmlgen`` module ============================= .. include:: ..\version.h .. include:: ref.h .. contents:: Table of Contents :backlinks: top ----------- 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* [#]_ 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 :f:`b()` may be easily confused with a variable called b. For this reason is is recommend that your import should be, .. Python:: from grail.misc import htmlgen Not the simpler, .. Python:: 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. .. Python:: 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 :dc:`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, .. code-block:: HyperText contents... .. Note:: This does not open a physical file handle to to the :file:`path`. That is only done when the :f:`generate()` method is executed. .. :df:`generate(*contents)` Actually writes the contents out to the file. Argument: :a:`*contents` : variable argument list An arbitrarily long list of strings that will be put together to generate the final HTML document. HTMLStream Class ---------------- class :dc:`HTMLStream(stream)` You do not want to send the output directly to a file via the :c:`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 :c:`file`, a :c:`cStringIO` object or just :d:`sys.stdout`. :df:`generate(*contents)` Writes out the :a:`contents` out to the stream. Argument: :a:`*contents` : variable argument list An arbitrarily long list of strings that will be put together to generate the final HTML document. Table Class ----------- class :dc:`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, .. Python:: 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 ...
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. :df:`generate()` Returns a HTML string of the data inserted into the table. Use this string as an argument to your :c:`HTMLDoc` class. :df:`setcell(row, column, *components, **kws)` Set the contents of a cell in the table. Arguments: :a:`row` Row number. :a:`column` Column number. :a:`components` Such as headers, javascripts, text. :a:`*kws` : keyword dictionary Keywords applicable to the tag, for example, :a:`align` or :a:`bgcolor`. :df:`setheader(column, *components, **kws)` Set the contents of the header. Arguments: :a:`column` Column number. :a:`components` Such as headers, javascripts, text. :a:`*kws` : keyword dictionary Keywords applicable to the tag, for example, :a:`align` or :a:`bgcolor`. :df:`setheaderattr(**kws)` Allows set attributes for all headers. :df:`setrowattr(row, **kws)` Allows you set an attribute for a row. Arguments: :a:`column` Column number. :a:`components` Such as headers, javascripts, text. :a:`*kws` : keyword dictionary Keywords applicable to the tag, for example, :a:`align` or :a:`bgcolor`. :df:`settableattr(**kws)` Allows you to set attributes at the table level. Arguments: :a:`*kws` : keyword dictionary Keywords applicable to the tag, for example, :a:`align` or :a:`bgcolor`. --------- Functions --------- :df:`ahref(link, name, **kws)` Returns name. :df:`aname(tag, name)` Returns name. :df:`body(*components, **kws)` Returns components. Keywords are applied as parameters to the BODY tag. For example the following call, .. Python:: body(h1("Test"), bgcolor='ebebeb') Will return, .. code-block:: HyperText

Test

:df:`br()` Returns a
tag. :df:`div(class_, *contents)` Returns
contents
. :df:`h1(s)` Returns

s

. :df:`h2(s)` Returns

s

. :df:`h3(s)` Returns

s

. :df:`h4(s)` Returns

s

. :df:`h5(s)` Returns
s
. :df:`head(*components)` Returns components. Typical components include: title, javascript, style. :df:`html(*components)` Returns components. Typical components include: head, body. .. Note:: The :c:`HTMLDoc` class wraps your contents with the HTML tag. :df:`javascript(*functions)` Returns . :df:`p(*contents)` Returns

contents

. :df:`pre(*contents)` Returns 
contents
. :df:`style(*contents)` Returns . 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. :df:`table(*rows, **kws)` Returns
rows
. 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. :df:`td(*items, **kws)` Returns items. The return value is supplied to the tr() function. :df:`th(*items, **kws)` Returns items. The return value is typically supplied to the tr() function. :df:`title(s)` Returns s. :df:`tr(columns, **kws)` Returns a columns. These are supplied to the table() function. The columns are generated using the td() function. ---- Data ---- :dd:`BR` The
tag doesn't typically take attributes so it is available via a straight constant. ---- .. [#] University of Miami. *HTML Quick Reference*. 1998. 2 June 2004.