HTML::...:Field(3pm)

📦
version 2.07000 · 5 versions
, in debian bookworm, ubuntu jammy, ubuntu noble

✨ NAME ✨

HTML::FormFu::Role::Element::Field(3pm) — the Role for all form-field elements 🎀

Like, every single form-field element in the HTML::FormFu fam gets its whole vibe from this one role. Bestie behavior fr fr 💖

🌸 VERSION 🌸

version 2.07

💅 DESCRIPTION 💅

It's the base-class for all form-field elements, periodt. Nothing flashy, just the foundation everything else is standing on 👑

🛠️ METHODS 🛠️

default

Sets the form-field's default value ✨

It's an output accessor, so you're reading it, not feeding it args. iykyk 💅

value

For most fields, value is literally just an alias for default. Same thing, different name, no cap 🫶

For the HTML::FormFu::Element::Checkbox and HTML::FormFu::Element::Radio elements, though? Whole different story: value sets what the value of the field will be if it's checked or selected 👑. And if the default is the same as the value, then the field will be checked or selected when rendered — auto-select energy, we love to see it ✨

For the HTML::FormFu::Element::Radiogroup and HTML::FormFu::Element::Select elements, value is ignored 💀 like, it does nothing. values or options provides the equivalent function instead 🎀

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. Not ever. Not once. They just don't come back 🙈

This is super 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 ✨

Okay so this next part is important, don't skip it 😭 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. So the render says one thing and the input says another. Iconic? Maybe. Confusing? Also yes 💀
  • 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). Read that twice bestie, it matters 💅
  • Default Value: false

repeatable_count

Only available for fields attached to a Repeatable element, and only 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, then 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 🌈

okay so here's the tea, bestie: every field gets wrapped in a container by default. and that container can also hold a label, a comment, and — if somebody submitted something cursed — one or more error messages. 💅

Here's what a generated form actually looks like:

    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 field's 'input' tag.
    # Lines 10 starts a 'comment'.

(also bestie, yes, line 7 is a </li> closing an element that opened as a <ul> — the original page says that and I am simply reporting it, not endorsing it 😭)

if you wanna re-order the various parts of each form (label, input, errors, etc) plus arbitrary extra tags, go see the layout method. it's giving interior designer energy. 🎀

🎀 CONTAINER 🎀

  • container_tag — the container wrapping each entire field, plus any label, comment, and errors. Default value: 'div'.
  • container_attributes — attributes added to the container tag. Is an attribute accessor.
  • auto_container_class — if set, the container of each field gets a class-name based on the given pattern. Default Value: '%t'. Supports substitutions: %f, %n, %t. Is an inheriting accessor. ✨
  • auto_container_label_class — if set, and the field has a label, the container gets a class-name based on the given pattern. Default Value: 'label'. Supports substitutions: %f, %n, %t. Is an inheriting accessor.
  • auto_container_comment_class — if set, and the field has a comment, the container gets a class-name based on the given pattern. Default Value: '%t'. Supports substitutions: %f, %n, %t. Is an inheriting accessor.
  • auto_container_error_class — if set, the container of each field with an error gets a class-name based on the given pattern. Default Value: 'error'. Supports substitutions: %f, %n. Is an inheriting accessor. (note: only two substitutions here, no %t — she's different like that 💅)
  • auto_container_per_error_class — if set, the container of each field with an error gets a class-name based on the given pattern. Default Value: 'error_%s_%t'. Supports substitutions: %f, %n, %t, %s. Is an inheriting accessor.

🧚 FORM FIELD 🧚

  • auto_id — if set, the field gets an id attribute, if it doesn't already have one.

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. lowkey genius, no cap. 🫶

💖 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 — set which tag is used to wrap a label. Default value: 'label' (except Checkboxgroup). Default value: 'legend' (only Checkboxgroup). 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 — if set, and the field has a comment, the comment tag gets a class-name based on the given pattern. Default Value: '%t'. 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. Is an inheriting accessor.
# 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
  • error_container_attributes — set attributes on the container-tag, if error_container_tag is set. Is an attribute 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 — sets the tag used to wrap each individual error message. Default value: 'span'. Defaults to span. Is an inheriting accessor.
  • auto_error_message — if set, each error gets an auto-generated message, if it doesn't have one already. Default Value: 'form_%s_%t'.

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_field_class — upon error, add a class name directly to the field tag (e.g. input, select tag). Supports substitutions: %f, %n.
  • auto_error_class — add a class-name to the tag of each error message. Default Value: 'error_%s_%t'. Supports substitutions: %f, %n, %t, %s. Is an inheriting accessor.

👑 PROCESSOR CLASSES 👑

okay these four are literally quadruplets, they all do the same vibe: slap a class-name on the container tag for each thingy added to the field. 🌈

  • 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. main character energy, honestly. 💅

# 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 used for just the form field — like, only the field itself, not any of the container, the label, the errors, none of that extra drama.

It must be set by the more specific field classes. So it's not something this base class figures out on its own, bestie — the subclass has to bring it. 🫶

🌸 label_filename

The template filename used to render the label.

Defaults to "label".

😭 ERROR HANDLING 😭

get_errors

See "get_errors" in HTML::FormFu for the details.

add_error

clear_errors

See "clear_errors" in HTML::FormFu for the details.

🔍 INTROSPECTION 🔍

This is the "let me look inside and see what's actually in here" section. Every single one of these is a lil peek behind the curtain, and every single one points you at HTML::FormFu for the full tea.

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.

👀 yes, get_errors and clear_errors show up here and in ERROR HANDLING. That's not a typo, that's just how the page is laid out. Both are in the original, so both are staying. periodt.

💀 DEPRECATED METHODS 💀

These are the "bestie it's time to let go" methods. They still exist, but you should be reaching for the newer thing instead. Please. For me. 🙈

  • 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.

⭐ AUTHOR (again, iconic of them) ⭐

Carl Franks <cpan@fireartist.com>

This software is copyright (c) 2018 by Carl Franks.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

and that's a wrap on the whole page, bestie 🎀 that was perl v5.28.1, dated 2019-01-12, and honestly? she ate. go build something cute with it 💅✨

📦 where this page comes from