GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  HTML::FORMFU::ROLE::ELEMENT::FIELD (3)

.ds Aq ’

NAME

HTML::FormFu::Role::Element::Field - Role for all form-field elements

CONTENTS

DESCRIPTION

Base-class for all form-field elements.

METHODS

    default

Set the form-field’s default value.

Is an output accessor.

    value

For most fields, value is an alias for default.

For the HTML::FormFu::Element::Checkbox and HTML::FormFu::Element::Radio elements, value sets what the value of the field will be if it is checked or selected. If the default is the same as the value, then the field will be checked or selected when rendered.

For the HTML::FormFu::Element::Radiogroup and HTML::FormFu::Element::Select elements, the value is ignored: values or options provides the equivalent function.

Is an output accessor.

    non_param

Arguments: bool

Default Value: false

If true, values for this field are never returned by params in HTML::FormFu, param in HTML::FormFu and valid in HTML::FormFu.

This is useful for Submit buttons, when you only use its value as an indicator

    placeholder

Sets the HTML5 attribute placeholder to the specified value.

Is an output accessor.

    javascript

Arguments: [$javascript]

If set, the contents will be rendered within a script tag, within the field’s container.

    retain_default

If retain_default is true and the form was submitted, but the field didn’t have a value submitted, then when the form is redisplayed to the user the field will have its value set to its default value, rather than the usual behaviour of having an empty value.

Default Value: false

    force_default

If force_default is true and the form was submitted, and the field has a default/value set, then when the form is redisplayed to the user the field will have its value set to its default value.

If the default value is being changed after FormFu->process is being called the later default value is respected for rendering, *but* nevertheless the input value doesn’t respect that, it will remain the first value.

Default Value: false

    default_empty_value

Designed for use by Checkbox fields. Normally if a checkbox is not checked, no value is submitted for that field. If default_empty_value is true, the Checkbox field is given an empty value during process. Please note that, with this setting, the checkbox gets an EMPTY value (as opposed to no value at all without enabling it), NOT the default value assigned to the element (if any).

Default Value: false

    repeatable_count

Only available for fields attached to a Repeatable element, after $repeatable->repeat($count) has been called.

The value is inherited from repeatable_count in HTML::FormFu::Element::Repeatable.

    clone

See clone in HTML::FormFu for details.

    deflators

See deflators in HTML::FormFu for details.

    deflator

See deflator in HTML::FormFu for details.

    auto_datalist_id

Arguments: [$string]

If any Input element had a datalist, but does not have datalist_id in HTML::FormFu::Role::Element::Input set, auto_datalist_id is used to generate the datalist id.

The following character substitution will be performed: %f will be replaced by $form->id, %n will be replaced by $field->name, %r will be replaced by $block->repeatable_count.

Is an inheriting accessor.

FORM LOGIC AND VALIDATION

    filters

See filters in HTML::FormFu for details.

    filter

See filter in HTML::FormFu for details.

    constraints

See constraints in HTML::FormFu for details.

    constraint

See constraint in HTML::FormFu for details.

    inflators

See inflators in HTML::FormFu for details.

    inflator

See inflator in HTML::FormFu for details.

    validators

See validators in HTML::FormFu for details.

    validator

See validator in HTML::FormFu for details.

    transformers

See transformers in HTML::FormFu for details.

    transformer

See transformer in HTML::FormFu for details.

CUSTOMIZING GENERATED MARKUP

Each field is, by default, wrapped in a container. Each container may also contain a label, a comment, and after an invalid submission may contain 1 or more error messages.

Example of generated form:



    1   <form action="" method="post">
    2       <div class="has-errors">    # container
    3           <ul class="errors">     # error container
    4               <li>                # error message
    5                   This field must contain an email address
    6               </li>
    7           </li>
    8           <label>Foo</label>      # label
    9           <input name="foo" type="text" value="example.com" />
    10          <span class="comment">  # comment
    11              This is Foo
    12          </span>
    13      </div>
    14  </form>

    # Line 2 starts the container - by default a DIV.
    # Line 2 starts an error container, which may contain 1 or more error
             messages - in this case, a unordered list (UL).
    # Line 4 starts a single error message - in this case, a list item (LI).
    # Line 8 shows a label.
    # Line 9 shows the fields input tag.
    # Lines 10 starts a comment.



To re-order the various parts of each form (label, input, errors, etc) and arbitrary extra tags, see the layout method.

    CONTAINER

container_tag

Default value: ’div’

The container wrapping each entire field, any label, comment, and errors.

container_attributes

