%META:TOPICINFO{author="TWikiContributor" date="1432932395" format="1.1" version="$Rev$"}%
---+!! Autocomplete Plugin
<!--
   Contributions to this plugin package are appreciated. Please update this 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 extension in the SVN repository.
-->
<sticky>
<div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div>
<div style="float:right; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
<img src="%PUBURLPATH%/%WEB%/%TOPIC%/autocomplete-screenshot.png" alt="Autocomplete screenshot" width="176" height="86" />
</div>
</sticky>
%SHORTDESCRIPTION%

---++ Introduction

This TWiki plugin adds an autocomplete input field type to TWiki forms and TWiki applications. Start typing to get a list of items to choose from, or click on the pulldown button next to the input field to see all items.

#InTWikiForms
---++ Use Autocomplete in !TWikiForms

This package adds an =autocomplete= type to %SYSTEMWEB%.TWikiForms:

| *Type* | *Description* | *Size* | *Value* |
| =autocomplete= | <img src="%PUBURLPATH%/%WEB%/AutocompletePlugin/autocomplete-screenshot.png" alt="screenshot-small" width="176" height="86" align="right" style="margin-left:20px;" /> Autocomplete input field. Start typing to get a list of items to choose from, or click on the pulldown button to see all items. %IF{ "'%BASETOPIC%'='TWikiForms'" then="[[AutocompletePlugin][See details]]." }% | Size of input field in number of characters | Comma-space separated list of autocomplete options |
| =autocomplete+restrict= | Autocomplete, where input is restricted to list of autocomplete options. The value in the input field will be cleared if it does not match one of the autocomplete options. Partial input is expanded - for example if one of the options is "JavaScript" and the user typed "ja", the input field is expanded to "JavaScript" on focus loss. %IF{ "'%BASETOPIC%'='TWikiForms'" then="[[AutocompletePlugin][See details]]." }% |||
| =autocomplete+values= | Like =autocomplete=, allowing definition of inserted values that are different to the displayed autocomplete options. An autocomplete option is defined as =value: title=, where the =value= is the text inserted into the input field when picking the =title= option. For example:%BR% =&#124; Field 9 &#124; autocomplete+values &#124; 3 &#124; One, 2: Two, III: Three &#124; Various values formats &#124;= %BR% shows autocomplete options <form><select size="3" style="font-size: 90%;"><option>One</option><option>Two</option><option>Three</option></select></form> but the inserted values of autocomplete options =Two= and =Three= are =2= and =III=, respectively. %IF{ "'%BASETOPIC%'='TWikiForms'" then="[[AutocompletePlugin][See details]]." }% %BR% __Note:__ Autocomplete types can be combined: =autocomplete+restrict+values= |||

__Note:__ The field attributes =M= (for mandatory fields), and =H= (for hidden fields) are supported. In addition, the =key="value"= parameters of the AUTOCOMPLETE variable can be specified as well, such as =style="color: blue;"=. If combined, the =key="value"= parameters must be specified after the M and H attributes.

Example form definition:

| *Name:* | *Type:* | *Size* | *Values:* | *Tooltip message:* | *Attributes:* |
| Marital Status | autocomplete+restrict | 50 | Single, Engaged, Married, It's complicated, Divorced | Specify marital status | M style="color: blue;" |

#InHtmlForms
---++ Use Autocomplete in HTML Forms

You can also use the autocomplete input field directly in your HTML forms, without having to write any code. Just include this in the topic text:
<verbatim>
<form action="...">
%AUTOCOMPLETE{ name="Mood" value="Indifferent" options="Happy, Indifferent, Confused, Unhappy, Angry" size="10" }%
<form>
</verbatim>
This will show an HTML input field named "Mood" and an autocomplete pulldown when typing.

%INCLUDE{ "VarAUTOCOMPLETE" section="parameters" }%

Test: (this only works if the !AutocompletePlugin is installed and enabled)

<form>
%AUTOCOMPLETE{ name="Mood" value="Indifferent" options="Happy, Indifferent, Confused, Unhappy, Angry" size="10" }%
</form>

---++ Plugin Installation &amp; Configuration

You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the TWiki server.

