It’s been a while since I’ve written about Jaxer, and it’s a shame, because there’s been a lot of major changes over the past several months. Anyway, I’ve been getting back into server-side javascript hacking, and found myself needing to get Jaxer up and running on a local dev server (and subsequently this one). You could also always work with Jaxer in Aptana’s cloud, where you’d get all the benefits of Jaxer integration with Aptana Studio and deployment workflows (SVN, staging, production, and just plain awesomeness) if you don’t want to (or need to) install Jaxer yourself. However, my needs (and presumably yours) required me to go down this route.

So, before we get started, let’s go over the list of prerequisites and assumptions:

• You’re on Ubuntu 8.04 (newer versions should work the same as well)
• You’ve got Apache installed (via aptitude, or you will have to adjust paths accordingly)
• You’ve got root access to your server

That’s about it. MySQL is also good to have, but not required. Last thing before we start: many of the steps outlined here came from this site, which was contributed by a Jaxer user at Aptana’s forums. Right, let’s get busy…

Step 1: Get Jaxer

As you would expect, the first thing we’ll do is grab the latest version of Jaxer. However, before we do so, let’s make sure we know whether we’re on a 64 or 32-bit version of Ubuntu. Easy enough, from the command line:

uname -a

which outputs something like:

Linux genxdesign 2.6.24-19-xen #1 SMP Sat Jul 12 00:15:59 UTC 2008 x86_64 GNU/Linux

You can see, in my case I’m on 64 bit, as indicated by the “x86_64″. Now that we’ve got that, we can head over to http://aptana.com/jaxer/download, and grab the appropriate linux distribution. Easiest way to do so is to right-click on the link, select “Copy link location”, and then use it in the following command on your sever:

wget [pasted url]

Of course, you could also download it locally, then unzip and upload it to your server. I am assuming that you’re doing all this in your home directory on the server. Note also that the way the downloads work with Jaxer currently may give you a goofy file with wget. For example, at the time of writing, my wget url was “http://ec2-67-202-37-218.compute-1.amazonaws.com/downloads/jaxer/ubu64/Jaxer_package_withApache.zip?version=1.0.1.4310&cb=1000″ which gave me a file called: “Jaxer_package_withApache.zip?version=1.0.1.4310″ on the file system. Not an issue, I can fix this by doing:

mv Jaxer_package_withApache.zip\?version\=1.0.1.4310 jaxer.zip

Finally, on the server, simply type:

unzip jaxer.zip

to unzip the file.

Once the file’s unzipped or uploaded to your server, we’ll need to move the contents to their final home in /opt. So, back in your home directory:

sudo mv AptanaJaxer/ /opt

and we’re golden!

Step 2: Get the Mozilla Stuff

This is a bit easier than grabbing Jaxer itself, just one command:

sudo apt-get install firefox-3.0-dev firefox-dev

which we’ll follow with on more to make sure our libraries line up properly:

sudo ln -s /usr/lib/libexpat.so.1 /usr/lib/libexpat.so.0

That’s all we’ve got to do for Mozilla. Onward…

Step 3: Configure and Start

Believe it or not, we’re nearly done. At this point, we need to slurp out the Apache module configs from the Jaxer directory, and put them in the appropriate place for our Apache on Ubuntu. Two simple commands will take care of this:

sudo sh -c "grep '^LoadModule' /opt/AptanaJaxer/jaxer/confs/jaxer-linux.httpd.conf > /etc/apache2/mods-available/jaxer-linux.httpd.load"
sudo sh -c "grep -v '^LoadModule' /opt/AptanaJaxer/jaxer/confs/jaxer-linux.httpd.conf > /etc/apache2/mods-available/jaxer-linux.httpd.conf"

Now that we’ve got the module configs in the right place, we can enable the module for Apache by doing the following:

sudo a2enmod jaxer-linux.httpd

It will tell you that you need to reload apache. Don’t do that just yet. First, we need to let Jaxer create some directories, so let’s start Jaxer:

sudo JAXERBASE=/opt/AptanaJaxer /opt/AptanaJaxer/scripts/startJaxer.sh

Don’t worry about any warnings you see, those are just about Jaxer setting things up for the first time (similar to the first run of MySQL in a fresh install). We can go ahead and stop jaxer now, and then restart Apache:

sudo JAXERBASE=/opt/AptanaJaxer /opt/AptanaJaxer/scripts/stopJaxer.sh
sudo /etc/init.d/apache2 restart

if you don’t get any warnings or errors from Apache, go ahead and start Jaxer again:

sudo JAXERBASE=/opt/AptanaJaxer /opt/AptanaJaxer/scripts/startJaxer.sh

and you should be all set! If there aren’t any errors being spit out by anything, you can now browse to the Jaxer url on your server: http://yourdomain.com/aptana, and then run the server diagnostics. If everything’s working right, you’ll see some spinners, and then a screen that looks similar to this one:

click image for larger view

Just a few more things to do now…

Step 4: Configure Apache

Well, what we’ve currently got is Jaxer set up and running properly, but it isn’t set up for any of our sites. To do this, you’ll have to add a few lines to your vhost configuration(s) wherever you’d like Jaxer to actually run on your web site. For this example, I’ll assume you’re using the “default” site that comes with the standard Apache install on Ubuntu, but you can simply put these lines wherever you need them in your vhost files.

So, what we’re basically going to do here is tell Apache to use Jaxer as a filter for certain files in our web site. We do this by adding some directives in the appropriate “” area of our config. Let’s take a look at what a typical config might look like. If you type the following:

sudo vi /etc/apache2/sites-available/default