Attributes added to the container tag.

Is an attribute accessor.

auto_container_class

Default Value: ’%t’

If set, then the container of each field will be given a class-name based on the given pattern.

Supports substitutions: %f, %n, %t.

Is an inheriting accessor.

auto_container_label_class

Default Value: ’label’

If set, and if the field has a label, the container will be given a class-name based on the given pattern.

Supports substitutions: %f, %n, %t.

Is an inheriting accessor.

auto_container_comment_class

Default Value: ’%t’

If set, and if the field has a comment, the container will be given a class-name based on the given pattern.

Supports substitutions: %f, %n, %t.

Is an inheriting accessor.

auto_container_error_class

Default Value: ’error’

If set, then the container of each field with an error will be given a class-name based on the given pattern.

Supports substitutions: %f, %n.

Is an inheriting accessor.

auto_container_per_error_class

Default Value: ’error_%s_%t’

If set, then the container of each field with an error will be given a class-name based on the given pattern.

Supports substitutions: %f, %n, %t, %s.

Is an inheriting accessor.

    FORM FIELD

auto_id

If set, then the field will be given an id attribute, if it doesn’t have one already.

E.g., setting $form->auto_id(%n) will make each field have an ID the same as the field’s name. This makes our form config simpler, and ensures we don’t need to manually update IDs if any field names are changed.

Supports substitutions: %f, %n, %r.

Is an inheriting accessor.

    LABEL

label

Set a label to communicate the purpose of the form-field to the user.

Is an output accessor.

auto_label

If label isn’t already set, the value of auto_label is passed through localize to generate a label.

Supports substitutions: %f, %n.

The generated string will be passed to localize to create the label.

Is an inheriting accessor.

label_tag

Default value: ’label’ (except Checkboxgroup)

Default value: ’legend’ (only Checkboxgroup)

Set which tag is used to wrap a label.

Is an inheriting accessor.

label_attributes

Attributes added to the label container.

Is an attribute accessor.

    COMMENT

comment

Set a comment to be displayed along with the form-field.

Is an output accessor.

comment_attributes

Attributes added to the comment container.

Is an attribute accessor.

auto_comment_class

Default Value: ’%t’

If set, and if the field has a comment, the comment tag will be given a class-name based on the given pattern.

Supports substitutions: %f, %n, %t.

Is an inheriting accessor.

    ERROR CONTAINER

error_container_tag

If set, and if the field has any errors, a container of this type is wrapped around all of the field error messages.



    # Example - this would wrap each individual error in a li tag,
    # with a single ul tag wrapped around all the errors.
   
    element:
      name: foo
      error_container_tag: ul
      error_tag: li



Is an inheriting accessor.

auto_error_container_class

Add a class-name to the error container.

Supports substitutions: %f, %n.

Is an inheriting accessor.

auto_error_container_per_error_class

Add a class-name to the error container for each error on that field.

Supports substitutions: %f, %n, %t, %s.

Is an inheriting accessor.

    ERROR MESSAGES

error_tag

Default value: ’span’

Sets the tag used to wrap each individual error message.

Defaults to span.

Is an inheriting accessor.

auto_error_message

Default Value: ’form_%s_%t’

If set, then each error will be given an auto-generated message, if it doesn’t have one already.

The generated string will be passed to localize to create the message.

For example, a Required constraint will return the string form_constraint_required. Under the default localization behaviour, the appropriate message for form_constraint_required will be used from the default I18N package.

Supports substitutions: %f, %n, %t, %s.

Is an inheriting accessor.

error_attributes

Set attributes on the tag of each error message.

Is an attribute accessor.

auto_error_class

Default Value: ’error_%s_%t’

Add a class-name to the tag of each error message.

Supports substitutions: %f, %n, %t, %s.

Is an inheriting accessor.

    PROCESSOR CLASSES

auto_constraint_class

Add a class-name to the container tag, for each constraint added to the field.

Supports substitutions: %f, %n, %t.

Is an inheriting accessor.

auto_inflator_class

Add a class-name to the container tag, for each inflator added to the field.

Supports substitutions: %f, %n, %t.

Is an inheriting accessor.

auto_validator_class

Add a class-name to the container tag, for each validator added to the field.

Supports substitutions: %f, %n, %t.

Is an inheriting accessor.

auto_transformer_class

Add a class-name to the container tag, for each transformer added to the field.

Supports substitutions: %f, %n, %t.

Is an inheriting accessor.

    REORDERING FIELD COMPONENTS

    layout

