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)
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