we’re looking for a section of the file that looks like:

<Directory /var/www/>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All 

        Order allow,deny
        allow from all
</Directory>

Yours will probably be a bit different, but we’re basically looking for the directory directive that refers to the document root for this vhost (’/var/www’ in this case). Once you’ve located that, you need to add the following lines anywhere in there:

JaxerFilter html xhtml htm php
JaxerFilterContentType text/html application/xhtml+xml

What we’ve done is told Apache to run any html, xhtml, or php page through Jaxer as a filter (which is what we typically want). Once you’ve added these lines, you can stop Jaxer, restart Apache, and start Jaxer again:

sudo JAXERBASE=/opt/AptanaJaxer /opt/AptanaJaxer/scripts/stopJaxer.sh
sudo /etc/init.d/apache2 restart
sudo JAXERBASE=/opt/AptanaJaxer /opt/AptanaJaxer/scripts/startJaxer.sh

And that’s all there is to it!

A Few More Things…

Now that we’ve got everything running properly, I wanted to share a script to make starting / stopping Jaxer a bit easier, and a gotcha with URL re-writes you need to watch out for.

First, the control script. I am by no means a bash guru, and this script could use some major improvement. If you would like to improve upon it, let me know, I’d greatly appreciate it. Anyway, it does get the job done just fine. So, let’s go ahead and install it:

wget http://www.gen-x-design.com/downloads/jaxer_control.txt
sudo cp jaxer_control.txt /etc/init.d/jaxer
sudo chmod +x /etc/init.d/jaxer

Now, you can simply type “sudo /etc/init.d/jaxer [start|stop]” to start or stop Jaxer! Much easier than remembering that crazy sh file location.

Second, URL re-write gotchas. When I installed Jaxer on this server, I discovered the wordpress rewrite rules were breaking some special Jaxer urls needed for everything to function properly. Here’s what a typical offending set of rewrite rules could look like (in a .htaccess file, for example):

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>

Well, this breaks Jaxer, because the URL rewrites take precedence over the LocationMatch directives in the jaxer module configuration. As I said, we can luckily fix this problem by adding one line, thus making our rewrite rules look like:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_URI} !^/jaxer-.*\b
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>

So that the special Jaxer URLs aren’t redirected (in this case) to index.php.

Wrapping Up

And that’s it! Hopefully you find this quick and easy, and then you can get started with Jaxer, thus discovering how damn cool server-side javascript is. If you’d like to learn more about Jaxer, or need help, here are some useful URLs:

• Jaxer Docs – http://www.aptana.com/jaxer/guide/
• Jaxer Forums – http://forums.aptana.com/viewforum.php?f=51
• Jaxer Home Page – http://www.aptana.com/jaxer
• Aptana Cloud – The much better, easier way to work with Jaxer. Get a free trial! http://www.aptana.com/cloud.

This is just a short post to introduce myself. The talented Mr Selby has kindly invited me on board to blog about my experiences with mad scientist level JavaScript.

My names Davey and I work with Ian at Aptana, my role there is JavaScript Architect and as I result I spend a lot of time rooting around in the arcane depths of spidermonkey. I’m predominately interested in the topic of server side JS as it appears in our Jaxer product but occasionally venture out into the hostile environment that exists on the client.

I have an article primed and ready to go, but just need to put some finishing touches to it before publishing, In it I explore how to reproduce some of the interesting PHP capabilities that Ian is the master of. So it you have ever wanted to have the equivalent of __FILE__ or the __autoload function in javascript, keep watching all will be revealed soon.

As a first tip to any would-be JavaScript ninja, I heartily recommend The Douglas Crockford book ‘JavaScript, the good parts’, it’s just choc full o’ goodness.

cheers

I will do a post in the near future going over the code, and some of the configuration tweaks that I made, but hopefully this will hold you over until then.

Source Code

So, what’s new in this version of Jaxer? Quite a bit, actually, and if you’ve been using 0.9x releases of Jaxer until now, a lot has changed for you as well. As usual, Jaxer is available bundled into studio (starting with the recently released 1.2 version), as well as the usual stand-alone. Read on for a full summary of what’s new…

So, here’s a quick run-down of the shiny new version of Jaxer:

• Application context settings that allowing for easier app configuration, app properties, database settings, etc…
• Database API enhancements with richer APIs for working with result sets.
• Server-side image manipulation including server-side canvas support and ability to convert to other image types.
• Native command execution API so that you can run system commands and handle the output from those.
• Asynchronous server-side JavaScript processing lets you implement callbacks in your server-side code too.
• Ability to return custom content types (e.g. json, xml, gif, html, etc…)
• Full control of the request/response lifecycle including setting redirects, headers, content, etc…
• Secure sandbox supporting cross domain calls, sandboxed JavaScript execution, META refreshes, …
• Serialization support for JavaScript objects to and from XML, E4X and JSON

Pretty cool stuff, huh? What’s really exciting to me (outside the functionality that was already there previously, such as database and filesystem access), is the ability to return custom content types, specifically JSON. JSON returns are nice since the server-side is already natively JavaScript, as well as the fact that this means creating JSON data services for your existing apps becomes a snap. If JSON’s not your cup of tea (and you’re crazy if it isn’t), or perhaps you need to deal with XML for whatever reason, the E4X (native XML for JS) support being baked in is also nice. This essentially means that you can use Jaxer as a JSON or XML service provider to not only Ajax clients, but other things like flash / flex, Silverlight, and more. Writing your own RESTful API in JavaScript = crazy delicious!

