Web/Form/Field.pm

=begin properties

constructor
canonicalizer
available_values
ajax_validates
autocompleter

default_value
valid_values
validator
render_as
label
hints
placeholder
display_length
max_length
mandatory

=end properties

=cut

use warnings;
use strict;

package Jifty::Web::Form::Field;

=head1 NAME

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

=head1 DESCRIPTION

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

C<Jifty::Web::Form::Field>s stringify using the L</render> method, to
aid in placing them in L<HTML::Mason> components.

=cut

use base 'Jifty::Web::Form::Element';

use Scalar::Util qw/weaken/;
use Scalar::Defer qw/force/;
use HTML::Entities;

# We need the anonymous sub because otherwise the method of the base class is
# always called, instead of the appropriate overridden method in a child class.
use overload '""' => sub { shift->render }, bool => sub { 1 };

=head2 new

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

=cut

sub new {
    my $class = shift;
    my $self = $class->SUPER::new(
      { type          => 'text',
        class         => '',
        input_name    => '',
        default_value => '',
        sticky_value  => '',
        render_mode   => 'update' });
    my $args = ref($_[0]) ? $_[0] : {@_};

    $self->rebless( $args->{render_as} || $args->{type} || 'text' );

    for my $field ( $self->accessors() ) {
        $self->$field( $args->{$field} ) if exists $args->{$field};
    }

    # If they key and/or value imply that this argument is going to be
    # a mapped argument, then do the mapping and mark the field as hidden.
    # but ignore that if the field is a container in the model
    my ($key, $value) = Jifty::Request::Mapper->query_parameters($self->input_name, $self->current_value);
    if ($key ne $self->input_name && !$self->action->arguments->{$self->name}{container}) {
        $self->rebless('Hidden');
        $self->input_name($key);
        $self->default_value($value);
        $self->sticky_value(undef);
    }

    # now that the form field has been instantiated, register the action with the form.
    if ($self->action and Jifty->web->form->is_open and not (Jifty->web->form->printed_actions->{$self->action->moniker})) {
        Jifty->web->form->register_action( $self->action);
        Jifty->web->form->print_action_registration($self->action->moniker);
    }
    return $self;
}

=head2 $self->rebless($widget)

Turn the current blessed class into the given widget class.

=cut

sub rebless {
    my ($self, $widget) = @_;
    my $widget_class = $widget =~ m/::/ ? $widget : "Jifty::Web::Form::Field::".ucfirst($widget);

    $self->log->error("Invalid widget class $widget_class")
        unless Jifty::Util->require($widget_class);

    bless $self, $widget_class;
}

=head2 accessors

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

=cut

my @new_fields = qw(
    name type sticky sticky_value default_value action
    mandatory ajax_validates ajax_canonicalizes autocompleter preamble hints
    placeholder focus render_mode display_length max_length _element_id
    disable_autocomplete multiple attributes
);

my @semiexposed_fields = qw(
    label input_name available_values
);

sub accessors {
    shift->SUPER::accessors(), @new_fields, @semiexposed_fields;
}

__PACKAGE__->mk_accessors(@new_fields, map { "_$_" } @semiexposed_fields);

=head2 name [VALUE]

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

=head2 class [VALUE]

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

=head2 type [VALUE]

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

=head2 key_binding VALUE

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

=head2 key_binding_label VALUE

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

=head2 default_value [VALUE]

Gets or sets the default value for the form.

=head2 sticky_value [VALUE]

Gets or sets the value for the form field that was submitted in the last action.

=head2 mandatory [VALUE]

A boolean indicating that the argument B<must> be present when the
user submits the form.

=head2 focus [VALUE]

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

=head2 ajax_validates [VALUE]

A boolean value indicating if user input into an HTML form field for
this argument should be L<validated|Jifty::Manual::Glossary/validate>
via L<AJAX|Jifty::Manual::Glossary/AJAX> as the user fills out the
form, instead of waiting until submit. Arguments will B<always> be
validated before the action is run, whether or not they also
C<ajax_validate>.

