.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::FormFu::Element 3pm"
.TH HTML::FormFu::Element 3pm 2024-04-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
HTML::FormFu::Element \- Element Base Class
.SH VERSION
.IX Header "VERSION"
version 2.07
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 6
\&    \-\-\-
\&    elements:
\&      \- type: Text
\&        name: username
\&        constraints:
\&          \- type: Required
\&
\&      \- type: Password
\&        name: password
\&        constraints:
\&          \- type: Required
\&          \- type: Equal
\&            others: repeat\-password
\&
\&      \- type: Password
\&        name: repeat\-password
\&
\&      \- type: Submit
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Elements are the basic building block of all forms. Elements may be logical
form-fields, blocks such as \f(CW\*(C`div\*(C'\fRs and \f(CW\*(C`fieldset\*(C'\fRs, non-blocks such as
\&\f(CW\*(C`hr\*(C'\fRs and other special elements such as tables.
.PP
For simple, automatic handling of fieldsets see the
"auto_fieldset" in HTML::FormFu setting.
.PP
See "deflators" in HTML::FormFu for details of
Deflators.
.PP
See "FORM LOGIC AND VALIDATION" in HTML::FormFu for details of
Filters,
Constraints,
Inflators,
Validators and
Transformers.
.SH METHODS
.IX Header "METHODS"
.SS name
.IX Subsection "name"
For field element, this value is used as
the \f(CW\*(C`name\*(C'\fR attribute which the field's value is associated with.
.PP
For all elements, the "name" value can be useful for identifying and
retrieving specific elements.
.SS is_field
.IX Subsection "is_field"
Return Value: boolean
.PP
Returns \f(CW\*(C`true\*(C'\fR or \f(CW\*(C`false\*(C'\fR depending on whether the element is a logical
form-field.
.PP
This is used by "get_fields" in HTML::FormFu.
.SH "BUILDING AN ELEMENT"
.IX Header "BUILDING AN ELEMENT"
.SS load_config_file
.IX Subsection "load_config_file"
Arguments: \f(CW$filename\fR
.PP
Arguments: \e@filenames
.PP
Populate an element using a config file:
.PP
.Vb 4
\&    \-\-\-
\&    elements:
\&      \- type: Block
\&        load_config_file: \*(Aqelements.yml\*(Aq
.Ve
.PP
See "load_config_file" in HTML::FormFu for further details.
.SS load_config_filestem
.IX Subsection "load_config_filestem"
Arguments: \f(CW$filestem\fR
.PP
Arguments: \e@filestems
.PP
Like "load_config_file", but you shouldn't include the file extension
in the passed string. This allows you to change your config-file type,
without having to change the code that loads the files.
.SS config_file_path
.IX Subsection "config_file_path"
Arguments: \f(CW$directory_name\fR
.PP
"config_file_path" defines where configuration files will be
searched for, if an absolute path is not given to
"load_config_file".
.PP
Default Value: not defined
.PP
This method is a special 'inherited accessor', which means it can be set on
the form, a block element or a single element. When the value is read, if
no value is defined it automatically traverses the element's hierarchy of
parents, through any block elements and up to the form, searching for a
defined value.
.SS config_callback
.IX Subsection "config_callback"
See "config_callback" in HTML::FormFu for details.
.SS populate
.IX Subsection "populate"
See "populate" in HTML::FormFu for details.
.SS stash
.IX Subsection "stash"
See "stash" in HTML::FormFu for details.
.SS type
.IX Subsection "type"
Returns the \f(CW\*(C`type\*(C'\fR argument originally used to create the element.
.SH "CHANGING DEFAULT BEHAVIOUR"
.IX Header "CHANGING DEFAULT BEHAVIOUR"
.SS render_processed_value
.IX Subsection "render_processed_value"
See "render_processed_value" in HTML::FormFu for details.
.SS force_errors
.IX Subsection "force_errors"
See "force_errors" in HTML::FormFu for details.
.SH "ELEMENT ATTRIBUTES"
.IX Header "ELEMENT ATTRIBUTES"
See specific element types for which tag attributes are added to.
.SS attributes
.IX Subsection "attributes"
.SS attrs
.IX Subsection "attrs"
Arguments: [%attributes]
.PP
Arguments: [\e%attributes]
.PP
Return Value: \f(CW$form\fR
.PP
See "attributes" in HTML::FormFu for details.
.PP
"attrs" is an alias for "attributes".
.SS attributes_xml
.IX Subsection "attributes_xml"
.SS attrs_xml
.IX Subsection "attrs_xml"
See "attributes_xml" in HTML::FormFu for details.
.PP
"attrs_xml" is an alias for "attributes_xml".
.SS add_attributes
.IX Subsection "add_attributes"
.SS add_attrs
.IX Subsection "add_attrs"
Arguments: [%attributes]
.PP
Arguments: [\e%attributes]
.PP
Return Value: \f(CW$form\fR
.PP
See "add_attributes" in HTML::FormFu for details.
.PP
"add_attrs" is an alias for "add_attributes".
.SS add_attributes_xml
.IX Subsection "add_attributes_xml"
.SS add_attrs_xml
.IX Subsection "add_attrs_xml"
See "add_attributes_xml" in HTML::FormFu for details.
.PP
"add_attrs_xml" is an alias for "add_attributes_xml".
.SS del_attributes
.IX Subsection "del_attributes"
.SS del_attrs
.IX Subsection "del_attrs"
Arguments: [%attributes]
.PP
Arguments: [\e%attributes]
.PP
Return Value: \f(CW$form\fR
.PP
See "del_attributes" in HTML::FormFu for details.
.PP
"del_attrs" is an alias for "del_attributes".
.SS del_attributes_xml
.IX Subsection "del_attributes_xml"
.SS del_attrs_xml
.IX Subsection "del_attrs_xml"
See "del_attributes_xml" in HTML::FormFu for details.
.PP
"del_attrs_xml" is an alias for "del_attributes_xml".
.PP
The following methods are shortcuts for accessing "attributes" keys.
.SS id
.IX Subsection "id"
Arguments: [$id]
.PP
Return Value: \f(CW$id\fR
.PP
Get or set the element's DOM id.
.PP
Default Value: none
.SH "MODEL / DATABASE INTERACTION"
.IX Header "MODEL / DATABASE INTERACTION"
See HTML::FormFu::Model for further details and available models.
.SS model_config
.IX Subsection "model_config"
Arguments: \e%config
.SH RENDERING
.IX Header "RENDERING"
.SS filename
.IX Subsection "filename"
This value identifies which template file should be used by
"render" to render the element.
.SS prepare_id
.IX Subsection "prepare_id"
Arguments: \f(CW$render\fR
.PP
See "prepare_id" in HTML::FormFu::Role::Element::Field for details.
.SS prepare_attrs
.IX Subsection "prepare_attrs"
Arguments: \f(CW$render\fR
.PP
See "prepare_attrs" in HTML::FormFu::Role::Element::Field for details.
.SS render
.IX Subsection "render"
Return Value: \f(CW$string\fR
.SH INTROSPECTION
.IX Header "INTROSPECTION"
.SS parent
.IX Subsection "parent"
Returns the block element or
form object that this element is attached to.
.SS get_parent
.IX Subsection "get_parent"
Arguments: \e%options
.PP
.Vb 1
\&    my $repeatable = $field\->get_parent({ type => \*(AqRepeatable\*(Aq });
.Ve
.PP
Traverses the parent hierarchy, returning the first parent that matches the
supplied options.
.SS form
.IX Subsection "form"
Returns the HTML::FormFu object that the constraint's field is attached
to.
.SS clone
.IX Subsection "clone"
See "clone" in HTML::FormFu for details.
.SH "ADVANCED CUSTOMISATION"
.IX Header "ADVANCED CUSTOMISATION"
.SS tt_args
.IX Subsection "tt_args"
See "tt_args" in HTML::FormFu for details.
.SS render_method
.IX Subsection "render_method"
See "render_method" in HTML::FormFu for details.
.SH "CORE FORM FIELDS"
.IX Header "CORE FORM FIELDS"
.IP HTML::FormFu::Element::Button 4
.IX Item "HTML::FormFu::Element::Button"
.PD 0
.IP HTML::FormFu::Element::Checkbox 4
.IX Item "HTML::FormFu::Element::Checkbox"
.IP HTML::FormFu::Element::Checkboxgroup 4
.IX Item "HTML::FormFu::Element::Checkboxgroup"
.IP HTML::FormFu::Element::ComboBox 4
.IX Item "HTML::FormFu::Element::ComboBox"
.IP HTML::FormFu::Element::ContentButton 4
.IX Item "HTML::FormFu::Element::ContentButton"
.IP HTML::FormFu::Element::Date 4
.IX Item "HTML::FormFu::Element::Date"
.IP HTML::FormFu::Element::Email 4
.IX Item "HTML::FormFu::Element::Email"
.IP HTML::FormFu::Element::File 4
.IX Item "HTML::FormFu::Element::File"
.IP HTML::FormFu::Element::Hidden 4
.IX Item "HTML::FormFu::Element::Hidden"
.IP HTML::FormFu::Element::Image 4
.IX Item "HTML::FormFu::Element::Image"
.IP HTML::FormFu::Element::Number 4
.IX Item "HTML::FormFu::Element::Number"
.IP HTML::FormFu::Element::Password 4
.IX Item "HTML::FormFu::Element::Password"
.IP HTML::FormFu::Element::Radio 4
.IX Item "HTML::FormFu::Element::Radio"
.IP HTML::FormFu::Element::Radiogroup 4
.IX Item "HTML::FormFu::Element::Radiogroup"
.IP HTML::FormFu::Element::Reset 4
.IX Item "HTML::FormFu::Element::Reset"
.IP HTML::FormFu::Element::Select 4
.IX Item "HTML::FormFu::Element::Select"
.IP HTML::FormFu::Element::Submit 4
.IX Item "HTML::FormFu::Element::Submit"
.IP HTML::FormFu::Element::Textarea 4
.IX Item "HTML::FormFu::Element::Textarea"
.IP HTML::FormFu::Element::Text 4
.IX Item "HTML::FormFu::Element::Text"
.IP HTML::FormFu::Element::URL 4
.IX Item "HTML::FormFu::Element::URL"
.PD
.SH "OTHER CORE ELEMENTS"
.IX Header "OTHER CORE ELEMENTS"
.IP HTML::FormFu::Element::Blank 4
.IX Item "HTML::FormFu::Element::Blank"
.PD 0
.IP HTML::FormFu::Element::Block 4
.IX Item "HTML::FormFu::Element::Block"
.IP HTML::FormFu::Element::Fieldset 4
.IX Item "HTML::FormFu::Element::Fieldset"
.IP HTML::FormFu::Element::Hr 4
.IX Item "HTML::FormFu::Element::Hr"
.IP HTML::FormFu::Element::Label 4
.IX Item "HTML::FormFu::Element::Label"
.IP HTML::FormFu::Element::Multi 4
.IX Item "HTML::FormFu::Element::Multi"
.IP HTML::FormFu::Element::Repeatable 4
.IX Item "HTML::FormFu::Element::Repeatable"
.IP HTML::FormFu::Element::SimpleTable 4
.IX Item "HTML::FormFu::Element::SimpleTable"
.IP HTML::FormFu::Element::Src 4
.IX Item "HTML::FormFu::Element::Src"
.PD
.SH "ELEMENT BASE CLASSES"
.IX Header "ELEMENT BASE CLASSES"
The following are base classes for other elements, and generally needn't be
used directly.
.IP HTML::FormFu::Role::Element::Field 4
.IX Item "HTML::FormFu::Role::Element::Field"
.PD 0
.IP HTML::FormFu::Role::Element::Group 4
.IX Item "HTML::FormFu::Role::Element::Group"
.IP HTML::FormFu::Role::Element::Input 4
.IX Item "HTML::FormFu::Role::Element::Input"
.IP HTML::FormFu::Element::_MultiElement 4
.IX Item "HTML::FormFu::Element::_MultiElement"
.IP HTML::FormFu::Element::_MultiSelect 4
.IX Item "HTML::FormFu::Element::_MultiSelect"
.IP HTML::FormFu::Element::_MultiText 4
.IX Item "HTML::FormFu::Element::_MultiText"
.IP HTML::FormFu::Role::Element::NonBlock 4
.IX Item "HTML::FormFu::Role::Element::NonBlock"
.PD
.SH "REMOVED METHODS"
.IX Header "REMOVED METHODS"
.SS db
.IX Subsection "db"
Has been removed; use "default_args" instead.
.SH AUTHOR
.IX Header "AUTHOR"
Carl Franks, \f(CW\*(C`cfranks@cpan.org\*(C'\fR
.SH LICENSE
.IX Header "LICENSE"
This library is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.
.SH AUTHOR
.IX Header "AUTHOR"
Carl Franks <cpan@fireartist.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2018 by Carl Franks.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.