HTMLObject::Widgets(3)

NAME
HTMLObject::Widgets - HTML Widgets for HTMLObject users.

SYNOPSIS
  use HTMLObject::Widgets;
  my $widgets = HTMLObject::Widgets->new();

  $doc->print($widgets->generatePickerCode());  # fill in the parameters to the picker code.

DESCRIPTION
HTMLObject::Widgets provides a centralized module for all the extra methods that do non-standard html.

For example, the Date and Color pickers.

Exported FUNCTIONS

ref new()
      instantiates the object.

bool isValid()
     returns 1 if everything is ok, 0 otherwise.

hash generatePickerCode(type, baseUrl, phrase, width, height, form, itemName, itemValue, windowName, onClick, onChange, link, class, linkClass, year, seperator, displayPrevNextDateLinks, style)
     This is called from HTMLObject::Form->generate() for -Type = date-picker, datePicker, colorPicker or color-picker.

     Returns the HTML fragment needed to display the phrase as a link
     that allows the user to select a color or date and display their
     selection in the edit field to the right of the link and the
     javascript code to Include the necessary javascript library.

     If an error occured, we return undef and set the error string, so use
     $obj->error() to determine if an error happened and then
     $obj->errorMessage to get the message to display.

     The returned hash has the body and javascriptIncludes entries
     defined so you can just pass the hash to the print() method
     or extract the code yourself.

     For developers needing to get the link/Phrase part seperate
     from the input field definition, use the _link_ and _input_
     entries in the returned hash to get this information.

     requires:
      type: 'color', 'date'
      baseUrl: The url of the server, minus the /htmlobject part, that
        the /htmlobject directory exists at.  Can be empty to indicate
        the current server.
      form: name of the form we are currently in.
      itemName: name of the text field we are creating.
      windowName: name of the window we are going to create.
      phrase:  the string to display.

     optional:
      onClick:  specify any JavaScript code you need executed when the
                link is selected.  This is only valid when link = true.
      onChange: specify any JavaScript code you want executed when the
                edit field is modified. This will only be run if the
                validation code we output returned true to indicate
                you have a valid color or date specified.
      width: defaults to 640
      height: defaults to 410
      itemValue: the value to display in the text field.  defaults to "".
      link: true (1) - display the phrase as a link, false (0) - don't
        make it a link.
      class: specify the CSS class you want applied to the phrase and
        input text box.
      style: specify the CSS style you want applied to the phrase and
        input text box.
      linkClass: specify the CSS class the link is part of.
      year: only valid when type = 'date'.  Specifies the year to default
            to if the user doesn't specify the year when entering the
            date.
      seperator: only valid when type = 'date'.  Specifies the date
                 seperator to work with.  Defaults to '-'.
      displayPrevNextDateLinks: true (1) - display the Prev/Next links,
        false (0) - don't display the Prev/Next links.  Defaults to
        true (1).

      Notes: when displaying a date picker, 2 extra links are now
      output around the text box, if displayPrevNextDateLinks is true.
      They are < and >, to allow you to quickly change the current date 1
      day backwards or forwards.  The output will look like:
      Date < [text box] >, if phrase = "Date".

% generatePopulator(name, rows, required, options, manual, optionsTypes, customLabel, htmlTemplate, selectLocation, clearPhrase, tableClass, tableStyle, selectClass, selectStyle, debugLevel, numSelectRows, displayColumnHeaders, columnHeaders, displayLabels, -ReadOnly, -ReadOnlyMode, -ReadOnlyArgs, -ReadOnlyDisplayType)
     This is called from HTMLObject::Form->generate() for -Type = populator.

     required:
       name - name of the "populator" widget.  This is the prefix
         value that all generated form items will start with.
       rows - how many rows need to be generated.  Defaults to 1.
       required - how many rows are required to be filled in by the user.
         Defaults to 1.
       options - -Options array as provided to the
         HTMLObject::Form->generate() method.  Used to determine how many
         form items per row to generate.

         Each entry is a hash with the following values:
           label - value to display in the select box for this entry.
           data - array ref of column entries.

         All entries must have the same number of elements in their
         data array.
       manual - (boolean) if true (1), then we just generate the necessary
         javascript since the caller MUST have populated the template,
         profile and data hashes.  if false (0), then we generate the html
         template snippet, profile and data structures and the necessary
         javascript.

     optional:
       optionsTypes - array of hashes that defines what each columns form
         field is to be.  If specified as a string equal to:
           text - all form items are text fields
           datePicker - all form items are date pickers
           colorPicker - all form items are color pickers
         If not specified, it defaults to "text".
         If you provide the array of hashes, the hashes must be valid
         data structures that the HTMLObject::Form->generate() would
         accept as part of its data hash.  You do not need to define the
         name of the form item (as in the data hash you would pass to
         generate()), just the attributes for the form item, like
         -Type, -Label, -Value, etc.
         If you specify -Type => "searchBox", do not specify the hidden
         field support or use an associative array, as the code does not
         currently support this.
       customLabel - if optionsTypes is one of our special cases:
         text, datePicker, colorPicker
         then you can specify customLabel to provide the label for each
         form item generated, since they are all going to be the same.
         Defaults to "".
       htmlTemplate - user defined html snippet that represents the users
         layout for a row.  If defined and manual = 0, we use it for each
         generated row substituting the field_x_y (where y >= 0 and < the
         number of columns to be generated) values with the form names
         being generated.  The template should only define <td> cells
         and not the parent <tr> cell.
         Ex:
         htmlTemplate = "<td>#LRFI=field_x_0#</td><td>#LRFI=field_x_1#</td>"
         where we will substitute field_x_ with the field name and the
         row number we are currently processing when we generate the html.
       selectLocation - left or right.  specifies if the select box should
         be to the left of the rows or to the right.  Defaults to 'right'.
       clearPhrase - phrase to use for the Clear Row buttons.  Defaults to
         'clear'.
       tableClass - class to apply to the outer table.  Defaults to ''.
       tableStyle - style to apply to the outer table.  Defaults to ''.
       selectClass - class to apply to the select box.  Defaults to ''.
       selectStyle - style to apply to the select box.  Defaults to ''.
       debugLevel - indicate how much debug info you want the javascript
         code to generate.  Defaults to 0.
         Levels are:
           0 = none
           1 = show strings to be evaluated
           2 = show results of the evaluted strings
       numSelectRows - number of rows the select box should show.
         Minimum amount allowed is 5. Defaults to 10.
       displayColumnHeaders - boolean.  If 1 (true), then we generate
         a header row displaying the label for each column.  Defaults
         to 1 (true).
       columnHeaders - array of custom labels for each column.  If
         displayColumnHeaders is true and you do not want the label
         from the row to be displayed as the column header, then use
         this to specify each columns header label.
       displayLabels - boolean.  If 1 (true), then we output the
         html template tag to cause the -Label to be generated.
         Defaults to 0 (false), since the displayColumnHeaders is
         turned on by default.  If the entry is a date-picker or
         color-picker, the label will still be displayed so that
         the user can have the popup to select a date or color.
         If customLabel is defined, then it will be used instead.

       The following entries are passed into the generated form items, so
         that the developer can generate a read-only version of the
         populator widget.

       -ReadOnly - boolean.
       -ReadOnlyMode - (DOM or text)
       -ReadOnlyArgs - string
       -ReadOnlyDisplayType - (both, name or value)

     returns:
       hash with the following entries:
         html - generated html hash (contains javascript, body, onsubmit, link).
           body  - html template replacement for the generate() method.
           javascript - the javascript code needed for this widget to work.
           onsubmit - the onsubmit code to be added to the form.
             The form that outputs this widget must take care to add the
             onsubmit string to it's own onsubmit string.  By default,
             the onsubmit handler generated, only returns false if the
             validation method it calls fails.  Otherwise, it falls
             through which will cause the form to submit.
           link - string specifying a <link> tag to pull in an external
             css stylesheet.
         data - generated data hash that will be used by the generate()
           method to actually create the necessary form items
         profile - generated profile hash to specify what form items are
           required and/or how to validate them if there are special
           validation checks needed.
         order - array of form items in the order they should be processed,
           suitable for inclusion in the order array passed to the
           generate() method.

     summary:

     The generatePopulator() method will output a complex form selection
     widget that uses a select box to determine the values to populate the
     next available row.  The rows will be all the same, but there is no
     requirement that the columns have to be all the same.  You can specify
     a very complex input screen by defining the optionsTypes array.

     The generated html will consist of a table that takes up 100% of the
     available space.  It will be split into 2 columns, with the select box
     in the left or right column, based upon the selectLocation parameter.
     The other column will have a child table defined and for each generated
     row of form items, we wrap the htmlTemplate in the <tr></tr> tags.
     If htmlTemplate is not specified, then each form item is defined as:
       <td align="right" valign="top">#RL=field_x_y#</td>
       <td align="left">#FI=field_x_y#</td>

     where field_x_y means:
       field = name
       x = row #, starting at 0
       y = column #, starting at 0

     The generated javascript will store the options in a javascript array
     of objects with values = col0, col1, col2, etc. allowing quick and
     easy lookup and assignment.  The select box, will only have the label
     to be displayed for each selection.  The selectedIndex value will be
     used to index into the javascript array to determine the data to
     populate.  This way we don't have to do string splitting, etc., which
     is expensive and can have issues if the user wants to use our seperator
     value in their data.

     The javascript will attempt to find an empty row and populate it.  If
     no empty rows are found, then it will popup an alert and inform the
     user of this condition.

     On submission, if required > 0, then the javascript will first attempt
     to make sure that at least required rows were populated and then will
     make sure that required rows starting at index 0 and incrementing by
     1 are populated to meet the FormValidator requirements as specified
     by the profile.

     Sample usage for specifying in the HTMLObject::Form data hash:

      data{foo}->{bar} = { -Type => "populator", -Rows => 4, -Required => 1,
        -Options => \%selectOptions, manual => 0,
        -OptionsTypes => "datePicker", -SelectLocation => "left" };

