| blob | a8c0b0659080226f9288354a84b64cc75f465a98 |
1 /**
2 * jQuery byteLimit plugin.
3 *
4 * @author Jan Paul Posma, 2011
5 * @author Timo Tijhof, 2011-2012
6 */
7 ( function ( $ ) {
9 /**
10 * Utility function to trim down a string, based on byteLimit
11 * and given a safe start position. It supports insertion anywhere
12 * in the string, so "foo" to "fobaro" if limit is 4 will result in
13 * "fobo", not "foba". Basically emulating the native maxlength by
14 * reconstructing where the insertion occured.
15 *
16 * @param {string} safeVal Known value that was previously returned by this
17 * function, if none, pass empty string.
18 * @param {string} newVal New value that may have to be trimmed down.
19 * @param {number} byteLimit Number of bytes the value may be in size.
20 * @param {Function} fn [optional] See $.fn.byteLimit.
21 * @return {Object} Object with:
22 * - {string} newVal
23 * - {boolean} trimmed
24 */
25 function trimValForByteLength( safeVal, newVal, byteLimit, fn ) {
26 var startMatches, endMatches, matchesLen, inpParts,
27 oldVal = safeVal;
29 // Run the hook if one was provided, but only on the length
30 // assessment. The value itself is not to be affected by the hook.
31 if ( $.byteLength( fn ? fn( newVal ) : newVal ) <= byteLimit ) {
32 // Limit was not reached, just remember the new value
33 // and let the user continue.
34 return {
35 newVal: newVal,
36 trimmed: false
37 };
38 }
40 // Current input is longer than the active limit.
41 // Figure out what was added and limit the addition.
42 startMatches = 0;
43 endMatches = 0;
45 // It is important that we keep the search within the range of
46 // the shortest string's length.
47 // Imagine a user adds text that matches the end of the old value
48 // (e.g. "foo" -> "foofoo"). startMatches would be 3, but without
49 // limiting both searches to the shortest length, endMatches would
50 // also be 3.
51 matchesLen = Math.min( newVal.length, oldVal.length );
53 // Count same characters from the left, first.
54 // (if "foo" -> "foofoo", assume addition was at the end).
55 while (
56 startMatches < matchesLen &&
57 oldVal.charAt( startMatches ) === newVal.charAt( startMatches )
58 ) {
59 startMatches += 1;
60 }
62 while (
63 endMatches < ( matchesLen - startMatches ) &&
64 oldVal.charAt( oldVal.length - 1 - endMatches ) === newVal.charAt( newVal.length - 1 - endMatches )
65 ) {
66 endMatches += 1;
67 }
69 inpParts = [
70 // Same start
71 newVal.substring( 0, startMatches ),
72 // Inserted content
73 newVal.substring( startMatches, newVal.length - endMatches ),
74 // Same end
75 newVal.substring( newVal.length - endMatches )
76 ];
78 // Chop off characters from the end of the "inserted content" string
79 // until the limit is statisfied.
80 if ( fn ) {
81 // stop, when there is nothing to slice - bug 41450
82 while ( $.byteLength( fn( inpParts.join( '' ) ) ) > byteLimit && inpParts[1].length > 0 ) {
83 inpParts[1] = inpParts[1].slice( 0, -1 );
84 }
85 } else {
86 while ( $.byteLength( inpParts.join( '' ) ) > byteLimit ) {
87 inpParts[1] = inpParts[1].slice( 0, -1 );
88 }
89 }
91 newVal = inpParts.join( '' );
93 return {
94 newVal: newVal,
95 trimmed: true
96 };
97 }
99 var eventKeys = [
100 'keyup.byteLimit',
101 'keydown.byteLimit',
102 'change.byteLimit',
103 'mouseup.byteLimit',
104 'cut.byteLimit',
105 'paste.byteLimit',
106 'focus.byteLimit',
107 'blur.byteLimit'
108 ].join( ' ' );
110 /**
111 * Enforces a byte limit on an input field, so that UTF-8 entries are counted as well,
112 * when, for example, a database field has a byte limit rather than a character limit.
113 * Plugin rationale: Browser has native maxlength for number of characters, this plugin
114 * exists to limit number of bytes instead.
115 *
116 * Can be called with a custom limit (to use that limit instead of the maxlength attribute
117 * value), a filter function (in case the limit should apply to something other than the
118 * exact input value), or both. Order of parameters is important!
119 *
120 * @context {jQuery} Instance of jQuery for one or more input elements
121 * @param {Number} limit [optional] Limit to enforce, fallsback to maxLength-attribute,
122 * called with fetched value as argument.
123 * @param {Function} fn [optional] Function to call on the string before assessing the length.
124 * @return {jQuery} The context
125 */
126 $.fn.byteLimit = function ( limit, fn ) {
127 // If the first argument is the function,
128 // set fn to the first argument's value and ignore the second argument.
129 if ( $.isFunction( limit ) ) {
130 fn = limit;
131 limit = undefined;
132 // Either way, verify it is a function so we don't have to call
133 // isFunction again after this.
134 } else if ( !fn || !$.isFunction( fn ) ) {
135 fn = undefined;
136 }
138 // The following is specific to each element in the collection.
139 return this.each( function ( i, el ) {
140 var $el, elLimit, prevSafeVal;
142 $el = $( el );
144 // If no limit was passed to byteLimit(), use the maxlength value.
145 // Can't re-use 'limit' variable because it's in the higher scope
146 // that would affect the next each() iteration as well.
147 // Note that we use attribute to read the value instead of property,
148 // because in Chrome the maxLength property by default returns the
149 // highest supported value (no indication that it is being enforced
150 // by choice). We don't want to bind all of this for some ridiculously
151 // high default number, unless it was explicitly set in the HTML.
152 // Also cast to a (primitive) number (most commonly because the maxlength
153 // attribute contains a string, but theoretically the limit parameter
154 // could be something else as well).
155 elLimit = Number( limit === undefined ? $el.attr( 'maxlength' ) : limit );
157 // If there is no (valid) limit passed or found in the property,
158 // skip this. The < 0 check is required for Firefox, which returns
159 // -1 (instead of undefined) for maxLength if it is not set.
160 if ( !elLimit || elLimit < 0 ) {
161 return;
162 }
164 if ( fn ) {
165 // Save function for reference
166 $el.data( 'byteLimit.callback', fn );
167 }
169 // Remove old event handlers (if there are any)
170 $el.off( '.byteLimit' );
172 if ( fn ) {
173 // Disable the native maxLength (if there is any), because it interferes
174 // with the (differently calculated) byte limit.
175 // Aside from being differently calculated (average chars with byteLimit
176 // is lower), we also support a callback which can make it to allow longer
177 // values (e.g. count "Foo" from "User:Foo").
178 // maxLength is a strange property. Removing or setting the property to
179 // undefined directly doesn't work. Instead, it can only be unset internally
180 // by the browser when removing the associated attribute (Firefox/Chrome).
181 // http://code.google.com/p/chromium/issues/detail?id=136004
182 $el.removeAttr( 'maxlength' );
184 } else {
185 // If we don't have a callback the bytelimit can only be lower than the charlimit
186 // (that is, there are no characters less than 1 byte in size). So lets (re-)enforce
187 // the native limit for efficiency when possible (it will make the while-loop below
188 // faster by there being less left to interate over).
189 $el.attr( 'maxlength', elLimit );
190 }
193 // Safe base value, used to determine the path between the previous state
194 // and the state that triggered the event handler below - and enforce the
195 // limit approppiately (e.g. don't chop from the end if text was inserted
196 // at the beginning of the string).
197 prevSafeVal = '';
199 // We need to listen to after the change has already happened because we've
200 // learned that trying to guess the new value and canceling the event
201 // accordingly doesn't work because the new value is not always as simple as:
202 // oldValue + String.fromCharCode( e.which ); because of cut, paste, select-drag
203 // replacements, and custom input methods and what not.
204 // Even though we only trim input after it was changed (never prevent it), we do
205 // listen on events that input text, because there are cases where the text has
206 // changed while text is being entered and keyup/change will not be fired yet
207 // (such as holding down a single key, fires keydown, and after each keydown,
208 // we can trim the previous one).
209 // See http://www.w3.org/TR/DOM-Level-3-Events/#events-keyboard-event-order for
210 // the order and characteristics of the key events.
211 $el.on( eventKeys, function () {
212 var res = trimValForByteLength(
213 prevSafeVal,
214 this.value,
215 elLimit,
216 fn
217 );
219 // Only set value property if it was trimmed, because whenever the
220 // value property is set, the browser needs to re-initiate the text context,
221 // which moves the cursor at the end the input, moving it away from wherever it was.
222 // This is a side-effect of limiting after the fact.
223 if ( res.trimmed === true ) {
224 this.value = res.newVal;
225 }
226 // Always adjust prevSafeVal to reflect the input value. Not doing this could cause
227 // trimValForByteLength to compare the new value to an empty string instead of the
228 // old value, resulting in trimming always from the end (bug 40850).
229 prevSafeVal = res.newVal;
230 } );
231 } );
232 };
233 }( jQuery ) );