jQuery Plugin : Effects jTypeWriter v1.1

Thu, 21/08/2008 - 00:54 — DuMmWiaM

A very useful plugin for re-creating the effect of a typewriter in any number of HTML text nodes. jTypeWriter can handle the type writing of more than one nodes, and type the characters in sequential order, with a minimal footprint (2.8kb)!

Installation

In order to work you need the jQuery library (version 1.2.6+) and the javascript file of the jTypeWriter effect! Once you have them, link them inside the head of your html file:

<script type="text/javascript" src"folderName/jQuery.js"> </script>
<script type="text/javascript" src="folderName/jTypeWriter.js"> </script>

don't forget to replace "folderName" with the folder that you've stored the two ".js" files.

Compatibility

jTypeWriter has been test for compatibility issues with the following broswers:

Internet Explorer 6+
Mozilla Firefox 2+
Opera 9+
Safari 3+
iPhone Safari, a little bit slow, bit it works :).

Probably it will work, with earlier versions of Opera and Safari, but I haven't try it out.

Usage

To properly use the jTypeWriter, you must first make sure that the DOM is ready to be traversed and manipulated. To acheive that the code of any jTypeWriter implementation must reside inside the event ready. For example let's assume you want to apply the jTypeWriter effect in the heading of your document which an <h1> with id="title" and you want the animation to last 1.5 seconds.

<script language="javascript" type="text/javascript">
$(function() {
$('h1 #title').jTypeWriter({duration:1.5});
}
</script>

An alternative way to achieve the same thing, is to ensure that the jTypeWriter is placed after the DOM element that you want to handle. Although it's not the "appropriate" way, you could do it (for example the Google analytics javascript code, is placed before the end of the <body>).

...html...
<script language="javascript" type="text/javascript">
$('h1 #title').jTypeWriter({duration:1.5});
</script>

Using jTypeWriter to this heading.

jTypeWriter Parameters

jTypeWriter plugin can accept 6 different parameters that can fully change effect and the final outcome. Below you can find the list of parameters of jTypeWriter:

duration: [number] default : 2
The duration of the type writer effect. How long it will take the whole animtation to complete. The default value of this parameter is: 2 (seconds).
type: [string->"letter","word","phrase"] default : "letter"
What type of animation will be performed. Currently there are 3 available options: "letter", "word" and "phrase". In "letter" the animation shows the characters one by one, as if you typed on your keyboard. The "word" animations shows one by one the words of the typed text. Finally the "phrase" shows whole phrases-clauses (from dot to dot), and it could be useful in cases where the typed text is very large. The default value of this parameter is: "letter".
sequential: [boolean] default: true
The sequential parameter, comes in handy when you have selected more than one DOM elements with the jQuery selector, in that case the jTypeWriter effect will start from the top DOM element and procceed to the next until it completes. If you set sequential:false and you have more than one DOM elements selected, the type writer for ALL effects will start and finish at the same time. The default value of this parameter is: true, which means that if you don't use it, it will type all text of all DOM elements in sequential order.
text: [string] default :null
If in any (weird) case you want to change the default text of the DOM element to be typed you can pass a parameter to that the text property and replace the default text. This parameter is not suggested for us if you try to aplly the jTypeWriter effect in multiple nodes, because the same text value (passed in the parameter) will replace the current text on each node. Maybe in next versions of jTypeWriter, I will change this parameter to accept arrays in order to replace the text values of multiple nodes. The default value of this parameter is: null, which means that the text of the selected DOM element(s) will not be affected.
loop:[boolean] default : false
If this parameter is set to true, then the animation will NEVER end :). Each time the animation completes, the text will be removed and will start again. The default value of this parameter is: false.
loopDelay:[number] default : 0.
This parameter is taken into consideration only if loop is set to true and it controls the delay in seconds between loops. The default value is 0 which means, that in a loopable animation once the typing completes it will start all over again (very awkard for large chunks of text).
onComplete: [function] default : null]
Although it is parameter, technically speaking it is an event (aka a function) that will be called when the type writer effect completes.So if you want something to happen when the effect completes, then pass the name of the function(without the brackets) that will be fired on the completion of the animation.
For example: $('h1.title').jTypeWriter({onComplete:functionName});
The default value of this parameter is: null.Which means no function will be executed :).
Important Note: In case you have the paremeter loop: true, the function that you have provided for the onComplete event will be fired EVERY time the jTypeWriter complete the typing circle and starts a new one.

Notes & Advanced Features

Bellow you will find notes and explations on various advanced features:

Force end jTyperWriter effect!

In case you want to force the jTypeWriter effect to finish the animation before the completion of the duration circle, you can access a special function called: endEffect(). This function should be offered as a way to the user to prematurely end the jTyperWriter effect and read the text that it is been currently animated (in cases that the animated text or the duration is taking longer than anticipated). My suggestion is to bind that function to an event, probably some a click event in a button, placed near by the text. I would not suggest to place the button bellow the animated text, because as the text will be typed and new lines appear on the browser the button will be moved (unless you apply some good CSS).

