Skip to content
This repository has been archived by the owner on May 2, 2023. It is now read-only.
/ tokchi Public archive

A jQuery plugin that brings Mac OS style tokens to your web input fields

License

Notifications You must be signed in to change notification settings

tiguchi/tokchi

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

41 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Tokchi

jQuery plugin that adds Mac OS X style tokens or Android style chips to a text input field, including an auto-completion dropdown box that shows up as you type.

Token example

This plugin was mainly created for a keyword-based search bar that automatically recognizes keywords and replaces them with MacOS-style input field tokens.

What else is it good for?

Email Recipients

Tokchi can also be used for recognizing recipients from a contacts database:

Token example

Just take a look at demo/email.html.

Online Communities: @/+User Name

Similar to Google+ or Facebook auto-completion, Tokchi could also be used for dynamic message input fields in order to select and highlight the name of a community member you want to include in a message.

Usage

This plugin adds a new jQuery function called tokchify that accepts an options parameter:

$('#my-search-bar').tokchify({
    onSearchKeyword : function (tokchi, keyword) {
        var result = doSomeSearch(keyword);
        tokchi.setSearchResult(result);
    }
});

That's almost enough to set up a very basic Tokchi input field instance. Of course you also want to customize the heck out of it. Take a look at the HTML and CSS files in the demos directory for getting some inspiration.

Making it Pretty

One more thing you need to do is define a couple of CSS classes:

  • tokchi-token styles a <div> tag that wraps a token
  • tokchi-dropdown is the class that styles a floating <ul> which contains the auto-completion suggestion items
  • tokchi-dropdown-item is the class that styles an auto-completion suggestion list item
  • tokchi-dropdown-item-selected is added to the currently selected auto-completion suggestion list item

You can also take a shortcut and just use the provided CSS file css/tokchi.css.

Initialization Options

The tokchify function accepts an options argument with any of the following properties:

Property Type Description
autoFocus boolean If set to true (= default), the Tokchi search bar is given focus when ready.
onReady function(tokchi) Called when Tokchi object is ready. See methods section below for available Tokchi methods.
onSearchKeyword function(tokchi, keyword) Keyword search handler function. Must call tokchi.setSearchResult(result) when search result is available.
onChange function(tokchi) Called when the user has added or removed one or more tokens from the input field.
onEdit function(tokchi, event) Callback for text editing events (key down, key up, key press). If this function returns false the event will be suppressed and the typed character is ignored.
onCreateToken function(tokchi, tokenHTMLNode, tokenObj) Function that adds the label and optional other content to a new token.
onCreateDropdownItem function(tokchi, itemHTMLNode, resultItem) Function that adds the label and optional other content to an auto-completion dropdown list item.
onUnwrapToken function(tokchi, tokenHTMLNode, tokenObj) Function that returns the token label string in case a token gets "unwrapped" for editing.
onPressReturn function(tokchi) Called when the return key has been pressed in the input field, while the auto-completion dropdown box is closed. Override this method if you want to act on this event, e.g. send the message from the input field to a server. This function is expected to return a boolean. If it returns true the enter key press event won't be propagated to the input field, essentially suppressing line breaks in the input.
onTokenAdded function(tokchi, tokenObj) Event handler function that is ontified about added tokens.
dropdownElement string or DOMNodeElement Optional <ul> container object for the suggestion dropdown box. Can be a CSS selector string or an actual DOM node element. If not specified, an element will be automatically created and added as a sibling to the search input field.
cssClasses object Contains an internally used map of the following CSS class names: tokchi-token, tokchi-token-close-button, tokchi-dropdown, tokchi-dropdown-item and tokchi-dropdown-item-selected.
dropdownStyle string follows = dropdown box will open up under current cursor position, fixed = dropdown box will appear under input field.
searchKeywordDelimiter RegExp Optional regular expression for detecting boundaries between keywords to search for. By default this regex covers white-space and western punctuation. If set to null only existing token objects act as boundaries.

The source file src/jquery.tokchi.js contains more detailed documentation for each option (see defaultOptions object).

Tokchi Object Methods

The Tokchi object is usually exposed to even handlers such as onCreateToken (see above). You can also call methods via jQuery, e.g.:

var value = $('.tokchi-input').tokchify('getValue');

Method Arguments Description
setSearchResult array 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.
addToken object Programmatically adds a token to the end of the input field.
removeToken DOMElementNode Programmatically removes a token DOM element node from the input field, and cleans up the markup of the input field.
setValue string or array Sets the input field value. String arguments are used as text value for the field. Array arguments are expected to be sequences of strings and / or token objects (see getValue function). If no argument is specified the input field will be cleared.
getTokens Returns a list of all token objects that are currently embedded in the input field.
getValue 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?' ]

Input Field Attributes

The Tokchi input field element can have the optional attribute data-value that provides a JSON array which serves as the initial input field value. Please read the documentation for getValue and setValue in order to learn about the expected content of that array.

About

A jQuery plugin that brings Mac OS style tokens to your web input fields

Resources

License

Stars

Watchers

Forks

Packages

No packages published