=head2 ajax_canonicalizes [VALUE]

A boolean value indicating if user input into an HTML form field for
this argument should be L<canonicalized|Jifty::Manual::Glossary/canonicalize>
via L<AJAX|Jifty::Manual::Glassary/AJAX> as the user fills out the
form, instead of waiting until submit.  Arguments will B<always> be
canonicalized before the action is run, whether or not they also
C<ajax_canonicalize>

=head2 disable_autocomplete [VALUE]

Gets or sets whether to disable _browser_ autocomplete for this field.

=head2 preamble [VALUE]

Gets or sets the preamble located in front of the field.

=head2 multiple [VALUE]

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

=head2 id

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

=head2 attributes

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

=cut

sub id {
    my $self = shift;
    return $self->input_name;
}

=head2 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.

=cut

sub input_name {
    my $self = shift;

# If we've been explicitly handed a name, we should run with it.
# Otherwise, we should ask our action, how to turn our "name"
# into a form input name.

    my $ret = $self->_input_name(@_);
    return $ret if $ret;

    my $action = $self->action;
    return $action ? $self->action->form_field_name( $self->name )
                   : '';
}


=head2 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.

=cut

sub fallback_name {
    my $self = shift;

    if ($self->action) {
    return $self->action->fallback_form_field_name( $self->name );
    }
    else {
        # XXX TODO, we should have a more graceful way to compose these in the absence of an action
        my $name = $self->input_name;
        $name =~ s/^J:A:F/J:A:F:F/;
        return($name)
    }
}


=head2 label [VALUE]

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

=cut

sub label {
    my $self = shift;
    my $val = $self->_label(@_);
    defined $val ? $val :  $self->name;

}

=head2 hints [VALUE]

Hints for the user to explain this field

=cut

sub hints {
    my $self = shift;
    return $self->_hints_accessor unless @_;

    my $hint = shift;
    # people sometimes say hints are "foo" rather than hints is "foo"
    if (ref $hint eq 'ARRAY') {
        $hint = shift @$hint;
    }
    return $self->_hints_accessor($hint);
}


=head2 element_id

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

=cut


sub element_id {
    my $self = shift;
    return $self->_element_id || $self->_element_id( $self->input_name ."-".Jifty->web->serial);
}

=head2 action [VALUE]

Gets or sets the L<Jifty::Action> object that this
C<Jifty::Web::Form::Field> is associated with.  This is called
automatically if this C<Jifty::Action> was created via
L<Jifty::Web::Form::Field/form_field>.

=cut

sub action {
    my $self = shift;

    if (@_) {
        $self->{action} = shift;

        # weaken our circular reference
        weaken $self->{action};
    }

    return $self->{action};

}

=head2 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.

=cut

sub current_value {
    my $self = shift;

    if ($self->sticky_value and $self->sticky) {
        return $self->sticky_value;
    } else {
        # the force is here because very often this will be a Scalar::Defer object that we REALLY
        # want to be able to check definedness on.
        # Because of a core limitation in perl, Scalar::Defer can't return undef for an object.
        return force $self->default_value;
    }
}

=head2 render

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

This is also what C<Jifty::Web::Form::Field>s do when stringified.

=cut

sub render {
    my $self = shift;
    $self->render_wrapper_start();
    $self->render_preamble();


    $self->render_label();
    if ($self->render_mode eq 'update') {
        $self->render_widget();
        $self->render_inline_javascript();
        $self->render_hints();
        $self->render_errors();
        $self->render_warnings();
        $self->render_canonicalization_notes();
    } elsif ($self->render_mode eq 'read'){
        $self->render_value();
        $self->render_preload_javascript();
    }
    $self->render_wrapper_end();
    return ('');
}

=head2 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.

=cut

sub render_inline_javascript {
    my $self = shift;

    my $javascript;

    $javascript = join(
        "\n",
        grep {$_} (
            $self->autocomplete_javascript(),
            $self->placeholder_javascript(),
            $self->key_binding_javascript(),
            $self->preload_javascript(),
        )
    );

    if($javascript =~ /\S/) {
        Jifty->web->out(qq{<script type="text/javascript">$javascript</script>
});
    }
}

