HTML::FormFu::Element - Element Base Class

HTML-FormFu documentation Contained in the HTML-FormFu distribution.

Index

Code Index:

NAME

Top

HTML::FormFu::Element - Element Base Class

SYNOPSIS

Top

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

DESCRIPTION

Top

Elements are the basic building block of all forms. Elements may be logical form-fields, blocks such as divs and fieldsets, non-blocks such as hrs and other special elements such as tables.

For simple, automatic handling of fieldsets see the auto_fieldset in HTML::FormFu setting.

See deflators in HTML::FormFu for details of Deflators.

See FORM LOGIC AND VALIDATION in HTML::FormFu for details of Filters, Constraints, Inflators, Validators and Transformers.

METHODS

Top

name

For field (HTML::FormFu::Element::_Field) element, this value is used as the name attribute which the field's value is associated with.

For all elements, the name value can be useful for identifying and retrieving specific elements.

is_field

Return Value: boolean

Returns true or false depending on whether the element is a logical form-field.

This is used by get_fields in HTML::FormFu.

BUILDING AN ELEMENT

Top

load_config_file

Arguments: $filename

Arguments: \@filenames

Populate an element using a config file:

    ---
    elements:
      - type: Block
        load_config_file: 'elements.yml'

See load_config_file in HTML::FormFu for further details.

load_config_filestem

Arguments: $filestem

Arguments: \@filestems

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.

config_file_path

Arguments: $directory_name

config_file_path defines where configuration files will be searched for, if an absolute path is not given to load_config_file.

Default Value: not defined

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.

config_callback

See config_callback in HTML::FormFu for details.

populate

See populate in HTML::FormFu for details.

stash

See stash in HTML::FormFu for details.

type

Returns the type argument originally used to create the element.

CHANGING DEFAULT BEHAVIOUR

Top

render_processed_value

See render_processed_value in HTML::FormFu for details.

force_errors

See force_errors in HTML::FormFu for details.

ELEMENT ATTRIBUTES

Top

See specific element types for which tag attributes are added to.

attributes

attrs

Arguments: [%attributes]

Arguments: [\%attributes]

Return Value: $form

See attributes in HTML::FormFu for details.

attrs is an alias for attributes.

attributes_xml

attrs_xml

See attributes_xml in HTML::FormFu for details.

attrs_xml is an alias for attributes_xml.

add_attributes

add_attrs

Arguments: [%attributes]

Arguments: [\%attributes]

Return Value: $form

See add_attributes in HTML::FormFu for details.

add_attrs is an alias for add_attributes.

add_attributes_xml

add_attrs_xml

See add_attributes_xml in HTML::FormFu for details.

add_attrs_xml is an alias for add_attributes_xml.

del_attributes

del_attrs

Arguments: [%attributes]

Arguments: [\%attributes]

Return Value: $form

See del_attributes in HTML::FormFu for details.

del_attrs is an alias for del_attributes.

del_attributes_xml

del_attrs_xml

See del_attributes_xml in HTML::FormFu for details.

del_attrs_xml is an alias for del_attributes_xml.

The following methods are shortcuts for accessing attributes keys.

id

Arguments: [$id]

Return Value: $id

Get or set the element's DOM id.

Default Value: none

MODEL / DATABASE INTERACTION

Top

See HTML::FormFu::Model for further details and available models.

model_config

Arguments: \%config

RENDERING

Top

filename

This value identifies which template file should be used by render to render the element.

prepare_id

Arguments: $render

See prepare_id in HTML::FormFu::Element::_Field for details.

prepare_attrs

Arguments: $render

See prepare_attrs in HTML::FormFu::Element::_Field for details.

render

Return Value: $string

INTROSPECTION

Top

parent

Returns the block element or form object that this element is attached to.

get_parent

Arguments: \%options

    my $repeatable = $field->get_parent({ type => 'Repeatable' });

Traverses the parent hierarchy, returning the first parent that matches the supplied options.

form

Returns the HTML::FormFu object that the constraint's field is attached to.

clone

See clone in HTML::FormFu for details.

ADVANCED CUSTOMISATION

Top

tt_args

See tt_args in HTML::FormFu for details.

render_method

See render_method in HTML::FormFu for details.

CORE FORM FIELDS

Top

HTML::FormFu::Element::Button
HTML::FormFu::Element::Checkbox
HTML::FormFu::Element::Checkboxgroup
HTML::FormFu::Element::ComboBox
HTML::FormFu::Element::ContentButton
HTML::FormFu::Element::Date
HTML::FormFu::Element::File
HTML::FormFu::Element::Hidden
HTML::FormFu::Element::Image
HTML::FormFu::Element::Number
HTML::FormFu::Element::Password
HTML::FormFu::Element::Radio
HTML::FormFu::Element::Radiogroup
HTML::FormFu::Element::Reset
HTML::FormFu::Element::Select
HTML::FormFu::Element::Submit
HTML::FormFu::Element::Textarea
HTML::FormFu::Element::Text

