HTML::TableLayout - Layout Manager for cgi-based web applications


This is a HTML-generating package for making graphical user interfaces via a web browser using a "Layout Manager" paradigm such as in Tk/Tcl or Java. It includes a component heirarchy for making new "widgets".



parameters window table cell header text image link list pre


form choice button hidden input_text password submit radio


  use HTML::TableLayout;
        $w = window(undef,"Hello World");
        $w->insert(table()->insert("hello world"));
        # ...


This documentation is incomplete and occassionally wrong. As always, the source is the best reference (and, in fact, is relatively well commented in this case). This documentation will improve as the API stabilizes.

On the other hand, some effort was made to bring it up-to-date with release 1.1.4.

Weird OO Syntax

I thought that "new" was too noisy and took up too much space, so I do not use it in the API. When you call, for example,


you are really doing


(but isn't it a whole lot nicer looking?)

User API


Constructor for default parameters. This is used for setting up application-wide defaults for parameters of various objects. It takes no arguments but has the following methods:

        $p->set($obj, %p);      # destructive
        $p->insert($obj, %p);   # non-destructive

Where the $obj is any instance of any component.

The hash %p is a hash of parameters. In all but a few cases these parameters are passed directly through as HTML parameters. E.g., if I write


then all tables will look like

<TABLE width="100%" border foo="bar">

(plus other parameters you add later). Note that it blindly passes through what is presumably a meaningless HTML flag--"foo".

Now, you might find the first argument (an instance of the object) passed in a little odd, to say the least. Once you pass in any instance of any object, it "recognizes" that kind of object in the future. This way, it works not only for built-in classes, but also any that you choose to derive yourself. (NOTE: this will change w/1.2.x, but it will probably still work this way for backwards compatibility)

One place that this is very useful is a trivial case. Let's say that I want to define a focused table--i.e., a table that I use consistently to guide the users attention. I can make a class like such:

        package FocusedTable;

        ## EOF

and then I can add a setting:

        $p->set(FocusedTable->new(), %focustable_settings);

Now, whenever you use a FocusedTable, it will use these settings, even though in reality it is the same as a table.

Hmm... you're thinking, but what if I derive a special Checkbox, but I want it to get the parameters for a regular checkbox. I've provided for this as well. In your constructor for this new checkbox (or an init() method):

        package myCheckbox;

        sub new {
                my ($class, %params) = @_;
                my  = {};
                bless , $class;
                return ;

And the mechanism that sets the parameters will think it is really just a Checkbox.

(It might be nice if instead of having to set this explicitely, the mechanism (_obj2tag(), actually) could check based upon inheritance and use the settings from the closest parent. The thing is (a) I don't know how to do this efficiently (b) I want to have this tl_inheritParamsFrom() anyway so that one can force whichever behavior she wants.)

NOTE: This is one of the things that will probably change/improve for version 1.2.x...


Constructor for a window. The first argument is a parameters object, while the third argument is the parameters specific to that window instance.

        window($parameters, $title, %params)

Constructor for a window header. The first argument is the number of the header, as in:

        win_header(2,"some text")

will produce:

        <H2>some text</H2>


        win_header(undef,"some text")

will produce

        some text

but will place it up at the top of the window.


Constructor for a table. Other than a few special cases (such as scripts and headers) everything is layed out via tables. Tables can be nested inside other tables. It takes a hash of parameters as an argument--these parameters will only be used for this table. One salient example would be "columns". If you want to have a 15-columned table, you'd say:


This parameter is passed directly out to the HTML, but this layout manager also pays attention to it internally.

Tables have one external method:


This something can be pretty much anything derived from HTML::TableLayout::Component. It can also be a form--as a general rule the table just does the right thing with whatever you stick in it. If it does not, it is a bug (please let me know!)


Constructor for a cell. You will be using a lot of these--these correspond to <TD></TD> in HTML. (Rows are handled magically by this layout manger). Tables create default cells when you stick something in them which is not a cell (or form). If you want to put more than one thing in a cell, or if you want to made a special cell (e.g., with some non-default alignment), then you need to create a cell explicitely. You insert "stuff" into cells much like you do into tables. In fact, when you stick something into a table that the table does not recognize, it just passes it along to a (new) cell.


Constructor for a cell header. The first argument is the contents (usually text), and the next arguments are a hash of parameters. You can set the orientation of such with the "Orientation" pseudo-tag. E.g., Orientation=>"left" will make the header appear to the left of the cell.


Constructor for text. It looks like:


The parameters are a bit special--if you put in stuff like bold=>undef or size=>"+2", then it will do the following:

        <FONT size=+2><b>whatever</b></FONT>

Like everything else here, this is supposed to "just work" as you expect it to, so I had to do some funky translations of HTML tags since HTML is pretty screwed up with this stuff.


Constructor for an image. Use it like


Where the url can be relative or absolute (straight HTML story).

Constructor for a link. Use it like


Note that $anchor might be something interesting, like an image, so:


should work like a charm.


Constructor for a list. A list sets up a list environment in HTML. Unlike a lot of other components here, it takes two rigid arguments, and not just parameters which get passed to HTML and maybe noticed by the layout manager.

        $l=list($numbered, $delimited);
        $l->insert("first element");
        $l->insert(text("second element",bold=>undef));
        $l->insert(link($url,"third element"));

Sets up a preformatted environment in HTML. Just give it some text; it prints it out raw.


Sets up an appropriate environment for a script. Put the script in the window if you want it to appear in the preamble; otherwise it will appear whereever you call it in the table.

NOTE there are other classes... see the source for now to find these.


See comments in code, particular TODO in


Stephen Farrell <>--feel free to write email with any questions.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 302:

You forgot a '=back' before '=head2'