=head2 render_preload_javascript

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

=cut

sub render_preload_javascript {
    my $self = shift;

    my $javascript = $self->preload_javascript;

    if($javascript =~ /\S/) {
        Jifty->web->out(qq{<script type="text/javascript">$javascript</script>
});
    }
}

=head2 classes

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

=cut


sub classes {
    my $self = shift;
    my $name = $self->name;
    return join(' ', ($self->class||()), ($name ? "argument-".$name : ()));
}


=head2 render_wrapper_start

Output the start of div that wraps the form field

=cut

sub render_wrapper_start {
    my $self = shift;
    my @classes = qw(form_field);
    if ($self->mandatory) { push @classes, 'mandatory' }
    if ($self->name)      { push @classes, 'argument-'.$self->name }
    Jifty->web->out('<div class="'.join(' ', @classes).'">' ."\n");
}

=head2 render_wrapper_end

Output the div that wraps the form field

=cut

sub render_wrapper_end {
    my $self = shift;
    Jifty->web->out("</div>"."\n");
}

=head2 render_preamble

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

Use this for sticking instructions right in front of a widget

=cut


sub render_preamble {
    my $self = shift;
    Jifty->web->out(
qq!<span class="preamble @{[$self->classes]}">@{[_($self->preamble) || '' ]}</span>\n!
    );

    return '';
}

=head2 render_label

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

=cut

sub render_label {
    my $self = shift;
    return '' unless defined $self->label and length $self->label;
    if ( $self->render_mode eq 'update' ) {
        Jifty->web->out(
qq!<label class="label @{[$self->classes]}" for="@{[$self->element_id ]}">@{[_($self->label) ]}</label>\n!
        );
    } else {
        Jifty->web->out(
            qq!<span class="label @{[$self->classes]}">@{[_($self->label) ]}</span>\n!
        );
    }

    return '';
}


=head2 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.

=cut

sub render_widget {
    my $self  = shift;
    my $field = qq!  <input !;
    $field .= qq! type="@{[ $self->type ]}"!;
    $field .= qq! name="@{[ $self->input_name ]}"! if ($self->input_name);
    $field .= qq! title="@{[ $self->title ]}"! if ($self->title);
    $field .= qq! id="@{[ $self->element_id ]}"!;
    $field .= qq! value="@{[$self->canonicalize_value(Jifty->web->escape($self->current_value))]}"! if defined $self->current_value;
    $field .= $self->_widget_class;

    if ($self->display_length) {
        $field .= qq! size="@{[ $self->display_length() ]}"!;
    }
    elsif ($self->max_length) {
        $field .= qq! size="@{[ $self->max_length() ]}"!;
    }

    $field .= qq! maxlength="@{[ $self->max_length() ]}"! if ($self->max_length());
    $field .= qq! autocomplete="off"! if defined $self->disable_autocomplete;
    $field .= " " .$self->other_widget_properties;
    $field .= $self->javascript;
    $field .= qq!  />\n!;
    Jifty->web->out($field);
    return '';
}


=head2 canonicalize_value

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

=cut

sub canonicalize_value {
    my $self = shift;
    return $_[0];
}

=head2 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.


=cut

sub other_widget_properties {''}

=head2 _widget_class

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

=cut

sub _widget_class {
    my $self = shift;
    my @classes = ( 'widget',
                    $self->classes,
                    ( $self->ajax_validates     ? ' ajaxvalidation' : () ),
                    ( $self->ajax_canonicalizes ? ' ajaxcanonicalization' : () ),
                    ( $self->autocompleter      ? ' ajaxautocompletes' : () ),
                    ( $self->focus              ? ' focus' : ()),
                    @_ );

    return qq! class="!. join(' ',@classes).  qq!"!

}

=head2 render_value

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

=cut


