HTMLgen_banner.jpg
blank.gif Next Top of Manual blank.gif

HTMLgen 2.0.6 Online Documentation

Overview


WHAT'S IT FOR?

HTMLgen is a class library for the generation of HTML documents with Python scripts. It's used when you want to create HTML pages containing information which changes from time to time. For example, you might want to have a page which provides an overall system summary of data collected nightly. Or maybe you have a catalog of data and images that you would like formed into a spiffy set of web pages for the world to browse. Python is a great scripting language for these tasks and with HTMLgen it's very straightforward to construct objects which are rendered out into consistently structured web pages. Of course, CGI scripts written in Python can take advantage of these classes as well.

ABOUT THIS RELEASE

This is the 2.0 release. It's a major release with a substantial rewrite of the implementation details as well as the class hierarchy. The methods used to generate the actual HTML text for each object have been changed to work much faster when they get large and complex. People generating large, complex tables should notice a good improvement. For other reasons, I now use the __str__ method instead of the __repr__ method to yield the HTML text for an object. This means any code which uses `backquotes` on HTMLgen objects will malfunction. These must be replaced with str() calls. In retrospect, I should never have used __repr__.

The Document classes have been renamed to more clearly describe their uses and they now share a more logical inheritance tree. (Aliases exist to provide backward compatibility.) There is a barchart module providing classes to create nicely formatted and color-coded bar charts, (see the Table section for examples of what they look like).

Cascading Style Sheets (CSS1) specifications are now fully supported throughout HTMLgen. In fact if you have the latest browser you are viewing this through CSS instructions stored in HTMLgen.css. The SimpleDocument and SeriesDocument classes support external and internal CSS specifications through the stylesheet and style attributes. All other classes support a Class and style attribute to tag individual objects with style. N.B. Note: Since "class" is a reserved word in Python you have to use the keyword Class when setting that tag attribute. All other attributes are lower case.

The simple HTML tag classes all now inherit from AbstractTag or AbstractTagSingle. The former base class provides generic support for HTML element attributes and container functions such as append, prepend, copy, and a new method called markup. The markup method is available to scan through the text contained in the object with a regular expression you furnish and perform a string substitution on the matching text. The method accesses two external functions - one written to support syntax of the regex module and the other to support syntax and objects from the new re module. For example, once you have a Para object "P" you could substitute all bracketed text with a bold font as follows:

p = Para('some text...')
strong = Strong()
p.markup( "(\[[^]]*\])", strong, regex_type="re" )

Note that the regular expression pattern or object given to this method must have a group defined. It treats group 1 as the target of the substitution. The above also demonstrates a new feature supplied by the AbstractTag class. Instances now can be used a functions through use of it's __call__ method. So you can now configure an HTMLgen class instance with all attributes set and then reuse the instance as a text markup function.

The release can be downloaded from the Starship Web site.

ARCHITECTURE

HTMLgen uses a simple model of having a separate class for each HTML element type. Each class instance supports an __str__ method to emit itself as HTML text markup. A SimpleDocument class provides the general container object which the user populates with objects from the markup classes. The SeriesDocument class also provides a general style template for page generation based on Patrick Lynch's Web Page Style Manual at the Yale Center for Advanced Instructional Media. See that page for more insights into the design of good web pages.

NOTES ON NAMING

The names I've selected for the classes in this module may need some explaining. There is a class for each of the common HTML elements and all classes use initial upper case for their name. All functions are lower case. I did not choose to use all caps for the classes that correspond to elements as A) HTML markup isn't case sensitive anyway and B) I hate typing things in all caps and C) I tend to use all-caps names to signify constants. I also modified the class names to make them more descriptive than the HTML standard. For example, I use Image rather than IMG in hopes that the longer names will be easier for the user to remember while coding the Python scripts. Also there is no A class. I use the Href class to specify hyper- references, (mostly because it's easier for me to remember). A little odd case is the Paragraph vs. P classes. The former class is used as a normal paragraph text container and uses the /P token while the latter is simply used to insert a <P> break in the output stream. Even though the class names might be 'Emphasis' rather than 'EM', I have provided aliases for these classes so that if you insist, you can use the HTML names as the class names.

DISTRIBUTION

This release comes with a mini-web of pages generated with the tool. The HTMLtest.py is the script used to build several pages in the html subdirectory. It functions both as a test case as well as usage examples. The reference manual output from gendoc-0.6 is there as well. Input data is read from the data directory and images used are all in the image directory. Once untaring the files simply run the test function:

>>> import HTMLtest
>>> HTMLtest.test()
wrote: "./html/overview.html"
wrote: "./html/document.html"
wrote: "./html/lists.html"
wrote: "./html/top-frames.html"
wrote: "./html/frames.html"
wrote: "./html/tables.html"
wrote: "./html/forms.html"
wrote: "./html/imagesmaps.html"
wrote: "./html/scripts.html"
wrote: "./html/independence.html"
wrote: "./html/parrot.html"
wrote: "./html/colorcube.html"

This should print the html files it generates as above. Browse them (well you ARE browsing them now I guess) to be sure things aren't hosed. The navigation buttons should work, etc. After you are satisfied just place HTMLgen.py* and HTMLcolors.py* into your PYTHONPATH (and any of the other modules you want to use) and have fun.

Comments are most welcome.
I've added a simple script called colorcube.py which generates a web-safe color table useful for selecting colors for your pages. Two additional sample pages are available as well. They are accessed by clicking the "Next" button on the last on-line doc page (Scripts). If you want to jump to them directly you can click here. If you're curious about the insect at the bottom of each page, that's my alma mater's mascot.


blank.gif Next Top of Manual blank.gif
Buzz.gif

Copyright © 1996-7 Robin Friedrich
All Rights Reserved
Comments to author: friedrich@pythonpros.com
Generated: Sat Mar 7 1998