Another interesting feature that I have yet to play with personally is the new secure sandbox. What this essentially lets you do is load pages (or page fragments) on the server from other domains and let their JS execute without giving them access to the Jaxer API, or any of your other server-side code. Why is this neat, you may ask? Well, if you are aggregating content from a site (news.com in several of the Jaxer samples), the content you’re retrieving may have some JS code that could get evaluated. Before the sandbox existed, this meant a bunch of JS errors would bubble up to the client-side related to this JS code. No longer… and obviously this is also important as it means nobody could try and compromise your system by modifying the content you fetch to try and execute destructive statements (i.e. “DROP DATABASE”). Obviously, there’s a lot of room for neat mash-ups with this new goodness, and Uri Sarid has written a nice article on DOM Scraping with Jaxer.

I hope to be cooking up some new articles related to this release in the coming days, and will definitely be covering this stuff in my upcoming speaking engagements. For now, enjoy these links:

• Download Aptana Studio w/ Jaxer 1.0 RC B
• Download Jaxer 1.0 RC B Server and Stand-Alone
• Learn about all the new goodness, and how to migrate from 0.x releases of Jaxer
• Tell us what you love, or hate in the forums

Read the full entry for details on the session, but here’s a little introductory overview (for the sake of not re-writing everything, I have just copied and pasted the announcement)…

Server-side JavaScript (SSJS) is growing in popularity fast since developers realize it can drastically simplify Web app creation by letting you use using the same technology stack on both the client and the server. While server-side JavaScript is not new – it was a part of Netscape’s vision 10 years ago – times have significantly changed with 10x faster hardware and networks, making that original vision for the Web now a reality.

In this session delegates will learn how to:

• Overcome common hurdles and pitfalls of client-side only JavaScript development.
• Speed up development time by cutting out extra server-side code and processing scripts that are no longer necessary.
• Clean up your code base by reducing (or even eliminating) the number of languages needed to leverage to accomplish common tasks (i.e. Why bother with server-side PHP scripts to fetch database results when you can do it all in JavaScript on the server? Why mess with Curl to fetch content that your JavaScript code can grab in one line?)

Selby will also get hands-on with a live demonstration of how to:

• Create JSON data services for your Ajax, Flash, Flex and Silverlight apps
• Implement JavaScript RMI
• Use your favorite Ajax libraries server-side.
• Manipulate the DOM server-side
• Talk to databases, file systems, networks, and remote sites or services (cross-domain XHRs are now a possibility!

The session will show Web developers how they can put their JavaScript skills to work on the server side using technologies like Mozilla Rhino and Aptana Jaxer, which embeds the entire Mozilla browser on the server side.

About AjaxWorld…

AJAXWorld RIA Conference & Expo 2008 West
The days when AJAX is the only game in town are over, and the 6th International AJAXWorld RIA Conference & Expo in San Jose, CA, on October 20-22, 2008 is your chance to come and see it and hear it for yourself.

Because it’s easy to misjudge priorities and invest in the wrong technology, AJAXWorld will help you invest in the right one for your particular business. It will help you find the optimal balance between business needs, technology potential, and enhanced user experience. AJAXWorld RIA Conference & Expo 2008 West is where you can find what you’re going to need for business survival and Web success in 2008, 2009 and beyond.

AJAXWorld’s 80+ technical sessions, Keynotes, Power Panels and General Session Demos will help you determine which Rich Internet Technology will provide the most meaningful impact in your business, organization or service. The conference program aims to inform and inspire you toward the detailed implementation plan that you’re going to need in the next 12 months in your own initiative whether that’s SaaS, financial services, healthcare, enterprise portals, ISV applications, or whatever.

The Expo floor additionally will allow you to follow up on the premier solutions already available and to choose which best suits your needs.

http://www.ajaxworld.com/

Before we dig in to the notifications, let’s do a little work to set up an example and some assumptions we’ll be operating under for the sake of this article. First, as prototype is my weapon of choice, that’s what we’ll be using. We’ll also be using prototype as Object.Event uses it as well! Now, let’s pretend that we have a website that has some social networking aspect of some kind. We want to display a short list of who’s currently online (say the 6 most recently active people) in some sort of side bar, and perhaps a count of the total members online in a footer element. Rather than having both these elements poll the server at some interval to update their information, let’s create a little data model that these areas can use instead.

Step 1 – Create a Data Model

For the sake of brevity, this will be stubbed out in a lot of places, but we’ll create enough functionality to get the concepts across.

var WhosOnlineSummary = Class.create(
{
    initialize: function initialize()
    {
        this.totalOnlineUsers   = 0;
        this.whosOnline         = new Hash();
        this.loading            = true;

        // do our initial fetch
        this.fetchUsers();

        // set this up to poll for new data every thirty seconds...
        this.dataPoller = new PeriodicalExecuter(function(pe)
        {
            this.fetchUsers();
        }.bind(this), 30);
    },

    fetchUsers: function fetchUsers()
    {
        // this would probably do some other stuff too

        new Ajax.Request('/your/data/service',
        {
            onComplete: function(response)
            {
                this.update(response.responseText);
            }.bind(this)
        })
    },

    update: function update(data)
    {
        // and you'd have some sort of logic
        // here to update the data... here's a stub..

        // I'm assuming the data returned is a JSON object here...

        if('totalOnlineUsers' in data)
        {
            this.totalOnlineUsers = data.totalOnlineUsers;
        }

        // and update our "who's online" stuff...
        if('onlineUsers' in data)
        {
            // simple way to refresh, just kill the current list
            this.whosOnline = new Hash();

            // pretend online users is an array of json objects here...
            // [ { id: userId, name: username, etc.}, {...}, ... ]
            data.onlineUsers.each(function(user)
            {
                this.whosOnline.set(user.id, user);
            }.bind(this));
        }

        if(this.loading)
        {
            this.loading = false;
        }
    }
});

// get this globally namespaced... we'll just declare it here for
// the sake of keeping things easy... you probably shouldn't do
// this in real life
var whosOnline = '';

Event.observe(window, 'load', function() {
    whosOnline = new WhosOnlineSummary();
});

OK, as you can see, we’ve got a very simple data model that updates itself every thirty seconds, and that our other “widgets” can easily tap into for their information. I’m not going to write these widgets out to any great extent, but I will create a small stub for the total online users functionality to help us out here.

Step 2 – Create Some Widgets

Now that we have a model, let’s start leveraging it to do something meaningful. As I just mentioned, this is only a stub, but it should give you a nice idea of where we’re going…

var TotalOnlineUsers = Class.create(
{
    initialize: function(element)
    {
        this.domElement = element;

        // any other useful variables could go here...

        this.parseOnlineUsers();
    },

    parseOnlineUsers: function parseOnlineUsers()
    {
        // nice and simple
        this.domElement.update('Currently ' + whosOnline.totalOnlineUsers + ' users online');
    }
});

And now we’re essentially ready to do some fun stuff. As you can see, all this looks nice, but our TotalOnlineUsers widget has no way of knowing when it needs to update the display, as there’s no way to know when the data model has changed. Enter Object.Event…

Step 3 – Make Your Data Model Smart

So, we need to get our data model publishing events that our widgets can listen for. This is actually pretty darn simple since all the heavy lifting has been done for us. Let’s go ahead and leverage the power of Object.Event (I’ll provide download links at the end of this article). The first thing we need to do is provide the data model with the “event” functionality. This is a simple one-liner that we can put right after our class declaration. It looks like this:

...
 if(this.loading)
        {
            this.loading = false;
        }
    }
});

Object.Event.extend(WhosOnlineSummary);

That’s it! Now, all that remains for us to do is to create events inside this object that can be observed (we’ll cover the actual observing shortly). This is done through simple additions of “notify” functions. Since we’ve extended our data model class, this is also a cinch. I’ll modify the update function to include two “events”:

...
    update: function update(data)
    {
        // and you'd have some sort of logic
        // here to update the data... here's a stub..

        // I'm assuming the data returned is a JSON object here...

        if('totalOnlineUsers' in data)
        {
            this.totalOnlineUsers = data.totalOnlineUsers;
        }

        // and update our "who's online" stuff...
        if('onlineUsers' in data)
        {
            // simple way to refresh, just kill the current list
            this.whosOnline = new Hash();

            // pretend online users is an array of json objects here...
            // [ { id: userId, name: username, etc.}, {...}, ... ]
            data.onlineUsers.each(function(user)
            {
                this.whosOnline.set(user.id, user);
            }.bind(this));
        }

        if(this.loading)
        {
            this.loading = false;
            this.notify('whosOnlineLoaded');
        }

        this.notify('whosOnlineUpdate');
    }
...

As you can see, we can create any custom events that we want, and we can name them whatever we want. Pretty cool stuff, huh? So, there’s only one thing that remains, and that’s making our widget listen for these events.

Step 4 – Make our Widgets Listen for Events

You’ll notice I created two events in our data model, but we’re only going to use one for this example. Let’s get right to it, as there’s no real need for explanation here…

var TotalOnlineUsers = Class.create(
{
    initialize: function(element)
    {
        this.domElement = element;

        // any other useful variables could go here...

        // watch for updates from the data model
        whoseOnline.observe('whosOnlineUpdate', function()
        {
            this.parseOnlineUsers()
        }.bind(this));

        this.parseOnlineUsers();
    },

    parseOnlineUsers: function parseOnlineUsers()
    {
        // nice and simple
        this.domElement.update('Currently ' + whosOnline.totalOnlineUsers + ' users online');
    }
});

Done. It’s really that easy!

Wrapping Up

Hopefully, you can see the huge benefit of approaching your apps this way, and integrating Object.Event. If you’ll remember, our so-called page also has a who’s online list. You could create a widget that also observes the “whosOnlineUpdate” event, so it will update whenever the model changes as well. We’ve effectively made the load on the server smaller, since we’ve only got one thing calling our data service, instead of 2 (in this case, but I’m sure there are many practical applications that would have many more somewhat redundant calls). We also know that our presentation will be in sync across all the different elements on this page, which leads to a much slicker user experience. The best part of all this? We’ve made very, very small tweaks to our code, and they were very unobtrusive as well. Enjoy, and thank Ryan for his bad-ass javascript kung-fu if you’ve got a moment!

As promised, here are your links to all the required libraries:

• Object.Event – Created by Ryan Johnson
• Prototype Framework

Seriously, take a look over an existing AJAX app you may have written. You’ve probably got a bunch of different functions for making AJAX calls to PHP scripts (or something similar), which process the input, and deal with the database, then return either parsed results, or results to be parsed by JavaScript. Wouldn’t it be nice if you could consolidate all that stuff into some smaller, simpler JavaScript code? Fewer files, less overhead… sounds good to me.