% generateSearchBox(form, name, label, class, data, shareData, isSorted, isAA, displayEmpty, displayHelp, onblur, onfocus)
     This is called from HTMLObject::Form->generate() for -Type = searchBox.

     requires:
       form - name of the form we are working with.
       name - name of the input field we are creating.
       label - string to display as the label for the input field.
         Defaults to ''.
       class - string to use to specify the class the label and
         input field should be part of.  Defaults to ''.
       isSorted - boolean. 1 (true) means the data should be
         sorted, 0 (false) means it is not sorted.
         Defaults to 0 (false).
       displayEmpty - boolean.  1 (true) means to display all
         available options when the input field is empty,
         else nothing is displayed.
         Defaults to 1 (true).
       displayHelp - boolean.  1 (true) generates a help link
         and allows the widget to process the user interaction
         with the help system.
         Defaults to 1 (true).
       onblur - string of code to be run when the focus is
         moving to another form item for real.
         Defaults to ''.
       onfocus - string of code to be run when the form item gets
         initial focus.  Defaults to ''.

     optional:
       data - array of values to let the user work with or hash
         of values where the key is displayed to the user and
         the keys value is set in the form item.  Defaults to undef.
       shareData - name of the javascript array to use.  If specified,
         then data will be ignored.  Defaults to ''.
       isAA - boolean.  1 (true) means the shareData javascript array
         is an associative array.  0 (false) means it is a normal array.
         Only valid if shareData is specified.  Defaults to 0.

     You must specify one of data or shareData.

     returns:
       hash with following entries (html, data, profile):
         html is a hash with (body, javascript, onload, javascriptIncludes)
           body - html template replacement for the generate() method.
             The #LFI=x# where x = -name will be replaced with this
             string, to allow for generating the hidden form item
             when -data is a hash.  The output will be either
             #LFI=x# or #F=x##LFI=y#, where x = -name and
             y = -name + 'Display'.
           javascript - javascript code needed for this widget to work.
           onload - javascript code needed to initialize the widget.
           javascriptIncludes - points to the search-methods.js library.
         data - generated data hash that will be used by the generate()
           method to actually create the necessary form items.  This will
           just specify the -Type and name, etc. of the form items.
           It will be upto the caller to add any extra things like
           size, disabled, etc.  Do not specify an onfocus or onblur
           handler directly on the resulting form item, otherwise they
           will not be processed.

     summary:
       This method will take the data you specified and setup the necessary
       javascript data structures to allow the searchBox code to do its
       thing.

       If you specified a hash for data, then 2 form items will be
       generated.  The item you named will be created as a hidden input
       field.  A text input field will then be created named
       name + 'Display', where name is the value you specified.  This
       input field will be what the searchBox uses to interact with the
       user and the hidden field is what the users end selection will be
       placed in.  The profile will only require the hidden field to be
       specified.  If you specify isSorted = 1 (true), then the
       javascript code will sort the keys after creating an array from
       them, otherwise your data is left in the order it is processed.

       If you specified an array for data, then only an input field will
       be created and no extra work will need to be done.  The input the
       user selected/typed will be what is returned to the server.

AUTHOR
James A. Pattie, htmlobject@pcxperience.com

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