HTMLObject::Template(3)

void setBodyAttribute(name => value)
     Arguments: hash style html attributes.
     Ex: onblur => "do something", onclick => "something else"

     Builds up name="value" to append to the <body> tag when the
     document is displayed.  name must be a valid html attribute.

     Requires <BODYARGSTAG>.

void setBodyClass(class)
    See the HTMLObject::Base manpage for more details.

scalar getBodyClass()
    See the HTMLObject::Base manpage for more details.

void setBodyID(id)
    See the HTMLObject::Base manpage for more details.

scalar getBodyID()
    See the HTMLObject::Base manpage for more details.

void setBodyStyle(style)
    See the HTMLObject::Base manpage for more details.

scalar getBodyStyle()
    See the HTMLObject::Base manpage for more details.

void setBodyTitle(title)
    See the HTMLObject::Base manpage for more details.

scalar getBodyTitle()
    See the HTMLObject::Base manpage for more details.

NAME
HTMLObject::Template - Perl extension for HTMLObject.

SYNOPSIS
  use HTMLObject::Template;
  my $doc = HTMLObject::Template->new(file => "/var/www/html/templates/index.html");

  $doc->setTitle("Test of HTMLObject::Template");
  $doc->substitute(tag => "<BODYTAG>", value => <<"END_OF_BODY");
  <center>
  <h1>HTMLObject::Template</h1>
  <br />
  This is cool!
  END_OF_BODY

  $doc->setCookie(name => 'cookie name', value => 'This rocks!');

  $doc->javascriptPrint(<<"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(code => "helloWorld();");

  # Actually generate the entire document!
  $doc->display();

DESCRIPTION
HTMLObject::Template builds on the HTMLObject::Normal 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::Normal module are available for use in this module unless specified as being invalid.

Exported FUNCTIONS
  scalar new(file)
    Creates a new instance of the HTMLObject::Template document type.
    You must specify the file to work with.  It should be a complete
    path to the file or just the name if it is in the same directory.

  void display()
    This function generates the Template 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 you used print() then the tags
    that you specified content for will have their substitution done
    now.  This allows you to create content without having to store it
    yourself and then do a substitute before calling display().

  void startDisplaying()
    This function is not valid.

  void endDisplaying()
    This function is not valid.

  void setFocus(section) (scalar value)
    This function is not valid.

  void print(string) (scalar value)
    This function is not valid.  See javascriptPrint and substitute.

  void printTag(tag, value, mode)
    requires: tag
    optional: value, 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.

  void javascriptPrint(string) (scalar value)
    This function appends the value passed in into the javascript body.
    Requires <JAVASCRIPTTAG>.

  void substitute(tag, value, global)
    This function validates that the specified tag exists in the
    document and then substitutes it for the contents of value.
    If global is specified and equals 1, then the substitution is done
    globally instead of just replacing the first instance of the tag.

  scalar read()
    This function is not valid.

  scalar readTag(tag)
    requires: tag
    returns the string from tagBuffers identified by tag

  void delete()
    Deletes the contents of the currently specified section. This is only
    valid with "javascript".
    Requires <JAVASCRIPTTAG>.

  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.
    Requires <JAVASCRIPTTAG>.

  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.
    Requires <JAVASCRIPTTAG>.

  scalar getJavascriptVersion()
    This function returns the current JavaScript version that is set in
    javascriptVersion.
    Requires <JAVASCRIPTTAG>.

  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.
    Requires <JAVASCRIPTTAG>.

  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.
    Requires <JAVASCRIPTTAG>.

  scalar isJavascriptErrorHandlerEnabled()
    This function returns the value of the javascriptErrorHandler to
    see if it is enabled or disabled.
    Requires <JAVASCRIPTTAG>.

  void setJavascriptErrorHandlerEmail(email => '')
    This function will set the value of $javascriptErrorHandlerEmail
    to the value specified.  This is used in the generic JavaScript error
    handler.
    Requires <JAVASCRIPTTAG>.

  scalar getJavascriptErrorHandlerEmail()
    This function returns the email address that will be used by the
    builtin error handling code.
    Requires <JAVASCRIPTTAG>.

  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.
    Requires <JAVASCRIPTTAG>.

  scalar getJavascriptErrorHandlerPrgName()
    This function returns the name of the program that we are generating
    a JavaScript error handler for.
    Requires <JAVASCRIPTTAG>.

  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.
    Requires <JAVASCRIPTTAG>.

  scalar getJavascriptErrorHandlerPrgVersion()
    This function returns the version of the program that we are generating
    a JavaScript error handler for.
    Requires <JAVASCRIPTTAG>.

  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.
    Requires <JAVASCRIPTTAG>.

  void setJavascriptErrorHandlerWindow(name => '')
    This function will set the base window name to prepend to the
    window creation code used by the builtin error handler.
    Requires <JAVASCRIPTTAG>.

  scalar getJavascriptErrorHandlerWindow()
    This function returns the window name that will be used by the
    builtin error handler.
    Requires <JAVASCRIPTTAG>.

  void onload(replace => bool, code => '')
    Requires <JAVASCRIPTTAG> and <BODYJAVASCRIPTTAG>.

    Calls the onload() method in HTMLObject::Normal.

  void setOnload(replace => bool, code => '')
    Requires <JAVASCRIPTTAG> and <BODYJAVASCRIPTTAG>.

    Calls the setOnload() method in HTMLObject::Normal.

  void onunload(replace => bool, code => '')
    Requires <JAVASCRIPTTAG> and <BODYJAVASCRIPTTAG>.

    Calls the onunload() method in HTMLObject::Normal.

  void setOnunload(replace => bool, code => '')
    Requires <JAVASCRIPTTAG> and <BODYJAVASCRIPTTAG>.

    Calls the setOnunload() method in HTMLObject::Normal.

  void onbeforeunload(replace => bool, code => '')
    Requires <JAVASCRIPTTAG> and <BODYJAVASCRIPTTAG>.

    Calls the onbeoreunload() method in HTMLObject::Normal.

  void setOnbeforeunload(replace => bool, code => '')
    Requires <JAVASCRIPTTAG> and <BODYJAVASCRIPTTAG>.

    Calls the setOnbeforeunload() method in HTMLObject::Normal.

  void setBase(href => '', target => '')
    This function allows the user to specify the base url of the webpage
    or more importantly the default target that all links should point to
    if not explicitly specified. This is mainly used in web pages that
    are in a frameset. Modifies $baseHrefString, $baseTargetString.
    Requires <BASETAG>.

  void setLink(href => '', name => '', rel => '', rev => '',
               target => '', title => '')
    This function allows the user to specify a <link> tag item that is
    stored in the @linkTag array to be displayed in the <head> when the
    document is created. Modifies @linkTag.
    Requires <LINKTAG>.

  void setStyleEntry(tag => '', attributes => undef)
    requires: tag,
      attributes (ref to hash of name, value pairs to apply to this tag)
    This generates a CSS entry to specify the style for the tag you
    specified.  Requires <STYLESHEETTAG>.

  void setLinkDecorations(link => 'none', alink => 'none',
                          vlink => 'none', hover => '')
    This function allows the user to specify the decorations that the link,
    visited link, active link and hover link have.  If you specify nothing,
    then by default it turns off all decorations (no underline).  This
    generates a CSS section to specify the link decorations you desire.
    Requires <STYLESHEETTAG>.  (The tag changed from <LINKSTYLESHEETTAG>
    to <STYLESHEETTAG> in 2.06.)

  void setLanguageEncoding(language => 'en', encoding => 'iso-8859-1')
    Sets the language and encoding values to the specified values after
    validating that they exist and are valid together.
    Requires <LANGTAG>.

  scalar getLanguage()
    Returns the value of $language.
    Requires <LANGTAG>.

  scalar getLanguageName()
    Returns the name of the language we are using.
    Requires <LANGTAG>.

  scalar lookupLanguageName(code => 'en')
    Returns the name of the language code that is specified.  Defaults
    to looking up english if nothing specified.  Returns an empty string
    if the language code is not defined in our hash.
    Requires <LANGTAG>.

  scalar getCharEncoding()
    Returns the value of $charsetEncoding.
    Requires <LANGTAG>.

  (scalar or @ ref) lookupCharEncoding(code => 'en')
    Returns the array ref or string that represents the valid charset
    encodings that this language code supports.  Defaults to looking up
    english if nothing specified.
    Requires <LANGTAG>.

  void setTitle(title)  (scalar value)
    Uses the specified string to set the title with. Modifies
    $titleString.
    Requires <TITLETAG>.

  scalar getTitle()
    Returns $titleString.
    Requires <TITLETAG>.

  scalar getHeadString()
    Invalid now.

  scalar getBodyString()
    Invalid now.

  void setMetaTag('http-equiv' => '', content => '')
    Creates an entry in the meta_tags array that specifies the http-equiv
    and content values for the specified Meta tag to be created when
    display is called. Modifies @metaTags.
    Requires <METATAG>.

  void setBodyBgcolor(color)  (scalar value)
    This function sets the background color for the body. Modifies
    $bodyBgcolor.
    Requires <BODYARGSTAG>.

  scalar getBodyBgcolor()
    This function returns the background color for the body.
    Requires <BODYARGSTAG>.

  void setBodyFgcolor(color)  (scalar value)
    This function sets the text color for the body. Modifies
    $bodyFgcolor.
    Requires <BODYARGSTAG>.

  scalar getBodyFgcolor()
    This function returns the text color for the body.
    Requires <BODYARGSTAG>.

  void setBodyLinkColor(color)  (scalar value)
    This function sets the default link color for the body. Modifies
    $bodyLinkColor.
    Requires <BODYARGSTAG>.

  scalar getBodyLinkColor()
    This function returns the default link color for the body.
    Requires <BODYARGSTAG>.

  void setBodyVlinkColor(color)  (scalar value)
    This function sets the visited link color for the body. Modifies
    $bodyVlinkColor.
    Requires <BODYARGSTAG>.

  scalar getBodyVlinkColor()
    This function returns the visited link color for the body.
    Requires <BODYARGSTAG>.

  void setBodyAlinkColor(color)  (scalar value)
    This function sets the active link color for the body. Modifies
    $bodyAlinkColor.
    Requires <BODYARGSTAG>.

  scalar getBodyAlinkColor()
    This function returns the active link color for the body.
    Requires <BODYARGSTAG>.

  void setBodyImage(image)  (scalar value)
    This function sets the background image for the body. Modifies
    $bodyImage.
    Requires <BODYARGSTAG>.

AVAILABLE TAGS
  The tags that are available and what they do are as follows:
  (They can only be specified once.  The first instance is what will be
  substituted on by the HTMLObject display code.  If you define them
  but do not define anything that the HTMLObject would generate, the
  tag will be removed from the final document.)

  <DOCTYPE HTML|XHTML|FRAME|XFRAME> - Instructs the <!DOCTYPE ...> tag to be
                                created and is output at the top of your
                                document.  HTML will generate a normal
                                tag while FRAME will generate a tag
                                suitable for a FRAMESET.
                                XHTML and XFRAME generate the XHTML version
                                of HTML and FRAMESET DocTypes.
                                All generated DocTypes are transitional.
                                HTML = 4.01
                                XHTML = 1.0
  <LANGTAG>                   - This should be used in the <html> tag to
                                set the LANGUAGE of the document.
  <TITLETAG>                  - This should be put between
                                <title></title> to allow you to
                                dynamically change the title of the page.
  <METATAG>                   - This should be in the <head> of your
                                document and will be replaced with any
                                Meta Tags you defined via the HTMLObject.
  <BASETAG>                   - This should be in the <head> of your
                                document and will be replaced with the
                                Base Tag you defined via the HTMLObject.
  <LINKTAG>                   - This should be in the <head> of your
                                document and will be replaced with the
                                Link Tags you defined via the HTMLObject.
  <STYLESHEETTAG>             - This should be in the <head> of your
                                document and will be replaced with the
                                style sheet created.
  <JAVASCRIPTTAG>             - This should be in the <head> of your
                                document and will be replaced with all
                                javaScript code (error Handler, onLoad,
                                onUnLoad and any code you wrote via
                                javascriptPrint()).
  <BODYARGSTAG>               - This must be in your <body> tag and will
                                be replaced with the bgColor and link
                                tags that the HTMLObject defines or you
                                specified.
  <BODYJAVASCRIPTTAG>         - This must be in your <body> tag and will
                                be replaced with the code necessary to
                                do the onload, onunload and onbeforeunload
                                events if you defined them.

  You can define any other tag you want and use the substitute command to
  replace them anywhere in your document.

  See examples/template.cgi for a sample CGI script using this module.
  See examples/templates/index.html for a sample Template HTML file.

AUTHOR
James A. Pattie, htmlobject@pcxperience.com

SEE ALSO
perl(1), HTMLObject::Base(3), HTMLObject::Normal(3), HTMLObject::FrameSet(3), HTMLObject::ReadCookie(3), HTMLObject::Form(3).

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 995:
    '=item' outside of any '=over'

Around line 1320:
    You forgot a '=back' before '=head1'