jQuery Plugin: Give Your Characters a NobleCount

NobleCount… for a more ‘proper’ count of the characters remaining.

A very common requirement with many of the more social products of the various companies I work with is the dynamic display of the number of characters remaining in a textarea, Twitter-style. When implemented, every one of these companies either developed a simple solution in-house or found a re-usable front-end plugin online. Most common, implemented within these products, and of all I could find open-sourced online, were sources lacking customization and/or, almost universally, lacking the desired user experience – updating the character count AFTER all or most of the user’s typing had ceased.

As a result, and also in my quest to always help provide my clients free, cheap and easy to use tools, I have been on the lookout for a jQuery plugin that would provide the ability to …

• provide non-delayed, real-time character counts,
• enable easy to customize visual behaviors, and
• permit event and DOM hooks for the savvy with more advanced character counting needs.

While there are other similar tools out there, none adequately met my goals. Therefore, I created the jQuery NobleCount plugin.

Usage

NobleCount is a customizable jQuery plugin for a more improved counting of the remaining characters, and handling of resulting behaviors, of a text entry object, e.g. input textfield, textarea. Also, NobleCount supports pre-existing text within the text object and jQuery chaining.

$('#textarea1').NobleCount('#characters_remaining1');
$('#textfield2').NobleCount('#characters_remaining2', { / * OPTIONS * / });

As text is entered into the target text area, an object for the purpose of tracking the total number of characters remaining, defined as the maximum number of characters minus the current total number of characters within the text entry object, is updated – storing that information visually and/or within the DOM as an HTML 5 compliant data-* attribute.

Events and CSS class alterations, if defined, are triggered based on current user interaction with the target text entry object as well as the current state (positive or negative) of the character remaining value.

Example:

$('#test1').NobleCount('#count1');

<div>
	<textarea id='test1'></textarea>
	<br>
	<span id='count1'></span> characters remaining remaining
</div>

METHOD(S)

To properly initialize, both the text entry object and the object that will store the total number of characters remaining must exist and be passed to NobleCount.

$(TEXT_ENTRY_OBJECT).NobleCount(CHARACTERS_REMAINING_OBJECT);

Both TEXT_ENTRY_OBJECT and CHARACTERS_REMAINING_OBJECT must be specified and valid.

Upon successful initialization, all appropriate events and classes are applied to the CHARACTERS_REMAINING_OBJECT, including the storage visually (if not disabled) or only in the DOM (if enabled) of the integer value representing the number of characters remaining.

The target maximum number of characters (max_chars) are determined by the following

precedence rules….

If max_chars passed via constructor
max_chars = max_chars passed
else if number exists within characters_remaining object and number > 0
max_chars = number within the text() of CHARACTERS_REMAINING_OBJECT
else use NobleCount’s default max_chars

Also note that within the NobleCount context…

NEGATIVE is defined as Integers < 0
POSITIVE is defined as Integers >= 0 [on_positive will fire when char_rem == 0]

Settings

By default, the maximum number of characters is set to 140 (à la Twitter), a negative number of characters remaining is permitted, and no events, classes, or DOM attribute modifiers are enabled.

To change these settings, they can either be accessed directly…

$.fn.NobleCount.settings.max_chars = 40;

… or at the time of initialization…

$(t_obj).NobleCount(c_obj, {max_chars:100});

The default settings data structure is…

$.fn.NobleCount.settings = {

on_negative: null,
on_positive: null,
on_update: null,
max_chars: 140,
block_negative: false,
cloak: false,
in_dom: false

};

The parameters are defined (and all can be overridden) thus…

on_negative

• class (STRING) or FUNCTION that is applied/called when characters remaining is negative IF DEFINED
• on_postitive class, if defined, is removed when on_negative event triggers

on_positive

• class (STRING) or FUNCTION that is applied/called when characters remaining is positive IF DEFINED
• on_negative class, if defined, is removed when on_positive event triggers

on_update

• FUNCTION that is called when characters remaining changes

max_chars

• target maximum number of characters

block_negative

• if TRUE, then all attempts are made to block entering more than max_characters
• if FALSE [default], text area will let individual entering the text to exceed max_chars limit (characters remaining can become negative)
• not effective against user pasting in blocks of text that exceed the max_chars value

cloak

• if TRUE, then no visual updates of characters remaining object (c_obj) will occur
• if FALSE [default], then the text within c_obj is constantly updated to represent the total number of characters remaining until the max_chars limit has been reached
• note, this does not have any effect on the char_rem value returned via any event callbacks

in_dom

• if TRUE and cloak is ALSO TRUE, then the number of characters remaining are stored as the attribute of c_obj named ‘data-noblecount’
• NOTE: if enabled, due to constant updating of a DOM element attribute, user experience can appear sluggish while the individual is modifying the text entry object (t_obj)

Settings example:

settings =
	{
		on_negative: 'go_red',
		on_positive: 'go_green',
		max_chars: 25,
		on_update: function(t_obj, char_area, c_settings, char_rem){
			if ((char_rem % 10) == 0) {
				char_area.css('font-weight', 'bold');
				char_area.css('font-size', '300%');
			} else {
				char_area.css('font-weight', 'normal');
				char_area.css('font-size', '100%');
			}
		}
	};

Any callback functions assigned to any of the available events are passed the following parameters: (t_obj, char_area, c_settings, char_rem)

t_obj

• text entry object

char_area

• characters remaining object

c_settings

• result of the options passed into NobleCount at the time of initialization merged with the default options

Having custom function append their own data to c_settings is also a great way to pass in and remember other state information that will be needed upon the triggering of NobleCount events.

char_rem

• integer representation of the total number of characters remaining resulting from the calculated difference between the target maximum number of characters and the current number of characters currently within t_obj

Get It

You can download NobleCount, dual licensed under GPL and MIT, from…

jQuery Repository
http://plugins.jquery.com/project/NobleCount

Git
Public Clone URL: git://github.com/theproductguy/NobleCount.git
GitHub: http://github.com/theproductguy/NobleCount

Zip
http://plugins.jquery.com/files/jQuery.NobleCount-source-bundle_1.0_20100322.zip

Demo

http://theproductguy.com/noblecount/noblecount.demo.html

Status updates can be found here, jQuery NobleCount.
If you find this useful, or have any questions, ideas, or issues, leave a comment.

Enjoy!

Jeremy Horn
The Product Guy