Tag Handler by ioncache
Basic Usage Instructions
- Tag Handler must be attached to one or more <ul> tags in your HTML.
- To add a tag, click on the tag box, type in a name, and hit enter or comma.
- Tags may be removed from the tag box by hitting backspace inside the box or by clicking on the tag.
-
The list of tags may be initialized in 1 of 3 ways:
- By passing arrays of tag names as options to the plugin ("availableTags" and "assignedTags"); or,
-
By supplying a "getURL" for the tags to be retrieved via AJAX.
When using this method, the server must supply a JSON formatted array named "availableTags" and optionally an additional array named "assignedTags". -
By supplying a "getURL" and initLoad: false.
When using this method, it will get the "assignedTags" from the array as in method 1. When the user writes a tag, it will query the server passing the typed in text to the server which can then return the related results as availableTags.
Using any of the initialization methods, the information from these 3 methods will be used in the following manner:
availableTags: each item in this array will populate the autocomplete drop-down list
assignedTags: each item in this array will become a tag in the tag box - Tags may be sent back to the server by supplying an "updateURL". In this case, an array will be sent back to the server named "tags".
- A sample CSS file is included that can be used to help with formatting tags.
Download
You can download this project in either zip or tar formats.
You can also clone the project with Git by running:
$ git clone git://github.com/ioncache/Tag-Handler
Plugin Setup and Usage Examples
Note: the ajax examples are using mockjax (http://github.com/appendto/jquery-mockjax) as the backend rather than a live server.
Example 1: The Tag Handler will be initialized with no options and no default tags:
$("#basic_tag_handler").tagHandler();
Example 2: The Tag Handler will be initialized with preset tags from the assignedTags and availableTags arrays, and autocomplete witll be turned on:
$("#array_tag_handler").tagHandler({
assignedTags: [ 'C', 'Perl', 'PHP' ],
availableTags: [ 'C', 'C++', 'C#', 'Java', 'Perl', 'PHP', 'Python' ],
autocomplete: true
});
Example 3: The Tag Handler will be initialized and pull data via ajax, also sending some data to the server:
$("#ajaxget_tag_handler").tagHandler({
getData: { id: 'user123', type: 'user' },
getURL: '/ajaxtest/get',
autocomplete: true
});
Example 4: Same as Example 3, but a different user is set in the getData/UpdateData options and now the tags will save when clicking the save button:
$("#ajaxupdate_tag_handler").tagHandler({
getData: { id: 'user234', type: 'user' },
getURL: '/ajaxtest/get',
updateData: { id: 'user234', type: 'user' },
updateURL: '/ajaxtest/update',
autocomplete: true
});
Example 5: Same as Example 4, but autoUpdate is true, tags will save automatically (no save button will be shown):
$("#ajaxautoupdate_tag_handler").tagHandler({
getData: { id: 'user234', type: 'user' },
getURL: '/ajaxtest/get',
updateData: { id: 'user234', type: 'user' },
updateURL: '/ajaxtest/update',
autocomplete: true,
autoUpdate: true
});
Example 6: The Tag Handler will be initialized but it will request the tag list when the user writes more than 2 chars (try typing in a mixed drink name for this example):
$("#ajax_no_initial_tag_handler").tagHandler({
getData: { id: 'user345', type: 'user' },
getURL: '/ajaxtest/get',
updateURL: '/ajaxtest/update',
autocomplete: true,
initLoad: false,
minChars: 2
});
Example 7: Same as example 6, but the user cannot create new tags
$("#ajax_no_add_tag_handler").tagHandler({
getData: { id: 'user345', type: 'user' },
getURL: '/ajaxtest/get',
updateURL: '/ajaxtest/update',
autocomplete: true,
initLoad: false,
minChars: 2,
allowAdd: false
});
Example 8: Same as example 2, but there are onAdd and onDelete callbacks
$("#callback_tag_handler").tagHandler({
assignedTags: [ 'C', 'Perl', 'PHP' ],
availableTags: [ 'C', 'C++', 'C#', 'Java', 'Perl', 'PHP', 'Python' ],
autocomplete: true,
onAdd: function(tag) { alert('Added tag: ' + tag); },
onDelete: function(tag) { alert('Deleted tag: ' + tag); }
});
Example 9: Setting maximum number of tags:
$("#max_tags_tag_handler").tagHandler({
assignedTags: [ 'Perl' ],
availableTags: [ 'C', 'C++', 'C#', 'Java', 'Perl', 'PHP', 'Python' ],
autocomplete: true,
maxTags:5
});
Plugin Methods
These are convenience methods for dealing with the Tag-Handler.
Note: clicking the example buttons will show any output as an alert and in the console.log.
getTags
$("#ajaxupdate_tag_handler").tagHandler("getTags");
getSerializedTags
$("#array_tag_handler").tagHandler("getSerializedTags");
Plugin Options
| Option | Description | Default Value |
|---|---|---|
| assignedTags | array to pass a list of already assigned tags | [ ] |
| availableTags | array to pass a list of all available tags | [ ] |
| getData | data field with additional info for getURL | {} |
| getURL | URL for retrieving tag lists via ajax | '' |
| initLoad | indicates if all tags should be loaded on init | true |
| updateData | data field with additional info for updtateURL | {} |
| updateURL | URL for saving tags via ajax | '' |
| Option | Description | Default Value |
|---|---|---|
| afterAdd | function to be called after a new tag is added | {} |
| afterDelete | function to be called after a tag is deleted | {} |
| onAdd | function to be called when a new tag is added -- if a false value is returned, the add will fail | {} |
| onDelete | function to be called when a tag is deleted | {} |
| Option | Description | Default Value |
|---|---|---|
| allowAdd | indicates whether the user can add new tags | true |
| allowEdit | indicates whether the tag list is editable | true |
| autocomplete | activates autocomplete dropdown functionality for tag name - requires jqueryui autocomplete plugin | false |
| autoUpdate | indicates whether updating occurs automatically whenever a tag is added/deleted - if set true, the save button will not be shown | false |
| className | base class name that will be added to the tag container | tagHandler |
| debug | will turn on some console logging debug information | false |
| delimiter | extra delimiter to use to separate tags - note 'enter' and 'comma' are always allowed | '' |
| maxTags | sets a limit to the number of allowed tags, set to 0 to allow unlimited | 0 |
| minChars | minimum number of chars to type before starting autocomplete | 0 |
| msgError | message shown when there is an error loading the tags | There was an error getting the tag list. |
| msgNoNewTag | message shown when the user cannot add a new tag | You don't have permission to create a new tag. |
| queryname | query term used to send user typed data to the server | q |
| sortTags | sets sorting of tag names alphabetically | true |
| Method | Description | Usage |
|---|---|---|
| getSerializedTags | Will return a comma separated string of the currently assigned tags for the object. | .tagHandler("getSerialzedTags") |
| getTags | Will return an array of the currently assigned tags for the object. | .tagHandler("getTags") |
| version | Returns the version of the TagHandler (as of 1.3.0) | .tagHandler("version") |
blog comments powered by Disqus
