%META:TOPICINFO{author="TWikiContributor" date="1412221793" format="1.1" version="$Rev$"}%
---+!! !AutoCompletePlugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/AutoCompletePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/AutoCompletePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.

One line description, required for extensions repository catalog.
   * Set SHORTDESCRIPTION = Auto-complete input field type for TWiki Forms (NO LONGER MAINTAINED, replaced by AutocompletePlugin)
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Overview

This plugin provides [[http://en.wikipedia.org/wiki/Autocomplete][autocomplete]] functionality for input field with select options as you type. It is based on Yahoo's User Interface Library.

All this plugin does is implement Arthur Clemens' TWiki:Plugins/AutoCompleteAddOn as a plugin, which allows users to provide an autocomplete text box using the =%<nop>AUTOCOMPLETE%= syntax, and also in %SYSTEMWEB%.TWikiForms (shown below).

<img src="%ATTACHURLPATH%/AutoCompletePluginScreenshot.png" alt="screenshot.png" />

__Note:__ This plugin is no longer maintained, it is replaced by the TWiki:Plugins.AutocompletePlugin (with lowercase "c").

---++ Usage

Before you can use this plugin, you need to set up some data for the autocomplete. Examples can be found at Sandbox.AutoCompletePluginTestData.

---+++ In Topics and Templates

This plugin expands the =%<nop>AUTOCOMPLETE{...}%= variable, which takes the parameters described in %TOPIC%#Parameters.

---+++ In !TWikiForms

To use this plugin in %SYSTEMWEB%.TWikiForms, create a form template as descibed in %SYSTEMWEB%.TWikiForms#Defining_a_Form. This plugin adds the =autocomplete= type of field. To pass the parameters required by the plugin, place them in the =Values= column. An example is shown below:

| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| Username | autocomplete | 25em | datatopic="Sandbox.AutoCompletePluginTestData" datasection="usernames" delimchar="," itemformat="item[0] + ' (' + item[1] + ')'" | |  | 

You can use many of same attributes as you would in topics, except the following:
   * =name=
   * =size=
   * =value=
   * =class=
   * =formname=

---+++ Parameters

| *Parameter* | *Comment* | *Default* | *Example* |
| =name= | A unique name for the textfield | required | =name="users"= |
| =datatopic= | The topic with data. Should be formatted as comma-separated string, or as an array of arrays (see Sandbox.AutoCompletePluginTestData#usernames for an example). Use with =datasection=. | required | =datatopic="Sandbox.AutoCompletePluginTestData"= |
| =datasection= | The topic section with data. Use with =datatopic=. | required | =datasection="usernames"= |
| =size= | The width of the input field in em or px. | =20em= | =size="20em" or size="200px"= |
| =value= | Default value of the input field | none | =value="%TOPIC%"= |
| =tabindex= | The tabindex of the textfield | none | =tabindex="2"= |
| =class= | Name of css class to add to the input field | none | =class="twikiInputField"= |
| =formname= | Name of the form which the input field is part of | none | =form="userlist"= |
| =itemformat= | The format of an item string in the autocomplete list. Use if the autocomplete list should display different names than the input field - for instance with full person names. The javascript input argument is =item=. | =item= | =itemformat="item[0] + ' (' + item[1] + ')'"= |
| =delimchar= | Used to accept multiple delimeted queries. | none | =delimchar=","= |
| =onblur=, =onfocus=, =onchange=, =onselect=, =onmouseover=, =onmouseout= | Javascript parameters for the textfield. | none | =onfocus="twiki.Form.clearBeforeFocusText(this);"= |
| =itemselecthandler= | Defines a javascript function to be executed when an item is selected. See http://developer.yahoo.com/yui/autocomplete/#customevents. | none | =itemselecthandler="submitJumpForm"= |

---+++ Example

If installed, the following should create an jump box (TWiki 4.2):

__Source:__
<verbatim>
<script type="text/javascript">
var SubmitJump = function(sType, aArgs) {
    document.myJumpForm.submit();
}
</script>
<form name="myJumpForm" action="%SCRIPTURLPATH{"view"}%/%BASEWEB%/%BASETOPIC%">%AUTOCOMPLETE{name="topic" datatopic="Sandbox.AutoCompletePluginTestData" onfocus="twiki.Form.clearBeforeFocusText(this);" onblur="twiki.Form.restoreBeforeFocusText(this);" datasection="topiclist" value="Jump" formname="myJumpForm" class="twikiInputField twikiInputFieldBeforeFocus"  itemselecthandler="SubmitJump" size="128px" }%</form>
</verbatim>

__Rendered:__
<script type="text/javascript">
var SubmitJump = function(sType, aArgs) {
    document.myJumpForm.submit();
}
</script>
<form name="myJumpForm" action="%SCRIPTURLPATH{"view"}%/%BASEWEB%/%BASETOPIC%">%AUTOCOMPLETE{name="topic" datatopic="Sandbox.AutoCompletePluginTestData" onfocus="twiki.Form.clearBeforeFocusText(this);" onblur="twiki.Form.restoreBeforeFocusText(this);" datasection="topiclist" value="Jump" formname="myJumpForm" class="twikiInputField twikiInputFieldBeforeFocus"  itemselecthandler="SubmitJump" size="128px" }%</form>

---++ Installation Instructions

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the extension home on twiki.org (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory.
      * Set the ownership of the extracted directories and files to the webserver user.
      * Install the dependencies (if any).

   * Plugin __configuration and testing__: 
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Configure additional plugin settings in the __Extensions__ section if needed.
      * Test if the installation was successful using the examples provided.


---++ Plugin Files

   | *File:* | *Description:* |
   | ==data/TWiki/AutoCompletePlugin.txt== | Documentation |
   | ==data/TWiki/VarAUTOCOMPLETE.txt== | Documentation |
   | ==lib/TWiki/Plugins/AutoCompletePlugin.pm== | Perl module |
   | ==data/Sandbox/AutoCompletePluginTestData.txt== | Test Data |
   | ==pub/TWiki/AutoCompletePlugin/AutoCompletePluginScreenshot.png== | Screenshot |
   | ==lib/TWiki/Plugins/AutoCompletePlugin/Config.spec== | Spec file for =configure= |


---++ Plugin Info

|  Plugin Author: | TWiki:Main.AndrewRJones |
|  Copyright: | &copy; 2007-2008, TWiki:Main.AndrewRJones <br /> &copy; 2007-2012 TWiki:TWiki.TWikiContributor |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Plugin Version: | 2012-11-12 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2012-11-12: | TWikibug:Item7020: Categorize TWiki Variable AUTOCOMPLETE -- TWiki:Main.PeterThoeny |
|  2011-05-14: | TWikibug:Item6701: Small fix in Config.spec -- TWiki:Main.PeterThoeny |
|  2011-05-01: | TWikibug:Item6701: Doc improvements -- TWiki:Main.PeterThoeny |
|  2010-04-01 | TWikibug:Item6415: Added VarAUTOCOMPLETE variable documentation topic -- TWiki:Main.PeterThoeny |
|  2008-09-12 | TWikibug:Item5745: Updated to use latest YUI (2.5.2); Fixed forms for 4.2; Fixed Jump Form example for 4.2 |
|  14585 | TWikibug:Item4469: Removed extra self-closing div-tag tail; Fixed Jump Form example |
|  14413 | TWikibug:Item4369: Allow users to define their own item select handler |
|  14391 | TWikibug:Item4356: Class names not being added |
|  14382 | TWikibug:Item4346: Added Javascript parameters (=onblur=, =onfocus=, etc) |
|  14381 | TWikibug:Item4345: Was adding 'null' after input if =delimchar= not set |
|  14379 | TWikibug:Item4342: Only sets correct size for one textfield in topic |
|  14290 | TWikibug:Item4304: Various bug fixes and enhancements |
|  14277 | TWikibug:Item4301: Initial release |
|  Dependencies: | <table border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">TWiki::Contrib::YahooUserInterfaceContrib</td><td align="left"> &gt;1.0</td><td align="left">Optional. If not found, will use files served from Yahoo! servers. See http://developer.yahoo.com/yui/articles/hosting/.</td></tr></table> |
|  [[TWiki:Plugins/Benchmark][Benchmarks]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, AutoCompletePlugin nn% |
|  Plugin Home: | http://twiki.org/cgi-bin/view/Plugins/AutoCompletePlugin |
|  Feedback: | http://twiki.org/cgi-bin/view/Plugins/AutoCompletePluginDev |
|  Appraisal: | http://twiki.org/cgi-bin/view/Plugins/AutoCompletePluginAppraisal |

__Related Topics:__ VarAUTOCOMPLETE, Sandbox.AutoCompletePluginTestData, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences
