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/

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.

Granted you can download a stand-alone Jaxer+Apache bundle, but if you’re like me, you want to be able to start seeing how it plays with existing web technologies (for me, that would be PHP). The other thing that you’ve probably already got (if you’re like me) is a test / development environment locally, and it’s most likely XAMPP (or something similar). Finally, if you’re slightly OCD like me, you like to have everything in one place, all nice and organized. Well, you’re in luck, because I’m going to show you how to get all of this goodness up and running. My examples will be for a Mac install of XAMPP, but the Windows / Linux methods will be pretty darned close. The only caveat with this walk-through is that it is written based on the upcoming 0.9.5 release (which will be out within the next week or so), and this is because it covers some important changes from the 0.9.4 releases. Now that we’ve got all that out of the way, let’s get into how we can get all this up and running. Read on…

Step 1 – XAMPP

There are a lot of nice Apache + MySQL + PHP packages out there, but none of them (in my opinion) are quite as easy as XAMPP. So, head on over to ApacheFriends.org and download the installer for your OS and, well, install it. Once you’ve done that, you’re ready to start installing Jaxer. But, before we do that, let’s take note of a few things:

• The XAMPP Program Root – On OS X, this is

  /Applications/xampp/xamppfiles

  On windows it will be something very similar.

• The Apache Conf File – This is located in

  /Applications/xampp/xamppfiles/etc

  For the uninitiated, the Apache config file is “httpd.conf”. To be honest, if you have never opened this file on any system, this might be a bit over your head, and I would suggest just working with the stand-alone Jaxer+Apache for now. If you’re feeling adventurous, or a quick learner, then read on, this stuff really isn’t rocket science!

We’ll soon be dropping Jaxer into the XAMPP root, and modifying our Apache config… then you’ll be ready to dive into the awesomeness that is Jaxer (seriously, it’s awesome… and no, I’m not getting payed to say that )

Step 2 – Download & Unpack Jaxer

Jaxer is always available at http://www.aptana.com/jaxer/download or bundled in Aptana Studio version 1.1 and higher.

REMEMBER, this walk-through is for version 0.9.5 of Jaxer, which (at the time of writing) will be released within a week or so. I’ll make sure to post when its out, so be sure to subscribe to my feed. Anyway, head on over to the the download link above and grab a copy of Jaxer for your system. Make sure you grab the full version, not the updater. Once its downloaded, we’re going to grab a copy of the Jaxer folder and move it (and some others) over to the XAMPP root. If you’re on the Mac, I would suggest going ahead and installing it (simply drag the Aptana_Jaxer folder to your Applications folder), so you have not only a working copy for reference, but a good place to start over from if you screw up.

OK, so, first, head over to either the package itself or the Jaxer install directory, and copy the whole “jaxer” folder and paste it into the XAMPP root we noted above. Check it out:

Remember that’s the “jaxer” folder inside the “Aptana_Jaxer” package to the

/Applications/xampp/xamppfiles

folder. While we’re at it, we need to grab one more folder and copy it to the same place: “local_jaxer”. If you look in the picture above, you’ll see that I’ve already got it there.

Step 3 – Supporting Directories

We’ve also got to manually create some directories in the XAMPP root. This is where it gets a little different for the Max / Linux users, as we need to also make sure that these directories have write permissions (I just use 777 since this is a local dev environment). Windows users, just create the directories, you’re fine with permissions.

Anyway, the easiest way to get this all done is to open up Terminal (Applications => Utilities => Terminal) and type the following (Linux users, adjust accordingly):

cd /Applications/xampp/xamppfiles
sudo mkdir data
sudo mkdir tmp
sudo chmod 777 logs
sudo chmod 777 data
sudo chmod 777 tmp

Jaxer needs the logs directory, but the latest XAMPP comes with one there already, so we only need to make sure it can be written to. Now, on to the fun stuff: setting up Apache!

Step 4 – Integrate With Apache

It just dawned on me that I completely failed to mention that this needs to be done with Apache 2.2 or higher… but if you’re still on Apache 1… well… I can’t think of anything nice to say. Anyway, we’re going to need to add some stuff to the Apache config, so head on over to the httpd.conf, open it with your favorite text editor, and add the following to the end of the file (it’s easiest to add to the end, and adjust your paths as needed folks):

<directory "/Applications/xampp/xamppfiles/jaxer/aptana">
    Order Deny,Allow
    Deny from all
    Allow from localhost
</directory>
Alias /aptana /Applications/xampp/xamppfiles/jaxer/aptana

<directory "/Applications/xampp/xamppfiles/jaxer/framework">
    Deny from All
    <files clientFramework_compressed.js>
        Allow from localhost
    </files>
</directory>
Alias /jaxer/framework/clientFramework_compressed.js /Applications/xampp/xamppfiles/jaxer/framework/clientFramework_compressed.js

LoadModule jaxer_module "/Applications/xampp/xamppfiles/jaxer/connectors/mod_jaxer.so"
<ifModule jaxer_module>
    DefaultInitEnv "SystemRoot"

    JaxerWorker localManagerWorker localhost 4327
    <location "/jaxer-server">
        SetHandler JAXER
        Order Deny,Allow
        Allow from all
    </location>

    <directory "/Applications/xampp/xamppfiles/jaxer/aptana">
        JaxerFilter localManagerWorker .html
        JaxerFilter localManagerWorker .xhtml
        JaxerFilter localManagerWorker .htm
        JaxerFilter localManagerWorker .php

        Order Deny,Allow
        Deny from all
        Allow from localhost
    </directory>

    <locationMatch "/jaxer-include/">
        JaxerPassThrough
        Order Deny,Allow
        Deny from all
        Allow from localhost
    </locationMatch>
</ifModule>

What we’ve essentially done is told Apache to load the Jaxer module, and then provided some rules for various parts of the Jaxer framework. At this point, you could technically start up Jaxer, but if you want to actually use it in your doc root (/Applications/xampp/xamppfiles/htdocs/ on the Mac), you’ll need to make one more tweak to the httpd.conf file. We need to add the following three lines to the conf file (for me, this was around line 209):

<directory "/Applications/xampp/xamppfiles/htdocs">
    JaxerFilter localManagerWorker .html
    JaxerFilter localManagerWorker .xhtml
    JaxerFilter localManagerWorker .htm
    ...

We do this so all html, xhtml, and html files in our Apache doc root will be filtered through Jaxer, thus allowing us to actually use Jaxer itself inside that directory. Now that all that’s set up, we can start up Jaxer and make sure everything’s running!

Step 5 – Starting Jaxer and Testing

I’ll show you a nice little start / stop script in a moment, but for now let’s just try to fire this puppy up and make sure everything is working properly. First, make sure Apache is stopped (use the XAMPP control panel). Then, bust open a terminal again, and type the following:

cd /Applications/xampp/xamppfiles/jaxer
./JaxerManager --webport=4327 --commandport=4328 --minprocesses=3 --maxprocesses=10 --requesttimeout=60

If everything’s working right, you’ll see the terminal appear to be hanging, with the last line of output being

JaxerManager 0.9.5.2312 (web 4327, command 4328)

That’s good, that means everything is working properly. Right now, Jaxer isn’t logging properly, but that’s OK, we just want to make sure everything is working.
Now that we’ve verified Jaxer will start properly, we can start up Apache (again, use the XAMPP control panel). You shouldn’t see any errors, and if you browse to http://localhost, you should end up at the XAMPP start page:

XAMPP & Jaxer Running Together… So far, so good!

OK, at this point we can do one of two things… We could either create a nice start / stop control script for Jaxer, or we could jump right into testing. I would suggest creating the control script because we can make sure that Jaxer will be logging properly when all is said and done. Right now, it isn’t, because we haven’t set up the proper environment variables for this. If you’re a windows user, you’re in luck, the script is already made for you… just double-click on the “StartJaxer.bat” file in the jaxer folder (inside of XAMPP). If you’re a mac / linux user you *could* technically use the .sh files that come with the stand-alone, but I’ve cooked up something even easier…

Step 6 – The Control Script and Jaxer Tests

OK, so, there’s a small catch with this control script: You have to run it from the command line, and from the jaxer directory. This is mostly because my bash kung-fu isn’t all that strong (if you can make this runnable from anywhere, let me know so I can update this script here). At any rate, the other thing to be aware of is that you must always start Jaxer first, then XAMPP’s Apache. If you ever restart Jaxer, you must also subsequently restart Apache.

OK, let’s get this script written. First, stop the Jaxer we left running by switching back to the terminal window and hitting ctrl+c. Then shut down apache. Create a new text file called “jaxerctl” in the jaxer directory, and paste the following into it:

#!/bin/sh
ARGV="$@"
JAXER_WEBPORT=4327
JAXER_COMMANDPORT=4328
JAXER_MINPROCESSES=3
JAXER_MAXPROCESSES=10
JAXER_REQUESTTIMEOUT=60
JAXER_MANAGER='JaxerManager'

case $ARGV in
start)
    echo Starting Jaxer...
    export JAXER_LOGFILE=file:///Applications/xampp/xamppfiles/logs/jaxer.log
    ./$JAXER_MANAGER --webport=$JAXER_WEBPORT --commandport=$JAXER_COMMANDPORT --minprocesses=$JAXER_MINPROCESSES --maxprocesses=$JAXER_MAXPROCESSES --requesttimeout=$JAXER_REQUESTTIMEOUT > ../logs/jaxer_log.log &
    ERROR=$?
    ;;
stop)
    echo Stopping Jaxer...
    ./tellJaxerManager -p $JAXER_COMMANDPORT stop
    ERROR=$?
    ;;
esac

exit $ERROR

Once you’ve got that saved, you’ll need to make it executable:

sudo chmod 755 jaxerctl

, and then we can start up Jaxer!

./jaxerctl start

That’s it! Now we can get started testing Jaxer, so go ahead and start up Apache again, head over to http://localhost and make sure the XAMPP page pops up. If it does, now we can head over to the Jaxer page: http://localhost/aptana

Remember, we set this up in the httpd.conf file, and all that you see here is provided by Aptana to help you diagnose problems with Jaxer, check out some cool examples, and read up on the documentation. You should see a screen that looks like this:

The Jaxer Server Start Screen

See it? Great, let’s run some tests. Click on the “Server Diagnostics” link to the left. The resulting screen will show you the result of some basic tests that get run to make sure Jaxer is running normally. If all’s well, your screen will look very close to this:

The Jaxer Diagnostics Screen

Wrapping Up and Next Steps

Not so bad, right? You’re all set to start playing around with some of the coolest new technology to hit the web. I really encourage you to do so, as I’m sure you’ll start realizing a lot of the things I have about Jaxer (and I’ll be writing about those soon), but hopefully the most important thing: You’re going to write less code, and it’s going to be cleaner! I’m not going to say how or why right now, but trust me, if you start playing around, you’ll see what I’m talking about.

So, what’s next? Check out the sample apps included with Jaxer (there’s a link on the left-hand side of the Jaxer server start page), or read the Jaxer Book / Documentation. There’s a lot of good stuff in there, and it’s all by the guys that wrote Jaxer. Seriously, this is cool stuff, and it’s so incredibly simple… it took me less than a day to get comfortable with the better part of Jaxer’s functionality and nuances. Coming soon: a Jaxer Photo Gallery (and how it’s more gooder than a plain ‘ol PHP+JavaScript gallery).