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

%TOC%

---++ Description
%STARTSECTION{"summary"}%
Turns a text input into a list widget with autocompletion.
This plugin adds a new formfield type =textboxlist= to DataForms.
%ENDSECTION{"summary"}%

---++ Usage

An html input field can be turned into a textboxlist widget either using javascript or using the =jqTextboxList= css class.

Using javascript:

<verbatim class="html">
<input type="text" name="tags" />

<script>
jQuery(function($) {
  $("input[name='tags']").textboxlist(options);
});
</script>
</verbatim>

Using css and HTML5 data:

<verbatim class="html">
<input type="text" name="tags" class="jqTextboxList" data-container-class="..." data-sorting="..." ... />
</verbatim>

---++ Options

| *Name* | *Description* | *Default* |
| containerClass | css class of the widget container | jqTextboxListContainer |
| listValueClass | css class of values in the list | jqTextboxListValue |
| closeClass | css class of the close button of a list value | jqTextboxListClose |
| enableClose | boolean flag toggling the display of a close button on a list value | true |
| sorting | option to enable sorting of the list of values, can =true=, =false= or =manual= | manual |
| inputName | name of the input element used for list values; equals to the name of the original input field if undefined | undefined |
| resetControl | jquery selector to specify a reset button; will revert changes to the initial list of values | undefined |
| clearControl | jquery selector to specify a clear button that will empty the textboxlist | undefined |
| autocomplete | defines the source for tag suggestions displayed using a %SYSTEMWEB.JQueryUIAutocomplete widget; e.g. this can be an array or an url | undefined |
| onClear | method called when the list is cleared | undefined |
| onReset | method called when the list is resetted | undefined |
| onSelect | method called when a value is selected | undefined |
| onDeselect | method called when a value is removed from the list | undefined |

----++ Events

Instead of specifying callbacks using the =onSelect= or =onDeselect= options, custom events are emitted by the textboxlist widget
that your own code can be bound to.

Example:

<verbatim class="html">
<input type="text" class="jqTextboxList" id="mylist" />
<script>
jQuery(function($) {
  $("#mylist").on("SelectValue", function(value) {
    ...
  });
});
</script>
</verbatim>

| *Event* | *Parameters* | *Description* |
| <nop>SelectValue | value | triggered when a value is selected |
| <nop>DeleteValue | value | triggered when a value is deselected |

---++ Examples
%JQREQUIRE{"textboxlist"}%

---+++ Tagging
<form>
<div class="foswikiFormSteps">
  <div class="foswikiFormStep">
    <h3>Tags:</h3>
    <input type="text" class="foswikiInputField jqTextboxList" size="20" name="tags" value="%URLPARAM{"tags" multiple="on" separator=", " default="foo, bar, baz"}%" />
    <div class="foswikiGrayText">
       Type in some keywords
    </div>
  </div>
  <div class="foswikiFormStep">
    %BUTTON{"%MAKETEXT{"Submit"}%" icon="fa-check" type="submit"}%
    %CLEAR%
  </div>
</div>
</form>

---+++ Tagging with autocomplete suggestions

Note, that you will need [[https://foswiki.org/Extensions/FilterPlugin][FilterPlugin]] to run the example successfully. 

<form>
<div class="foswikiFormSteps">
  <div class="foswikiFormStep">
    <h3>Tags:</h3>
    <input class="foswikiInputField jqTextboxList" data-autocomplete="%SCRIPTURL{"view"}%/%WEB%/%TOPIC%?section=data;skin=text" id="example" size='42'  />
    <div class="foswikiFormDescription">
      Tags are suggested as you type.
    </div>
  </div>
</div>
</form>

---++ Backend Implementation
<verbatim class="tml">
%STARTSECTION{"data"}%%FORMATLIST{
  "admin,
   backup,
   bash,
   emulation,
   games,
   irc,
   linux,
   mercurial,
   patches,
   perl,
   php,
   python,
   site,
   surfing,
   tag,
   test,
   foswiki,
   web,
   wiki,
   windows,
   windsurfing,
   wine
  "
  split="\s*,\s*"
  header="["
  format="{\"value\":\"$1\"} "
  footer="]"
  separator=",$n"
  include="\s*%URLPARAM{"term"}%.*"
}%%ENDSECTION{"data"}%
</verbatim>