OTHER CORE ELEMENTS

Top

HTML::FormFu::Element::Blank
HTML::FormFu::Element::Block
HTML::FormFu::Element::Fieldset
HTML::FormFu::Element::Hr
HTML::FormFu::Element::Label
HTML::FormFu::Element::Multi
HTML::FormFu::Element::Repeatable
HTML::FormFu::Element::SimpleTable
HTML::FormFu::Element::Src

ELEMENT BASE CLASSES

Top

The following are base classes for other elements, and generally needn't be used directly.

HTML::FormFu::Element::_Field
HTML::FormFu::Element::_Group
HTML::FormFu::Element::_Input
HTML::FormFu::Element::_MultiElement
HTML::FormFu::Element::_MultiSelect
HTML::FormFu::Element::_MultiText
HTML::FormFu::Element::_NonBlock

REMOVED METHODS

Top

db

Has been removed; use default_args instead.

AUTHOR

Top

Carl Franks, cfranks@cpan.org

LICENSE

Top

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

HTML-FormFu documentation Contained in the HTML-FormFu distribution. 
package HTML::FormFu::Element;
use Moose;

with 'HTML::FormFu::Role::Render',
     'HTML::FormFu::Role::FormAndElementMethods',
     'HTML::FormFu::Role::HasParent';

use HTML::FormFu::Attribute qw(
    mk_attrs
    mk_attr_accessors
    mk_output_accessors
    mk_inherited_accessors
    mk_inherited_merging_accessors
);
use HTML::FormFu::ObjectUtil qw(
    load_config_file
    load_config_filestem
    populate
    form
    stash
    parent
    get_parent
);
use HTML::FormFu::Util qw( require_class xml_escape process_attrs );
use Clone ();
use Scalar::Util qw( refaddr weaken );
use Carp qw( croak );

use overload (
    'eq' => '_string_equals',
    '==' => '_object_equals',
    '""' => sub { return shift->render },
    bool => sub {1},
    fallback => 1
);

__PACKAGE__->mk_attrs(qw( attributes ));

__PACKAGE__->mk_attr_accessors(qw( id ));

has type         => ( is => 'rw', traits  => ['Chained'] );
has filename     => ( is => 'rw', traits  => ['Chained'] );
has is_field     => ( is => 'rw', traits  => ['Chained'] );
has is_block     => ( is => 'rw', traits  => ['Chained'] );
has is_repeatable => ( is => 'rw', traits  => ['Chained'] );

__PACKAGE__->mk_inherited_accessors( qw(
        tt_args
        render_method
        config_file_path
) );

__PACKAGE__->mk_inherited_merging_accessors(qw( config_callback ));

after BUILD => sub {
    my ( $self, $args ) = @_;
    # TODO move to attribute 'default'
    $self->attributes({});
    $self->stash({});
    
    return;
};

sub name {
    my ( $self, $name ) = @_;

    if ( @_ > 1 ) {

        if ( $name =~ /[\.\[\]]/ ) {
            croak <<'ERROR_MESSAGE';
element names may not contain periods or square brackets
see documentation on nested_names() for details
ERROR_MESSAGE
        }

        $self->{name} = $name;

        return $self;
    }

    return $self->{name};
}

sub setup { }

sub get_elements { [] }

sub get_element { }

sub get_all_elements { [] }

sub get_all_element { }

sub get_fields { [] }

sub get_field { }

sub get_deflators { [] }

sub get_filters { [] }

sub get_constraints { [] }

sub get_inflators { [] }

sub get_validators { [] }

sub get_transformers { [] }

sub get_errors { [] }

sub clear_errors { }

sub pre_process { }

sub process { }

sub post_process { }

sub prepare_id { }

sub prepare_attrs { }

sub get_output_processors {
    my $self = shift;

    return $self->form->get_output_processors(@_);
}

sub get_output_processor {
    my $self = shift;

    return $self->form->get_output_processor(@_);
}

sub clone {
    my ($self) = @_;

    my %new = %$self;

    $new{tt_args} = Clone::clone( $self->{tt_args} )
        if $self->{tt_args};

    $new{attributes}   = Clone::clone( $self->attributes );
    $new{model_config} = Clone::clone( $self->model_config );

    return bless \%new, ref $self;
}

sub render_data {
    return shift->render_data_non_recursive(@_);
}

sub render_data_non_recursive {
    my ( $self, $args ) = @_;

    my %render = (
        name       => xml_escape( $self->name ),
        attributes => xml_escape( $self->attributes ),
        type       => $self->type,
        filename   => $self->filename,
        is_field   => $self->is_field,
        stash      => $self->stash,
        parent     => $self->parent,
        form       => sub { return shift->{parent}->form },
        object     => $self,
        $args ? %$args : (),
    );

    weaken( $render{parent} );

    $self->prepare_id( \%render );

    $self->prepare_attrs( \%render );

    return \%render;
}

__PACKAGE__->meta->make_immutable;

1;

__END__