# taggingJS **Repository Path**: xiaoxingli/taggingJS ## Basic Information - **Project Name**: taggingJS - **Description**: jQuery plugin to tagging like a charm! - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2015-06-04 - **Last Updated**: 2020-12-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # taggingJS # [![Build Status](https://travis-ci.org/sniperwolf/taggingJS.svg?branch=master)](https://travis-ci.org/sniperwolf/taggingJS) ## jQuery plugin to tagging like a charm! ## **taggingJS** is a jQuery plugin to create an high customizable front-end tag system. It is like `5 kb` and [support major browsers](#browser-support) in the world! Actual version is [`1.3.3`](https://github.com/sniperwolf/taggingJS/releases/tag/v1.3.3). ![Example Image](example/example_img.png) ## Getting Started ## You can find a working example in [Codepen.io](http://codepen.io/sniperwolf/pen/geFxq/) or in the project's [GitHub page](http://sniperwolf.github.io/taggingJS/). ### Simplest ### 1. **Download** the `tagging.min.js` file from this repository; 2. **Include** `` to the bottom of your page; 3. *Optional* - Include the basic CSS tag style `` to the `` of your page; 4. **Add** to your page something like `
preexisting-tag
`; 5. **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`. ### Manipulate tags with methods ### Here there are some **common pattern** to manipulate tags inside the tag box: **N.B.**: `$tag_box` is the tag box object. To get it: ```js var t, $tag_box; // We call taggingJS init on all "#tag" divs t = $( "#tag" ).tagging(); // This is the $tag_box object of the first captured div $tag_box = t[0]; ``` #### Get all tags (object) ```js // To get all tags inside tag box as an array of String $tag_box.tagging( "getTags" ); >>> ["preexisting-tag", "another-tag"] // To get all tags inside tag box as an array of jQuery Object $tag_box.tagging( "getTagsObj" ); >>> [x.fn.x.init[1], x.fn.x.init[1]] ``` #### Add new tags ```js // To add a tag with "A new tag added via JS" as text $tag_box.tagging( "add", "A new tag added via JS" ); >>> true // To add two tag, one with "tag 1" and the other with "tag 2" as text $tag_box.tagging( "add", ["tag 1", "tag 2"] ); >>> ["tag 1", "tag 2"] ``` #### Remove tags ```js // To remove a tag with text "A new tag added via JS" as text $tag_box.tagging( "remove", "A new tag added via JS" ); >>> $_obj // To remove two tag, one with "tag 1" and the other with "tag 2" as text $tag_box.tagging( "remove", ["tag 1", "tag 2"] ); >>> [$_obj] // Suppose that $tag is the jQuerify object of a tag inside the tag box, you can also do $tag_box.tagging( "remove", $tag] ); >>> $_obj ``` #### Remove all tags ```js // To remove all tags $tag_box.tagging( "removeAll" ); // or $tag_box.tagging( "reset" ); ``` #### Get Special Keys ```js // To get special Keys without distinctions $tag_box.tagging( "getSpecialKeys" ); >>> Object {comma: 188, enter: 13, spacebar: 32, del: 46, backspace: 8} // To get special Keys with distinctions $tag_box.tagging( "getSpecialKeysD" ); >>> Object {add: Object, remove: Object} ``` #### Add or Remove a Special Key ```js // To add the "left arrow" as a special key to add a new tag $tag_box.tagging( "addSpecialKeys", [ "add", { left_arrow: 37 } ] ); // To add the "right arrow" as a special key to remove a tag $tag_box.tagging( "addSpecialKeys", [ "remove", { right_arrow: 39 } ] ); // To remove the "right arrow" as a special key $tag_box.tagging( "removeSpecialKeys", 39 ); ``` #### Disable taggingJS ```js // To disable taggingJS $tag_box.tagging( "destroy" ); ``` #### Empty the `type_zone` ```js // To disable taggingJS $tag_box.tagging( "emptyInput" ); ``` #### Get or Set the value of `type_zone` ```js // To set "value" as value of the input $tag_box.tagging( "valInput", "value" ); // To get the value of the input $tag_box.tagging( "valInput" ); ``` #### Trigger Focus event the `type_zone` ```js // To Trigger Focus event the input $tag_box.tagging( "focusInput" ); ``` Please, see all [Available Methods](#available-methods). ### Customize ### There are **several ways** to customize the default behavior of taggingJS: 1. Use a JavaScript `custom_options` object to customize the global taggingJS behavior (see [First Way](#first-way---global-object)); 2. Use `data` attributes in the `tagBox` HTML Markup (see [Second Way](#second-way---data-attributes)); 3. Use a combination of the first two way (see [Third Way](#third-way---mixed-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 #### 1. **Create a custom options** `object`, like this `my_custom_options` (see [Available Options](#available-options)): ```js 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": [",", ".", "_", "?"] }; ``` 2. **Create a tag box** (or multiple tag box) like this: ```html
preexisting-tag
``` 3. **Add** to your main JavaScript file: ```js $("#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 #### 1. **Create a tag box** with some `data` attributes, like this (see [Available Options](#available-options)): ```html
preexisting-tag
``` 2. **Add** to your main JavaScript file: ```js $("#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. 1. **Create a tag box** with some `data` attributes, like this: ```html
preexisting-tag
``` 2. **Create *another* tag box** with no `data` attributes: ```html
preexisting-tag
``` 3. **Create a custom options** `object`, like this `my_custom_options` (see [Available Options](#available-options)): ```js var my_custom_options = { "no-duplicate": false, "tags-input-name": "taggone", "edit-on-delete": false, }; ``` 4. **Add** to your main JavaScript file ```js $(".tag-box").tagging( my_custom_options ); ``` Now you may see that: * The `#tagBox1` has a behavior that overwrite some `my_custom_options` options: - Does not accept duplicate tag (*for the respective `data` attribute*); - For each tag, it has `tag` as input name (*for the respective `data` attribute*); - On delete, the tag is completely removed (*for the `my_custom_options`*); * The `#tagBox2` has a behavior dictated only by `my_custom_options`: - Accept duplicate tag (*for the `my_custom_options`*); - For each tag, it has `tag` as input name (*for the `my_custom_options`*); - On delete, the tag is completely removed (*for the `my_custom_options`*); ## Available Options ## Below there are the **available options to customize taggingJS** with `type`, a little description 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. | | **tag-on-blur** | `Boolean` | `true` | If `true`, clicking away from the `$type_zone` will add a new tag. | | **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. | ## Available Methods ## Below there are the **available methods of taggingJS** with a little description, the argument that it can take and the return `type`: | Method | Description | Argument | Return | | ------ | ----------- | -------- | ------ | | **add( `text` or `[text]` )** | Add a new tag. | A `String` (or an `Array` of `String`) to add as tag, if `null` we get the content of tag box `type_zone`. | `Boolean` or `Funtion` | | **addSpecialKeys( `[ "type", obj ]` )** | Add a special keys to add or remove a tag. | `Array` - Where `"type"` is `"add"` or `"remove"`, `obj` is like `{ key_name: key_code }` (it can be also an `Array` of `obj`). | A `String` for error or `Object` Actually `"type"_key` (`add_key` or `remove_key`). | | **destroy()** | Remove `type_zone`, all tags and other things. | `void` | `Boolean` | | **emptyInput()** | Empty tag box's `type_zone`. | `void` | `$_obj` - The jQuerified `type_zone` itself. | | **focusInput()** | Trigger focus on tag box's `type_zone`. | `void` | `$_obj` - The jQuerified `type_zone` itself. | | **getDataOptions()** | Get Data attributes custom options. | `void` | `Object` - tag box data attributes custom options. | | **getSpecialKeys()** | Return all special keys inside an object (without distinction) | `void` | `Object` - All tags as member of strings. | | **getSpecialKeysD()** | Return all special keys inside an object (with distinction) | `void` | An `Object` with an `add` and `remove` properties. | | **getTagsObj()** | Return all tags as object | `void` | `Array` - All tags as member of objects. | | **init()** | Init method to bootstrap all things | `void` | `$_obj` - The jQuerify tag box. | | **refresh( `text` )** | Remove and insert all tag | A `String` with all tags separated by `pre-tags-separator` option value (if `null`, we call `getTags` method) | `Boolean` | | **remove( `text` or `$_obj` )** | Remove last tag or the specified ones in tag box's `type_zone`. | A `String` or `$_obj` (or an `Array` of them) of the tag to remove. | A `String` with error message or `$_obj` of the removed tag. | | **removeAll()** | Alias of reset | `void` | `Array` - All removed tags. | | **removeSpecialKeys( `[ "type", obj ]` )** | Remove a special key . | `Array` - Where `"type"` is `"add"` or `"remove"`, `obj` is like `{ key_name: key_code }` (it can be also an `Array` of `obj`). | `Object` - Actually `"type"_key` (`add_key` or `remove_key`). | | **reset()** | Remove all tags from tag box's `type_zone` | `void` | `Array` - All removed tags. | | **valInput( `text` )** | Get or set the tag box `type_zone`'s value | A `String` to put as tag box `type_zone`'s value. | The value `String` or `$_obj` of tag box's `type_zone`. | You can find example [here](#manipulate-tags). ## Contribute ## ### Set Up nodeJS and Grunt ### 1. Fork the repository; 2. Open a shell in project's directory; 3. Type `npm install` (make sure you have installed [nodeJS](http://nodejs.org)); 4. Type `grunt` to execute the default script (without minification), `grunt dist` to also minify the script (make sure you have installed [Grunt](http://gruntjs.com)). ### JavaScript Style Guide ### I follow the [jQuery's JavaScript style guide](https://contribute.jquery.org/style-guide/js/), please follow it you too :D Also take a look to [IdiomaticJS](https://github.com/rwaldron/idiomatic.js/) (**Principles of Writing Consistent, Idiomatic JavaScript**). ## Requirements ## - **jQuery** (`1.5.X` or more, also `2.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](LICENSE.md). ## Changelog (v1.3.X) ## ### 1.3.3 - [Oct 24, 2014] * Now you can add tags clicking away from the `$type_zone` (see [Available Options](#available-options)). * Fix [#22](https://github.com/sniperwolf/taggingJS/issues/22), Fix [#24](https://github.com/sniperwolf/taggingJS/issues/24), Fix [#26](https://github.com/sniperwolf/taggingJS/issues/26), Fix [#28](https://github.com/sniperwolf/taggingJS/issues/28) issues. ### 1.3.1 - [Apr 28, 2014] * Radically changed the architecture of the plugin. Now we are more flexible to changes and pull requests. * Added basic methods. * Now you can add (and remove) custom special keys to add or remove tags (see [Available Methods](#available-methods)). * Fix [#6](https://github.com/sniperwolf/taggingJS/issues/6), [#8](https://github.com/sniperwolf/taggingJS/issues/8), [#16](https://github.com/sniperwolf/taggingJS/issues/16), [#17](https://github.com/sniperwolf/taggingJS/issues/17), [#19](https://github.com/sniperwolf/taggingJS/issues/19) issues.