view release on metacpan or  search on metacpan

lib/Alien/GvaScript/AutoCompleter.pod  view on Meta::CPAN

  var myAutocompleter = new GvaScript.Autocompleter(datasource, options);

=head2 Datasources

=head3 Origin

A datasource may be

=over

=item a plain string

The string is taken as a base URL. Whenever a suggestion list is needed,
the autocompleter will send an Ajax requests to that URL, concatenated with 
the current value in the associated field. So for example if we have

  var ac = new GvaScript.Autocompleter("/myapp/completion?search=");
  ..
  <input name="someInput" onfocus="ac.complete(this)">

and user has typed C<ab> in the input field, then an Ajax request
will be sent to C</myapp/completion?search=ab>.

The server should return a JSON array, in the format explained below.

=item a callback function

That function will be called, with the current value of the field
as single argument.

=item an array

The array is taken as in-memory datasource. The returned suggestion
list is either the complete array (when C<options.ignorePrefix> is true)
or just the list of items that are prefixed by the current value 
of the field. See also C<options.caseSensitive>.

=item an object (JSONP)

Useful when accessing data on a different domain via JSONP services.

  Ex :   { json_url: 'http://search.yahooapis.com/WebSearchService/V1/relatedSuggestion?appid=YahooDemo&query=?1&output=json&callback=?2',
           json_list: 'ResultSet/Result' }

The object should hold details of the JSONP service to be called. 

C<json_url> : url to call with placeholders (?1, ?2) for value to look for and callback method respectively.

C<json_list> : path to the list in the json response

=back

=head3 Format of suggestions returned by datasources

Datasources should return a list of suggestions in the form
of a Javascript array (in case of Ajax requests, the response 
should be a JSON body containing a single array). 

For each suggestion in the array, the autocompleter needs
a I<label> (an HTML fragment to display in suggestion
dropdown lists) and a I<value> (a plain string to put into
the text field when the suggestion is selected). So 
each suggestion may be either

=over

=item a plain string

this string will be used both as label and as value.

=item an inline object

this object is supposed to have a C<label> property and a 
C<value> property. Actually, these are the default names for
the properties; they can be changed in the constructor options.

The C<label> property may contain rich HTML, i.e. including
formatting tags.

=back


=head2 Options

The options to construct an autocompleter object are :

=over

=item minimumChars

How many characters are needed before trying to find suggestions.

=item labelField

Name of the field that contains the HTML to display
(default is C<label>).

=item valueField

Name of the field that contains the value to put in input element
(default is C<value>).

=item autoSuggest

Boolean value; toggles whether suggestions are displayed automatically
when available (true by default). If false, suggestions are only
displayed when the C<ARROW_DOWN> key is pressed.


=item autoSuggestDelay

How many milliseconds to wait after a keypress before displaying 
suggestions. Default is 200.

=item typeAhead

If true (the default), the current suggestion will be automatically 
inserted into the input element.

=item maxHeight