taggingjs
v1.3.7
Published
[![Build Status](https://travis-ci.org/sniperwolf/taggingJS.svg?branch=master)](https://travis-ci.org/sniperwolf/taggingJS)
Downloads
27
Readme
taggingJS
A jQuery/Zepto plugin to make tagging easy.
taggingJS is a jQuery/Zepto plugin to create a highly customizable tagging UI.
It is less than 3 kb
and supports all major browsers!
The key api differnces between this and the main project is that jQuery or Zepto is passed in as first argument.
** other additions **
- support for browserify
- support for component
- events if event emitter is passed in options argument
Getting Started
You can find a working example in Codepen.io or in the project's GitHub page.
Simplest
Download the
tagging.min.js
file from this repository;Include
<script src="path/to/tagging.min.js"></script>
to the bottom of your page;Optional - Include the basic CSS tag style
<link href="tag-basic-style.css" rel="stylesheet">
to the<head>
of your page;Add to your page something like
<div data-tags-input-name="tag" id="tagBox">preexisting-tag</div>
;Add to your main JavaScript file
$("#tagBox").tagging();
;
The data-tags-input-name="tag"
is the name
attribute used by each input
inside the tagBox
.
Customize
There are several ways to customize the default behavior of taggingJS:
Use a JavaScript
custom_options
object to customize the global taggingJS behavior (see First Way);Use
data
attributes in thetagBox
HTML Markup (see Second Way);Use a combination of the first two way (see Third Way);
N.B.: Be careful! data
attributes have an higher priority than the custom_options
object,
because each data
attribute overwrite the global behavior.
In other words, the global settings work for all tags box captured, unless in
these are specified data
attributes (which may change the behavior).
First Way - Global Object
Create a custom options
object
, like thismy_custom_options
(see Available Options):var my_custom_options = { "no-duplicate": true, "no-duplicate-callback": window.alert, "no-duplicate-text": "Duplicate tags", "type-zone-class": "type-zone", "tag-box-class": "tagging", "forbidden-chars": [",", ".", "_", "?"] };
Create a tag box (or multiple tag box) like this:
<div id="tagBox">preexisting-tag</div>
Add to your main JavaScript file:
$("#tagBox").tagging(my_custom_options);
In this way, we customize the global behavior of taggingJS for all tag box caught with selector.
Second Way - Data Attributes
Create a tag box with some
data
attributes, like this (see Available Options):<div data-no-duplicate="true" data-pre-tags-separator="\n" data-no-duplicate-text="Duplicate tags" data-type-zone-class="type-zone" data-tag-box-class="tagging" data-edit-on-delete="true" id="tagBox">preexisting-tag</div>
Add to your main JavaScript file:
$("#tagBox").tagging();
N.B.: Use data method with no-duplicate-callback
and forbidden-chars
can cause some problems. Avoid it.
Third Way - Mixed Way
In this way, we mix data attributes and options object to customize taggingJS behavior for each tag box.
Create a tag box with some
data
attributes, like this:<div class="tag-box" data-no-duplicate="true" data-tags-input-name="tag" id="tagBox1">preexisting-tag</div>
Create another tag box with no
data
attributes:<div id="tagBox1" class="tag-box">preexisting-tag</div>
Create a custom options
object
, like thismy_custom_options
(see Available Options):var my_custom_options = { "no-duplicate": false, "tags-input-name": "taggone", "edit-on-delete": false, };
Add to your main JavaScript file
$(".tag-box").tagging(my_custom_options);
Now you may see that:
The
#tagBox1
has a behavior that overwrite somemy_custom_options
options:- Does not accept duplicate tag (for the respective
data
attribute); - For each tag, it has
tag
as input name (for the respectivedata
attribute); - On delete, the tag is completely removed (for the
my_custom_options
);
- Does not accept duplicate tag (for the respective
The
#tagBox2
has a behavior dictated only bymy_custom_options
:- Accept duplicate tag (for the
my_custom_options
); - For each tag, it has
tag
as input name (for themy_custom_options
); - On delete, the tag is completely removed (for the
my_custom_options
);
- Accept duplicate tag (for the
Available Options
Below there are the available options to customize taggingJS with a
little description, a type
and the default value:
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| case-sensitive | Boolean
| false
| If false
, all text is treated like lowercase. |
| close-char | String
| "×"
| Single Tag close character. |
| close-class | String
| "tag-i"
| Single Tag close class. |
| edit-on-delete | Boolean
| true
| true
to edit tag that has just been removed from tag box. |
| forbidden-chars | Array
| ["," , ".", "_", "?"]
| Array of forbidden characters. |
| forbidden-chars-callback | Function
| window.alert
| Function to call when is detected a forbidden character. |
| forbidden-chars-text | String
| "Forbidden character:"
| Basic text passed to forbidden-chars-callback
. |
| forbidden-words | Array
| []
| Array of forbidden words. |
| forbidden-words-callback | Function
| window.alert
| Function to call when is detected a forbidden words. |
| forbidden-words-text | String
| "Forbidden word:"
| Basic text passed to forbidden-words-callback
. |
| no-backspace | Boolean
| false
| Backspace key remove last tag by default, true
to avoid that. |
| no-comma | Boolean
| false
| Comma ","
key add a new tag by default, true
to avoid that. |
| no-del | Boolean
| false
| Del key remove last tag by default, true
to avoid that. |
| no-duplicate | Boolean
| true
| If true
, there will be no duplicate tag's name in the tag box. |
| no-duplicate-callback | Function
| window.alert
| Function to call when is detected a duplicate tag. |
| no-duplicate-text | String
| "Duplicate tag:"
| Basic text passed to no-duplicate-callback
. |
| no-enter | Boolean
| false
| Enter key add a new tag by default, true
to avoid that. |
| no-spacebar | Boolean
| false
| Spacebar key add a new tag by default. true
to avoid that.|
| pre-tags-separator | String
| ", "
| This is used to split
the initial text and add preexistint-tag
. By default, you must put new tags using a comma and a space (", "
). |
| tag-box-class | String
| "tagging"
| Class of the tag box. |
| tag-char | String
| "#"
| Single Tag char. |
| tag-class | String
| "tag"
| Single Tag class. |
| tags-input-name | String
| "tag"
| Name to use as name=""
in single tags' input. By default, all tags being passed as array like tag[]
. |
| type-zone-class | String
| "type-zone"
| Class of the type-zone. |
Contribute
Set Up nodeJS and Grunt
Fork the repository;
Open a shell in project's directory;
Type
npm install
(make sure you have installed nodeJS);Type
grunt
to execute the default script (without minification),grunt dist
to also minify the script (make sure you have installed Grunt).
JavaScript Style Guide
I follow the jQuery's JavaScript style guide, please follow it you too :D
Requirements
- jQuery (
1.5.X
or more, also2.X
works);
Browser Support
Supports all major browsers in the world (IE 6+
, Mozilla Firefox 1+
,
Google Chrome 1+
, Safari 5.1+
).
License
(C) Fabrizio Fallico 2014, released under the MIT license.
Changelog
1.2.5 - [Apr 10, 2014]
- Fix #5 issue;
- Changed
pre-tags-separator
andno-spacebar
default value; - Improved code formatting;
1.2.3 - [Apr 06, 2014]
- Add
case-sensitive
option; - Add
forbidden-words
option to block some words inside a tag, with callback and text; - Add callback and text to as
forbidden-chars
option; - Fixed
i.handler.apply is not function
bug; - Updated README.md with all Available Options;
- Improved code formatting;
- Passed to Semantic Versioning;
- Add taggingJS to jQuery Plugin Registry;
- Minor fix;
1.1 - [Mar 27, 2014]
- Add chance to use custom options;
- Add
no-duplicate
option to avoid duplicate tag (with custom callback); - Add
forbidden-chars
option to block some characters inside a tag; - Updated README.md with all Available Options;
- Updated example;
- Improved code formatting;
- Minor fix;
1.0 - [Mar 22, 2014]
- First Commit;