source: sapic/static/jquery-entropizer-master/README.md @ 8edeab8

# jQuery Entropizer

*Password strength meter jQuery plugin*

For the standalone Entropizer engine, click [here](https://github.com/jreesuk/entropizer)

## What is jQuery Entropizer?

jQuery Entropizer is a simple, lightweight jQuery plugin that uses the [Entropizer engine](https://github.com/jreesuk/entropizer) to
calculate password entropy. It's easy to set up and provides several hooks to customize the UI.

jQuery Entropizer supports [AMD](http://requirejs.org/) and [CommonJS](http://wiki.commonjs.org/wiki/CommonJS). It is available
as a [bower](http://bower.io/) component.

## Demos

Some basic demos can be found [here](http://jreesuk.github.io/jquery-entropizer/).

## Getting Started

This plugin requires both [jQuery](http://jquery.com/) (1.7.2+) and [Entropizer](https://github.com/jreesuk/entropizer).

Basic usage:

```html
<label for="pwd">Please enter a password</label>
<input type="password" id="pwd" name="pwd" />
<div id="meter"></div>
```

```js
// Creates a default Entropizer meter inside #meter and watches the first password field on the
// page by default
$('#meter').entropizer();
```

Options and examples:

```js
// Create an Entropizer meter using custom options
$('#meter').entropizer({

        // The input field to watch: any selector, DOM element or jQuery instance
        // Default: 'input[type=password]:first'
        target: '#pwd',
        
        // The event(s) upon which to update the meter UI
        // Default: 'keydown keyup'
        on: 'keydown',

        // Used to calculate the percentage of the bar to fill (see map function below)
        // Default: 100
        maximum: 80,

        // An array of ranges to use when classifying password strength. Used internally by default map
        // function and can be used publicly via $.entropizer.classify(value, buckets). Properties
        // 'min' and 'max' are used to calculate which bucket to use - upon finding a match, an object
        // containing all the other properties is returned, e.g. below, a value of 42 returns
        // { message: ':)' }
        // Default: 4 ranges with strength and color properties (see source for values)
        buckets: [
                { max: 40, message: ':(' },
                { min: 40, max: 60, message: ':)' },
                { min: 60, message: ':D' }
        ],

        // Either an Entropizer engine options object or an Entropizer instance
        // Default: a new Entropizer instance with default settings
        engine: {
                classes: ['lowercase', 'uppercase', 'numeric']
        },

        // A callback controlling UI creation - takes a jQuery instance representing the container
        // and returns an object containing UI components for access in update and destroy
        // Default: creates a track element (the bar background), a bar element and a text element
        create: function(container) {
                var bar = $('<div>').appendTo(container);
                return { foo: bar };
        },
        
        // A callback controlling UI cleanup - takes the UI object created by create
        // Default: removes the track, bar and text elements
        destroy: function(ui) {
                ui.foo.remove();
        },

        // A callback that maps the raw entropy value to an object passed to update. First argument is
        // the number of bits of entropy, second argument is an object containing all properties on
        // the options object apart from target, on, engine and the callbacks (i.e. by default, just
        // maximum and buckets)
        // Default: uses maximum and buckets above to return an object with entropy, percent, strength
        // and color properties
        map: function(entropy, mapOptions) {
                return $.extend({ entropy: entropy }, $.entropizer.classify(entropy, mapOptions.buckets));
        },

        // A callback controlling UI updates - takes the data returned by map and the ui object
        // Default: updates the width and background color of the bar, and displays the number of bits
        update: function(data, ui) {
                ui.foo.text(data.entropy.toFixed(0) + ' ' + data.message);
        }
});
```

If you need to remove an `entropizer` instance:

```js
$('#meter').entropizer('destroy');
```

This will unbind all Entropizer events from the target and invoke the `destroy` callback.

## Styling

The default UI creates elements for the track, bar and text - these use the CSS classes
`entropizer-track`, `entropizer-bar` and `entropizer-text` respectively. Default styles for these
elements can be found in the provided CSS stylesheet.

## Engine options

For a guide to Entropizer engine options, see the readme [here](https://github.com/jreesuk/entropizer).

## Browser compatibility

jQuery Entropizer supports IE6+, Firefox, Chrome and Opera.