“jQuery patternLock” Documentation by “Bharat Patil” v1.0

“jQuery patternLock”

Created: 29/10/2014
By: Bharat Patil
Email: sun.bharat.patil@gmail.com

Getting Started
Basic Example - with id selector
Basic Example - with class selector
Example with center circles
Show or hide pattern line and change color of pattern line
Change pattern hole highlight color
Number of rows and columns
Width and Height of pattern lock
drawEnd() callback function
pattern value separator
valueArray option
Enable/Disable repeated selection of pattern hole
Pattern selection timeout
Destroy pattern lock
How to use patternLock inside a <form></form>
How to modify CSS to personalize patterLock

A) Getting Started - top

Before you can start using patternLock you have to include the css and the js files inside the <head></head> section of your webpage:

	
<link  href="patterLock.css" type="text/css" > 
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="jquery.patternlock.js"></script>

B) Basic Example - with id selector - top

Once above files are included you can use patternLock like below

<div id="pattern"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#pattern').patternLock();
	});
</script>

Output

B) Basic Example - with class selector - top

You can even use jquery class selector to create pattern lock

<div class="pattern"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('.pattern').patternLock();
	});
</script>

Output

D) Example with center circles - top

You can choose to show center circles as well as you can change size of it

<div id="patternCircles"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternCircles').patternLock({
			centerCircle: true,
			centerCircleSize: 20
		});
	});
</script>

Output

E) Show or hide pattern line and change color of pattern line - top

You can choose to hide pattern line. Also you can change color or width of line. Pattern line is by default visible.

Visible Pattern Line

<div id="patternLineEx"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternLineEx').patternLock({
			lineWidth: 10,
			patternLineColor: '#ff0000',
			showPatternLine: true
		});
	});
</script>

Hidden Pattern Line

<div id="patternLineEx"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternLineEx').patternLock({
			showPatternLine: false
		});
	});
</script>

Output

Visible Pattern Line	Hidden Pattern Line

F) Change pattern hole highlight color - top

To set background color of selected pattern hole, you can use 'selectionColor' option. It accepts css color value. If you don't want to highlight then pass 'transparent' as value.

<div id="patternHighlightColor"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternHighlightColor').patternLock({
			selectionColor: '#ff0000'
		});
	});
</script>

Output

G) Number of rows and columns - top

With these options you can set your own number of rows and columns. By default 3 rows and 3 columns will be created.

<div id="patternRowsColumns"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternRowsColumns').patternLock({
			rows: 4,
			columns: 4

		});
	});
</script>

Output

H) Width and Height of pattern lock - top

These options allow you to specify width and height of pattern lock. By default 250px is the width and height of pattern lock.
For best result it's adviced to keep same width and height of pattern lock.

<div id="patternWidthHeight"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternWidthHeight').patternLock({
			width: 300,
			height: 300
		});
	});
</script>

Output

I) drawEnd() callback function - top

To get value of drawn pattern, you can use this callback function. It will return value as a string joined with 'valueSeparator'.

<div id="patternDrawEnd"></div>
<h3>Drawn value is: </h3>
<div id="patternDrawEndValue"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternDrawEnd').patternLock({
			drawEnd: function(value) {
				$('#patternDrawEndValue').text(value);
			}
		});
	});
</script>

Output

Drawn value is:

J) pattern value separator - top

This allows you to specify value separator for pattern value. In above example you can see returned pattern value. They are by default separated by commas. If you want something else to separate those values, you can use this option to sepcify it. And if you don't want any separator, then simply set this option as empty string.

<div id="patternValueSeparator"></div>
<h3>Drawn value is: </h3>
<div id="patternValueSep"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternValueSeparator').patternLock({
			valueSeparator: '|',
			drawEnd: function(value) {
				$('#patternValueSep').text(value);
			}
		});
	});
</script>

Output

Drawn value is:

K) valueArray option - top

This option allows you to specify your own set of values that can be assigned to each pattern hole. Values will be assigned in a direction of left to right and top to bottom. Default values are
1 - 2 - 3
4 - 5 - 6
7 - 8 - 9
This is because pattern lock by default is of 3 rows and 3 columns, and it is result of number of rows into number of columns i.e. number of rows multiply by number of columns i.e. 9. If you specify array whose length doesn't match with number of rows multiply by number of columns then this option will be neglated and default values will be assigned.

<div id="patternArrayValue"></div>
<h3>Drawn value is: </h3>
<div id="generatedPattern"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternArrayValue').patternLock({
			valueArray: ['a', 'b', 'c', 'x', 'y', 'z', 'l', 'm', 'n'],
			drawEnd: function(value) {
				$('#generatedPattern').text(value);
			}
		});
	});
</script>

Output

Drawn value is:

