| 1 | # ==================================================================== | ||
| 2 | # Copyright (C) 1997,1998 Stephen Farrell <stephen@farrell.org> | ||
| 3 | # | ||
| 4 | # All rights reserved. This program is free software; you can | ||
| 5 | # redistribute it and/or modify it under the same terms as Perl | ||
| 6 | # itself. | ||
| 7 | # | ||
| 8 | # ==================================================================== | ||
| 9 | # File: TableLayout.pm | ||
| 10 | # Author: Stephen Farrell | ||
| 11 | # Created: August, 1997 | ||
| 12 | # Locations: http://www.palefire.org/~sfarrell/TableLayout/ | ||
| 13 | # CVS $Id: TableLayout.pm,v 1.16 1998/09/20 21:28:26 sfarrell Exp $ | ||
| 14 | # ==================================================================== | ||
| 15 | ## | ||
| 16 | ## Thanks for help and comments from: Jeff Stampes, Andreas Koenig, ... | ||
| 17 | ## | ||
| 18 | ## | ||
| 19 | ## To do: | ||
| 20 | ## o A thought is to have two versions of symbols to export, one | ||
| 21 | ## which is "short", but might be considered "rude" to the average | ||
| 22 | ## user's namespace. This will need a special tag (:NS_HOG | ||
| 23 | ## perhaps). alternatively, all the symbols will be prefixed like | ||
| 24 | ## TL_window, TL_cell, etc. whatever. | ||
| 25 | |||
| 26 | =head1 NAME | ||
| 27 | |||
| 28 | HTML::TableLayout - Layout Manager for cgi-based web applications | ||
| 29 | |||
| 30 | =head1 DESCRIPTION | ||
| 31 | |||
| 32 | This is a HTML-generating package for making graphical user interfaces | ||
| 33 | via a web browser using a "Layout Manager" paradigm such as in Tk/Tcl | ||
| 34 | or Java. It includes a component heirarchy for making new "widgets". | ||
| 35 | |||
| 36 | =head1 EXPORT | ||
| 37 | |||
| 38 | =over 12 | ||
| 39 | |||
| 40 | =item DEFAULT | ||
| 41 | |||
| 42 | C<parameters window table cell header text image link list pre> | ||
| 43 | |||
| 44 | =item FORM | ||
| 45 | |||
| 46 | C<form choice button hidden input_text password submit radio> | ||
| 47 | |||
| 48 | =back | ||
| 49 | |||
| 50 | =head1 SYNOPSIS | ||
| 51 | |||
| 52 | use HTML::TableLayout; | ||
| 53 | $w = window(undef,"Hello World"); | ||
| 54 | $w->insert(table()->insert("hello world")); | ||
| 55 | # ... | ||
| 56 | $w->print(); | ||
| 57 | |||
| 58 | =head2 WARNING: DOCUMENTATION INCOMPLETE AND SOMETIMES WRONG. | ||
| 59 | |||
| 60 | This documentation is incomplete and occassionally wrong. As always, | ||
| 61 | the source is the best reference (and, in fact, is relatively well | ||
| 62 | commented in this case). This documentation will improve as the API | ||
| 63 | stabilizes. | ||
| 64 | |||
| 65 | On the other hand, some effort was made to bring it up-to-date with | ||
| 66 | release 1.1.4. | ||
| 67 | |||
| 68 | =head2 Weird OO Syntax | ||
| 69 | |||
| 70 | I thought that "new" was too noisy and took up too much space, so I | ||
| 71 | do not use it in the API. When you call, for example, | ||
| 72 | |||
| 73 | window($x,$y,$z), | ||
| 74 | |||
| 75 | you are really doing | ||
| 76 | |||
| 77 | HTML::TableLayout::Window->new($x,$y,$z). | ||
| 78 | |||
| 79 | (but isn't it a whole lot nicer looking?) | ||
| 80 | |||
| 81 | |||
| 82 | =head1 User API | ||
| 83 | |||
| 84 | =over 12 | ||
| 85 | |||
| 86 | =item C<parameters> | ||
| 87 | |||
| 88 | Constructor for default parameters. This is used for setting up | ||
| 89 | application-wide defaults for parameters of various objects. It takes | ||
| 90 | no arguments but has the following methods: | ||
| 91 | |||
| 92 | $p->set($obj, %p); # destructive | ||
| 93 | $p->insert($obj, %p); # non-destructive | ||
| 94 | $p->delete(@tags); | ||
| 95 | |||
| 96 | Where the $obj is any instance of any component. | ||
| 97 | |||
| 98 | The hash %p is a hash of parameters. In all but a few cases these | ||
| 99 | parameters are passed directly through as HTML parameters. E.g., if I | ||
| 100 | write | ||
| 101 | |||
| 102 | $p->set(table(),width=>"100%",border=>undef,foo=>"bar"), | ||
| 103 | |||
| 104 | then all tables will look like | ||
| 105 | |||
| 106 | <TABLE width="100%" border foo="bar"> | ||
| 107 | |||
| 108 | (plus other parameters you add later). Note that it blindly passes | ||
| 109 | through what is presumably a meaningless HTML flag--"foo". | ||
| 110 | |||
| 111 | |||
| 112 | Now, you might find the first argument (an instance of the object) | ||
| 113 | passed in a little odd, to say the least. Once you pass in any | ||
| 114 | instance of any object, it "recognizes" that kind of object in the | ||
| 115 | future. This way, it works not only for built-in classes, but also | ||
| 116 | any that you choose to derive yourself. (NOTE: this will change | ||
| 117 | w/1.2.x, but it will probably still work this way for backwards | ||
| 118 | compatibility) | ||
| 119 | |||
| 120 | One place that this is very useful is a trivial case. Let's say that | ||
| 121 | I want to define a focused table--i.e., a table that I use | ||
| 122 | consistently to guide the users attention. I can make a class like | ||
| 123 | such: | ||
| 124 | |||
| 125 | package FocusedTable; | ||
| 126 | @ISA=qw(HTML::TableLayout::ComponentTable); | ||
| 127 | |||
| 128 | ## EOF | ||
| 129 | |||
| 130 | and then I can add a setting: | ||
| 131 | |||
| 132 | $p->set(FocusedTable->new(), %focustable_settings); | ||
| 133 | |||
| 134 | Now, whenever you use a FocusedTable, it will use these settings, even | ||
| 135 | though in reality it is the same as a table. | ||
| 136 | |||
| 137 | Hmm... you're thinking, but what if I derive a special Checkbox, but I | ||
| 138 | want it to get the parameters for a regular checkbox. I've provided | ||
| 139 | for this as well. In your constructor for this new checkbox (or an | ||
| 140 | init() method): | ||
| 141 | |||
| 142 | package myCheckbox; | ||
| 143 | @ISA=qw(HTML::TableLayout::FormComponent::Checkbox); | ||
| 144 | |||
| 145 | sub new { | ||
| 146 | my ($class, %params) = @_; | ||
| 147 | my = {}; | ||
| 148 | bless , $class; | ||
| 149 | ->tl_inheritParamsFrom(checkbox()); | ||
| 150 | return ; | ||
| 151 | } | ||
| 152 | |||
| 153 | And the mechanism that sets the parameters will think it is really | ||
| 154 | just a Checkbox. | ||
| 155 | |||
| 156 | (It might be nice if instead of having to set this explicitely, the | ||
| 157 | mechanism (_obj2tag(), actually) could check based upon inheritance | ||
| 158 | and use the settings from the closest parent. The thing is (a) I | ||
| 159 | don't know how to do this efficiently (b) I want to have this | ||
| 160 | tl_inheritParamsFrom() anyway so that one can force whichever behavior | ||
| 161 | she wants.) | ||
| 162 | |||
| 163 | NOTE: This is one of the things that will probably change/improve for | ||
| 164 | version 1.2.x... | ||
| 165 | |||
| 166 | |||
| 167 | =item C<window> | ||
| 168 | |||
| 169 | Constructor for a window. The first argument is a parameters object, | ||
| 170 | while the third argument is the parameters specific to that window | ||
| 171 | instance. | ||
| 172 | |||
| 173 | window($parameters, $title, %params) | ||
| 174 | |||
| 175 | |||
| 176 | =item C<win_header> | ||
| 177 | |||
| 178 | Constructor for a window header. The first argument is the number of | ||
| 179 | the header, as in: | ||
| 180 | |||
| 181 | win_header(2,"some text") | ||
| 182 | |||
| 183 | will produce: | ||
| 184 | |||
| 185 | <H2>some text</H2> | ||
| 186 | |||
| 187 | Similarly, | ||
| 188 | |||
| 189 | win_header(undef,"some text") | ||
| 190 | |||
| 191 | will produce | ||
| 192 | |||
| 193 | some text | ||
| 194 | |||
| 195 | but will place it up at the top of the window. | ||
| 196 | |||
| 197 | =item C<table> | ||
| 198 | |||
| 199 | Constructor for a table. Other than a few special cases (such as | ||
| 200 | scripts and headers) everything is layed out via tables. Tables can | ||
| 201 | be nested inside other tables. It takes a hash of parameters as an | ||
| 202 | argument--these parameters will only be used for this table. One | ||
| 203 | salient example would be "columns". If you want to have a | ||
| 204 | 15-columned table, you'd say: | ||
| 205 | |||
| 206 | $t=table(columns=>15); | ||
| 207 | |||
| 208 | This parameter is passed directly out to the HTML, but this layout | ||
| 209 | manager also pays attention to it internally. | ||
| 210 | |||
| 211 | Tables have one external method: | ||
| 212 | |||
| 213 | $t->insert($some_component); | ||
| 214 | |||
| 215 | This something can be pretty much anything derived from | ||
| 216 | HTML::TableLayout::Component. It can also be a form--as a general | ||
| 217 | rule the table just does the right thing with whatever you stick in | ||
| 218 | it. If it does not, it is a bug (please let me know!) | ||
| 219 | |||
| 220 | =item C<cell> | ||
| 221 | |||
| 222 | Constructor for a cell. You will be using a lot of these--these | ||
| 223 | correspond to <TD></TD> in HTML. (Rows are handled magically by this | ||
| 224 | layout manger). Tables create default cells when you stick something | ||
| 225 | in them which is not a cell (or form). If you want to put more than | ||
| 226 | one thing in a cell, or if you want to made a special cell (e.g., with | ||
| 227 | some non-default alignment), then you need to create a cell | ||
| 228 | explicitely. You insert "stuff" into cells much like you do into | ||
| 229 | tables. In fact, when you stick something into a table that the table | ||
| 230 | does not recognize, it just passes it along to a (new) cell. | ||
| 231 | |||
| 232 | |||
| 233 | =item C<cell_header> | ||
| 234 | |||
| 235 | Constructor for a cell header. The first argument is the contents | ||
| 236 | (usually text), and the next arguments are a hash of parameters. You | ||
| 237 | can set the orientation of such with the "Orientation" pseudo-tag. | ||
| 238 | E.g., Orientation=>"left" will make the header appear to the left of | ||
| 239 | the cell. | ||
| 240 | |||
| 241 | =item C<text> | ||
| 242 | |||
| 243 | Constructor for text. It looks like: | ||
| 244 | |||
| 245 | $c->insert(text($text,%params)); | ||
| 246 | |||
| 247 | The parameters are a bit special--if you put in stuff like bold=>undef | ||
| 248 | or size=>"+2", then it will do the following: | ||
| 249 | |||
| 250 | <FONT size=+2><b>whatever</b></FONT> | ||
| 251 | |||
| 252 | Like everything else here, this is supposed to "just work" as you | ||
| 253 | expect it to, so I had to do some funky translations of HTML tags | ||
| 254 | since HTML is pretty screwed up with this stuff. | ||
| 255 | |||
| 256 | =item C<image> | ||
| 257 | |||
| 258 | Constructor for an image. Use it like | ||
| 259 | |||
| 260 | $c->insert(image($url,%params)); | ||
| 261 | |||
| 262 | Where the url can be relative or absolute (straight HTML story). | ||
| 263 | |||
| 264 | =item C<link> | ||
| 265 | |||
| 266 | Constructor for a link. Use it like | ||
| 267 | |||
| 268 | $c->insert(link($url,$anchor,%params)); | ||
| 269 | |||
| 270 | Note that $anchor might be something interesting, like an image, so: | ||
| 271 | |||
| 272 | $c->insert(link("whatever.html",image("image.gif"))); | ||
| 273 | |||
| 274 | should work like a charm. | ||
| 275 | |||
| 276 | |||
| 277 | =item C<list> | ||
| 278 | |||
| 279 | Constructor for a list. A list sets up a list environment in | ||
| 280 | HTML. Unlike a lot of other components here, it takes two rigid | ||
| 281 | arguments, and not just parameters which get passed to HTML and maybe | ||
| 282 | noticed by the layout manager. | ||
| 283 | |||
| 284 | $l=list($numbered, $delimited); | ||
| 285 | $l->insert("first element"); | ||
| 286 | $l->insert(text("second element",bold=>undef)); | ||
| 287 | $l->insert(link($url,"third element")); | ||
| 288 | |||
| 289 | |||
| 290 | |||
| 291 | =item C<pre> | ||
| 292 | |||
| 293 | Sets up a preformatted environment in HTML. Just give it some text; | ||
| 294 | it prints it out raw. | ||
| 295 | |||
| 296 | =item C<script> | ||
| 297 | |||
| 298 | Sets up an appropriate environment for a script. Put the script in | ||
| 299 | the window if you want it to appear in the preamble; otherwise it will | ||
| 300 | appear whereever you call it in the table. | ||
| 301 | |||
| 302 | =head2 | ||
| 303 | |||
| 304 | NOTE there are other classes... see the source for now to find these. | ||
| 305 | |||
| 306 | =head1 BUGS | ||
| 307 | |||
| 308 | See comments in code, particular TODO in TLCore.pm | ||
| 309 | |||
| 310 | =head1 AUTHOR | ||
| 311 | |||
| 312 | Stephen Farrell <stephen@farrell.org>--feel free to write email with | ||
| 313 | any questions. | ||
| 314 | |||
| 315 | =cut | ||
| 316 | |||
| 317 | package HTML::TableLayout; | ||
| 318 | |||
| 319 | $HTML::TableLayout::VERSION = 1.001008; | ||
| 320 | |||
| 321 | use HTML::TableLayout::Symbols; | ||
| 322 | |||
| 323 | use HTML::TableLayout::TLCore; | ||
| 324 | |||
| 325 | use HTML::TableLayout::Component; | ||
| 326 | |||
| 327 | use HTML::TableLayout::Form; | ||
| 328 | |||
| 329 | use Exporter; | ||
| 330 | @ISA=qw(Exporter); | ||
| 331 | @EXPORT=qw( | ||
| 332 | parameters | ||
| 333 | window | ||
| 334 | win_header | ||
| 335 | table | ||
| 336 | cell | ||
| 337 | cell_header | ||
| 338 | script | ||
| 339 | text | ||
| 340 | image | ||
| 341 | link | ||
| 342 | list | ||
| 343 | pre | ||
| 344 | comment | ||
| 345 | hrule | ||
| 346 | container | ||
| 347 | font | ||
| 348 | ); | ||
| 349 | @EXPORT_OK=qw( | ||
| 350 | form | ||
| 351 | choice | ||
| 352 | button | ||
| 353 | checkbox | ||
| 354 | textarea | ||
| 355 | hidden | ||
| 356 | faux | ||
| 357 | input_text | ||
| 358 | password | ||
| 359 | submit | ||
| 360 | radio | ||
| 361 | ); | ||
| 362 | |||
| 363 | %EXPORT_TAGS=(FORM=> | ||
| 364 | [qw( | ||
| 365 | form | ||
| 366 | choice | ||
| 367 | button | ||
| 368 | checkbox | ||
| 369 | textarea | ||
| 370 | hidden | ||
| 371 | faux | ||
| 372 | input_text | ||
| 373 | password | ||
| 374 | submit | ||
| 375 | radio | ||
| 376 | )]); | ||
| 377 | |||
| 378 | |||
| 379 | |||
| 380 |