/ 
HTML-Controls-0.1
/ HTML::Controls::ACString

NAME

HTML::Controls::ACString - clas for an auto-completing string control

SYNOPSIS

my $localAC=HTML::Controls::ACString->new('name1',\@completions,{jsurl=>'/js'});
my $AJAXAC=HTML::Controls::ACString->new('name2',$completion_url,{jsurl=>'/js'});

This class implements a string control with auto-completion capabilities using the Prototype and script.aculo.us JavaScript libraries.

Note: right now it does not use HTML::Prototype or Template::Plugin::HTML::Prototype, but it might in the future to simplify template maintenance.

USAGE REQUIREMENTS

For the generated controls to work, you must serve the appropriate JavaScript libraries under the URL that you specify as the jsurl option to the constructor. The files needed are: prototype.js from http://prototype.conio.net/; controls.js, effects.js from http://script.aculo.us/.

If you use the AJAX auto-completer, you will need to handle POST requests to the URL you gave to the constructor and return XML documents having a <ul> root element and the various completion possibilities as <li> children. See http://wiki.script.aculo.us/scriptaculous/show/Ajax.Autocompleter for details.

VALUE FORMAT

Just a scalar, this class derives from HTML::Controls::String.

REDEFINED PUBLIC METHODS

new

The constructor. Takes the control's name, a completion specification, and various options.

The completion can be specified as either a reference to an array containing strings, in which case the control will use the "local auto-completer"; or as a scalar containing a URL to use for the AJAX auto-completer (see "USAGE REQUIREMENTS").

The options are passed as a hash reference. The hash must contain a jsurl key, whose value must be the URL under which the JavaScript libraries can be found (see "USAGE REQUIREMENTS"). If the control is using the "local auto-completer", these other options can be passed:

choices

how many choices to present to the user, at most. Defaults to 4.

ignore_case

if case should be ignored while looking for completions. Defaults to true.

partial_chars

how many characters to enter before triggering a partial match. Defaults to 2.

whether to search for completions at the beginning of every word in every item, or just at the beginning of each whole item. Defaults to true, which selects the first behaviour.

if both this and partial_search are true, search for completions anywhere in each item. Defaults to false.

See also "_ac_local_opts", "_ac_local_defaults", "_ac_ajax_opts" and "_ac_ajax_defaults" to change recognized options and defaults in your sub-classes.

REDEFINED PROTECTED METHODS

_head_template_name

Returns 'acstring-head.wt'. The stock template outputs the <script> elements to load the JavaScript libraries, and a CSS fragment to give a basic style to the completions' pop-up.

_head_template_parms

Calls the inherited method, then "_add_template_parms" to add the data needed for the auto-completer.

_body_template_name

Returns 'acstring-head.wt'. The stock template outputs the <input> element, the <div> for the completions, and the JavaScript call to attach the auto-completer.

_body_template_parms

Calls the inherited method, then "_add_template_parms" to add the data needed for the auto-completer.

ADDITIONAL METHODS

_add_template_parms

This is a utility method, called by both "_body_template_parms" and "_head_template_parms". It adds to the passed hash reference:

jsurl

The URL for the JavaScript libraries

acstyle

'local' or 'ajax'

acitems

if using the "local auto-completer", the array of possible completions

acurl

if using the AJAX auto-completer, the URL to call to obtain the completions

opts

the options hash, as passed to the constructor, with missing values filled in by defaults.

_ac_local_opts

Returns a list of acceptable option names for the "local auto-completer" (choices, partial_search, full_search, partial_chars, ignore_case).

_ac_local_defaults

Returns a hash (not a reference) containing default values for all the options returned by "_ac_local_opts". See "new" for the values.

_ac_ajax_opts

Returns a list of acceptable option names for the AJAX auto-completer. Right now, the empty list.

_ac_ajax_defaults

Returns a hash (not a reference) containing default values for all the options returned by "_ac_ajax_opts". Right now, the empty hash.

COPYRIGHT

Copyright 2005 Gianni Ceccarelli, All Rights Reserved.

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