L) Enable/Disable repeated selection of pattern hole - top

You can enable or disable repeated selection of pattern holes. By default if you have selected a pattern hole already and try to re-select it, it is not allowed. With this option set to true, you can enable it.

<div id="patternRepeatedSelection"></div>
<h3>Drawn value is: </h3>
<div id="generatedPatternS"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternRepeatedSelection').patternLock({
			allowRepeatSelection: true,
			drawEnd: function(value) {
				$('#generatedPatternS').text(value);
			}
		});
	});
</script>

Output
Note: Try selecting 1,2,3,2 and see the below generated pattern

With repeated selection enabled

Drawn value is:

With repeated selection disabled

Drawn value is:

M) Pattern selection timeout - top

Once you choose a pattern, whatever is drawn is shown for a particular time. For what time drawn pattern should be visible, that can be specified with this option in milliseconds. Default value if 500 which means half second.

<div id="patternTimeout"></div>
<h3>Drawn value is: </h3>
<div id="generatedPatternT"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternTimeout').patternLock({
			timeout: 4000,
			drawEnd: function(value) {
				$('#generatedPatternT').text(value);
			}
		});
	});
</script>

Output

Drawn value is:

N) Destroy pattern lock - top

You can inialize of destroy pattern lock. This is particularly useful in single page application to avoid memory leaks. When you call this method, it will remove any data associated with element and also unbinds events thus freeing memory.

<input type="button" value="Destroy" id="destroyPatternLock" />
<input type="button" value="Create" id="createPatternLock" />
<br><br>
<div id="patternDe"></div>
<script type="text/javascript">
	function createPatternLock() {
		$('#patternDe').patternLock();
	}
	function destroyPatternLock() {
		$('#patternDe').patternLock('destroy');
	}	
	$(document).ready(function(){
		createPatternLock();

		$('#destroyPatternLock').click(function(){
			destroyPatternLock();
		});

		$('#createPatternLock').click(function(){
			createPatternLock();
		});		
	});
</script>

Output

O) How to use patternLock inside a <form></form> - top

It is very easy to use pattern lock inside form elements. Just put your pattern selector inside <form></form> element and specify 'fieldName' option with the name that you want. And a hidden field will be generated automatically with that name.

<form>
	<div id="patternForm"></div>
	<input type="submit"/>		
</form>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternForm').patternLock({
			fieldName: 'generatedPattern'
		});
	});
</script>

Output

P) How to modify CSS to personalize patterLock - top

jQuery patternLock is highliy customizable. You can customize look and feel the way you want. To do this you need to know which are main CSS classes to be modified to customize patternLock. Also you can find these classes in given css file, though you need not to directly modify this file.
Please refer following diagram:

Let's understand the CSS classes from bottom to top:

.patternLock - This is the class of outermost wrapper of plugin. You can override this class to add background-image or background-color to entire rounded square etc.
.patternLock .tbl td - <td> is an html element used to draw pattern holes. Similar to above you can use this class to add background images or colors or to remove border radius, shadows etc.
.patternLock .tbl td.selected - Whenever user drags across pattern holes to draw a pattern, internally script adds "selected" class to each selected pattern hole and removes it automatically after given timeout.
.patternLock .centerCircle - In image above you can see small concentric yellow circles. This is the class of those circles. These circles are inside <td>
.patternLock .tbl td.selected .centerCircle - Similar to ".patternLock .tbl td.selected", as user drags to draw a pattern, you can use this CSS hierarchy to modify css for centerCircles as holes getting selected.

Example:

<!DOCTYPE html>
<html>
<head>
	<title>Basic Example - jQuery patternLock</title>
	<link rel="stylesheet" type="text/css" href="patternLock.css">
	<script type="text/javascript" src="jquery-1.11.1.min.js"></script>
	<script type="text/javascript" src="jquery.patternlock.min.js"></script>
	<style type="text/css">
	
	.patternlock {
		background: url("pattern.png");
	}
	.patternlock .tbl td {
		background: #fff url("pattern1.png");
	}	
	.patternlock .tbl td:hover {
	 	background: #fff url("pattern.png");   
	}

	.patternlock .tbl td.selected {
	 	background: #fff url("pattern2.png") !important;   
	}	

	.patternlock .tbl td.selected .centerCircle {
	 	background: #f00 !important;   
	}
	.patternlock .centerCircle {
		background-color: black;
		border: none;
	}
	
	</style>
</head>
<body>
<div id="patternCSSClasses"></div>
<script type="text/javascript">
	$(document).ready(function(){
		$('#patternCSSClasses').patternLock({
			centerCircle: true
		});
	});
</script>
</body>
</html>

Output

Note: You can find above example inside example directory with filename 'css-example-1.html'

Bharat Patil

Go To Table of Contents