That’s one of the great things about Jaxer. If you’ve done any reading, you probably know that Jaxer works with SQLite out of the box, and you might be aware that it’s also able to work with MySQL, but most of the people I’ve talked to have stopped there. Aside from the above objections (which I’ll smash shortly ), I’ve also heard that they simply don’t want to learn another complex API. Well, the time for silly excuses is over, and I’m going to show you how easy all this stuff can be. I would suggest that you first set up Jaxer with XAMPP so you can follow along, but if you want to use the stand-alone Jaxer and Apache, you’ll be just fine. Let’s get our hands dirty…

Setting up Jaxer to Use MySQL

This is actually pretty simple, and already documented in the Jaxer documentation, but I’ll go over it here as well. First, some background on how Jaxer works internally with databases. Whether you’re using SQLite or MySQL, Jaxer leverages a database for some of its own internal functionality (session management and other goodness). As such, it needs a database for its own stuff, which it will create if it doesn’t exist. We’re also going to need a default application database for Jaxer to connect to when it spins up, but it won’t be writing anything to it.

So, let’s tell Jaxer to use MySQL. If you’re set up according to my Jaxer+XAMPP tutorial, we’re going to edit:

/Applications/xampp/xamppfiles/local_jaxer/conf/config.js

If you’re working with the standalone, browse to wherever you’ve installed it and edit:

Path-to-Aptana_Jaxer/local_jaxer/conf/config.js

What we’re looking for is around line 44 (it should be commented out):

Config.DB_IMPLEMENATION = "MySQL";

Now, some more assumptions:

• You’ve got a database created for your app, and one for jaxer itself. For my “sandbox” testing, these are the same… I use “jaxer_db”
• You know what port MySQL is using (unless you’ve changed something, it’s 3306). If you’re using XAMPP, you’re good to go

OK, so let’s uncomment all the MySQL-specific stuff and change our default stuff. Here’s what I’ve got:

Config.DB_IMPLEMENTATION = "MySQL";
Config.DB_CONNECTION_PARAMS =
    {
        HOST: "127.0.0.1",
        PORT: 3306,
        NAME: "jaxer_db",
        USER: "root",
        PASS: "",
        CLOSE_AFTER_EXECUTE: false,
        CLOSE_AFTER_REQUEST: true
    };
    Config.DB_FRAMEWORK_IMPLEMENTATION = "MySQL";
    Config.DB_FRAMEWORK_CONNECTION_PARAMS =
    {
        HOST: "127.0.0.1",
        PORT: 3306,
        NAME: "jaxer_db",
        USER: "root",
        PASS: "",
        CLOSE_AFTER_EXECUTE: false,
        CLOSE_AFTER_REQUEST: true
    }; 

If you’re going to use (and you should for production stuff) a different Jaxer internal database, change the Config.DB_FRAMEWORK_CONNECTION_PARAMS to reflect this appropriately. Now that we’ve changed everything, restart Jaxer, then restart Apache. If everything’s good, you should be able to browse to the Jaxer Unit Tests (located in the Server Diagnostics… usually located at http://localhost/aptana or the start page from the Jaxer control panel for stand-alone users), and run the “DB – test_DB_MySQL.html” test (just click on that link). If all is well, you’ll see a bunch of passes:

Jaxer MySQL Unit Tests

Getting a Few Things Set Up

Awesome, now that we’re up and running, let’s set up some test data to play around with. Let’s create a test table and populate it with some data… just copy and paste this code in your MySQL client of choice:

create table if not exists `users` (
user_id int(10) unsigned NOT NULL auto_increment,
first_name varchar(50) NOT NULL,
last_name varchar(50) NOT NULL,
username varchar(50) NOT NULL,
date_created datetime NOT NULL default '0000-00-00 00:00:00',
date_updated timestamp NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP,
primary key (`user_id`));
INSERT INTO users SET first_name='Ian', last_name='Selby', username='iselby', date_created=NOW();
INSERT INTO users SET first_name='John', last_name='Doe', username='jdoe', date_created=NOW();

Of course, you could certainly add more, but we’re not writing an app, so this should suffice just fine.

One last little bit of groundwork, let’s set up the page that’s going to contain some of our test code. Basically, it’s just going to be a sandbox page of sorts, so there’s nothing too tough here:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<title>Sample Jaxer DB Stuff

	<script type="text/javascript" runat="server-proxy">
	// we'll add our sample code here
	</script>
</head>
<body>
	<div id="results"></div>
</body>
</html>

Great! Now we’re ready to start working with the Jaxer & MySQL API.

Getting Our Feet Wet… Connecting to MySQL and Basic API Functions

First thing we need to do (obviously), is to set up a connection to the database. While we have set up a default database in our Jaxer configuration, we can connect to any database that we want to. So, let’s set up that connection now. Place the following between our script tags:

var dbConnection = new Jaxer.DB.MySQL.Connection({
	'HOST': 'localhost',
	'PORT': 3306,
	'USER': 'root',
	'PASS': '',
	'NAME': 'jaxer_db',	// the name of the db to use
	'CLOSE_AFTER_EXECUTE': false
});

So far, pretty simple, no? Obviously, you can change any of these parameters to suit your needs. Remember, the end user will not see any of this as we’re running it at the server level (which we defined with the runat= in our script tags). Now that we’ve got a connection, we can start running queries. Before we build anything practical, let’s take a look at our basic API stuff.

Queries
As stated in the introduction to this article, there is, in fact, a way to prepare statements to prevent SQL injection. Let’s take a look at a basic example, then a prepared query:

// assuming we are using the above connection...
var query_string = 'SELECT * FROM user';
var result = dbConnection.execute(query_string);
// and now a prepared statement
var query_string = 'SELECT * FROM user WHERE first_name LIKE ? OR last_name LIKE ?';
var result = dbConnection.execute(query_string, ['%' + someInput + '%', '%' + someOtherInput + '%']);

It’s really that easy! Of course, if you aren’t interested in a result, you can omit the “var result =” (such as update or insert statements). Again, as long as your queries are in a runat=”server” or runat=”server-proxy” script block (or .js include), the end user will never see your code. So, everything’s nice and secure.
Result Sets
If you’re a PHP developer, you are probably familiar with the mysql_fetch_object() or mysql_fetch_array() functions for traversing result sets (shame on you for not using mysqli tho ). If you’re not, don’t worry, I’m not going to be referring to them here. Anyway, regarding those functions, you’re in luck! The fine folks who programmed Jaxer were kind enough to provide results similar to those of PHP (and other languages I would imagine). I’ll go over a sample result set in a moment, but here’s a quick look at what the “result” variable from the examples above would contain:

• columns – An array of column names for all rows in this resultSet.
• hasData – I’ll give you three guesses (true / false folks!)
• rows – The array of rows in the resultSet in the order retrieved from the database.
• rowsAsArrays – An alternate representation of the rows of the resultSet
• singleResult – The value in the first column of the first row of the resultSet (think SELECT COUNT(*) FROM…)

As you can see, it’s about as robust as you could possibly hope for. So, based on our sample data, and the sample SELECT * FROM user query above, what would a resultSet object look like in real life? It looks like this:

result =
{
	"rows":
	[
		{"user_id":1,"first_name":"Ian","last_name":"Selby","username":"iselby","date_created":"2008-02-23T17:46:24","date_updated":"2008-02-23T17:46:24","$values":[1,"Ian","Selby","iselby","2008-02-23T17:46:24","2008-02-23T17:46:24"]},
		{"user_id":2,"first_name":"John","last_name":"Doe","username":"jdoe","date_created":"2008-02-23T17:46:35","date_updated":"2008-02-23T17:46:35","$values":[2,"John","Doe","jdoe","2008-02-23T17:46:35","2008-02-23T17:46:35"]}
	],
	"rowsAsArrays":
	[
		[1,"Ian","Selby","iselby","2008-02-23T17:46:24","2008-02-23T17:46:24"],
		[2,"John","Doe","jdoe","2008-02-23T17:46:35","2008-02-23T17:46:35"]
	],
	"columns":
	[
		"user_id","first_name","last_name","username","date_created","date_updated"
	],
	"singleResult":1,
	"hasData":true
}

We’ve also got a bunch of functions we can execute on a result set. Rather than go over them in detail, you can check them out online or in your local instance of Jaxer’s API documentation:

• Online at Aptana
• Locally (If you installed according to my tutorial

OK, go take a look over that goodness (I suggest locally if you can, as it will be more up-to-date), and then let’s take a look at how we could do this in a more real-world environment.

Doing Something Practical

Alright, to do something practical, we’re going to need to wrap our stuff in some functions, so we can call them when we need them. So, go ahead and remove everything in our <script> block, and create the following function:

function fetchUsers(search_for)
{
	var dbConnection = new Jaxer.DB.MySQL.Connection({
		'HOST': '127.0.0.1',
		'PORT': 3306,
		'USER': 'root',
		'PASS': '',
		'NAME': 'jaxer_db', // the name of the db to use
		'CLOSE_AFTER_EXECUTE': false
	});

	// if we've been provided with search params
	if (search_for)
	{
		search_for = '%' + search_for + '%';
		var query_string = 'SELECT * FROM user WHERE first_name LIKE ? OR last_name LIKE ? ORDER BY last_name';
		var params = [search_for, search_for];

		var result = dbConnection.execute(query_string, params);
	}
	// default result set
	else
	{
		var query_string = 'SELECT * FROM user ORDER BY last_name';
		var result = dbConnection.execute(query_string);
	}

	return result.toHTML();
}

Pretty straight-forward, right? OK, one last thing, and we’ll actually have something that works. In order for this to execute on load, we can do one of two things: onload or onserverload. Basically, these are the same thing, except the onserverload is evaluated when the server-side DOM is created (essentially before it ends up on the client-side of things… where all our runat=”server” stuff is executed). So, let’s alter our tag:

<body onserverload="document.getElementById('results').innerHTML = fetchUsers();">

Save your page, reload it, and if everything works, you’ll have a really ugly HTML table of results! Pretty damn cool, right? If you’re sharp, you can see that we’re working our way towards a simple search, so let’s dive right into that. Rather than go over it step-by-step, I’ll just show you the final HTML (because this really isn’t rocket science ):

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<title>Sample Jaxer DB Stuff

	<style type="text/css">
		body, td, p { font-family: Lucida Grande, Arial; font-size: 11px; }
		td { border: 1px solid #ccc; padding: 3px; }
	</style>

	<script type="text/javascript" runat="server-proxy">

	function fetchUsers(search_for)
	{
		var dbConnection = new Jaxer.DB.MySQL.Connection({
			'HOST': '127.0.0.1',
			'PORT': 3306,
			'USER': 'root',
			'PASS': '',
			'NAME': 'jaxer_db', // the name of the db to use
			'CLOSE_AFTER_EXECUTE': false
		});

		// if we've been provided with search params
		if (search_for)
		{
			search_for = '%' + search_for + '%';
			var query_string = 'SELECT * FROM user WHERE first_name LIKE ? OR last_name LIKE ? ORDER BY last_name';
			var params = [search_for, search_for];

			var result = dbConnection.execute(query_string, params);
		}
		// default result set
		else
		{
			var query_string = 'SELECT * FROM user ORDER BY last_name';
			var result = dbConnection.execute(query_string);
		}

		return result.toHTML();
	}

	</script>
	<script type="text/javascript" runat="client">
		function doSearch()
		{
			var search_for = document.getElementById('searchFor').value;
			document.getElementById('results').innerHTML = fetchUsers(search_for);
		}
	</script>
</head>
<body onserverload="document.getElementById('results').innerHTML = fetchUsers();">
	<label for="searchFor">Search For: </label><input name="searchFor" id="searchFor" />
	 <button onclick="doSearch();">Search</button>
	<div id="results"></div>
</body>
</html>

Most of this stuff should be pretty self-explanatory, but I’ll go over a few things of note. The first thing you should notice is that I’ve created a new client-side script tag. This is so I can create a function that will have access to the results div, as well as our server-side function. Remember, after the server-side DOM and functions are evaluated, that DOM goes away. So, the server-side functions will no longer have access to the DOM when we’re doing our search, regardless of the fact we proxy that function. All the proxy does is allow the functions to be executed from the client-side without exposing any of the server-side code (so our SQL statements won’t be seen or anything like that).

DB-Driven Search Using JavaScript… WOW! (Jaxer rules folks)

Wrapping Up

As you can see, it’s really darn easy to work with MySQL in Jaxer. It’s also perfectly safe, and there are no real causes for concern from a security standpoint. As Jaxer is still in its beta stage, there’s a lot of feature development currently taking place, but we (at Aptana) would love your feedback and suggestions. You can certainly provide feedback with comments here and I’ll pass them along, but the best place to do so is in the Aptana Forums. I’m currently cooking up a prototype database abstraction class that is essentially like a PHP class in order to obviously make things easier development-wise, but should also provide a bit of a familiar environment for PHP developers looking to make the jump to Jaxer.

One of the coolest things about developing ajax-enabled applications and sites is the level of interactivity that you can bring to your users. And perhaps one of the most crucial aspects of this process is adding activity indicators to your site. While a lot of ajax requests can be very fast, it’s still important to let your users know that something is happening. All too often I see people forgetting to add these indicators, purposefully omitting them because there wasn’t a good place to include them in the design, or implementing them poorly. One of the biggest omissions that I see is with live searches and auto-completion widgets, but not without good reason. Activity indicators can break up a good layout, as they can require a fair amount of page real estate. They’re also a major pain to incorporate into your apps, as you often end up writing a lot of redundant code to display and hide different indicators on different pages or parts of a page.

So, what can we do about these problems? Well, if you’re using prototype as a part of your framework, you can register global indicator functions. These get executed when there are active requests, and when the requests complete. However, there’s another dilemma with this method too: Where do you place a indicator that can potentially appear often and keep it from being obtrusive, or, even worse, not being seen as it’s placed outside of the content that’s currently in view? I had to tackle that issue this week while starting development on a new project at work. I wanted to create an indicator that would be in the same place on every page, and that I never had to write extra code to use. View a demo of the solution here.

The solution, in hindsight, seems very obvious and I can’t believe that I hadn’t come up with it earlier: Place a div that spans the entire width of the window at the bottom of the window and make it stick there when the user scrolled. Then use scriptaculous, or moo.fx (whichever you prefer) to show/hide the indicator when ajax requests were made/completed respectively. So how did I do it? Read on…

Step 1: Gather the Tools

Before we write any code, we need to grab some javascript libraries. For this implementation, I use the latest versions of scriptaculous (1.6.1 at the time of writing) and Prototype (1.5.0_rc0 at the time of writing). If you don’t have them, head over to the scriptaculous website and grab the latest version. Prototype comes bundled with it, so that ought to save you some time.

Once you have the file, grab everything in the src folder (the scriptaculous files) and prototype from the lib directory and place them in whatever directory you would like in your site. This example will assume they are in the root.

Step 2: Laying the Groundwork: The CSS

Now for the tricky part. The key to this whole solution is to keep the div at the bottom of the window, not the page. We want to make sure the user always sees the indicator. The solution is actually a slightly modified version of SitePoint’s Catfish Script. If you’ve been to their site lately, you have probably noticed their cool little ads that appear at the bottom of the screen after a few seconds. Well, they call that a catfish, which makes complete sense to me now, but was of no use to me when I was searching for their solution. As usual, I’m going to summarize and borrow from their article, but I suggest you stop reading now and read their full post before continuing. Also, just to be perfectly clear, I’m not trying to steal their work, or claim it as my own, I’m just using it to achieve our goal (don’t need people thinking I’m plaigarizing!).

Anyway, here’s the css for the notification area to work, at least in everything but IE:

#notification {
	position: fixed;
	bottom: 0;
	padding: 0;
	height: 20px;
	margin: 0;
	width: 100%;
	background-color: #FFFF99;
	display: block;
	text-align: center;
	font-weight: bold;
	font-size: 1.3em;
	font-family: Verdana, Arial, Helvetica, sans-serif;
	padding-top: 5px;
}
html,body {
	height: 100%;
}

html {
	padding: 0 0 25px 0;  /* create area for notification area */
}

I’ll take an excerpt from the sitepoint article to explain why this won’t work in IE, and what we need to do to fix it:

At this point the major issue became the small matter that it didn?t work at all in Internet Explorer. If you’re viewing the demo in IE you’ll see that the DIV is behaving exactly as if it were “position: static” (the default).
[...]
We also made another decision at this point. Since FireFox, Opera and Safari do a dandy job with the W3C standard “position:fixed”, why throw extra markup at them?only IE would be getting the extra markup.

The article goes into greater detail, and explains the problem further, but for the sake of continuity, I’ll just post the code we need to get IE to play nice on the next page

First, we need to create a separate css file for IE. Let’s call it IEhack.css:

#header {
	width: auto; /*needed to keep IE from throwing a horizontal scrollbar in the page */
}
#notification {
     position: absolute;
     z-index: 100;
     overflow: hidden;
}
html, body {
     height:100%;
     overflow: hidden;
     width:auto;
}

