NAME

HTMLObject::Normal - Perl extension for HTMLObject.

SYNOPSIS

  use HTMLObject::Normal;
  my $doc = HTMLObject::Normal->new();
  $doc->setTitle("Test of HTMLObject::Normal");
  $doc->setFocus("body");
  $doc->print(<<"END_OF_BODY");
  <center>
  <h1>HTMLObject::Normal</h1>
  <br />
  This is cool!
  END_OF_BODY
  $doc->setCookie(name => 'cookie name', value => 'This rocks!');
  $doc->setFocus("javascript");
  $doc->print(<<"END_OF_JAVASCRIPT");
    function helloWorld()
    {
      document.write("Hello World");
    }
  END_OF_JAVASCRIPT  # This must be left aligned all the way.
  # cause the helloWorld function to be called when the page has been
  # loaded!
  $doc->setOnload("helloWorld();");
  # Actually generate the entire document, cookie and all!
  $doc->display();

DESCRIPTION

HTMLObject::Normal builds on the HTMLObject::Base object and provides JavaScript support that facilitates making Dynamic HTML documents much easier than before. See the documentation.html file for more details. All core methods in the HTMLObject::Base module are available for use in this module. For documentation see the HTMLObject::Base man page.

Exported FUNCTIONS

string displayJavaScriptHead(void)
 returns the string of all javascript related code that needs to
 be output in the <head> tag.
string displayJavaScriptBody(void)
 returns the string of javascript related attributes that needs to
 be output in the <body> or <frameset> tags.
void setFocus(section) (scalar value)
 Validates the section name specified and then sets the internal
 pointer to the specified section. The output of any following print,
 read, or delete commands will work with the specified section.
 Modifies $currentSection.  This version handles "javascript" and
 passes everything else to the HTMLObject::Base class to handle.
void print(string|hash) Appends the contents of string to the currently specified section. This could modify $headString, $bodyString, $javascriptBody.
    If string is a hash, then we use the keys to determine what
    sections to append text to.  This allows you to work with the
    following strings and data structures by name:
    strings:
      - javascript
      - onload
      - onunload
      - onbeforeunload
    structures:
      - javascriptIncludes
    structures can be modified by sending in a single string or an
    arrayref of strings to be modified.
    All structures are checked to make sure duplicates are not
    entered.
    Ex: $doc->print(body => "$bodyStr", head => "$headStr",
                    javascript => "$javascriptStr");
void onload(replace => bool, code => '')
 Frontend to the setOnload() method.
void setOnload(replace => bool, code => '')
 If not passing by name and only one argument specified, it is
 assumed to be the code argument.
 This function builds up a javascript function doOnLoad() that
 is called by the onload attribute on the <body> tag.
 The code snippet you specify is appended to any previously
 specified onload code unless you specify replace => 1.
void onunload(replace => bool, code => '')
 Frontend to the setOnunload() method.
void setOnunload(replace => bool, code => '')
 If not passing by name and only one argument specified, it is
 assumed to be the code argument.
 This function builds up a javascript function doOnUnLoad() that
 is called by the onunload attribute on the <body> tag.
 The code snippet you specify is appended to any previously
 specified onunload code unless you specify replace => 1.
void onbeforeunload(replace => bool, code => '')
 Frontend to the setOnbeforeunload() method.
void setOnbeforeunload(replace => bool, code => '')
 If not passing by name and only one argument specified, it is
 assumed to be the code argument.
 This function builds up a javascript function doOnBeforeUnLoad() that
 is called by the onbeforeunload attribute on the <body> tag.
 The code snippet you specify is appended to any previously
 specified onbeforeunload code unless you specify replace => 1.
 How to take advantage of the onbeforeunload event:
 1) If you want the browser to alwasy prompt when leaving the current
 page, have your code be:
 return "";
 2) If you want to specify a message to be displayed when the prompt is
 output, have your code be:
 return "This is the message to display, or whatever you want.";
 3) If you decide you don't want to prompt when the user leaves the page,
 have your code be:
 return;
 You have to explicitly put the return call in.
hash generatePickerCode()
 This method now moved to HTMLObject::Widgets!

