NAME

       Jifty::Web::Form::Element - Some item that can be rendered in a form

DESCRIPTION

       Describes any HTML element that might live in a form, and thus might have javascript on it.

       Handlers are placed on Jifty::Web::Form::Element objects by calling the name of the javascript event
       handler, such as "onclick" or "onchange", with a set of arguments.

       The format of the arguments passed to "onclick" (or any similar method) is a string, a hash reference, or
       a reference to an array of multiple hash references.  Strings are inserted verbatim.

       Hash references can take a number of possible keys.  The most important is the mode of the fragment
       replacement, if any; it is specified by providing at most one of the following keys:

       append => PATH
           Add the given "PATH" as a new fragment, just before the close of the CSS selector given by "element",
           which defaults to the end of the current region.

       prepend => PATH
           Add  the given "PATH" as a new fragment, just after the start of the CSS selector given by "element",
           which defaults to the start of the current region.

       popout => PATH
           Displays the given "PATH" as a new fragment in a lightbox-style popout.

       replace_with => PATH
           Replaces the region specified by the "region" parameter (which defaults to the current  region)  with
           the fragment located at the given "PATH".  If "undef" is passed as the "PATH", acts like a "delete".

       refresh => REGION
           Refreshes the given "REGION", which should be a Jifty::Web::PageRegion object, or the fully qualified
           name of such.

       refresh_self => 1
           Refreshes  the  current region; this is the default action, if a non-empty "args" is supplied, but no
           other mode is given.

       delete => REGION
           Removes the given "REGION" from the page, permanently.

       The following options are also supported:

       toggle => BOOLEAN
           If set to true, then the link will possibly toggle the region to empty, if the region's current  path
           is the same as the path the region is trying to be set to.

       region => REGION
           The region that should be updated.  This defaults to the current region.

       element => CSS SELECTOR
           A  css  selector  specifying where the new region should be placed; used with "append" and "prepend",
           above.  The "get_element" in Jifty::Web::PageRegion method may be useful in  specifying  elements  of
           parent page regions.

       submit => MONIKER
           A Jifty::Action, Jifty::Action moniker, hashref of
               { action => Jifty::Action::Subclass,
                arguments => { argument => value, argument2 => value2 }

           or an arrayref of them.

           These  actions are submitted when the event is fired. Any arguments specified will override arguments
           submitted by form field.

           If you explicitly pass "undef",  then  all  actions  will  be  submitted.   This  can  be  useful  in
           conjunction  with  an "onclick" handler, since declaring an "onclick" handler intentionally turns off
           action submission.

       disable => BOOLEAN
           If true, disable all form fields associated with  the  actions  in  "submit"  when  this  Element  is
           clicked. This serves to give immediate visual indication that the request is being processed, as well
           as to prevent double-submits.

           Defaults to true.

       args => HASHREF
           Arguments  to  the region.  These will override the arguments to the region that the region was given
           when it was last rendered.

       effect => STRING
           The Scriptaculous or jQuery visual effect to use when updating or creating the fragment.

       effect_args => HASHREF
           A hashref of arguments to pass to the effect when it is created.  These can be  used  to  change  the
           duration of the effect, for instance.

       remove_effect => STRING
           As "effect", but for when the previous version of the region is removed.

       remove_effect_args => HASHREF
           As "effect_args", but for "remove_effect".

       beforeclick => STRING
           String contains some Javascript code to be used before a click.

       confirm => STRING
           Prompt  the user with a Javascript confirm dialog with the given text before carrying out the rest of
           the handlers. If the user cancels, do nothing, otherwise proceed as normal.

           TODO: This does not have a non-Javascript fallback method yet.

   handlers
       The following handlers are supported:

       onclick onchange ondblclick onmousedown  onmouseup  onmouseover  onmousemove  onmouseout  onfocus  onblur
       onkeypress onkeydown onkeyup onselect

       NOTE: onload, onunload, onsubmit and onreset are not yet supported

       WARNING:  if you use the onclick handler, make sure that your javascript is "return (function name);", or
       you may well get a very strange-looking error from your browser.

   accessors
       Any descendant of Jifty::Web::Form::Element should be able to accept any of the event handlers (above) as
       one of the keys to its "new" parameter hash.

   new PARAMHASH OVERRIDE
       Create a new "Jifty::Web::Form::Element" object blessed with PARAMHASH, and set with  accessors  for  the
       hash values in OVERRIDE.

   onclick
       The  onclick  event occurs when the pointing device button is clicked over an element. This attribute may
       be used with most elements.

   onchange
       The onchange event occurs when a control loses the input focus and its  value  has  been  modified  since
       gaining focus. This handler can be used with all form elements.

   ondblclick
       The  ondblclick  event  occurs  when  the pointing device button is double clicked over an element.  This
       handler can be used with all form elements.

   onmousedown
       The onmousedown event occurs when the pointing device button is pressed over an  element.   This  handler
       can be used with all form elements.

   onmouseup
       The onmouseup event occurs when the pointing device button is released over an element.  This handler can
       be used with all form elements.

   onmouseover
       The onmouseover event occurs when the pointing device is moved onto an element.  This handler can be used
       with all form elements.

   onmousemove
       The onmousemove event occurs when the pointing device is moved while it is over an element.  This handler
       can be used with all form elements.

   onmouseout
       The  onmouseout event occurs when the pointing device is moved away from an element.  This handler can be
       used with all form elements.

   onfocus
       The onfocus event occurs when an element receives focus either by  the  pointing  device  or  by  tabbing
       navigation.  This handler can be used with all form elements.

   onblur
       The  onblur  event  occurs  when  an  element  loses  focus  either  by the pointing device or by tabbing
       navigation.  This handler can be used with all form elements.

   onkeypress
       The onkeypress event occurs when a key is pressed and released over an element.  This handler can be used
       with all form elements.

   onkeydown
       The onkeydown event occurs when a key is pressed down over an element.  This handler can be used with all
       form elements.

   onkeyup
       The onkeyup event occurs when a key is released over an element.  This handler can be used with all  form
       elements.

   onselect
       The onselect event occurs when a user selects some text in a text field.  This attribute may be used with
       the text and textarea fields.

   _handler_setup
       This method is used by all handlers to normalize all arguments.

   handlers_used
       Returns the names of javascript handlers which exist for this element.

   javascript
       Returns the javascript necessary to make the events happen, as a string of HTML attributes.

   javascript_attrs
       Returns the javascript necessary to make the events happen, as a hash of attribute-name and value.

   javascript_preempt
       Returns  true  if  the  the  javascript's handlers should prevent the web browser's standard effects from
       happening; that is, for "onclick", it prevents buttons from submitting and the like.  The default  is  to
       return true, but this can be overridden.

   class
       Sets the CSS class that the element will display as

   title
       Sets the title that the element will display, e.g. for tooltips

   key_binding
       Sets the key binding associated with this element

   key_binding_label
       Sets  the  key binding label associated with this element (if none is specified, the normal label is used
       instead)

   id
       Subclasses must override this to provide each element with a unique id.

   label
       Sets the label of the element.  This will be used for the key binding legend if key_binding_label is  not
       set.

   key_binding_javascript
       Returns the javascript fragment to add key binding for this input, if one exists.

   render_key_binding
       Renders the javascript from "key_binding_javscript" in a <script> tag, if needed.

   handler_allowed HANDLER_NAME
       Returns 1 if the handler (e.g. onclick) is allowed.  Undef otherwise.

       The set defined here represents the typical handlers that are permitted.  Derived classes should override
       if they stray from the norm.

       By default we allow:

       onchange  onclick  ondblclick  onmousedown  onmouseup  onmouseover  onmousemove onmouseout onfocus onblur
       onkeypress onkeydown onkeyup

perl v5.14.2                                       2011-04-25                     Jifty::Web::Form::Element(3pm)