Skip to content

Commit ad618aa

Browse files
SerhioromanoSerhioromano
committed
Some documentation
1 parent 611a6b3 commit ad618aa

File tree

1 file changed

+133
-8
lines changed

1 file changed

+133
-8
lines changed

‎README.md‎

Lines changed: 133 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
11
# Bootstrap Tags
22

3-
In fact it is not tags it sort of mix of typeahead, and pills. I just did not know how to name it in english, I named it after my task I did it to use in my applicatin to manage tags.
3+
In fact it is not tags it sort of mix of typeahead, and tags/pills. I just did not know how to name it in english, I named it after my task I did it to use in my application to manage tags.
44

5+
Please see [demo](http://bootstrap-tags.azurewebsites.net/) here. Demo is updated automatically on every push to repository so it always contains latest version.
6+
7+
## Features
8+
9+
- Based on templates. Thus you can change any HTML markup of any element, and fully control how this UI components looks.
10+
- Flexible API. There are few methods to make the same thing like pre-populate, remove or add tags/pills. you can use it as standard element with form submission or on fully AJAXed sites.
511

612
## Install
713

@@ -36,15 +42,112 @@ to see what files to use run
3642

3743
The minimal requirments are Bootstrap and jquery loaded and `bootstrap-tags.css`, `bootstrap-tags.js`.
3844

39-
## Load deafult values
45+
## Feed format
46+
47+
As for default values or _typeahead_ suggestions the format is the same. It is an array of values. Values can be `string` or `object` or mixed.
48+
49+
[
50+
{
51+
"id": "1",
52+
"text": "Apple",
53+
"html": "This is <b>Apple</b>!",
54+
"num": 5
55+
},
56+
{
57+
"id": "3",
58+
"text": "Mango",
59+
"html": "I like <b>Mango</b>!",
60+
"url": "/"
61+
},
62+
"Banana"
63+
]
64+
65+
Object may contain following properties
66+
67+
Property | Required | Description
68+
---------|----------|------------
69+
id | Yes | Required only if object. If it is a string, the same value for `text` and `id` will be used.
70+
text | Yes | Used as tag text.
71+
html | No | If not set `text` will be used. This property is used to display in typeahead suggestions.
72+
num | No | If set, number will be shown after the text.
73+
url | No | If set, text will be as link. Not that there is `tag_link_target` option. Eg. `$('#bs-tags').tags({tag_link_target:"_blank"});`
74+
75+
## Options
76+
77+
You can use following options when construction element. Like `$('#bs-tags').tags(options);`
78+
79+
Option | Default | Description
80+
-------|---------|------------
81+
values | [] | Default values to pre-populate component with tags/pills
82+
tag\_link\_target || Default target for tags/pills with links. To add link to tag you have to set `url` property in feed object. See _Feed format_ for details.
83+
can_delete | true | Set if current user can delete tags/pills
84+
can_add | true | Set if current users can add new tags
85+
remove_url | | Set URL where `POST` request will be sent on tag/pill removal.
86+
input_name | tags[] | Set name of the hidden `<input>` element to be added with every tag/pill. Ше should end with `[]` in order to support multiple values.
87+
templates | | Set HTML markup. This let you fully manage and style output as you want. No limitations. See _Templates_ for more details.
88+
89+
## Templates
90+
91+
Templates option allow you fully manage how tags/pills will look like. Then with additions of few CSS styles you may create very beautiful outputs. See demo for examples.
92+
93+
You can path template through `templates` option.
94+
95+
$('#bs-tags').tags({
96+
templates: {
97+
pill: '<span class="badge badge-info" data-tag-id="{1}">{0}</span>',
98+
delete_icon: '<i class="icon-remove-sign"></i>',
99+
number: ' <sup><small>{0}</small></sup>'
100+
}
101+
});
102+
103+
![pill template](http://serhioromano.s3.amazonaws.com/github/bs-tags/bs-tags-template.png)
104+
105+
Template | Default | Descritpion
106+
---|---|---
107+
pill | `<span class="badge badge-info" data-tag-id="{1}">{0}</span>` | This is main HTML element of the pill. This is also what will be passed to `onRemove(pill)` method. After full pill creation it will include also hidden `<input>`, number if passed and remove icon. `{0}` is the tag text, `{1}` is the tag id. `data-tag-id` is required attribute.
108+
number | `<sup><small>{0}</small></sup>` | If `num` property exists in _feed_ then number will be added. This is template how to format it.
109+
delete_icon | `<i class="icon-remove-sign"></i>` | This is delete icon. If you use FontAwesome or IcoMoon you can change it to display better icon.
110+
111+
112+
Final pill may look like this.
113+
114+
<span class="badge badge-info" data-tag-id="2">
115+
<a class="tag-link" target="" href="http://tags/">Apple</a>
116+
<sup><small>5</small></sup>
117+
<a href="javascript:void(0)" class="tag-remove" data-toggle="tooltip" title="Delete">
118+
<i class="icon-remove-sign"></i>
119+
</a>
120+
<input data-tag-hidden="2" name="tags[]" type="hidden" value="2">
121+
</span>
40122

41-
Theer are 3 methods to load default values. Methods are listed in order it is executed. In all 3 methods format of values are the same.
123+
## Events
42124

43-
Array example `["banana", "strawberry", "apple"]`. Or you can use objects or even mix like
44-
`[{id: 1, text: "Apple", html: "This is <b>Apple</b>!"}, {id: 2, text: "Pear"}, "banana"]` where `html` is optional
45-
key. In objects `id` is used to save, text to display in pill and `html` in typeahead suggestions.
125+
Event | Description
126+
---------------|-------------
127+
onLoadDefaults | Triggered before render element. What you return will be used to pre-populate component with tags/pills
128+
onRemove | Triggered before removing HTML element of tag/pill.
46129

47-
1. First method is to path default values as option.
130+
templates: {
131+
// {0} - text, {1} - id, {2} - delete icon
132+
pill: '<span class="badge badge-info" data-tag-id="{1}">{0}</span>',
133+
delete_icon: '<i class="icon-remove-sign"></i>',
134+
number: ' <sup><small>{0}</small></sup>'
135+
},
136+
137+
input_name: 'tags[]',
138+
139+
lang: {
140+
delete: "Delete"
141+
},
142+
143+
remove_url: '',
144+
145+
146+
## Load default values
147+
148+
There are 3 methods to load default values or pre-populate tags/pills. Methods are listed in order of execution.
149+
150+
1. First method is to pass default values as `values` option.
48151

49152
$('#bs-tags').tags({values:["banana", "apple"]});
50153

@@ -61,4 +164,26 @@ key. In objects `id` is used to save, text to display in pill and `html` in type
61164
});
62165
Here `values` contain already loaded values with previos methods.
63166

64-
Or you can use all methods at once. All values will be merged.
167+
Or you can use all methods at once. All values will be merged.
168+
169+
## Remove tag/pill
170+
171+
First there is `can_delete` option to allow or disallow tags removing.
172+
173+
$('#bs-tags').tags({can_delete:true});
174+
175+
This will allow simply remove tag HTML element with hidden `<input>`. But if you want callback on the event you can use `onRemove(pill)` callback.
176+
177+
$('#bs-tags').tags({
178+
can_delete: true,
179+
onRemove(pill) {
180+
// do something...
181+
}
182+
});
183+
184+
Where `pill` is an HTML element.
185+
186+
And another way to control removal, is to set special URL where `POST` request will be sent with `id` parameter.
187+
188+
$('#bs-tags').tags({can_delete: true, remove_url: 'http://mysite.com/removetag.php'});
189+

0 commit comments

Comments
 (0)