Documentation jQuery Handwriting by Digitalplant

JQUERY HANDWRITING

View Demos || Purchase jQuery Handwriting

If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here.

Table of Contents

  1. Description
  2. Quick Start Guide
  3. Add Some Basic Options
  4. Decorate Animated Text with Images
  5. Advanced Usage
  6. Features
  7. Options
  8. Methods
  9. Events
  10. Demos Explained

Description - top


This is a javascript based tool that uses the canvas object to draw symbols. Each symbol is defined using multiple curves and each curve consists of start, end and control point. The tool comes with two sets of curves with limited number of symbols, but more symbols and more sets can be created and added to the tool in the future. The tool allows decoration of the curves with images defined by user. The tool features more than 20 options to customize but it can also be used in a simple configuration.

Quick Start Guide - top


1. In order to play, the tool needs to execute on an object that contains text content. I did all my tests with a div object. It is a must that the div is relatively or absolutely positioned, because the tool creates layers of canvas objects within the div that are absolutely positioned. Another important attributes are the width and the height of the div element. The div may have class or id attribute in order to be easily selected. Lastly the div needs to have text content.
<div id="hello_world" style="position: relative; width: 580px; height: 280px;">Hello World</div>
2. After you have created the div element you will need to import some Javascript files. These are jQuery (version 1.8.0+), and the handwriting plugin. In my demos, I add these in the header of the document.
<script src="http://code.jquery.com/jquery-1.8.0.js"></script>
<script src="jquery.handwriting.js"></script>
3. Lastly you need to select the div element and run the handwriting animation. It is possible to not specify any options and the default ones will be used.

Note: The tool gives errors when working with jquery versions lower than 1.8.0, because the absence of parseHTML method. Most of the testing during development was performed with jquery 1.9.1.

<script>
 jQuery(document).ready(function($){  
  $('#hello_world').HandWriting();
 });  
</script>

Add Some Basic Options - top


The default options set will display the text animation, but you will have to tweak the animation to your needs, by defining some options. Here is a list of some basic options:

1. Color of the text. It can be set in different ways: 'white', '#ffffff', 'rgb(255,255,255)'. This color will apply to all the text that has no individual setting for color.

jQuery('.handwritingSIMPLE').HandWriting({
  text_color: 'rgba(250,250,250,1)'
});

2. Stroke width. This is an integer number starting from 1. This option will apply to all text, except for one with individual setting of stroke width.

jQuery('.handwritingSIMPLE').HandWriting({
  text_lineWidth: 5
});

3. Scale and line height. Scale option allows the setting of the size of the symbols animated. Every symbol set (or we may call it font) that I created for the tool has some default value for the width and height of letters. The scale parameter can increase or decrease these values resulting in changing of font size. Typical values range from 0.2 to 2.0. The line height option is used when the text cannot fit on one line. It is set in pixels and is affected by the hw_scale option.

jQuery('.handwritingSIMPLE').HandWriting({
  hw_scale: 2.0,
  line_height: 50
});

4. Padding and alignment. Integer values in pixels can be set to define offset from side and top borders of the div. Note that these values are affected by the hw_scale option. Thus if you enter 10px and have hw_scale of 2.3 you will have 23 px as a result. Alignment can be 'center', 'left' or 'right'.

jQuery('.handwritingSIMPLE').HandWriting({
  line_offset_x: 0,
  line_offset_y: 25,
  text_align: 'right'
});

5. Pen. Pen can be visible or hidden. You can define the pen image. Note that the tool expects the top left corner of the image to be the drawing part. Png files with transparency are the best choice.

jQuery('.handwritingSIMPLE').HandWriting({
  show_pen: true,
  pen_image: 'mc_pen.png',
});

6. Symbols drawing accuracy. Each symbols consists of curves and each curve can be drawn in number of steps. Higher values mean a more slow and accurate drawing. A value can be set for the symbols, and another one for the invisible pen animation between letters.

jQuery('.handwritingSIMPLE').HandWriting({
  letter_steps: 3,
  steps_between_letters: 3
});

7. Overall animation control. It is possible to pause the animation in the begining and then play it with a public method. It is possible to auto replay the animation when it ends. Animation can wait a number of milliseconds and then fade out in number of milliseconds. Or it can just stay visible after finish.

jQuery('.handwritingSIMPLE').HandWriting({
  paused: false,
  replay: true,
  wait_after_finish_duration: 3000,
  finish_effect: 'fade',
  finish_effect_duration: 1000
});

Decorate Animated Text with Images - top


The main feature of the tool is the ability to decorate the animated text with images - drawings[]. This can be done in two possible ways.