div#zip {
     width: 100%;
     padding:0;
     margin:0;
     height: 100%;
     overflow: auto;
     position: relative;
}

Now, we need to write a bit of javascript:

function wrapFish() {
	var catfish = document.getElementById('notification');
	var subelements = [];
	for (var i = 0; i < document.body.childNodes.length; i++) {
 		subelements[i] = document.body.childNodes[i];
	}

	var zip = document.createElement('div');    // Create the outer-most div (zip)
	zip.id = 'zip';                      // call it zip

	for (var i = 0; i < subelements.length; i++) {
	zip.appendChild(subelements[i]);
	}
	document.body.appendChild(zip); // add the major div
	document.body.appendChild(catfish); // add the catfish after the zip
}

addLoadEvent(function() {
	wrapFish();
});

Finally, as mentioned by the SitePoint article, we need to create a way to serve this css and js to only IE users. Here's the code:

<!--[if IE]>
<link rel="stylesheet" href="IEHack.css" type="text/css" />
<script type="text/javascript" src="notification.js"></script>
<![endif]-->

So, we've got our CSS, we've got our IE hacks, but we still need our HTML, and the main JavaScript that sets this all up for us. Let's get into the HTML next...

Step 3: The HTML

There's no real need for explanation here, as the HTML is pretty basic. I'm just going to give you the HTML from my demo page, but you should be able to easily modify it to suit your needs:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Global Ajax Activity Indicator Demo</title>
<script type="text/javascript" src="prototype.js"></script>
<script type="text/javascript" src="scriptaculous.js?load=effects"></script>
<script type="text/javascript" src="responder.js"></script>
<style type="text/css">
<!--
html,body {
	height: 100%;
}

