AutoCompletePlugin < System

You are here: Foswiki>System Web>AutoCompletePluginEditAttach
---+!! !AutoCompletePlugin
<!--
One line description, required for extensions repository catalog.
    * Set SHORTDESCRIPTION = Provides an Autocomplete input field based on Yahoo's User Interface Library
-->
This plugin allows you to create an autocomplete input field based on Yahoo's User Interface Library.

This plugin originally implemented Arthur Clemens' Foswiki:Extensions/AutoCompleteAddOn as a extension, which allows users to provide an autocomplete text box using the =%<nop>AUTOCOMPLETE%= syntax, and also in %SYSTEMWEB%.DataForms (shown below), but has since grown in its own right.

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

%TOC%

---++ 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 !DataForms

To use this plugin in %SYSTEMWEB%.DataForms, create a form template as descibed in %SYSTEMWEB%.DataForms#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=

For a working example of this, see Sandbox.AutoCompletePluginFormExample.

---+++ 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="foswikiInputField"= |
| =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="foswiki.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:

__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="foswiki.Form.clearBeforeFocusText(this);" onblur="foswiki.Form.restoreBeforeFocusText(this);" datasection="topiclist" value="Jump" formname="myJumpForm" class="foswikiInputField foswikiInputFieldBeforeFocus"  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="foswiki.Form.clearBeforeFocusText(this);" onblur="foswiki.Form.restoreBeforeFocusText(this);" datasection="topiclist" value="Jump" formname="myJumpForm" class="foswikiInputField foswikiInputFieldBeforeFocus"  itemselecthandler="SubmitJump" size="128px" }%</form>

---++ Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.


---++ Debugging

Debug information will be generated if the following preference is set in [[%LOCALSITEPREFS%]]:

   * Set AUTOCOMPLETEPLUGIN_DEBUG = 1

__Note:__ Setting it here will have no effect.

---++ Plugin Info

|  Plugin Author(s): | Foswiki:Main.AndrewJones |
|  Copyright: | &copy; 2007 - 2011, Foswiki:Main.AndrewJones |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Plugin Release: | 1.2.1 |
|  Plugin Version: | 10530 (2011-01-13) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  12 Jan 2011 | Fixed bug in generated CSS in case the form name was a wiki word. |
|  05 Dec 2010 | Add a working example of using the plugin in a form |
|  07 Sept 2009 | Foswikitask:Item2009 - Remove debug setting from =configure= |
|  23 Mar 2009 | Foswikitask:Item1249 - Port to Foswiki as 1.0; Use latest YUI (2.7.0) |
|  12 Sept 2008 | 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 texfield in topic |
|  14290 | TWikibug:Item4304 - Various bug fixes and enhancements |
|  14277 | TWikibug:Item4301 - Initial release |
|  Dependencies: | <table class="foswikiTable" border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Foswiki::Contrib::YahooUserInterfaceContrib</td><td align="left"> &gt;=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> |
|  Plugin Home: | http://foswiki.org/Extensions/%TOPIC% |
|  Support: | http://foswiki.org/Support/%TOPIC% |

__Related Topics:__ [[%SYSTEMWEB%.Plugins][Plugins]], %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.DefaultPreferences, %USERSWEB%.SitePreferences

<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the feedback topic on foswiki.org instead. -->
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	AutoCompletePluginScreenshot.png	manage	0.1 K	21 May 2002 - 01:43	ProjectContributor	Screenshot
Topic revision: r1 - 13 Jan 2011, UnknownUser
System
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback