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:
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.
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:
Simple Console Mode
If you pass ffdebug as HTTP parameter to a page in which ffjs is loaded, it will create a simple logging console via
DOM builder and output all firebug log statements to it.
( Note that firebug's message formatting options are not fully supported, but simplified.)
The simple debug console is unstyled by default but has ids / classes enabling you to style the console to your liking. The debug console is a div with the id "ffdebug". A div with the class "debug", "info", "warn" or "error" is created for every log entry inside it. A double click handler that toggles the class minimized is added to the debug console. This only works with apropriate styles.
See the style sheet of this page for an example of how to style the debug console to look ok and to correctly minimize.
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 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.
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.
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.
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.
<script type="text/javascript" src="script.js"></script>
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.
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.
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.