| 5 |
lars |
1 |
# [Bootstrap MaxLength](http://mimo84.github.com/bootstrap-maxlength/) [](https://travis-ci.org/mimo84/bootstrap-maxlength) [](https://sourcegraph.com/github.com/mimo84/bootstrap-maxlength)
|
|
|
2 |
|
|
|
3 |
|
|
|
4 |
This plugin integrates by default with Twitter bootstrap using badges to display the maximum length of the field where the user is inserting text.
|
|
|
5 |
This plugin uses the HTML5 attribute "maxlength" to work.
|
|
|
6 |
|
|
|
7 |
The indicator badge shows up on focusing on the element, and disappears when the focus is lost.
|
|
|
8 |
|
|
|
9 |
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=4DVL2K9LZW6YL)
|
|
|
10 |
|
|
|
11 |
## Configurable options
|
|
|
12 |
|
|
|
13 |
* **alwaysShow**: if true the threshold will be ignored and the remaining length indication will be always showing up while typing or on focus on the input. Default: false.
|
|
|
14 |
* **threshold**: this is a number indicating how many chars are left to start displaying the indications. Default: 10.
|
|
|
15 |
* **warningClass**: it's the class of the element with the indicator. By default is the bootstrap "label label-success" but can be changed to anything you'd like.
|
|
|
16 |
* **limitReachedClass**: it's the class the element gets when the limit is reached. Default is "label label-important label-danger" (to support Bootstrap 2 and 3).
|
|
|
17 |
* **separator**: represents the separator between the number of typed chars and total number of available chars. Default is "/".
|
|
|
18 |
* **preText**: is a string of text that can be outputted in front of the indicator. preText is empty by default.
|
|
|
19 |
* **postText**: is a string outputted after the indicator. postText is empty by default.
|
|
|
20 |
* **showMaxLength**: if false, will display just the number of typed characters, e.g. will not display the max length. Default: true.
|
|
|
21 |
* **showCharsTyped**: if false, will display just the remaining length, e.g. will display remaining lenght instead of number of typed characters. Default: true.
|
|
|
22 |
* **placement**: is a string, define where to output the counter. Possible values are: **bottom** ( *default option* ), **left**, **top**, **right**, **bottom-right**, **top-right**, **top-left**, **bottom-left** and **centered-right**.
|
|
|
23 |
* **appendToParent**: appends the maxlength indicator badge to the parent of the input rather than to the body.
|
|
|
24 |
* **message**: an alternative way to provide the message text, i.e. 'You have typed %charsTyped% chars, %charsRemaining% of %charsTotal% remaining'. %charsTyped%, %charsRemaining% and %charsTotal% will be replaced by the actual values. This overrides the options separator, preText, postText and showMaxLength. Alternatively you may supply a function that the current text and max length and returns the string to be displayed. For example, function(currentText, maxLength) { return '' + Math.ceil(currentText.length / 160) + ' SMS Message(s)'; }
|
|
|
25 |
* **utf8**: if true the input will count using utf8 bytesize/encoding. For example: the '£' character is counted as two characters.
|
|
|
26 |
* **twoCharLinebreak**: count linebreak as 2 characters to match IE/Chrome textarea validation.
|
|
|
27 |
* **customMaxAttribute**: allows a custom attribute to display indicator without triggering native maxlength behaviour. Ignored if value greater than a native maxlength attribute. 'overmax' class gets added when exceeded to allow user to implement form validation.
|
|
|
28 |
* **placement**: is a string, object, or function, to define where to output the counter.
|
|
|
29 |
* Possible string values are: **bottom** ( *default option* ), **left**, **top**, **right**, **bottom-right**, **top-right**, **top-left**, **bottom-left** and **centered-right**.
|
|
|
30 |
* Custom placements can be passed as an object, with keys **top**, **right**, **bottom**, **left**, and **position**. These are passed to $.fn.css.
|
|
|
31 |
* A custom function may also be passed. This method is invoked with the {$element} Current Input, the {$element} MaxLength Indicator, and the Current Input's Position {bottom height left right top width}.
|
|
|
32 |
|
|
|
33 |
|
|
|
34 |
## Events
|
|
|
35 |
|
|
|
36 |
* **maxlength.reposition** on an input element triggers re-placing of its indicator. Useful if textareas are resized by an external trigger.
|
|
|
37 |
* **maxlength.shown** is triggered when the indicator is displayed.
|
|
|
38 |
* **maxlength.hidden** is triggered when the indicator is removed from view.
|
|
|
39 |
|
|
|
40 |
## Examples
|
|
|
41 |
|
|
|
42 |
Basic implementation:
|
|
|
43 |
```javascript
|
|
|
44 |
$('input[maxlength]').maxlength();
|
|
|
45 |
```
|
|
|
46 |
|
|
|
47 |
Change the threshold value:
|
|
|
48 |
```javascript
|
|
|
49 |
$('input.className').maxlength({
|
|
|
50 |
threshold: 20
|
|
|
51 |
});
|
|
|
52 |
```
|
|
|
53 |
|
|
|
54 |
An example with some of the configurable options:
|
|
|
55 |
```javascript
|
|
|
56 |
$('input.className').maxlength({
|
|
|
57 |
alwaysShow: true,
|
|
|
58 |
threshold: 10,
|
|
|
59 |
warningClass: "label label-info",
|
|
|
60 |
limitReachedClass: "label label-warning",
|
|
|
61 |
placement: 'top',
|
|
|
62 |
preText: 'used ',
|
|
|
63 |
separator: ' of ',
|
|
|
64 |
postText: ' chars.'
|
|
|
65 |
});
|
|
|
66 |
```
|
|
|
67 |
|
|
|
68 |
The same example using the message option:
|
|
|
69 |
|
|
|
70 |
```javascript
|
|
|
71 |
$('input.className').maxlength({
|
|
|
72 |
alwaysShow: true,
|
|
|
73 |
threshold: 10,
|
|
|
74 |
warningClass: "label label-info",
|
|
|
75 |
limitReachedClass: "label label-warning",
|
|
|
76 |
placement: 'top',
|
|
|
77 |
message: 'used %charsTyped% of %charsTotal% chars.'
|
|
|
78 |
});
|
|
|
79 |
```
|
|
|
80 |
|
|
|
81 |
An example allowing user to enter over max characters. Sample HTML element:
|
|
|
82 |
```html
|
|
|
83 |
<textarea class="form-control" id="xyz" name="xyz" maxlength="10"></textarea>
|
|
|
84 |
```
|
|
|
85 |
|
|
|
86 |
```javascript
|
|
|
87 |
// Setup maxlength
|
|
|
88 |
$('.form-control').maxlength({
|
|
|
89 |
alwaysShow: true,
|
|
|
90 |
validate: false,
|
|
|
91 |
allowOverMax: true
|
|
|
92 |
});
|
|
|
93 |
|
|
|
94 |
// validate form before submit
|
|
|
95 |
$('form').on('submit', function (e) {
|
|
|
96 |
$('.form-control').each(
|
|
|
97 |
function () {
|
|
|
98 |
if ($(this).hasClass('overmax')) {
|
|
|
99 |
alert('prevent submit here');
|
|
|
100 |
e.preventDefault();
|
|
|
101 |
return false;
|
|
|
102 |
}
|
|
|
103 |
}
|
|
|
104 |
);
|
|
|
105 |
});
|
|
|
106 |
```
|
|
|
107 |
|
|
|
108 |
An example of triggering a `maxlength.reposition` event whenever an external autosize plugin resizes a textarea:
|
|
|
109 |
```javascript
|
|
|
110 |
$('textarea').on('autosize.resized', function() {
|
|
|
111 |
$(this).trigger('maxlength.reposition');
|
|
|
112 |
});
|
|
|
113 |
```
|
|
|
114 |
|
|
|
115 |
## Changelog
|
|
|
116 |
|
|
|
117 |
### 1.6.0
|
|
|
118 |
* Added new custom events: maxlength.reposition, maxlength.shown, maxlength.hidden. Thanks to dr-nick.
|
|
|
119 |
* Buped up required jQuery to 1.9.x
|
|
|
120 |
* Added option `placement` for custom placement handler. Thanks to Kreegr
|
|
|
121 |
* Extended `message` option. Now it can also be optionally a function. Thanks to Vincent Pizzo
|
|
|
122 |
|
|
|
123 |
### 1.5.7
|
|
|
124 |
* Fixed issue with bower
|
|
|
125 |
|
|
|
126 |
### 1.5.6
|
|
|
127 |
* Added over maxlength functionality with customMaxAttribute
|
|
|
128 |
* Added twoCharLinebreak option
|
|
|
129 |
|
|
|
130 |
### 1.5.5
|
|
|
131 |
* Implemented input event rather than keydown to improve usability
|
|
|
132 |
* Fixed jshint, jscs errors
|
|
|
133 |
|
|
|
134 |
### 1.5.4
|
|
|
135 |
|
|
|
136 |
* When an input with associated maxlength element is removed, maxlength is also removed.
|
|
|
137 |
|
|
|
138 |
### 1.5.3
|
|
|
139 |
|
|
|
140 |
* Fixed #40, error on resize event.
|
|
|
141 |
|
|
|
142 |
### 1.5.2
|
|
|
143 |
|
|
|
144 |
* Fixed #44 (pasted text in can cause it to go over the max length)
|
|
|
145 |
|
|
|
146 |
### 1.5.1
|
|
|
147 |
|
|
|
148 |
* Added self protection of multiple focus events
|
|
|
149 |
* Added back detection of window resizing
|
|
|
150 |
|
|
|
151 |
### 1.5.0
|
|
|
152 |
|
|
|
153 |
* Removed window.resize event
|
|
|
154 |
* Maxlength is created and destroyed each time
|
|
|
155 |
* Fixed Doesn't update the limit after input's maxlength attribute was changed [#31](https://github.com/mimo84/bootstrap-maxlength/issues/31)
|
|
|
156 |
* Added Gruntfile
|
|
|
157 |
* Added qunit unit tests
|
|
|
158 |
|
|
|
159 |
### 1.4.2
|
|
|
160 |
|
|
|
161 |
* Fixed issue with counting when the user moves with shift+tab keyboard shortcut.
|
|
|
162 |
* Replaced the warningClass limitReachedClass options to use labels rather than badges for Bootstrap 3.0 better compatibility.
|
|
|
163 |
|
|
|
164 |
### 1.4.1
|
|
|
165 |
|
|
|
166 |
* Added support for TAB key when the maxlength is reached.
|