view release on metacpan or  search on metacpan

lib/Apache2/Autocomplete.pm  view on Meta::CPAN

This specifies the name of the form element where the autocompletion occurs

=item * document.f.btnG

This specified the name of the submit button of the form

=item * search

This specifies that I<http://localhost/complete/search> will be used to
get results for the autocompletion; if a value of, for example,
I<my_handler> was used instead of I<search>, then
I<http://localhost/complete/my_handler> will be used.

=item * en

When the user types something into the form (after a specified
timeout), a call to the specified handler is made in order to get
the results to be displayed for the autocompletion. This will be
of the form
I<http://localhost/complete/search?hl=en&client=suggest&js=true&qu=a>,
where I<qu> is the query typed so far and I<en> is the value specified
for the variable I<hl> by this argument. If you need a value from
the form to be sent to the autocompletion handler, you can do so
in the following way: suppose we wanted to send the value of a
form element with name I<extra>:

 <input name="extra" type="hidden" value="secret">

If we specify the last argument to I<InstallAC> as
I<document.f.extra.value> (with no quotes), rather than I<"en">, then the
autocompletion handler will be called as
I<http://localhost/complete/search?hl=secret&client=suggest&js=true&qu=a>,
so that the value of I<hl> will be the value of the I<extra> element
of the originating form.

=back

=head1 Apache Handler

The autocompletion handler is specified through an
Apache configuration directive such as

  PerlModule Apache2::MyAutoComplete
  <Location /complete/search>
     SetHandler perl-script
     PerlResponseHandler Apache2::MyAutoComplete
  </Location>

Here, I<search> is the value specified by the fourth argument
to I<InstallAC>, as discussed above - the I<complete> part
of the location is hard-coded in I<ac.js>. The Perl module
which handles requests for this location has the form

  # module file Apache2/MyAutoComplete.pm
  package Apache2::MyAutoComplete;
  use base qw(Apache2::Autocomplete);
  # use whatever else
  
  sub expand {
    my ($self, $query) = @_;
    # decide what completions to return, based on the $query
    (lc $query, $names, $values, [""]);
  }
  
  sub handler {
    my $r = shift;
    my $ac = __PACKAGE__->new($r);
    $ac->run();
    return Apache2::Const::OK;
  }

This must inherit from I<Apache2::Autocomplete>. Within this
handler must be an I<expand> method:

  sub expand {
    my ($self, $query) = @_;
    # decide what completions to return, based on the $query
    (lc $query, $names, $values, [""]);
  }

which is to return a list of 4 elements
to be used for autocompletion of the I$query> argument
passed in from the form. This list has the
following elements:

=over

=item * $query

This is the query as returned to the frontend script
(typically converted to lowercase)

=item * $names

This is an array reference of results to be used as the list of
suggested completions.

=item * $values

This is an array reference of values that are usually shown on
the right-hand side of the drop-down box in the front end;
Google uses it for the estimated result count.

=item * $prefix

As discussed in L<JavaScript::Autocomplete::Backend>,
the purpose of I<$prefix> is not certain at this time. It
appears that if the array is empty, the drop-down menu appears
but the word in the input box itself is not completed,
while if the array is not empty (for example,
contains an empty string as its only element), the word
in the input box is completed as well.

=back

The Apache handler itself:

  sub handler {
    my $r = shift;
    my $ac = __PACKAGE__->new($r);
    $ac->run();
    return Apache2::Const::OK;
  }

creates the object and calls the I<run> method on it, which
returns the autocomplete results in the form of JavaScript code that
the original form then uses to fill in the suggestions.

=head1 Methods

The following methods are available.

=over

=item * my $ac = __PACKAGE__-E<gt>new($r);

This creates the object, and takes a mandatory