NAME

       Jifty::Web::Form::Field - Web input of some sort

DESCRIPTION

       Describes a form input in a Jifty::Action.  "Jifty::Web::Form::Field"s know what action
       they are on, and acquire properties from the Jifty::Action which they are part of.  Each
       key in the "arguments" in Jifty::Action hash becomes a "Jifty::Web::Form::Field" whose
       "name" is that key.

       "Jifty::Web::Form::Field"s stringify using the "render" method, to aid in placing them in
       HTML::Mason components.

   new
       Creates a new Jifty::Web::Form::Field (possibly magically blessing into a subclass).
       Should only be called from "$action->arguments".

   $self->rebless($widget)
       Turn the current blessed class into the given widget class.

   accessors
       Lists the accessors that are able to be called from within a call to "new".  Subclasses
       should extend this list.

   name [VALUE]
       Gets or sets the name of the field.  This is separate from the name of the label (see
       "label") and the form input name (see "input_name"), though both default to this name.
       This name should match to a key in the "arguments" in Jifty::Action hash.  If this
       "Jifty::Web::Form::Field" was created via "form_field" in Jifty::Action, this is
       automatically set for you.

   class [VALUE]
       Gets or sets the CSS display class applied to the label and widget.

   type [VALUE]
       Gets or sets the type of the HTML <input> field -- that is, 'text' or 'password'.
       Defaults to 'text'.

   key_binding VALUE
       Sets this form field's "submit" key binding to VALUE.

   key_binding_label VALUE
       Sets this form field's key binding label to VALUE.  If none is specified the normal label
       is used.

   default_value [VALUE]
       Gets or sets the default value for the form.

   sticky_value [VALUE]
       Gets or sets the value for the form field that was submitted in the last action.

   mandatory [VALUE]
       A boolean indicating that the argument must be present when the user submits the form.

   focus [VALUE]
       If true, put focus on this form field when the page loads.

   ajax_validates [VALUE]
       A boolean value indicating if user input into an HTML form field for this argument should
       be validated via AJAX as the user fills out the form, instead of waiting until submit.
       Arguments will always be validated before the action is run, whether or not they also
       "ajax_validate".

   ajax_canonicalizes [VALUE]
       A boolean value indicating if user input into an HTML form field for this argument should
       be canonicalized via AJAX as the user fills out the form, instead of waiting until submit.
       Arguments will always be canonicalized before the action is run, whether or not they also
       "ajax_canonicalize"

   disable_autocomplete [VALUE]
       Gets or sets whether to disable _browser_ autocomplete for this field.

   preamble [VALUE]
       Gets or sets the preamble located in front of the field.

   multiple [VALUE]
       A boolean indicating that the field is multiple.  aka. has multiple attribute, which is
       useful for select field.

   id
       For the purposes of Jifty::Web::Form::Element, the unique id of this field is its input
       name.

   attributes
       If the field object is generated by Jifty::Action::Record, this holds the additional
       attributes declared to the corresponding column of the model.

   input_name [VALUE]
       Gets or sets the form field input name, as it is rendered in the HTML.  If we've been
       explicitly named, return that, otherwise return a name based on the moniker of the action
       and the name of the form.

   fallback_name
       Return the form field's fallback name. This should be used to create a hidden input with a
       value of 0 to accompany checkboxes or to let comboboxes fall back to the text input if,
       and only if no value is selected from the SELECT.  (We use this order, so that we can
       stick the label and not the value in the INPUT field. To make that work, we also need to
       clear the SELECT after the user types in the INPUT.

   label [VALUE]
       Gets or sets the label on the field.  This defaults to the name of the object.

   hints [VALUE]
       Hints for the user to explain this field

   element_id
       Returns a unique "id" attribute for this field based on the field name. This is consistent
       for the life of the Jifty::Web::Form::Field object but isn't predictable;

   action [VALUE]
       Gets or sets the Jifty::Action object that this "Jifty::Web::Form::Field" is associated
       with.  This is called automatically if this "Jifty::Action" was created via "form_field"
       in Jifty::Web::Form::Field.

   current_value
       Gets the current value we should be using for this form field.

       If the argument is marked as "sticky" (default) and there is a value for this field from a
       previous action submit AND that action did not have a "success" response, returns that
       submit field's value. Otherwise, returns the action's argument's default_value for this
       field.

   render
       Outputs this form element in a span with class "form_field".  This outputs the label, the
       widget itself, any hints, any errors, and any warnings using "render_label",
       "render_widget", "render_hints", "render_errors", and "render_warnings", respectively.
       Returns an empty string.

       This is also what "Jifty::Web::Form::Field"s do when stringified.

   render_inline_javascript
       Render a <script> tag (if necessary) containing any inline javascript that should follow
       this form field. This is used to add an autocompleter, placeholder, keybinding, or
       preloading to form fields where needed.

   render_preload_javascript
       Render a <script> tag (if necessary) containing any inline preload javascript that should
       follow this form field.

   classes
       Renders a default CSS class for each part of our widget.

   render_wrapper_start
       Output the start of div that wraps the form field

   render_wrapper_end
       Output the div that wraps the form field

   render_preamble
       Outputs the preamble of this form field, using a <span> HTML element with CSS class
       "preamble" and whatever "class" specifies.  Returns an empty string.

       Use this for sticking instructions right in front of a widget

   render_label
       Outputs the label of this form field, using a <label> HTML element with the CSS class
       "label" and whatever "class" specifies.  Returns an empty string.

   render_widget
       Outputs the actual entry widget for this form element.  This defaults to an <input>
       element, though subclasses commonly override this.  Returns an empty string.

   canonicalize_value
       Called when a value is about to be displayed. Can be overridden to, for example, display
       only the "YYYY-MM-DD" portion of a DateTime.

   other_widget_properties
       If your widget subclass has other properties it wants to insert into the html of the main
       widget and you haven't subclassed render_widget then you can just subclass this.

       If you have subclassed render_widget then just stick them in your local sub render_widget.

       We use this for marking password fields as not-autocomplete so the browser does not try to
       use its form autocompletion on them.

   _widget_class
       Returns the "class=" line for our widget. Optionally takes extra classes to append to our
       list.

   render_value
       Renders a "view" version of the widget for field. Usually, this is just plain text.

   render_autocomplete
       Renders the div tag and javascript necessary to do autocompletion for this form field.
       Deprecated internally in favor of "autocomplete_javascript", but kept for backwards
       compatibility since there exists external code that uses it.

   autocomplete_javascript
       Returns renders the tiny snippet of javascript to make an autocomplete call, if necessary.

   placeholder_javascript
       Returns the javascript necessary to insert a placeholder into this form field (greyed-out
       text that is written in using javascript, and vanishes when the user focuses the field).

   focus_javascript
       Returns the javascript necessary to focus this form field on page load, if necessary.

   preload_javascript
       Returns the javascript necessary to load regions that have been marked for preloading, as
       plain javascript. The "javascript" method will look for regions marked with preloading and
       swap them in, instead of loading them directly.

   render_hints
       Renders any hints for using this input.  Defaults to nothing, though subclasses commonly
       override this.  Returns an empty string.

   render_errors
       Outputs a <div> with any errors for this action, even if there are none -- AJAX could fill
       it in.

   render_warnings
       Outputs a <div> with any warnings for this action, even if there are none -- AJAX could
       fill it in.

   render_canonicalization_notes
       Outputs a <div> with any canonicalization notes for this action, even if there are none --
       AJAX could fill it in.

   available_values
       Returns the available values for this field.

   length
       # Deprecated API