Listag is a JQuery UI widget, fully integrated with JQuery UI Autocomplete, that will turn any list element into a tag list, with a searching input and, optionally, a custom value input.
It's aimed to those scenarios where you have a big or huge list of predefined possible tags, such as products from a catalog or custom fields for a settings configuration. You can also include a custom, editable value for each tag added for further personalization.
- Simple basic usage.
- Fully integrated with JQuery UI Autocomplete widget.
- Form friendliness! Toggle usage of hidden inputs with custom name attributes.
- Possibility of adding a custom value to each tag for further customization.
- Visual cues like placeholders, highlighting existing tags, and buttons to add a tag and show full list of tags.
- Integration with Fancybox 2 plugin for showing all the posible tags in a modal window.
- Convenient callbacks.
- Ability to provide initial tags on creation via list items or options.
- JQuery UI styling conventions to enable ThemeRoller support.
- Extend the
fullList
option to accept local arrays and callbacks.
-
Include the files in your
head
:<link rel="stylesheet" type="text/css" href="css/redmond/jquery-ui-1.8.21.custom.css"> <script src="js/jquery-1.7.2.min.js"></script> <script src="js/jquery-ui-1.8.21.custom.min.js"></script> <script src="js/jquery.listag.js"></script>
-
Call it!
$('ul').listag({ source: 'source.json' });
Option | Default | Description |
---|---|---|
source |
null |
Maps to JQuery Autocomplete UI source option. |
limit |
0 |
Max number of tags. |
customValue |
false |
If true , a custom value input field is activated and custom values are shown in tags. |
initialTags |
[] |
Initial array of tags. You can use public tag method to format. |
renderHTMLTag |
false |
(false |
HTMLTagName |
'tags' |
Name property for the rendered HTML tag. |
customValueName |
'custom' |
Same as above, for the custom value HTML tag. |
fullList |
false |
If true , it takes source value. If string, expects a URL that returns the full JSON tags array. |
showAddButton |
false |
Show an add tag button. |
delay |
250 |
Typing delay for the search input. |
placeholder |
'Search...' |
Placeholder for the search input. |
customValuePlaceholder |
null |
Placeholder for the custom value input. |
highlightColor |
'#f33' |
Existing tags highlighting color. If false , no highlighting is called. |
addButtonHTML |
'Add tag' |
|
fullListButtonHTML |
'Show full list' |
|
beforeAddTag |
null |
Called before adding a tag. Returning false will cancel the addition. |
onTagAdded |
null |
Called when tag has been already added. |
onTagUpdated |
null |
Called after the tag is updated. |
onTagDeleted |
null |
Called when a tag has been deleted. |
onLimitReached |
null |
Called when limit is reached. |
The most basic way of get Listag working is:
$('ul').listag({
source: 'source.json'
});
This will create the search input and add existing li
child elements as tags. source
is the only option required, as it maps directly to the autocomplete plugin. It can be an array with local data, a string specifying a URL or a callback (read the official docs).
Existing li
elements will be added as tags. Their text will be used as labels, and (if present) HTML5 data attributes data-value
and data-custom-value
(last one is only necessary if custom value option is true) will become, respectively, value
and customValue
properties of each tag.
In order to use Listag within regular forms and allow tags submission, you can tell the plugin to render HTML elements.
$('ul').listag({
source: 'source.json',
renderHTMLTag: 'select',
HTMLTagName: 'mytagarray'
});
This will render a hidden <select name="mytagarray">
that will store each tag as an <option value="">
element.
Optionally, you can set renderHTMLTag
as hidden
and a <input type="hidden" name="mytagarray[]" value="">
will be rendered within each tag.
Note that HTMLTagName
will become the name attribute in both cases. For the hidden inputs case, though, []
will be concatenated to it except if the limit
option is setted to 1.
In case you need to give the user the ability to specify a custom value, you can set it as follows:
$('ul').listag({
source: 'source.json',
renderHTMLTag: 'hidden',
HTMLTagName: 'mytagarray',
customValue: true,
customValueName: 'quantity',
});
This time, a custom value input will be added next to the searching input and the tags will show that value next to the label. Also, tags will have an edit button which will let the user modify it.
If the renderHTMLTag
options is set to hidden
, an aditional <input type="hidden" name="quantity[]" value="">
will be added to each tag. If it is set to select
, the <option>
elements will have an HTML5 data-custom-value
attribute containing the custom value.
If the autocomplete pattern isn't user-friendly enough (e.g. you've got a big list of items which the user may not remember) you can enable a full list button.
Fancybox 2 plugin required. You can download it from the web site or Github. Without it, this feature won't work.
$('ul').listag({
source: 'source.json',
renderHTMLTag: 'select',
fullList: 'showalltheitems.json'
});
Giving the fullList
option a string, it will become the URL that must return a (full) properly formatted array of tags, and a show full list button will be added next to the search. This button will open a fancybox containing all the tags, which will be added by clicking on them.
The format expected from the source
, fullList
and initialTags
options is a simple JSON array encoding:
[
{
label: 'Example tag',
value: 1,
customValue: 33
},
{
...
}
]
value
is intended to be used as id for each tag, e.g. when adding products and having to process them later filtering by id. customValue
, if defined, will become the default value for that tag and will be shown in the custom tag input (if customValue: true
) when the user selects the tag, before adding it.
You can use the public tag
method for formatting purposes:
var tag = $.jito.listag.tag(label, value, customValue);
customarray.push(tag);
beforeAddTag
It expects a function(event, tag)
where event
is an empty event and tag
is the JSON formatted tag object. Returning false
will abort the tag addition method.
onTagAdded
Same format as above, but triggered when the tag has already been added. You can access the label
, value
and customValue
properties as usual, plus an element
one, which is the DOM tag element inserted in the list.
onTagDeleted
Will be fired after a tag is removed. It does not takes any arguments.
onTagUpdated
A function(event, tag)
, similar to beforeAddTag
, fired once the editable tag has been updated.
onLimitReached
It is fired after the user tries to add a tag, before the addition itself, and after the beforeAddTag
method. Useful to give the user some feedback about what happened.
placeholder
and customValuePlaceholder
For a better user experience, you can set placeholders on the search and custom value inputs, to give the user a hint of the expected content or behavior.
showAddButton
When true
, an Add tag button will be rendered next to search and custom value inputs. Enter
keydown behavior (i.e. add a tag) is not overrided, both will do the same job.
delay
Maps to the autocomplete delay option. This is the time in ms between the last key stroke and the begining of the search.
highlightColor
The color used for background highlighting effect when the user tries to add a tag that already exists. If false
, no highlight will be applied (though this is not recommended -you should always give the user some feedback).
addButtonHTML
and fullListButtonHTML
For i18n purposes.
This widget is based on jQuery Tagit by Matthew Hailwood, and licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported license.