Bellow I am displaying an example of forcing the jTypeWriter effect to end.

var obj1 = $("h1.title").jTypeWriter({duration:2 , order:"sequential" , type:"letter" , loop:true});
$("button#end").clickclick(function(){
obj1.endEffect();
}

First of all in line (1) we must assign a variable to the returned value of the jTypeWriter effect, in this case I use a generic name obj1. In line (3) we are using the build in function endEffect() of obj1 to force end the animation, when the button is clicked in code line (2).

A multiple node jTypeWriter example.

With loop enabled.

That will be ended when you click the "END effect" button.

HTML entitites inside selected DOM nodes

I have not taken into consideration the existance of any HTML elements or nodes inside the DOM nodes that the jTypeWriter affects. jTypeWriter must be used only inside nodes that have text, nothing else. For example if you want to animate the contets of an unordered or order list (<ul> or <ol>) you should select the list items (<li>)with jQuery.
For example: If you want to animate an unorder list with id="chapters", you should use: $('ul#chapters li').jTypeWriter();
instead of:
$('ul#chapters').jTypeWriter();

Image nodes are not an exception. Avoid applying jTypeWriter inside DOM nodes that have images inside (until I figure of a way of improving the plugin).

Examples

Example A : Simple usage

Use of jTypeWriter, without any parameters to a series of headings simple element.
CODE: $('.exampleA_Header').jTypeWriter();

Using jTypeWriter to this two paragraphs of text.

The type writer effect is continuous.

Example B : Duration & Word Typing

The first and most important parameter, is duration, by setting duration to any number (integer or decimal) you set the duratio of the typing effect.
By setting the type parameter to "words" we force the jTypeWriter to type words, not letters.
CODE: $('.exampleA_Header').jTypeWriter({duration:6.5,type:"words"});

This paragraphed will be typed, word-by-word and it will show very slowly since the duration is set to 6.5 seconds, which is rather slow for this size of text.

Example C : Simultaneous typing & Looping!

In this example we examine tree parameters of the jTypeWriter. If we set the sequential parameter to false then all the nodes selected with the initial query, will be typed in the same order.

Finally if we set the loop parameter to true, and the loopDelay to 5 then the animation will loop endlessly and will pause for 5 seconds between every loop!
CODE: $('.exampleC_Header').jTypeWriter({sequential:false, loop:true, loopDelay:5});

Type all DOM elements simultaneously...with a loop!

Very risky effect, but still it's available.

I wouldn't recommend it unless you have someting in mind.

Read Notes and Advanced Features, to see how you can force end the jTypeWriter effect.

Example D : OnComplete Event!

If you want to do something when the jTypeWriter has finished, you can pass a function inside the onComplete parameter.
CODE: $('.exampleD_Header').jTypeWriter({sequential:false,loop:true});

When this paragraph finishes typing an alert message will be shown!

Download

You can download a set of files, full of working examples. Click bellow to download it!

Download jTypeWriter v1.1 examples!

ChangeLog

30 AUG 2008: version 1.1 released. Changes:

Parameter: order removed. Replaced with parameter: sequential, that accepts true or false.
New option added in parameter: type. The new parameter is the third available and it's called: "phrase", allowing users to type whole phrases (clauses).
The names of type, parameter have changed from singular to plurar, "word" instead of "words" and "letter" instead of "letters". Default value is still "letter".
New parameter added: loopDelay, it accepts numeric values and it defines the number of seconds to delay before the jTypeWriter goes in new loop. This parameter works in conjuction with, loop:type.

21 AUG 2008: version 1.0 released

License

jTypeWriter is released under GPL Open Source Licenses...thus it is completely and totally free!. You are obligated to keep all credits (links, names etc) and if you feel like it a link to this page will be appreciated!

jQuery

Comments

Sun, 21/09/2008 - 16:58 — petey (not verified)

Is it possible for each loop

Is it possible for each loop to write out different text rather than repeat the same text?

Sun, 21/09/2008 - 19:58 — DuMmWiaM

It can be done but...

I think it can be done, but there must be a single node selected and an array of strings to loop through. Currently though maybe I will include it in version :) 1.3.0.

Wed, 17/09/2008 - 23:13 — Anonymous (not verified)

;)) bravo ts@kI

Tue, 26/08/2008 - 09:37 — DuMmWiaM

Hmmmm

Nice effect, I will try to implement it in version 1.3.0. Currently I am completing version 1.2.0. and then I will give it a go. I am afraid that older browsers (for example IE 6.), would not be able to handle this kind of speed an quality in this kind of effect. Don't forget that what you saw was in Flash...and Flash is much faster!

Mon, 25/08/2008 - 23:38 — pixeline (not verified)

nice _ another effect

nice! would you be able to add such text animation as this one? (see bottom) http://www.yugop.com/