Exported FUNCTIONS - NonInline POD

  scalar new()
    Creates a new instance of the HTMLObject::Normal document type.
  void reset()
    Resets the HTMLObject::Normal document back to the defaults.
  void display( debug => 0|1, print => 0|1 )
    optional: debug (defaults to 0), print (defaults to 1)
    This function generates the Normal Document displaying any cookies,
    JavaScript, Base, Links, etc. that were specified by the user plus
    the contents of the Body that the user created.  This function prints
    the generated document to standard out which is then hopefully being
    sent to a web server to process, if print = 1.  If debug is defined
    (and equals 1), then the contents of the current Document are
    returned in a format ready to display in another Document so that the
    user can see what would have been generated and the string is not
    printed out.
    The generated output is always returned to the caller.
  void startDisplaying()
    This function generates the Base Document displaying any cookies,
    plus the contents of the Body that the user created.  This function
    prints the generated document to standard out which is then hopefully
    being sent to a web server to process.  This also sets a flag
    bufferMode to 0 so that the methods know that we are no longer
    buffering user input but should just print it to the standard output.
    The only valid commands are error related, endDisplaying and print.
  void endDisplaying()
    This function closes the document that is currently being displayed
    in non-Buffering mode.  It is not valid to call this more than once.
  void printTag(tag, value, mode)
    requires: tag, value
    optional: mode (global or single replace)
    appends the contents of value to the tagBuffers->{tag} string.
    The tagBufferMode is set for the tag based upon the value of mode.
    If no mode is specified and a mode has not yet been set for the tag,
    then it is defaulted to single replacement mode, not global
    replacement.  Tags are only worked with in the BODY section.
  scalar read()
    Returns the contents of the currently specified section. This could
    be $headString, $bodyString, $javascriptBody.
  scalar readTag(tag)
    requires: tag
    returns the string from tagBuffers identified by tag
  void delete()
    Deletes the contents of the currently specified section. You should
    call read() before doing this so you can restore if this was an
    accident. This could modify $headString, $bodyString,
    $javascriptBody.
  void deleteTag(tag)
    required: tag
    We remove the contents from tagBuffers for the tag.
  void setJavascriptInclude(version => '', file => '')
    This function creates an entry in the @javascriptIncludes array that
    will create the code to include the specified javascript file and run
    it at the specified language version. If the version is not
    specified, then "JavaScript" is the default language and version.
    Modifies @javascriptIncludes.
  void setJavascriptVersion(version) (scalar value)
    This function sets what the Javascript version should be for the
    JavaScript body section. If not specified before the user calls
    display(), then the version will be JavaScript1.1. Modifies
    $javascriptVersion.
  scalar getJavascriptVersion()
    This function returns the current JavaScript version that is set in
    javascriptVersion.
  void printJavascriptRequired(version => '', message => '')
    This function will create the <noscript>$message</noscript> tags in
    the head that will be run if the browser does not support scripting
    at all and will also generate the code to display the message if the
    specified version of scripting is not supported. Modifies
    $javascriptRequiredMessage, $javascriptRequiredVersion.
  void disableJavascriptErrorHandler()
    This function sets the variable $javascriptErrorHandler to 0 so
    that I know not to generate that block of code when displaying the
    document.
  scalar isJavascriptErrorHandlerEnabled()
    This function returns the value of the javascriptErrorHandler to
    see if it is enabled or disabled.
  void setJavascriptErrorHandlerVersion(version => 'both')
    This function is now deprecated and will be removed in the next
    version of the HTMLObject since the javascript Error Handler
    output is now the same for Version 4 and 5 browsers.
    Mozilla's functionality has apparently been fixed since
    2001-11-01!  Argh!
  scalar getJavascriptErrorHandlerVersion()
    This function is now deprecated and will be removed in the next
    version of the HTMLObject.
    It now always returns "both".
  void setJavascriptErrorHandlerEmail(email => '')
    This function will set the value of $javascriptErrorHandlerEmail
    to the value specified.  This is used in the generic JavaScript error
    handler.
    This is the only way to get the javascript error handler enabled
    unless you use enableJavascriptErrorHandler().
    By default, the error handler is now disabled until a valid
    e-mail address is specified.  (new in version 2.18)
  scalar getJavascriptErrorHandlerEmail()
    This function returns the email address that will be used by the
    builtin error handling code.
  void setJavascriptErrorHandlerPrgName(name => '')
    This function will set the value of $javascriptErrorHandlerPrgName
    to the value specified.  This is used in the generic JavaScript error
    handler to specify the name of the Program we are generating an
    error handler for.
  scalar getJavascriptErrorHandlerPrgName()
    This function returns the name of the program that we are generating
    a JavaScript error handler for.
  void setJavascriptErrorHandlerPrgVersion(version => '')
    This function will set the value of $javascriptErrorHandlerPrgVersion
    to the value specified.  This is used in the generic JavaScript error
    handler to specify the version of the Program we are generating an
    error handler for.
  scalar getJavascriptErrorHandlerPrgVersion()
    This function returns the version of the program that we are generating
    a JavaScript error handler for.
  void setJavascriptErrorHandler(code => '')
    This function will set the code to use for the JavaScript error
    handler and will assign it to $javascriptErrorHandlerCode.  It is
    up to the user to properly set the return value so that JavaScript
    does not continue to process the error message.  The user must also
    create their own JavaScript window, etc.
  void setJavascriptErrorHandlerWindow(name => '')
    This function will set the base window name to prepend to the
    window creation code used by the builtin error handler.
  scalar getJavascriptErrorHandlerWindow()
    This function returns the window name that will be used by the
    builtin error handler.

JavaScript Include files available

The HTMLObject module provides several javascript libraries that should be available as /htmlobject/js/libraryname in your web environment. They should be installed into the /usr/share/htmlobject directory on your server and made available via an apache Include configuration file.