html {
	padding: 0 0 25px 0;  /* create area for notification area */
}
body,td,th,p {
	font-family: Verdana, Arial, Helvetica, sans-serif;
	font-size: 12px;
	color: #333333;
}
body {
	margin-left: 0px;
	margin-top: 0px;
	margin-right: 0px;
	margin-bottom: 0px;
}
#notification {
	position: fixed;
	bottom: 0;
	padding: 0;
	height: 20px;
	margin: 0;
	width: 100%;
	background-color: #FFFF99;
	display: block;
	text-align: center;
	font-weight: bold;
	font-size: 1.3em;
	font-family: Verdana, Arial, Helvetica, sans-serif;
	padding-top: 5px;
}
#header {
	padding: 5px;
	background-color: #CCCCCC;
	font-size: 15px;
	font-weight: bold;
}
#content {
	padding: 5px;
}
-->
</style>
<!--[if IE]>
<link rel="stylesheet" href="IEHack.css" type="text/css" />
<script type="text/javascript" src="notification.js"></script>
<![endif]-->
</head>
<body>
<div id="header">This would be your fancy header!</div>
<div id="content">
And all your site content could go here! Notice that if you keep executing requests so that the page gets longer than the window, you the notification stays "stuck" to the bottom.<br />
<br />
<a onClick="testClass.demoRequest();" style="cursor: pointer; color: #0066CC;">Click Here to Execute a Request</a><br />
</div>
<div id="notification" style="display: none;"><img src="ajax_indicator.gif" width="16" height="16" align="absmiddle"> Working...</div>
</body>
</html>

Let's take a look at the HTML. In the header, we've included all our necessary javascript, including the file that we'll create in the next step. We've also included the IE-specific code, and the base css. This could, of course, be a part of your main CSS file, I just put it in the header for clarity. In the body, the only two necessary elements are the header and notification divs. The only other thing we need before we start writing the javascript, is the indicator:

The activity indicator

Alright, let's get to the fun stuff: the javascript!

Step 4: The JavaScript

OK, so all that's left for us to do is to create the javascript that will show/hide our notification area when there are active/complete requests. What we're going to do is use prototype's ajax responder functions to display the notification area when there are any open requests, and then hide it when all requests complete. The code is pretty straightforward:

Ajax.Responders.register({
	onCreate: function() {
		if($('notification') && Ajax.activeRequestCount > 0)
			Effect.Appear('notification',{duration: 0.25, queue: 'end'});
	},
	onComplete: function() {
		if($('notification') && Ajax.activeRequestCount == 0)
			Effect.Fade('notification',{duration: 0.25, queue: 'end'});
	}
});

This code can either be placed in a file that you include on every page, or, as I prefer to do, place it at the top of the file that contains all my javascript for a particular page. It's completely up to you how you do it, just make sure that it gets included once on every page you want the notification area to work with. You can also change the scriptaculous effects to whatever you would like, I simply prefer the fading, but the blind effects could work nicely as well. Of course, you could also use another effects package, such as moo.fx, or simply change the display from none to block.

Wrapping Up

That's all there is to it! A simple, unobtrusive, but extremely useful notification area that will stick to the bottom of your window. You could also use this area for other notifications, such as successful saves, or any other event that occurs in your app. Like I said before, this saves you the effort of writing function-specific indicators, and of trying to find a place to put the indicator in your design. If you have any comments, suggestions, or improvements, don't hesitate to let me know. Enjoy!

Resources