sub render_value {
    my $self  = shift;
    my $field = '<span';
    $field .= qq! class="@{[ $self->classes ]} value"> !;
    # XXX: force stringify the value because maketext is buggy with overloaded objects.
    $field .= $self->canonicalize_value(Jifty->web->escape("@{[$self->current_value]}")) if defined $self->current_value;
    $field .= qq!</span>\n!;
    Jifty->web->out($field);
    return '';
}


=head2 render_autocomplete

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

=cut

sub render_autocomplete {
    my $self = shift;
    return unless $self->autocompleter;
    Jifty->web->out(qq!<script type="text/javascript">@{[$self->autocomplete_javascript]}</script>!);
    return '';
}

=head2 autocomplete_javascript

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

=cut

sub autocomplete_javascript {
    my $self = shift;
    return unless($self->autocompleter);
    my $element_id = $self->element_id;
    return "jQuery(document).ready(function(){Jifty.addAutocompleter('$element_id');});"
}

=head2 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).

=cut

sub placeholder_javascript {
    my $self = shift;
    return unless $self->placeholder;
    my $placeholder = $self->placeholder;
    $placeholder =~ s{(['\\])}{\\$1}g;
    $placeholder =~ s{\n}{\\n}g;
    $placeholder =~ s{\r}{\\r}g;
    return qq!new Jifty.Placeholder('@{[$self->element_id]}', '$placeholder');!;
}

=head2 preload_javascript

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

=cut

sub preload_javascript {
    my $self = shift;

    my $structure = $self->_javascript_attrs_structure;
    my @javascript;
    for my $trigger (keys %$structure) {
        my $trigger_structure = $structure->{$trigger};
        next unless $trigger_structure->{preload_key};

        my @preloaded;

        my $preload_json = Jifty::JSON::encode_json(
            {
                fragments   => $trigger_structure->{fragments},
                preload_key => $trigger_structure->{preload_key},
            }
        );

        push @javascript, "Jifty.preload($preload_json, this);";
    }

    return join "\n", @javascript;
}

=head2 render_hints

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

=cut

sub render_hints {
    my $self = shift;
    Jifty->web->out(
qq!<span class="hints @{[$self->classes]}">@{[_($self->hints) || '']}</span>\n!
    );

    return '';

}


=head2 render_errors

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

=cut

sub render_errors {
    my $self = shift;

    return unless $self->action;

    Jifty->web->out(
qq!<span class="error @{[$self->classes]}" id="@{[$self->action->error_div_id($self->name)]}">@{[  $self->action->result->field_error( $self->name ) || '']}</span>\n!
    );
    return '';
}

=head2 render_warnings

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

=cut

sub render_warnings {
    my $self = shift;

    return unless $self->action;

    Jifty->web->out(
qq!<span class="warning @{[$self->classes]}" id="@{[$self->action->warning_div_id($self->name)]}">@{[  $self->action->result->field_warning( $self->name ) || '']}</span>\n!
    );
    return '';
}

=head2 render_canonicalization_notes

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

=cut

sub render_canonicalization_notes {
    my $self = shift;

    return unless $self->action;

    Jifty->web->out(
qq!<span class="canonicalization_note @{[$self->classes]}" id="@{[$self->action->canonicalization_note_div_id($self->name)]}">@{[$self->action->result->field_canonicalization_note( $self->name ) || '']}</span>\n!
    );
    return '';
}

=head2 available_values

Returns the available values for this field.

=cut

sub available_values {
    my $self = shift;

    # Setter
    if (@_) {
        return $self->_available_values(@_);
    }

    # If the available_values are available in the field..
    if (my $available = $self->_available_values) {
        return @$available;
    }

    # Otherwise consult the action

    my $values =  $self->action->available_values($self->name);
    if (!ref($values) || ref($values) ne 'ARRAY') {
        die "available_values of parameter '" . $self->name . "' returned a " . (ref($values) || 'nonreference') . ", expected array reference";
    }

    return @$values;
}

=for private

=head2 length

# Deprecated API


=cut

sub length {
    my $self = shift;
    Carp::carp("->length is deprecated; use ->max_length instead");
    $self->max_length(@_);
}


1;