cookies.js
Cookie library providing the following functions:
string encodeCookiePart(value)
Returns the converted string after making sure it contains only the valid characters a cookie can contain.

string decodeCookiePart(value)
Returns the original string that was passed into encodeCookiePart().

void createCookie(name, value, days, domain, path)
Creates a cookie of name=value. If days == 0, then it expires when the browser closes. If days > 0, then it expires days days later. If days < 0, then it expires and is deleted.

If domain is specified, then the cookie is restricted to the specified domain. Ex: .pcxperience.com

If path is specified, then the cookie is restricted to the specified path, else it defaults to '/'.

string readCookie(name)
Returns the un-encoded cookie value or null if the cookie was not found.

void eraseCookie(name, domain, path)
Calls createCookie(name, ``'', -1, domain, path) to delete the specified cookie.

form_methods.js
Javascript library of methods that make working with forms much nicer.
void selectAll(widget)
If the widget is a select box, we then select all entries.

void unSelectAll(widget)
If the widget is a select box, we then un-select all entries.

void toggleSelection(widget)
If the widget is a multi-select box, we go through and invert all the entries selected states.

string selectAllButton(form, item)
returns the html snippet used to create the ``Select All'' button for the named form item in the specified form.

string toggleSelectButton(form, item)
returns the html snippet used to create the ``Toggle'' button for the named form item in the specified form.

int getTimeStamp()
returns the current date/time via the getTime() method.

void calcDatePrev(field)
Calculates the previous date from the specified fields value. The date must be in ISO format and - seperated. The new date is put back into field.value.

void calcDateNext(field)
Calculates the next date from the specified fields value. The date must be in ISO format and - seperated. The new date is put back into field.value.

bool isValidColor(widget)
returns true/false according to if the widget.value matches this regular expression: /^((#([A-F]|[0-9]){6})|transparent|inherit)( !important)?$/

bool isValidISODate(widget, seperator)
returns true/false according to if the specified widget contains a valid ISO Date using the specified seperator. The seperator must be one of - or /.

string formatDateNumber(value)
Makes sure that the specified value is 2 digits and is 0 prefixed, if < 10. returns the updated value.

bool fixupISODate(widget, seperator, year)
returns true if the date specified by the widget was already a valid ISO Date, or was able to be fixed. returns false if the date specified by the widget was not able to be turned into a valid ISO Date. seperator is used to determine what the year, month and day parts will be seperated by. year is for when the given date is only 2 parts, both with length <= 2, then we treat them as month and day and use the year to create the date from.

The updated ISO Date is put into widget.value.

void displayCalculatorHelp()
Pops up a window and outputs the calculator widgets help content into it.

void calculateFormula(field)
The user passes in the form item object. If the current value appears to be a valid formula, we first save the current value on the calculatorUndo array under the form items name, this allows for multiple calculator fields. We then eval the formula and put the result in the fields value.

A valid formula is made up of (), +, -, /, *, numbers and form field identifiers F{name} that are to be substituted with the value of the specified form item (in the same form as the specified field.

void calculateUndo(field)
pops the calculatorUndo array and replaces the fields value with the popped value. disables the Undo button once no more entries are available.

float processNumber(value)
takes the string to convert to a float. returns 0.00 if the value evaled to NaN, otherwise the float version of value.

bool validate_formula(field)
takes the form item to validate it's value as a formula. Makes sure that the formula is well balanced and that it doesn't reference itself as a Field to pull values from.

array parse_formula(formula)
builds up a result array with the following entries: [0] = The error string if an error occured, empty otherwise. [1] = the array of parsed tokens from the formula.

functions used by HTMLObject::Form select-picker code
 a = assigned hidden element
 u = unassigned hidden element
 aS = assigned Select box
 uS = unassigned Select box
 sep = seperator string
void htmlForm_assignOneEntry(a, u, aS, uS, sep)
moves over those selected items from the unassigned select box to the assigned select box.

calls htmlForm_updateEntries() to update the hidden form items that depict the new state of things.

void htmlForm_unAssignOneEntry(a, u, aS, uS, sep)
moves over those selected items from the assigned select box to the unassigned select box.

calls htmlForm_updateEntries() to update the hidden form items that depict the new state of things.

void htmlForm_assignAllEntries(a, u, aS, uS, sep)
moves all items from the unassigned select box to the assigned select box.

calls htmlForm_updateEntries() to update the hidden form items that depict the new state of things.

void htmlForm_unAssignAllEntries(a, u, aS, uS, sep)
moves all items from the assigned select box to the unassigned select box.

calls htmlForm_updateEntries() to update the hidden form items that depict the new state of things.

void htmlForm_updateEntries(a, u, aS, uS, sep)
walks the assigned and unassigned select boxes and builds up the strings to populate a and u with.

AUTHOR

James A. Pattie, htmlobject@pcxperience.com

SEE ALSO

perl(1), HTMLObject::Base(3), HTMLObject::FrameSet(3), HTMLObject::ReadCookie(3), HTMLObject::Form(3), HTMLObject::Widgets(3).