NAME

html.pl - shortcuts for generating HTML


SYNOPSIS

  require "html.pl";

  # Most common methods shown here.  See METHODS for others.

  # generating html headers & opening tags
  print HT_init($title); # or ...
  print HT_form_init($title, "foo.pl", $target_frame); # or ...

  # some common shortcuts
  print HT_diamond($label, $url);
  print HT_href($label, $url);
  print HT_nav($label, $url);
  print HT_img($img-src, $dest-url, $width, height);
  print HT_space($width, $height);
  print HT_mail("rexjak@yahoo.com");

  # making lists of links
  $links =  ["yahoo", $yahoo-url, 
             "foo",   "foo.pl"];
  print HT_list_diamond($links);
  print HT_list_plain($links);

  # making a table using template
  $tt->{HEADER} = ["Name", "Age", "Sex"];
  $tt->{ROWS} = [ ["James", "44","M"], 
                  ["Smith", "28", "F"] ];
  $tt->{COLOR} = "PINK-GREEN";
  $tt->{ALIGN} = "LEFT";
  print HT_table($tt);

  # making a table without template
  print HT_table(["Name", "Sex"], 
                 [["James", "M"], ["Smith", "F"]]);

  # closing html page
  print HT_end(); # or ...
  print HT_form_end();

  # context

  if ($CONTEXT{user} == 'privileged') {
    print "here is your privileged information!";
  }
  print "The subject is $CONTEXT{subject} and the view is $CONTEXT{view}";


REQUIRES

wrm.pl, CGI


DESCRIPTION

html.pl is an interface built on the popular perl module CGI.pm that encapsulates some common user-interface constructs in high-level functions which emit HTML strings. CGI programmers should feel free to bypass html.pl and use the CGI.pm methods directly if they so desire.

There are no methods in html.pl which depend on the repository object model, so this API can be used independently of a WIRM repository. User interface methods which deal directly with repo objects can be found in the gateway API.


METHODS

HT_date_prompt($paramname, $default)
Generates a popup menu of the twelve month names (using 3-letter abbreviations), with textfields for day, and year, using $paramname as the parameter name, and having the optional $default value (in the form 'DD-MM-YYYY').

HT_date_parse($paramname)
Parses elements of date specified by $paramname and returns a string of the form DD-MM-YYYY.

HT_diamond($label, $url)
Generates a hyperlink to $url using the specified label, bulleted by a red diamond-shaped graphic.

HT_end()
Emits the closing tags to end an HTML document.

HT_form_init($title, $action, $target)
Emits the header information for starting a form. The $action parameter should name a script to be executed when SUBMIT is pressed. The optional $target field names the target frame for the resulting action. Uses multipart form so file uploading will work. Makes background white. Uses $title parameter for document title.

Reads the current context from the 'context' CGI parameters, and assigns the context variables to the %CONTEXT hash.

HT_form_end()
Emits the closing tags to end an HTML form. Also emits HT_carry_context(), which carries the context CGI parameters to the next invocation so they don't have to be explicitly passed by the CGI programmer as hidden parameters.

HT_href($label, $url);
Generates a hyperlink to $url with specified label. Passes current context along URL, unless overridden by explicit mention of cx variables in URL.

HT_nav($label, $url, $space)
Generates a hyperlink to $url with specified label, surrounded by brackets, followed by a space delimiter $space pixels wide.

HT_img($src, $link, $width, $height)
Generates image tag using $src image. If optional $link is supplied, the image will be a hyperlink to that url. If optional $height and $width are specified, the image will be scaled (in pixels). Note: the image will not download faster if scaled in this manner.

HT_init($title)
Emits the header information for starting a non-form HTML page. Makes background white. Uses $title parameter for document title.

HT_list_diamond($items)
Generates a diamond-bulleted list of hyperlinks. The $items parameter should be a reference to a list of labels & urls of the form [$label1, $url1, $label2, $url2, ...].

HT_list_plain($items)
Generates a non-bulleted list of hyperlinks. The $items parameter should be a reference to a list of labels & urls of the form ($label1, $url1, $label2, $url2, ...).

HT_mail($address)
Emits a mailto: url to the specified address.

HT_nph()
Emits a non-parsed header. Scripts which use this header will send their output directly to the client browser's screen as it is generated, rather than buffering the output until the script completes. Useful for long-running scripts that generate periodic output.

HT_space($width, height)
Generates a space of the specified dimensions (in pixels). Useful for spacing form elements which would otherwise be scrunched together. Defaults to 15 pixels wide.

HT_table($header, $rows)
Generates an HTML table. $header should be a ref to an array of strings to be used as column headers. For example: [``Name'', ``Age'', ``Sex''].

$rows should be a ref to a list of refs to lists of cell values. For example: [ [``James'', ``44'',``M''], [``Smith'', ``28'', ``F''] ] For tables with a single row, a single ref to an array will suffice.

Default colors for rows of table will be alternating tan & gray. For control over the colors, alignment, and other table features, use the Table Template version described below.

HT_table($tt)
Generates an HTML table using a Table Template (TT). The TT is a hash ref with the following keys:

HEADER - A ref to an array of strings to be used as column headers. For example: [``Name'', ``Age'', ``Sex'']. If no HEADER value supplied, the table will have no headers.

ROWS - A ref to a list of refs to lists of cell values. For example: [ [``James'', ``44'',``M''], [``Smith'', ``28'', ``F''] ] For tables with a single row, a single ref to an array will suffice.

COLOR - a pair of color names (delimited by a hyphen) to indicate colors of alternating rows. Defaults to ``TAN-GREY''. Also accepts ``NONE''. Currently only supports GREY, TAN, and WHITE.

ALIGN - The alignment of values within their table cells. Can be ``LEFT'', ``RIGHT'', or ``CENTER'' (default).

CELLPADDING - The number of pixels padding cell borders. Default is 2.

BORDER - The width of the cell borders. Default = 0 (no border).

Note that table templates may be re-used (i.e. store favorite template settings and then update the ROWS & HEADER fields).

HT_textify($string)
Removes all markup tags (bracketed values) from $string.


AUTHOR

Rex Jakobovits, rex@cs.washington.edu


SEE ALSO

CGI, gateway.pl