Wednesday, May 30, 2012

Maxlen Jquery Plugin

You know that little functionality where you want to limit the characters entered into an input field while showing the user how many characters they have entered or how much characters remaining? Think Twitter style, that limits the characters entered to 140 and shows you how many characters you have left for your tweet?

This is exactly the functionality the Maxlen JQuery Plugin implements, a JQuery plugin I had to put together as I got tired of the repetitiveness of having to implement this in my projects.

Thing is, I recently implemented this function twice on two different projects in the last 2month, and I got irritated with having to copy and paste code all about the place. And so I used it as an excuse to just write a JQuery plugin.

JQuery obviously has a cool Plugin architecture so it did not take much time to put my first JQuery Plugin together :)

Maxlen JQuery Plugin is that: a simple JQuery plugin that allows you easily limit the number of characters that a user can write in a field and state either how many characters has been used or how many characters is left. It works with both Textarea field and the Input type text HTML element.


How It Works
Maxlen JQuery Plugin can be used on either Textarea element or Input[type=text]. Once the Plugin is activated for the desired field, the number of characters entered would then be limited based on supplied settings. The default characters allowed is 160. This can easily be changed.

The really useful part of the Maxlen JQuery Plugin is the feedback it gives users as they type in, as the allowed character length can easily be done with the HTML maxlength property. The plugin has two options of showing this: It can either show how many characters has been used or how many characters are remaining before the stipulated limit is reached.

Usage is simple. To activate the plugin on a textarea with an ID of "feedback" write:

$(document).ready(function()
{
$('textarea#feedback').maxlen();

}
);

This would use the default values and limit allowed characters to 160.

Maxlen JQuery Plugin can be used on more than one element at the same time. So the following code would work:

$(document).ready(function()
{
$('textarea,input').maxlen();
}
);

or

$(document).ready(function()
{
$('textarea').maxlen();
$('input').maxlen();
}
);

Note that even though the type of Input is not specified, the plugin would only take effect on input[type=text]

Options available

The previous codes initiates the Plugin with its default settings. But that is not the only way it can be used. It offers some level of customization options.

To initiate the plugin with all the full options, you have:

$('textarea').maxlen({
      'limit' : 160,
      'order' : 'desc',
      'class' : 'maxlen_class',
      'position' : 'above'
    });

A quick explanation of the options:

limit
States the limit of characters allowed. Default is 160.

order
States whether the plugin would show how much characters has been used in the limit specified or how much is remaining.The allowed options are 'desc' and 'asc'. 'desc' shows remaining characters, 'asc' shows used characters. The default is 'desc'.

class
States the class name for the indicator showing the characters. The default is maxlen_class. You can change this to whatever string you want. Use this class name to style the indicator.

position
States where the indicator should be placed, whether above the input element or below. The allowed options are 'above' and 'below' The default is 'above'.

That is all to it.

So now that the plugin is out there, I hope it would prove useful to others too. To get your hands on it and for full details on how to use it in your project, please head over to Github where it is hosted. You can grab it here and find the readme file here

No comments: