>> ff javascript library user documentation


The basic idea behind the ff javascript library is to provide a common AJAX/DOM API for all current browsers but to keep the size and thus the page load / render times at a minimum. At less than 7k in the javascript compressed version and even less than 3k for the gzip compressed version it is very well suited even for dial-up access. It enables you to write modular, well-structured cross-browser javascript code.

The library is based on the javascript part of my japano webapp toolkit which is currently not being actively developed. In contrast to japano it is available on a more liberal license ( a BSD-like license ).

The ff javascript library consist of the following parts:

What is ff javascript not?

The ff javascript library allows you to use a common API for these essential features and is not meant to contain fancy javascript effects or widgets or whatever, although it might be used to develop these. It also does not try to reinvent javascript. If you want fancier language features you might want to add them from another library.

Logging / Error Reporting

The ff javascript library supports the firebug extension for Firefox. It uses the extension internally to log errors and it also sets up a quick emulation of it in case the extension is not installed or it is running on a completely different browser. The emulation has two different modes:

Aptana Code Assist

The source version of the ff javascript library contains ScriptDoc comments enabling you to have Code Assist functionality within the Aptana IDE / Eclipse plugin. To enable this you have to add the uncompressed source version of the library to your "Code Assist Profiles". Now the code completion of Aptana will show a short help text for all ff javascript library functions.

ff.event and "this" caveats

ff.event ensures that the this keyword points to the event target element (e.g. the DOM element you clicked on for a click event). This is the standard behaviour for old style event declarations with onclick="..." and for events registered with addEventListener. ff.event ensures that this is also the behaviour in Internet Explorer.

Note the different meaning of the keyword this in the hello.js script. this only refers to the hello object in the foo method. In the event handlers the this object refers to the DOM element that is the source of the current event. For Functions called from ff.event.onload and ff.request the this object refers to the window, as if the window was the source of the event. So if you want to access the hello object from the event functions you have to use the global hello variable. ( You can see the console.debug messages by either running the script in firefox with the firebug extension installed or by clicking this link )

The hello object is a singleton (There will only be one hello object per document) which makes it easy to access it without being able to use this. Look at the ffview example for how to deal with objects were multiple instances exist in the document.

Best development practices

When developing javascript enabled websites, it is really important to structure the code in a way that allows the javascript code to be modular, extensible and to keep a good overview over sites growing in complexity.


Let's take a look at the Hello World Example. It is more complicated than it could be in favour of a structure demonstrating the best practice. This structure starts at the separation of everything into different layers:
  1. The XHTML Document is the content layer.
  2. The document imports a style sheet that is the layout layer.
  3. The ff javascript library and the hello.js script are the behavioural layer.

There is a rather strict separation between those layers. The XHTML markup does neither contain style nor onclick nor onload attributes but only id and class attributes used to style the content and to retrieve the DOM elements to add event handlers.

The XHTML document imports a common style sheet and defines some local styles only used in the Hello World Example. The button click handler requests a document fragment via AJAX and pastes the response at the end of div with the di "page". The document fragment again does not include style attributes but uses the locally defined style classes.

Unobtrusive Javascript

You should always write your javascript in a way now commonly referred to as "unobtrusive javascript". This describes a set of principles used to separate Javascript and HTML and to enable modularity of scripts.

  1. The first important step is separation. Put all scripts into their own files and import them into the HTML documents
  2.   <script type="text/javascript" src="script.js"></script>
  3. Don't use onclick="" or onload="" to setup events but use the ff.event functions to handle all events. In a perfect world you could just use the w3 DOM Event functions but unfortunately Internet Explorer does not care about standards and has a totally different event model. This is the reason for the existence of ff.event which offers a unified API for all browsers.

  4. Degrade gracefully. That means first write the pages to work without javascript. Then register an onload handler that transforms the page into a javascript enabled version. You should use ff.event.onload to register the onload functions as it allows you to register more than one onload function. The purpose of this is to seperate your javascript into multiple files that all have their own onload functions that work independently from each other.

    For example instead of doing popups like the traditional, bad way

    <a href="#" onclick="window.open('page.html')">my page</a> BAD!
    Do them like shown in the popup example

See the ffjs Examples for more examples of unobtrusive javascript and separation.

Developing ff javascript

There are two versions of the ff javascript library included in this release, a compressed version for optimal size and speed and an uncompressed source version to use during site development, to develop or change the library itself and as source for the code assist of the Aptana IDE / plugin.

There is a compressJs script included in the distribution which you can use to compress the source version. You need to download the custom_rhino.jar from the dojo javascript compressor and copy it into the same directory as the script. The script allows compression of javascript files while preserving conditional compilation directives used by the ff javascript library for Internet Explorer compatibility. The script is a bash script which was written to be used under Linux but should also work under OS-X or cygwin for windows.

<< Back