Skip to content
This repository was archived by the owner on Sep 10, 2023. It is now read-only.

Commit 8a8390e

Browse files
loopjloopj
committed
Migrate from gh-pages
1 parent 76dbc51 commit 8a8390e

File tree

3 files changed

+163
-9
lines changed

3 files changed

+163
-9
lines changed

‎README.md

+163-9
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,166 @@
1-
jQuery Tokeninput: A Tokenizing Autocomplete Text Entry
2-
=======================================================
31

4-
Overview
5-
--------
6-
Tokeninput is a jQuery plugin which allows your users to select multiple items from a predefined list, using autocompletion as they type to find each item. You may have seen a similar type of text entry when filling in the recipients field sending messages on facebook.
2+
# jQuery Tokeninput: A Tokenizing Autocomplete Text Entry
73

8-
Documentation, Features and Demos
9-
---------------------------------
10-
Full details and documentation can be found on the project page here:
4+
## Overview
115

12-
<http://loopj.com/jquery-tokeninput/>
6+
Tokeninput is a jQuery plugin which allows your users to select multiple items
7+
from a predefined list, using autocompletion as they type to find each item.
8+
You may have seen a similar type of text entry when filling in the recipients
9+
field sending messages on facebook.
10+
11+
## Features
12+
13+
- Intuitive UI for selecting multiple items from a large list
14+
- Easy to skin/style purely in css, no images required
15+
- Supports any backend which can generate JSON, including PHP, Rails, Django, ASP.net
16+
- Smooth animations when results load
17+
- Select, delete and navigate items using the mouse or keyboard
18+
- Client-side result caching to reduce server load
19+
- Crossdomain support via JSONP
20+
- Callbacks when items are added or removed from the list
21+
- Preprocess results from the server with the onResult callback
22+
- Programatically add, remove, clear and get tokens
23+
- Customize the output format of the results and tokens
24+
25+
## Screenshots
26+
27+
![List style](list-style.png)
28+
29+
Vertical list style item selection
30+
31+
![List style](facebook-style.png)
32+
33+
Facebook style item selection
34+
35+
## Installation & Setup
36+
37+
### Create a server-side script to handle search requests
38+
39+
Create a server-side script (PHP, Rails, ASP.net, etc) to generate your
40+
search results. The script can fetch data from wherever you like, for
41+
example a database or a hardcoded list. Your script must accept a GET parameter
42+
named `q` which will contain the term to search for. E.g.
43+
<http://www.example.com/myscript?q=query>
44+
45+
Your script should output JSON search results in the following format:
46+
47+
```javascript
48+
[
49+
{"id":"856","name":"House"},
50+
{"id":"1035","name":"Desperate Housewives"},
51+
...
52+
]
53+
```
54+
55+
You may optionally specify an attribute of "readonly" and set it to true if you
56+
would like some of the tokens to be non-removable:
57+
58+
```javascript
59+
[
60+
{"id":"856","name":"House","readonly":true},
61+
{"id":"1035","name":"Desperate Housewives"},
62+
...
63+
]
64+
```
65+
66+
Note that you may omit "readonly" on entities where it is not necessary. This
67+
attribute is acceptable wherever JSON entities are passed, e.g. .tokenInput("add")
68+
(see Methods section below).
69+
70+
### Include and initialize the plugin
71+
72+
Include jQuery and Tokeninput Javascript and stylesheet files on your page, and
73+
attach to your text input:
74+
Tokeninput stylesheet:
75+
76+
```html
77+
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
78+
<script type="text/javascript" src="yourfiles/jquery.tokeninput.js"></script>
79+
<link rel="stylesheet" type="text/css" href="yourfiles/token-input.css" />
80+
81+
<script type="text/javascript">
82+
$(document).ready(function () {
83+
$("#my-text-input").tokenInput("/url/to/your/script/");
84+
});
85+
</script>
86+
```
87+
88+
## Configuration
89+
90+
The tokeninput takes an optional second parameter on intitialization which
91+
allows you to customize the appearance and behaviour of the script, as well as
92+
add your own callbacks to intercept certain events. The following options are
93+
available:
94+
95+
### Search Settings
96+
97+
| Option | Description | Default |
98+
| ------ | ----------- | ------- |
99+
| `method` | The HTTP method (eg. GET, POST) to use for the server request. | `"GET"` |
100+
| `queryParam` | The name of the query param which you expect to contain the search term on the server-side. | `"q"` |
101+
| `searchDelay` | The delay, in milliseconds, between the user finishing typing and the search being performed. | `300` |
102+
| `minChars` | The minimum number of characters the user must enter before a search is performed. | `1` |
103+
| `propertyToSearch` | The javascript/json object attribute to search. | `"name"` |
104+
| `jsonContainer` | The name of the json object in the response which contains the search results. This is typically used when your endpoint returns other data in addition to your search results. Use `null` to use the top level response object. | `null` |
105+
| `crossDomain` | Force JSONP cross-domain communication to the server instead of a normal ajax request. Note: JSONP is automatically enabled if we detect the search request is a cross-domain request. | `false` |
106+
107+
### Pre-population Settings
108+
109+
| Option | Description | Default |
110+
| ------ | ----------- | ------- |
111+
| `prePopulate` | Prepopulate the tokeninput with existing data. Set to an array of JSON objects, eg: `[{id: 3, name: "test"}, {id: 5, name: "awesome"}]` to pre-fill the input. | `null` |
112+
113+
### Display Settings
114+
115+
| Option | Description | Default |
116+
| ------ | ----------- | ------- |
117+
| `hintText` | The text to show in the dropdown label which appears when you first click in the search field. | `"Type in a search term"` |
118+
| `noResultsText` | The text to show in the dropdown label when no results are found which match the current query. | `"No results"` |
119+
| `searchingText` | The text to show in the dropdown label when a search is currently in progress. | `"Searching..."` |
120+
| `deleteText` | The text to show on each token which deletes the token when clicked. If you wish to hide the delete link, provide an empty string here. Alternatively you can provide a html string here if you would like to show an image for deleting tokens. | `"&times;"` |
121+
| `animateDropdown` | Set this to `false` to disable animation of the dropdown | `true` |
122+
| `theme` | Set this to a string, eg "facebook" when including theme css files to set the css class suffix | |
123+
| `resultsLimit` | The maximum number of results shown in the drop down. Use `null` to show all the matching results. |`null` |
124+
| `resultsFormatter` | A function that returns an interpolated HTML string for each result. Use this function with a templating system of your choice, such as jresig microtemplates or mustache.js. Use this when you want to include images or multiline formatted results | `function(item){ return "<li>" + item.propertyToSearch + "</li>" }` |
125+
| `tokenFormatter` | A function that returns an interpolated HTML string for each token. Use this function with a templating system of your choice, such as jresig microtemplates or mustache.js. Use this when you want to include images or multiline formatted tokens. Quora's people invite token field that returns avatar tokens is a good example of what can be done this option. | `function(item){ return "<li><p>" + item.propertyToSearch + "</p></li>" }` |
126+
127+
### Tokenization Settings
128+
129+
| Option | Description | Default |
130+
| ------ | ----------- | ------- |
131+
| `tokenLimit` | The maximum number of results allowed to be selected by the user. Use `null` to allow unlimited selections. | `null` |
132+
| `tokenDelimiter` | The separator to use when sending the results back to the server. | `","` |
133+
| `preventDuplicates` | Prevent the user from selecting a token that has already been selected? | `false` |
134+
| `tokenValue` | The value of the token input when the input is submitted. Set it to `id` in order to get a concatenation of token IDs, or to `name` in order to get a concatenation of names. | `"id"` |
135+
136+
### Callbacks
137+
138+
| Option | Description | Default |
139+
| ------ | ----------- | ------- |
140+
| `onResult` | A function to call whenever we receive results back from the server. You can use this function to pre-process results from the server before they are displayed to the user. | `null` |
141+
| `onAdd` | A function to call whenever the user adds another token to their selections. | `null` |
142+
| `onDelete` | A function to call whenever the user removes a token from their selections. | `null` |
143+
| `onReady` | A function to call after initialization is done and the tokeninput is ready to use. | `null` |
144+
145+
## Methods
146+
147+
| Method | Description |
148+
| ------ | ----------- |
149+
| `selector.tokenInput("add", {id: x, name: y});` | Add a new token to the tokeninput with id `x` and name `y`. |
150+
| `selector.tokenInput("remove", {id: x});` | Remove the tokens with id `x` from the tokeninput. |
151+
| `selector.tokenInput("remove", {name: y});` | Remove the tokens with name `y` from the tokeninput. |
152+
| `selector.tokenInput("clear");` | Clear all tokens from the tokeninput. |
153+
| `selector.tokenInput("get");` | Gets the array of selected tokens from the tokeninput (each item being an object of the kind `{id: x, name: y}`). |
154+
155+
## Reporting Bugs or Feature Requests
156+
157+
Please report any bugs or feature requests on the github issues page for this
158+
project here:
159+
160+
<https://github.com/loopj/jquery-tokeninput/issues>
161+
162+
## License
163+
164+
Tokeninput is released under a dual license. You can choose either the GPL or
165+
MIT license depending on the project you are using it in and how you wish to
166+
use it.

‎facebook-style.png

8.14 KB
Loading

‎list-style.png

6.92 KB
Loading

0 commit comments

Comments
 (0)