__Note:__ The older TWiki:Plugins.AutoCompletePlugin (with upper case "C") has similar functionality. This new plugin removes the dependency on the !YahooUserInterfaceContrib, and has a simple syntax that is more in line with other TWiki form input types. Use one or the other plugins, they cannot be installed and used together.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * 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 Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/AutocompletePlugin.txt== | Plugin topic |
        | ==data/TWiki/VarAUTOCOMPLETE.txt== | Variable documentation topic |
        | ==pub/TWiki/AutocompletePlugin/*.gif== and ==*.png== | Image files |
        | ==lib/TWiki/Plugins/AutocompletePlugin.pm== | Plugin Perl module |
      * Set the ownership of the extracted directories and files to the webserver user.

   * Plugin configuration:
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.

   * Test if the configuration is successful:
      * See example in [[#InHtmlForms][Use Autocomplete in HTML Forms]]

   * If you run TWiki-6.0.1 or older and want to use key="value" parameters in field attributes of %SYSTEMWEB%.TWikiForms, you need to patch the core TWiki. Patch for =lib/TWiki/Form.pm=:
<blockquote>
<verbatim>
--- lib/TWiki/Form.pm	(revision 28279)
+++ lib/TWiki/Form.pm	(working copy)
@@ -220,7 +220,10 @@
 # Returns array of arrays
 #   1st - list fields
 #   2nd - name, title, type, size, vals, tooltip, attributes
-#   Possible attributes are "M" (mandatory field)
+# Possible attributes are:
+#   "M" (mandatory field - DEPRECATED - now mandatory="1"),
+#   "H" (hidden field - DEPRECATED - now hidden="1"),
+#   followed by type-specific name="value" configuration pairs
 sub _parseFormDefinition {
     my( $this, $meta, $text, $options ) = @_;
     $options ||= {};
@@ -279,9 +282,27 @@
 
             $tooltip ||= '';
 
+            # Item7577: TWikiForms field types with configure attributes:
+            # Attributes are represented by key="value" parameters.
+            # Example attributes cell: | mandatory="1" style="color: blue;" |
+            # Legacy single character attribute flags M and H are supported as well.
+            # Example attributes cell: | M style="color: blue;" |
+            # results in:
+            # - $attributes: 'M'
+            # - $parameters: TWiki::Attrs object with:
+            #   { mandatory => '1', style => 'color: blue;' }
             $attributes ||= '';
-            $attributes =~ s/\s*//go;
-            $attributes = '' if( ! $attributes );
+            my $parameters = '';
+            if( $attributes =~ s/([a-zA-Z0-9]+\=.*)$// ) {
+                $parameters = $1;
+            }
+            $parameters .= ' hidden="1"' if( $attributes =~ /H/ );
+            $parameters .= ' mandatory="1"' if( $attributes =~ /M/ );
+            require TWiki::Attrs;
+            $parameters = new TWiki::Attrs( $parameters );
+            $attributes = '';
+            $attributes .= 'H' if( $parameters->{hidden} );
+            $attributes .= 'M' if( $parameters->{mandatory} );
 
             my $definingTopic = "";
             if( $title =~ /\[\[(.+)\]\[(.+)\]\]/ )  {
@@ -305,6 +326,7 @@
                   value => $vals,
                   tooltip => $tooltip,
                   attributes => $attributes,
+                  parameters => $parameters,
                   definingTopic => $definingTopic,
                   web => $this->{web},
                   topic => $this->{topic}
@@ -612,8 +634,8 @@
     foreach my $fieldDef ( @{$this->{fields}} ) {
         my $fm = $meta->get( 'FIELD', $fieldDef->{name} );
         next unless $fm;
-        my $fa = $fm->{attributes} || '';
-        unless ( $fa =~ /H/ ) {
+        my $fp = $fm->{parameters};
+        unless ( $fp && $fp->{hidden} ) {
             $fieldFound = 1;
             my $row = $rowTemplate;
              # Legacy; was %A_TITLE% before it was $title
</verbatim>
</blockquote>

%ENDTWISTY%

---++ Plugin Info

   * Set SHORTDESCRIPTION = Autocomplete input field, for use in TWiki forms and TWiki applications

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Author: | TWiki:Main.PeterThoeny, [[http://twiki.org/][TWiki.org]] |
|  Copyright: | &copy; 2013-2014 Wave Systems Corp. %BR% &copy; 2013-2015 TWiki:Main.PeterThoeny %BR% &copy; 2013-2015 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Sponsor: | [[http://www.wave.com/][Wave Systems Corp.]] |
|  Version: | 2015-05-29 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}% "
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2015-05-29: | TWikibug:Item7604: Switch from GPL v2 to v3 |
|  2014-12-10: | TWikibug:Item7556: Support additional input field attributes max, min and translate |
|  2014-10-17: | TWikibug:Item7556: Support additional input field attributes pattern and title; doc fixes |
|  2014-10-13: | TWikibug:Item7556: Support key="value" parameters in field attributes of TWiki form fields |
|  2014-10-08: | TWikibug:Item7556: Add =selectstyle= and =containerstyle= parameters |
|  2014-10-06: | TWikibug:Item7556: Support input field attributes: class, formname, id, maxlength, onblur, onfocus, onchange, onselect, onmouseover, onmouseout, placeholder, spellcheck, style, tabindex |
|  2014-10-04: | TWikibug:Item7556: Add =autocomplete+restrict= type |
|  2014-10-04: | TWikibug:Item7556: Fix format issue where =autocomplete+values= row did not show up in !TWikiForms topic |
|  2014-10-03: | TWikibug:Item7556: Fix bug where multiple autocomplete on same topic would overwrite each other's options |
|  2014-10-02: | TWikibug:Item7556: Support for autocomplete options with =value: title= syntax |
|  2014-10-01: | TWikibug:Item7556: Initial version of !AutocompletePlugin |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.2 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  [[TWiki:Plugins.Benchmark][Plugin Benchmark]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  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, %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiForms, %SYSTEMWEB%.TWikiPlugins

%META:FILEATTACHMENT{name="autocomplete-screenshot.png" attachment="autocomplete-screenshot.png" attr="h" comment="" date="1412217329" path="autocomplete-screenshot.png" size="2854" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="pick.gif" attachment="pick.gif" attr="h" comment="" date="1412057901" path="pick.gif" size="135" user="TWikiContributor" version="1"}%