Specify the order that each sub-part of the element should appear in the rendered markup.



    # Default Value
    $element->layout( [
        errors,
        label,
        field,
        comment,
        javascript,
    ] );



Example: Move the form field (the input tag or equivalent) inside the label tag, after the label text. Remove the comment - this will now never be rendered.



    # YAML config
    layout:
      - errors
      - label:
          - label_text
          - field
      - javascript
   
    # prettified example of rendered markup
    <div>
        <span>This field is required.</span>
        <label>
            Foo
            <input name="foo" type="text" />
        </label>
    </div>



Example: Don’t wrap the label text inside it’s usual tag. Insert the form field (the input tag or equivalent) inside an arbitrary extra tag.



    # YAML config
    layout:
      - errors
      - label_text
      -
        div:
          attributes:
            class: xxx
          content: field
      - comment
      - javascript
   
    # prettified example of rendered markup
    <div>
        <span>This field is required.</span>
        Foo
        <div class="xxx">
            <input name="foo" type="text" />
        </div>
    </div>



The following elements override the default layout value:
HTML::FormFu::Element::Checkboxgroup
HTML::FormFu::Element::Hidden
Specification

The layout method accepts an array-ref, hash-ref, or string argument.

The processing is recursive, so each item in an array-ref may be any value accepted by the layout method.

A hash-ref must contain a single key and value pair. If the hash key is the string label, it creates a label tag, using any previously defined LABEL customizations. This allows the label tag to contains other elements, such as the form field.

All other hash key values are asssumed to be an arbitrary block tag name. The value must be a hash-ref, and may contain one or both attributes or content keys.

Any attributes value must be a hash-ref, whose key/values are added to the block tag. No processing or expansion is done to the attributes hash-ref at all.

The content value may be anything accepted by the layout method.

The following strings are accepted:
errors Renders the element error messages.

See ERROR CONTAINER and ERROR MESSAGES to customize the tags and attributes.

label Renders the element label.

See LABEL to customize the tag and attributes.

label_text Renders the element label text, without the usual label_tag.
field Renders the form field control (an input tag, button, or other control).
comment Renders the element comment.

See COMMENT to customize the tag and attributes.

javascript Renders a script tag containing any javascript.

    multi_layout

Specify the order that each sub-part of each element within a HTML::FormFu::Element::Multi should appear in the rendered markup.



    # Default Value
    $element->multi_layout( [
        label,
        field,
    ] );



Example: Swap the label/field order. This is equivalent to the now-deprecated reverse_multi method.



    # YAML config
    multi_layout:
      - field
      - label



The following elements override the default multi_layout value:
HTML::FormFu::Element::Checkbox

RENDERING

    field_filename

The template filename to be used for just the form field - not including the display of any container, label, errors, etc.

Must be set by more specific field classes.

    label_filename

The template filename to be used to render the label.

Defaults to label.

ERROR HANDLING

    get_errors

See get_errors in HTML::FormFu for details.

    add_error

    clear_errors

See clear_errors in HTML::FormFu for details.

INTROSPECTION

    get_deflators

See get_deflators in HTML::FormFu for details.

    get_deflator

See get_deflator in HTML::FormFu for details.

    get_filters

See get_filters in HTML::FormFu for details.

    get_filter

See get_filter in HTML::FormFu for details.

    get_constraints

See get_constraints in HTML::FormFu for details.

    get_constraint

See get_constraint in HTML::FormFu for details.

    get_inflators

See get_inflators in HTML::FormFu for details.

    get_inflator

See get_inflator in HTML::FormFu for details.

    get_validators

See get_validators in HTML::FormFu for details.

    get_validator

See get_validator in HTML::FormFu for details.

    get_transformers

See get_transformers in HTML::FormFu for details.

    get_transformer

See get_transformer in HTML::FormFu for details.

    get_errors

See get_errors in HTML::FormFu for details.

    clear_errors

See clear_errors in HTML::FormFu for details.

DEPRECATED METHODS

reverse_single See layout instead.
reverse_multi See multi_layout instead.
errors_filename See layout_errors_filename instead.

SEE ALSO

Base-class for HTML::FormFu::Role::Element::Group, HTML::FormFu::Role::Element::Input, HTML::FormFu::Element::Multi, HTML::FormFu::Element::ContentButton, HTML::FormFu::Element::Textarea.

Is a sub-class of, and inherits methods from HTML::FormFu::Element

HTML::FormFu

AUTHOR

Carl Franks, cfranks@cpan.org

LICENSE

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 HTML::FORMFU::ROLE::ELEMENT::FIELD (3) 2014-05-05

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.