1. The standard decoration mode uses one or more images and places them on the curves. The density of placement depends on the letter_steps option. For example if set to 3 that means each curve will have 4 images placed on it. I used small images 30px x 30px in PNG format with transparency. This size is too big for small texts though. That is why I have an option that defines a scale factor for each image - isc[]. Another feature of the tool is that the decodation images animate their scale and rotation. I have an option that defines in how many frames each image will animate - anim_layers. Each image will show zoomed out and with random or fixed rotation (around center) - image_rotation and then will gradually for anim_layers frames animate to full width defined by its dimensions and isc[] scale factor. The anim_layers options is set to 0 by default so it is mandatory to choose a number >0 in order to run the animation. Lastly images can be positioned exactly on the curves - that is when random_pos_x, random_pos_y are set to 0, or slightly offset by a factor of their dimensions, when the options are set with a float number >0 and <=1. In the example below three images will be used to fill the curves of the symbols with decoration alternatively. Each of them will show very small with random orienation and will animate for 12 frames to its full width/height scaled by corresponding isc value. the images will be randomly offset by 15% of their dimensions (again scaled by isc. This decoration mode is switched on by animate: false option. False is the default value of this option so it is not mandatory to set it.

jQuery('.handwritingDECORATED').HandWriting({
  letter_steps: 3,
  drawings: ['lred.png', 'lyellow.png', 'lgreen.png'],
  isc: [0.35, 0.5, 0.75],
  anim_layers: 12,
  image_rotation: 'random',
  random_pos_x: 0.15,
  random_pos_y: 0.15
});

2. The sequence animation mode uses more than one images, which are frames taken from an animation. In my demos I have a blooming flower animation. I created it in Flash and then exported PNG sequence. There are different programs that can create animated frames in separate files. This is a tutorial that can be used by Flash users. The tool will again decorate the curves with the letter_steps density, but it will not zoom the images. It will just change the image for each decoration point every step of the animation. Still dandom orientation and placement can be used. The number of frames for animation duration of the image is not needed here - it is defined by the number of files entered. This decoration mode is switched on by animate: true option.

jQuery('.handwritingDECORATED').HandWriting({
  animate: true,
  letter_steps: 8,
  drawings: ['anim/b0001.png', 'anim/b0002.png', 'anim/b0003.png', 'anim/b0004.png', 'anim/b0005.png', 'anim/b0006.png'],
  isc: [0.6],
  image_rotation: 'random',
  random_pos_x: 0.2,
  random_pos_y: 0.2
});

3. Stroke. You can define if the stroke will at all be visible by use_stroke option. Also it is possible to display the stroke above the image decoration layer with the stroke_above_image option.

jQuery('.handwritingDECORATED').HandWriting({
  ...
  stroke_above_image: true,
  use_stroke: true
});

Advanced Usage - top


The tool allows the use of few public methods, also the setting of complete event handler and the use of span objects for setting individual options for parts of the text.

1. There are two public methods that can be used in the following way.

var hworld = jQuery('#hello_world').HandWriting({
  paused: true
});
hworld.play_anim();

A variable is defined that can later be used to call the play_anim method. For example the animation can wait for a click event from a button. The same way a playing animation can be paused.

var hworld = jQuery('#hello_world').HandWriting({
  replay: true
});
hworld.pause_anim();

2. It is possible to define a function to execute when the animation is finished.

var hworld = jQuery('#hello_world').HandWriting({
  complete: function(){alert('Hello world')}
});
hworld.pause_anim();

3. In order to define individual options to parts of texts span objects can be used. Parts of text can have different color:

Hello <span style="color:#fff">World</span>

or different stroke width.

Hello <span data-width="2">World</span>

Lines brakes can be inserted:

<span>Hello <br /><br />World</span>

Lastly different images can be assigned for decoration. This is done using the data-images attribute. The possible values are the ids of selected images from the drawings[] option.

jQuery('.handwritingDECORATED').HandWriting({
  animate: false,
  letter_steps: 3,
  drawings: ['lred.png', 'lyellow.png', 'lgreen.png'],
  isc: [0.35, 0.5, 0.75],
  anim_layers: 12,
  image_rotation: 'random',
  random_pos_x: 0.15,
  random_pos_y: 0.15,
});
...
<div id="hello_world" style="position: relative; width: 580px; height: 280px;"><span data-images="0-2">Hello</span> <span data-images="0,2">World</span></div>

The word 'Hello' will be decorated with images 'lred.png', 'lyellow.png', 'lgreen.png' (ids from 0 to 2). The word 'World' will be decorated with images 'lred.png', 'lgreen.png' (ids 0 and 2). This feature can used in creative ways. For example if animation mode is selected images can be animated backwards - data-images="10-0". It allows to slow down parts of animation too data-images="0,0,0,0,1-8,9,9,9,10,10", etc.

4. There is one special option called clear_frames. When set to true, it will force a clearRect of the canvases on each frame. That may be needed in animation mode. When set to false (default value) it allows each animated image to combine with the one below it, which can be used in creative way. When set to true the performance suffers. All demos are using the false value of that option.

5. In order to make the div linkable, a click method can be defined for the div, or put the div in a link.

6. The font size and color of the targeted div are only used to display its content if javascript is disabled, thus these properties are not used in the actual animation. On the other hand text alignment can be set in the div and it will be used by the tool.

The only possible text content is raw text, or text within spans with style, data-width and data-images attributes. All other html tags will be ignored.

Features - top


Options - top


OptionDefault ValueDescription
xml_file'letters_verdana.xml'This is the name of the file that holds curve information for each symbol of the font.
hw_scale0.5Each symbol in the xml file has its default width and height, which can be scaled by the value of this parameter in order to increase or decrease font size. This is a float number and 1.0 means 100% of default values will be used.
line_height50When text is too much to fit in one line this parameter is used to define how far down the next line will go. It is measured in pixels and is affected by hw_scale.
text_color'rgba(127,127,127,1)'Defines the color of the stroke to be used. Applies on all curves. Different colors can be set for parts of text within span objects with inline style set color. <span style="color: #f00">Example</span>
text_lineWidth1Defines width of stroke in pixels. Not affected by hw_scale. Can be set for parts of text within span objects with defined data-width value. <span data-width="3">Example</span>
line_offset_x0Defines indent from side borders in pixels. It is affected by hw_scale value.
line_offset_y0Defines indent from top border in pixels. It is affected by hw_scale value.
text_align'left'Possible values - 'left', 'right' and 'center'. Alignment can also be set with inline style for the selected div objects.
letter_steps3Defines in how many frames each curve is animated. More steps mean a more slow and delicate movement of pen while drawing. This option also defines how many images will decorate each curve of each symbol. More steps mean more images.
steps_between_letters3Defines how smooth the pen will move between letters. This is invisible animation with no stroke and no images.
show_pentrueCan be set to true or false. Shows or hides the pen image.
pen_image'pen.png'A png image for the pen. The ball of the pen must be positioned in top/left corner.
drawings[]Array of paths to images to be used to decorate the curves. Images apply to all text curves, but can be applied individually to parts of text in span object with data-images value set. For example if we have option defined: drawings: ['flower.png', 'leave.png', 'flake.png', 'red_lamp.png'] and part of text <span data-images="2,2,3,1-3">Example</span> flake,flake,red_lamp,leave,flake,red_lamp images will be used for these curves. Can be very well used for reversed animations too. If we have drawings: ['f0.png', 'f1.png', 'f2.png', 'f3.png', 'f4.png'] we can use data-images="0-4,3-0" to play the sequence forward and backwards, or "0,0,0,1,1,2,3,4" to slow the speed for first frames, etc.
isc[]Array of float numbers used to scale each image from drawings. If more images are defined than scale values the isc[0] value is used.
anim_layers0This option defines number of frames to animate each image that decorates the curves. More layers mean a longer animation, which is fixed to a zoom in of width and height from 1/anim_layers of the respectful scale to 100% of respectful scale. There are two modes of image usage. In the sequence animation mode anim_layers is not used.
image_rotation'random'Can be set to 'fixed' or 'random'. If fixed, no rotation is applied to images. If random, each image receives a random number (0..2*PI). When used in no sequence animation mode, upon growing each image is additionally rotated with 0..PI/2. When used in sequence animation mode no additional angle is added to the randomly generated.
random_pos_x0Each image can be placed exactly on the curve or slightly offset. This option is used to generate random offset for x coordinate. The actual number in pixels uses the width of image, the isc scale value and this value. When 0.5 is used that means 50% of the width scaled by isc will be the maximum possible random number to offset the image.
random_pos_y0Same as above applied for y coordinate.
animatefalseThis is the option that sets one of the two methods of image usage. When set to false each image is used on its own with the growing rotating effect. When set to true, images are used as frames from a sequence animation.
clear_framesfalseWhen set to true the image animation canvas gets erased on each step. In the case where we have a bigger image changing to smaller image that will help to visualize correctly. When set to false each image draws upon the last one, which also can be used to achieve interesting effects. When set to true it kills the performance.
stroke_above_imagefalseDefines z order of stroke and images canvas. Applies to all text.
use_stroketrueIf false no stroke is animated.
pausedfalseAnimation can wait initially if set to true.
replayfalseAnimation can start again if set to true.
wait_after_finish_duration2000Time in milliseconds to wait after animation is done.
finish_effect'none'Can be 'none' or 'fade' to define effect of fading after wait_after_finish_duration milliseconds.
finish_effect_duration1000Duration of fade effect in milliseconds if set.
msundefinedIf not set it will auto calculate. If set that is the number of milliseconds for each frame. There is hard coded setting of ms to 30 if it is more than 30.

Methods - top


pause_anim()If animation is playing this method can be called to pause the animation.
play_anim()If animation is paused by default or after using the pause_anim() method, it can be started by this method.

Events - top


completeA function can be tied to this event which will execute every time the animation is finished.

Demos explained - top


MERRY CHRISTMAS

var hw_mc = $('#merry_christmas').HandWriting({
 text_color: 'rgba(0,100,0,1)',
 text_lineWidth: 2,
 show_pen: true,
 pen_image: 'mc_pen.png',
 anim_layers: 20,
 steps_between_letters: 8,
 letter_steps: 8,
 isc: [0.75, 0.75, 0.75, 0.75, 0.75, 0.5],
 hw_scale: 2.0,
 line_offset_x: 0,
 line_offset_y: 25,
 drawings: ['lred.png', 'lyellow.png', 'lgreen.png', 'ggold.png', 'gred.png', 'g2.png'],
 replay: true,
 wait_after_finish_duration: 3000,
 finish_effect: 'fade',
 image_rotation: 'random',
 random_pos_x: 0,
 random_pos_y: 0,
 text_align: 'center',
 complete: function(){hw_hny.play_anim();}
});
<div id="merry_christmas" style="position: relative; top: 0px; left: 0px;width: 600px; height: 300px; border: 1px solid #300; font-size: 100px; background-image: url('mc_bgr.jpg'); color: #080"><span data-images="4,5,2,0">Merry</span> <span data-images="3,5,5,1">Christmas</span></div>

This demo plays in a div with id 'merry_christmas', which has 600px width and 300px height. It is relatively positioned which is a must in order for the absolutely positioned generated canvases to work. It has background image and font size matched closely to that of the animation to be plaid. It has greenish text color (text_color), stroke width of 2 px (text_lineWidth), will show pen using mc_pen.png, will use 8 frames to animate symbol curves and 8 frames to animate between symbols. Will use 20 frames to animate the images set in drawings with scales set in isc. The overall scale is set to 200%. A vertical offset is set for vertical alignment. The animation will fade and replay. Images will show exactly upon curves with random rotation. Animation will be centered horizontally. The text "Merry" will use gred.png (red decoration), g2.png(green leave), lgreen.png (green light) and lred.png (red light). The text Christmass will use gold decoration, green leave, green leave and yellow lamp. Also when animation is completed the HAPPY NEW YEAR animation is started.

HAPPY NEW YEAR

var hw_hny = $('#hny2014').HandWriting({
 text_color: 'rgba(0,100,0,1)',
 text_lineWidth: 2,
 show_pen: true,
 pen_image: 'mc_pen.png',
 anim_layers: 10,
 steps_between_letters: 12,
 letter_steps: 12,
 isc: [0.08, 0.5, 0.75, 0.75],
 hw_scale: 1.8,
 line_offset_x: 0,
 line_offset_y: 25,
 drawings: ['sn4.png', 'g2.png', 'lcyan.png', 'lgreen.png'],
 replay: true,
 paused: true,
 wait_after_finish_duration: 3000,
 finish_effect: 'fade',
 image_rotation: 'random',
 random_pos_x: 0.1,
 random_pos_y: 0.1,
 line_height: 60,
});
<div id="hny2014" style="position: relative; top: 0px; left: 0px;width: 600px; height: 300px; border: 1px solid #111; text-align: center; font-size: 100px; background-image: url('hny_bgr.jpg')"><span style="color:#888" data-images="0,0,0,3">Happy New Year</span> <span style="color:#080" data-images="1,3">2014</span></div>

The difference here from above demo is that alignment is set not with parameter but with inline style "text-align: center". Also in this demo different colors for text are used in the span objects. This animation is paused by default and waits for MERRY CHRISTMAS animation to finish and start it.

BE MY VALENTINE

var hw_sv = $('#saint_valentine').HandWriting({
	text_lineWidth: 3,
	text_color: 'rgba(0,100,0,1)',
  xml_file: 'letters_verdana.xml',
  show_pen: true,
	steps_between_letters: 7,
	letter_steps: 7,
	hw_scale: 2.3,
	line_offset_x: 0,
	line_offset_y: 10,
	drawings: ['f11.png', 'f2.png', 'f1.png', 'f7.png', 'f8.png', 'f9.png'],
	isc: [0.5,0.5,0.5,0.5,0.5,0.5,0.75],
	paused: false,
	replay: true,
	animate: false,
	anim_layers: 15,
	wait_after_finish_duration: 3000,
	finish_effect: 'fade',
	image_rotation: 'random',
	random_pos_x: 0.15,
	random_pos_y: 0.15,
	line_height: 60
});			
<div id="saint_valentine" style="position: relative; top: 0px; left: 0px;width: 600px; height: 300px; border: 1px solid #300; text-align: center; font-size: 100px; background-image: url('sv_bgr.jpg')"><span data-images="1" style="color:#800">Be My</span> <span data-images="0-5">Valentine</span></div>

Only difference here is that images are set with interval method - data-images="0-5" instead of data-images="0,1,2,3,4,5"

BURN MARKS

var hw_anim = $('#animation1').HandWriting({
 xml_file: 'letters_verdana.xml',
 text_color: 'rgba(0,0,0,1)',
 show_pen: false,
 steps_between_letters: 15,
 letter_steps: 15,
 hw_scale: 2.70,
 line_offset_x: 0,
 line_offset_y: 10,
 drawings: [		
   'anim/b0001.png', 'anim/b0002.png', 'anim/b0003.png', 'anim/b0004.png', 'anim/b0005.png', 'anim/b0006.png',
   'anim/b0007.png', 'anim/b0008.png', 'anim/b0009.png', 'anim/b0010.png', 'anim/b0011.png', 'anim/b0012.png', 'anim/b0013.png'],
 isc: [0.6],
 stroke_above_image: false,
 paused: false,
 replay: true,
 animate: true,
 wait_after_finish_duration: 3000,
 finish_effect: 'fade',
 image_rotation: 'random',
 random_pos_x: 0.15,
 random_pos_y: 0.15,
 line_height: 50,
 use_stroke: false,
 ms:30
});
<div id="animation1" style="position: relative; top: 0px; left: 0px;width: 600px; height: 300px; border: 1px solid #111; text-align: center; font-size: 130px; background-image: url('burn_bgr.jpg'); color: #000;"><span data-images="0,0,0,0,0,0,1,1,1,1,1,2,2,2,2,3,3,3,4,4,4,5,5,5,6,6,6,7,7,8,8,9,9,10,10,11,12">Burn Marks</span></div>

In this usage the sequence animation mode is present. (animate: true). Also as you can see in the data-images parameter the images from the start of the animation are used more than once, which results in a kind of delay of burning. The images are semi transparent, which also adds to the effect when used with clear_frames: false. Also in this demo no stroke is animated and only images are used. In this demo also ms is set to 30 milliseconds.

BLOOMING FLOWERS

var hw_anim = $('#animation2').HandWriting({
 xml_file: 'letters_verdana.xml',
 show_pen: false,
 steps_between_letters: 4,
 letter_steps: 4,
 hw_scale: 2.50,
 line_offset_x: 0,
 line_offset_y: 10,
 drawings: [	
   'anim/p0001.png', 'anim/p0002.png', 'anim/p0003.png', 'anim/p0004.png', 'anim/p0005.png', 'anim/p0006.png', 
   'anim/p0007.png', 'anim/p0008.png', 'anim/p0009.png', 'anim/p0010.png', 'anim/p0011.png', 'anim/p0012.png', 
   'anim/p0013.png', 'anim/p0014.png', 'anim/p0015.png', 'anim/p0016.png', 'anim/p0017.png', 'anim/p0018.png', 
   'anim/p0019.png', 'anim/p0020.png', 'anim/p0021.png', 'anim/p0022.png', 'anim/p0023.png'],
 isc: [0.6],
 stroke_above_image: false,
 paused: false,
 replay: true,
 animate: true,
 wait_after_finish_duration: 3000,
 finish_effect: 'fade',
 image_rotation: 'random',
 random_pos_x: 0.1,
 random_pos_y: 0.1,
 line_height: 50,
 ms:20
});
<div id="animation2" style="position: relative; top: 0px; left: 0px;width: 600px; height: 300px; border: 1px solid #151; text-align: center; font-size: 120px; color: #E4312F; background-image: url('green.jpg')"><span data-images="0-22,21-0">blooming flowers</span></div>

Here we also have sequence animation mode. "0-22,21-0" in data-images is used to play forward and backwards the blooming animation. If clear_frames is set to true here the final frame of each animation will look like the first, but now they just pile up.