%META:TOPICINFO{author="ProjectContributor" date="1315479654" format="1.1" version="1"}%
%META:TOPICPARENT{name="JQueryPlugin"}%
---+ %TOPIC%
%JQPLUGINS{"autocomplete"
  format="
    Homepage: $homepage <br />
    Author(s): $author <br />
    Version: $version
  "
}%

%STARTSECTION{"summary"}%
<div class="foswikiWarningMessage">
Warning: This plugin is deprecated. Please use the autocomplete library as part of JQueryUI.
</div>

Autocomplete an input field to enable users quickly finding and selecting some
value from a set provided by the server.
By giving an autocompleted field focus or entering something into it, the
plugin starts searching for matching entries and displays a list of values to
choose from. By entering more characters, the user can filter down the list to
better matches.
This can be used to enter previous selected values, eg. for tags, to complete
an address, eg. enter a city name and get the zip code, or maybe enter email
addresses from an addressbook.

See also [[%SYSTEMWEB%.JQueryAjaxHelper][JQueryjaxHelper]] for examples on how to integrate autocompletion
into Foswiki.

%X% *Caution*: the original author of this plugin discontinued to support this plugin. A replacement has been added to
the JQueryUI package. Here is a [[http://www.learningjquery.com/2010/06/autocomplete-migration-guide][Migration Guide]] for the autocompletion plugin.
%ENDSECTION{"summary"}%

---++ Usage

Autocompletion is activated for HTML input elements whose ==autocomplete== attribute value does not equal =off=.
It can either be list of candidate values, or an URL, in which case candidate values are queried from an AJAX backend.
The current input prefix is provided via the =q= URL parameter. The backend must return a list of matching values
separated by newlines.

---++ Example
%JQREQUIRE{"autocomplete"}%

This example queries candidate values from a simple AJAX backend using the
wiki application in the =data= section of this topic.

See also JQueryTextboxList

First, here's the set of values we want to pick from:
   * backup
   * bash
   * emulation
   * games
   * irc
   * linux
   * mercurial
   * patches
   * perl
   * php
   * python
   * site
   * surfing
   * tag
   * test
   * foswiki
   * web
   * wiki
   * windows
   * windsurfing
   * wine

Here's the code that the client browser runs:

<div class="foswikiFormSteps">
  <div class="foswikiFormStep">
    <h3>Enter tags:</h3>
    <input class="foswikiInputField {multiple:true, matchCase:false, matchSubset:true, minChars:1}" size='42' autocomplete="%SCRIPTURL{"view"}%/%WEB%/%TOPIC%?section=data;skin=text" />
    <div class="foswikiFormDescription">
      Tags are suggested as you type. Separate multiple tags using a comma (,).
    </div>
  </div>
</div>

And here's the section of this topic that provides the data:
'%SEARCH{
 "^   \* (%ENCODE{"%URLPARAM{"q"}%" old="$comma, " new="|,"}%).*$"
 web="%WEB%"
 topic="%TOPIC%"
 type="regex"
 multiple="on"
 nonoise="on"
 format=" $pattern(.*?\* ([^ \n]*).*) "
 separator="$n"
}%'
<verbatim class="tml">
%STARTSECTION{"data"}%%SEARCH{
 "^   \* (%ENCODE{"%URLPARAM{"q"}%" old="$comma, " new="|,"}%).*$"
 web="%WEB%"
 topic="%TOPIC%"
 type="regex"
 multiple="on"
 nonoise="on"
 format=" $pattern(.*?\* ([^ ]*).*) "
 separator="$n"
}%
%ENDSECTION{"data"}%
</verbatim>

---++ Alternative implementation using !FilterPlugin

If you don't have Foswiki 1.1, you can use the
Foswiki:Extensions.FilterPlugin which has the capability to filter a list
based on a regular expression passed from Javascript.

<div class="foswikiFormSteps">
  <div class="foswikiFormStep">
    <h3>Enter tags:</h3>
    <input class="foswikiInputField {multiple:true, matchCase:false, matchSubset:true, minChars:1}" size='42' autocomplete="%SCRIPTURL{"view"}%/%WEB%/%TOPIC%?section=data_fp;skin=text" />
    <div class="foswikiFormDescription">
      Tags are suggested as you type. Separate multiple tags using a comma (,).
    </div>
  </div>
</div>

<verbatim class="tml">
%STARTSECTION{"data_fp"}%%FORMATLIST{
" 
  backup
  bash
  emulation
  games
  irc
  linux
  mercurial
  patches
  perl
  php
  python
  site
  surfing
  tag
  test
  foswiki
  web
  wiki
  windows
  windsurfing
  wine
"
 include=".*%URLPARAM{"q"}%.*"
 split="\n"
 format=" $1 "
 separator="$n"
}%%ENDSECTION{"data_fp"}%
</verbatim>
