jQuery Plugin For Mac OS-style Token Input with Autocomplete Support - Tokchi

File Size: 38.8 KB
Views Total: 1367
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
jQuery Plugin For Mac OS-style Token Input with Autocomplete Support - Tokchi

Tokchi is a robust jQuery plugin used for converting a regular input field into a Mac OS- or Android-style token input that allows the users to select multiple items from a predefined list, using autocompletion as they type to find each item. 

More examples:

How to use it:

1. Download the tokchi plugin and include the JavaScript file jquery.tokchi.js onto the webpage.

<script src="//code.jquery.com/jquery-1.11.3.min.js"></script>
<script src="src/jquery.tokchi.js"></script>

2. Create a normal text field for the token input.

<input class="input" id="demo">

3. Initialize the plugin and we're ready to go.

$('#demo').tokchify()

4. Default options.

allowLineBreaks : false,

// If set to true (= default), the Tokchi search bar is given focus when ready.
autoFocus : true,

/**
 * Callback that gets invoked when the Tokchi instance is ready.
 * 
 * @param tokchi Tokchi instance.
 */ 
onReady : function (tokchi) {
},

/**
 * Callback for a change (addition / removal) of tokens in input field.
 * 
 * @param tokchi Tokchi instance.
 */ 
onChange : function (tokchi) {
},

/**
 * Callback for return button press.
 * 
 * @param tokchi Tokchi instance.
 * @return True in order to suppress return press event propagation
 *      to input field.
 */ 
onPressReturn : function (tokchi) {
    return true;
},

/**
 * Keyword search handler.
 *
 * Must call `tokchi.setSearchResult(result)` when search result is available.
 * 
 * @param tokchi Tokchi instance.
 * @param token Keyword to search.
 */ 
onSearchKeyword : function (tokchi, keyword) {
    tokchi.setSearchResult([{label : keyword}]);
},

/**
 * Adds a label and optional other content to a token that is about to be
 * added to the input field.
 * 
 * Override this option if your search result object properties differ from
 * the default, i.e. the presence of `tokenObj.label` is expected for
 * the label text. You can also customize the appearance and add more
 * elements to the `tokenHTMLNode`, such as a small profile picture or
 * your own custom close button to remove the token.
 * 
 * @param tokchi Tokchi instance.
 * @param tokenHTMLNode Token node to add label to.
 * @param tokenObj Token data object from search result.
 */ 
onCreateToken : function (tokchi, tokenHTMLNode, tokenObj) {
    $(tokenHTMLNode).text(tokenObj.label).append(
        $('<span>')
            .text('⊗')
            .addClass(tokchi._options.cssClasses['token-close-button'])
            .click(function () {
                tokchi.removeToken(tokenHTMLNode);
            })
    );
},

/**
 * Handler that get called when a token is edited and needs to be reverted into
 * its text representation. This function is responsible for providing the text
 * representation of the token.
 * 
 * @param tokchi Tokchi instance.
 * @param tokenHTMLNode Token node that is about to be unwrapped.
 * @param tokenObj Token data object from search result.
 * 
 * @return Unwrapped token text.
 */ 
onUnwrapToken : function (tokchi, tokenHTMLNode, tokenObj) {
    return tokenObj.label;
},

/**
 * Adds a label and other optional content to the dropdown item of each
 * search result object.
 * 
 * Override this function to create your own customizations for the
 * appearance of each dropdown item.
 * 
 * @param tokchi Tokchi instance.
 * @param itemHTMLNode Dropdown item node to add label to.
 * @param resultItem Token search result object.
 */ 
onCreateDropdownItem : function (tokchi, itemHTMLNode, resultItem) {
    $(itemHTMLNode).text(resultItem.label);
},

cssClasses : {
    'dropdown' : 'tokchi-dropdown',
    'dropdown-item' : 'tokchi-dropdown-item',
    'dropdown-item-selected' : 'tokchi-dropdown-item-selected',
    'token' : 'tokchi-token',
    'token-close-button' : 'tokchi-token-close-button'
},

/**
 * `follows` = Dropdown box will open up under current cursor position
 * `fixed` = Dropdown box will appear under input field
 */ 
dropdownStyle : 'follows',

/**
 * Regular expression for finding boundary between search keywords.
 * 
 * Can be set to `null` in order to ignore word boundaries. In this
 * case the whole text input at the current cursor position is
 * taken into account, while only previously inserted tokens act
 * as boundaries.
 */ 
searchKeywordDelimiter : /[\s\u00A0,.:;\?!\)\(\[\]\{\}"`<>+\-]/

5. API methods.

// Programmatically adds a token to the end of the input field.
$('#demo').tokchify('addToken', tokenObj)

// Programmatically removes a token from the input field.
$('#demo').tokchify('removeToken', tokenObj)

// Returns a list of all token objects that are currently embedded in the input field.
$('#demo').tokchify('getTokens')

// Returns the current input text as an array of strings and token objects in the order of appearance. 
// HTML formattings will be ignored. 
// Example: [ 'Hello ', {id : 123, label : '+Ferris'}, '! How are you?' ]
$('#demo').tokchify('getValue')

// Callback method for onSearchKeyword that sets the auto-completion result set of a token keyword search. 
// The expected argument can be null or an array of objects that contain the individual token labels and arbitrary other properties (e.g. an id for identifying a token). 
// The default label property is called label.
$('#demo').tokchify('setSearchResult', {array})

Change log:

v1.1.0 (2016-02-12)

  • Tokchi methods can be called through jQuery tokchify function call
  • Added new events onEdit and onTokenAdded
  • added focus method
  • Bugfixes

v1.0.1 (2015-11-28)

  • Bugfixes
  • Input field can have an additional attribute named data-value which provides a JSON array used as initial input field value. The deserialized array is automatically passed on to the setValue method on construction.

2015-11-21

  • v1.0

2015-11-13

  • Fix for Firefox editing and cursor movement bug (fixes T41)

This awesome jQuery plugin is developed by tiguchi. For more Advanced Usages, please check the demo page or visit the official website.