Wednesday, May 7, 2008

Introduction

This is a generic JS Class, that allows you to translate(parse) the content of text nodes, and replace them for the new content.
You only need to specify the parsing function, and the starting (root) node.
All the text nodes inside it, will get parsed.

Modes

The class supports synchronous and asynchronous parsing.
The parsing function will receive the original text as first argument.
If you can parse the text right away, then just return it from the parsing function.
If it needs to be delayed (f.e: AJAX request), then the set the attribute 'sync' of the instance, to false. By doing this, you will get a second argument in the parsing function, which will be a function that you need to call, passing it the parsed text.

Returned data

The parsed data you return can be:

a string

This is the standard, a string replacing the old one.

nothing

new If you don't return data, or the same string, it will just get skipped.

a node

new You can return an html node.

an array

new You can return an array with nodes and/or strings.

Filteringnew

Optionally, you can pass the translator, a filtering function. This way you can exclude elements (and their descendants) from the parsing.
To use it, pass the function as second argument to the constructor.
It will receive the (element) node, and it must return true or false.

How to use

Check the demo to see both modes and filtering in action.
You need to call the method 'traverse' of the instance, passing it the root node.
Remember to call the method after the html document is parsed, so you can access all the nodes in it.

14
comments:

- instead of having take Translator take a function, have it take an object and use a property of the object as callback function. This way, callers can add custom data to receive in the callback. (Use the same technique as in jQuery.ajax).

- for large pages, when this script is applied to the root node, it will freeze the page. To avoid this, split the processing into a configurable chunks that are processing in each configurable interval.

- finally, a feature that would exclude subtrees that are root in certain elements (such as <a>) would be nice.

These three features would significantly simplify the implementation of such functionality as autolinking (for a Firefox script that implements items #2 and #3, see Ruderman's autolinking script )

ad 1) an object-based design seems more forward looking as it would keep the signature of the constructor identical as you add more functionality to your translator. For instance, your current code assumes that "parse" returns text that's then transformed into a text node.... but what if I'd like to, say, highlight a word? That would split the text node into multiple text nodes and elements.

ad 2) Instead of using recursion, you could use an array as a stack. Then pass the array to the continuation function. In each call, process n array elements.

My serialScroll works well, but my slides are html blocks with clickable links to go to specific pages, THE PROBLEM IS IF A CLICK ON THOSE LINKS THE ONLY THINK THAT HAPPENS IS THAT THE CONTENT SCROLLS BUT THE LINK DOES NOT SEND THE USER TO THAT PAGE.