package Rose::HTMLx::Form::Field::Autocomplete;
use strict;
use warnings;
use Carp;
our $VERSION = '0.02';
use base qw( Rose::HTML::Form::Field::Text );
use Rose::Object::MakeMethods::Generic (scalar => [qw( autocomplete limit )]);
sub url
{
my $self = shift;
my $u = $self->autocomplete or croak "no autocomplete URL set";
my $n = $self->name || $self->local_name;
my $l = $self->limit || 30;
return [$u, {c => $n, l => $l}];
}
# borrowed from TT::Plugin::URL
sub url_as_string
{
my $self = shift;
my $url = $self->url;
my $args = $url->[1];
my $esc = join('&',
map { _url_args($_, $args->{$_}) }
grep { defined $args->{$_} && length $args->{$_} }
sort keys %$args);
return $url->[0] . '?' . $esc;
}
# borrowed from TT::Plugin::URL
sub _url_args
{
my ($key, $val) = @_;
$key = _escape($key);
return map { "$key=" . _escape($_); } ref $val eq 'ARRAY' ? @$val : $val;
}
# borrowed from TT::Plugin::URL, which borrowed froM CGI.pm
sub _escape
{
my $toencode = shift;
return undef unless defined($toencode);
$toencode =~ s/([^a-zA-Z0-9_.-])/uc sprintf("%%%02x",ord($1))/eg;
return $toencode;
}
1;
__END__
=head1 NAME
Rose::HTMLx::Form::Field::Autocomplete - Ajax autocompletion for text fields
=head1 SYNOPSIS
my $field = Rose::HTMLx::Form::Field::Autocomplete->new(
label => 'Complete Me',
name => 'completer',
size => 30,
maxlength => 128,
autocomplete => 'http://myserver.foo/completer/url,
limit => 30
);
print $field->xhtml;
...
=head1 DESCRIPTION
This subclass of Rose::HTML::Form::Field::Text is intended to make it easier
to integrate Ajax autocompletion into your web applications. You define
a URL where your web application can find suggested values for the field,
and optionally, a limit on the number of suggestions returned by the server.
This subclass is expected to be used with
Catalyst::Controller::Rose::Autocomplete but that is not required.
=head1 METHODS
Only changes from Rose::HTML::Form::Field::Text are documented here.
=head2 autocomplete
Expects a URL value but any string is acceptable. See url().
=head2 limit
Expects an integer, which will be used in the construction of url().
=head2 url
Returns the URL for use in your template. The return value is an array
ref, with the first value being the base URI and the second value being
a hashref of param key/value pairs. The hashref keys are in the syntax
that Catalyst::Controller::Rose::Autocomplete expects.
See the Catalyst::Controller::Rose example application for examples
of using the url() method with Template Toolkit.
=head2 url_as_string
Like url() but the return value is a scalar string, not an array ref.
The value is the URI-escaped value of url().
=head1 AUTHOR
Peter Karman <perl@peknet.com>
Thanks to Atomic Learning, Inc for sponsoring the development of this module.
=head1 LICENSE
This library is free software. You may redistribute it and/or modify it under
the same terms as Perl itself.
=head1 SEE ALSO
Catalyst::Controller::Rose::Autocomplete,
Rose::HTML::Objects, Rose::HTML::Form::Field
=cut