One real benefit of end-user documentation is that it generally will help make your application better. When you’re explaining in depth how to use your application, it becomes immediately obvious where you’re application is deficient, confusing, or inconsistent.

Try writing a walk-through of your application. Write down what each element of your application does, and why. If you find areas that are confusing to write down, chances are you’ll be getting an e-mail from a client who is confused as well.

Let’s start with the instructions for installing the latest version to /usr/local. If you’re not familiar with what this means, check out Dan’s article on Using /usr/local.

curl -O http://www.sphinxsearch.com/downloads/sphinx-0.9.8-rc2.tar.gz
tar -xzf sphinx-0.9.8-rc2.tar.gz
cd sphinx-0.9.8-rc2
./configure --prefix=/usr/local
make
sudo make install
cd ../
rm -fr sphinx-0.9.8-rc2*

Troubleshooting

If you’re installing Sphinx on Leopard on the 64 bit architecture you need to run

LDFLAGS="-arch x86_64" ./configure

If make is throwing you an error that looks like this:

...
make[2]: *** [sphinx.o] Error 1
make[1]: *** [all] Error 2
make: *** [all-recursive] Error 1

You may need to specify the path to mysql using the –with-mysql option to ./configure.

./configure --with-mysql=/usr/local/mysql

If make is throwing you an error that looks like this:

sphinx.cpp:17343: error: ‘XML_STATUS_ERROR’ was not declared in this scope
sphinx.cpp:17367: error: ‘XML_STATUS_OK’ was not declared in this scope
sphinx.cpp: In member function ‘bool CSphSource_XMLPipe2::ParseNextChunk(int, CSphString&)’:
sphinx.cpp:17775: error: ‘XML_STATUS_OK’ was not declared in this scope
make[2]: *** [sphinx.o] Error 1
make[1]: *** [all] Error 2
make: *** [all-recursive] Error 1

This is from having an incompatible version of expat installed. Here are instructions for installing the latest version of expat.

curl -O -L http://downloads.sourceforge.net/expat/expat-2.0.1.tar.gz
tar -xzf expat-2.0.1.tar.gz 
cd expat-2.0.1
./configure --prefix=/usr/local
make 
sudo make install
cd ../
rm -fr expat-2.0.1*

The only problem with my setup was that it required me to connect these drives to my laptop and eject them as I move my computer around the house. Time Capsule solves this by making my setup wireless.

You can view the hard drive volumes mounted on your Mac from the terminal:

$> ls /Volumes
./                    Macintosh HD@
../                   Derek's Time Capsule/

When using a Time Capsule drive, it may not appear in /Volumes if it isn’t mounted. You can mount your drive with a simple bash script that uses mount_afp.

Save as mount_capsule.sh

#!/bin/bash
 
# configure - enter your capsule name, ip, and username:password
CAP_NAME="Derek's Time Capsule"
CAP_IP="192.168.1.103"
USER="username:password"
 
if ! [ -d "/Volumes/$CAP_NAME" ]; then
  echo "[info] Mounting $CAP_NAME..."
 
  mkdir "/Volumes/$CAP_NAME"
  mount_afp "afp://$USER@$CAP_IP/$CAP_NAME" "/Volumes/$CAP_NAME"
fi
 
echo "[info] $CAP_NAME mounted"

And now let’s make the script executable and run it.

$> chmod 744 mount_capsule.sh
$> ./mount_capsule.sh
[info] Mounting Derek's Time Capsule...
[info] Derek's Time Capsule mounted

Once we’ve mounted the drive, we can proceed to copy/move/rsync data to it.

rsync -avz --delete /Users/derek/work /Volumes/Derek\'s\ Time\ Capsule/backup

The book covers the language reference, while this reference aims to translate as many of the PHP methods as possible. We’ve even put together an easy way of searching for your favorite PHP functions by typing them in the url like: http://railsforphp.com/preg_match_all.

Enjoy!

Enabling Cache

We use asset helpers such as javascript_include_tag and stylesheet_link_tag in our layouts to include external Javascript and CSS files. One benefit of using these helpers is the ability to cache these resources. Asset cache is turned on when the perform_caching configuration option is set to true.

Rails applications default to having caching disabled during development, and enabled in production. We can change this in config/environments/development.rb to test out caching during development.

config.action_controller.perform_caching = true

Caching Assets

We enable asset caching in our applications using the :cache option in our helpers. We can cache Javascript files by doing the following:

<%= javascript_include_tag "prototype", "application", "effects",
                           :cache => "cache/all" %>

When caching is disabled, Rails will generate the normal references to these resources.

<script src="/javascripts/prototype.js?1197321216" type="text/javascript"></script>
<script src="/javascripts/application.js?1197321216" type="text/javascript"></script>
<script src="/javascripts/effects.js?1197321216" type="text/javascript"></script>

However when caching is enabled, Rails will generate a single external Javascript file in the location we specified. It will then reference this file instead of the original source files.

<script src="/javascripts/cache/all.js" type="text/javascript"></script>

As you can see in the above example, we’re going to store our asset cache in subdirectories named cache/. This makes it easier to clear out the cache later on. Caching external CSS files works similar to the Javascript example:

<%= stylesheet_link_tag "typography", "layout", "color",
                        :cache => "cache/all" %>

Clearing Cache

Rails comes with some useful built-in tasks for clearing out temporary files under the tmp: rake namespace. Rails does not come with a built-in task for clearing out the asset cache. We’ll add this ourselves by adding a new rake task named rake tmp:assets:clear. Create a new file in your Rails application named at lib/tasks/tmp.rake, and add the following code.

namespace :tmp do
  namespace :assets do 
    desc "Clears javascripts/cache and stylesheets/cache"
    task :clear => :environment do      
      FileUtils.rm(Dir['public/javascripts/cache/[^.]*'])
      FileUtils.rm(Dir['public/stylesheets/cache/[^.]*'])
    end
  end
end

The custom tmp:assets:clear task we added removes all files from both the javascripts/cache/ and stylesheets/cache/ directories. Let’s give it a whirl:

$> rake tmp:assets:clear

Wrap Up

Using asset cache can significantly reduce the number of requests sent to the server for external CSS and Javascript files. Along with a good gzip strategy, this is an essential feature when working with large multi-file Javascript libraries.

For additional performance increases using asset helpers, check out Chad Fowler’s write-up of Distributed Asset Hosts.

We’ll go over the basics needed to test your Rails applications in IE6/IE7 on Parallels in the most convenient way possible.

• Getting Started
• Open Ports on the Network
• Browsing in IE
• Browse By Name with Bonjour

Getting Started

I’ll start out by saying that the first prerequisite for this setup is having an Intel powered Mac. This article is useless without one unless you’re just here to drool over neat tools.

Being able to use Parallels comes at a cost. You’ll need to shell out $79.99 for a copy of Parallels for Mac, and a couple hundred more for a copy of Windows. I believe this is a nominal business cost for what the software offers, and is much cheaper than having to buy and maintain a separate PC to run Windows. Both Parallels and Windows have a trial versions you can use to verify that this setup is worth your money.

Once you download Parallels for Mac, you can unpack and install the software as usual. Parallels has a great guide for getting started with the software. It will take you through Installing Parallels Desktop, Creating new Virtual Machines, and Installing Windows on the machine. I started out by installing a single Windows XP virtual machine and set it up with IE6 and all other default settings I use. I then just copied that setup to create a new VM on which I upgraded to IE7.

Open Ports on the Network

When developing Rails applications on the Mac, the typical setup is to develop everything on localhost, and serve the applications using mongrel.

$ cd maintainable
$ mongrel_rails start -d -p 3000

We can of course access this directly in our native Mac browsers by navigating to http://localhost:3000. To make this application accessible from IE on our Windows VM, we’ll have to accept network traffic through our firewall on port 3000. Open up your Apple System Preferences and go to the sharing window.

Navigate to the Firewall Tab in the Sharing pane, and click on the New button so that we can add an additional port(s).

Here is where we make our Rails ports available on the network. We’re going to open up ports 3000-3099 for any additional Rails applications we choose to bind to a port in that range. Enter

• Port Name: Other
• TCP Port Number(s): 3000-3099
• Description: Rails Applications (30xx)

Browsing in IE

Now we should be able to browse to this from IE in our Parallels machine by pointing to our internal IP Address. We can find out this internal address by taking a look at the Services tab on our Sharing pane. Near the bottom it will say something like “Other Macintosh Users can access your computer at afp://192.168.1.100″.

This is the number we’re looking for, and we can alternately find it using this command from the terminal.

$ ifconfig | grep 192 | awk '{print $2}'

Once we have our internal IP, let’s fire up our IE browser and check out our site. In IE, navigate to http://192.168.1.100:3000.

Browse By Name with Bonjour

The problem with browsing by internal IP address is that it’s likely to change from day to day. A better approach is to install Bonjour for Windows so that we can simply refer to our computer by name instead of number.

We’ll first go back into our Services tab on the Sharing pane in Apple System Preferences. Here we’re going to shorten our name to be something easy to remember and type into the browser. Click on the Edit Button near the top.

I’m going to simply rename this to derek.local. Feel free to be more creative with your own.

To seamlessly network with our Windows VM without the hassle of dealing with network settings manually, we’re going to install Bonjour for Windows. Download BonjourSetup.exe, and choose the default settings for the installation. With Bonjour installed, we can now browse to our application at http://derek.local:3000.

This number can be cut down a little bit with Douglas Crockford’s JSMin filter. This filter creates a smaller version of your Javascript source by stripping out extraneous code like whitespace and comments. The minified versions of Prototype is 52K, and Effects is 28K. This saves us around 25K off the bat.

Since we like to keep as much of our code as possible in the Ruby family, we use the Ruby version of the minifier. Copy The jsmin.rb file to script/javscript/jsmin.rb in your Rails application.

Now let’s add a handy Rake task to minify your javascript code using this script. The following task will combine prototype.js, effects.js, and application.js. This will create our final minified file as all_min.js. You can add additional javascript files to the libs array as needed, or adjust what you want the final file to be named. Then copy the code into a file named lib/tasks/js.rake.

namespace :js do
  desc "Minify javascript src for production environment"
  task :min => :environment do
    # list of files to minify
    libs = ['public/javascripts/prototype.js', 
            'public/javascripts/effects.js', 
            'public/javascripts/application.js']
 
    # paths to jsmin script and final minified file
    jsmin = 'script/javascript/jsmin.rb'
    final = 'public/javascripts/all_min.js'
 
    # create single tmp js file
    tmp = Tempfile.open('all')
    libs.each {|lib| open(lib) {|f| tmp.write(f.read) } }
    tmp.rewind
 
    # minify file
    %x[ruby #{jsmin} < #{tmp.path} > #{final}]
    puts "\n#{final}"
  end
end

Before we run the task, there is a single point in Prototype version 1.5 stable that breaks the jsmin filter. There is a patch for this in the Rails trac, but we will need to manually add the single missing semi-colon until it is applied. You may want to also run your application code through JSLint Verifier and clean up any issues that may jam the jsmin filter.

Now we can minify our javascript by running this new task. It will create a new javascript file with the combined source. From the root of your rails application run:

$ rake js:min
(in /Users/derek/work/sportspyder/trunk)
 
created public/javascripts/all_min.js
<pre>
 
In our development environment we don't want to have to re-minify our javascript after every change. We'll still use our separate and easy to read source files. We can do this by putting a conditional in our layout to include the minified version in production mode, and the separate files during development.
 
 
<pre lang="ruby">
<% if RAILS_ENV == 'production' %&gt;
<%= javascript_include_tag "all_min" %&gt;
<% else %&gt;
<%= javascript_include_tag "prototype", "effects",
                           "application" %&gt;
<% end %>

One of the added benefits of this approach is that you have a single Javascript source file for the client to download instead of multiple resources for the browser to pull.

You’ll have to make sure to run this rake task before you deploy, and may want to add it directly to your deployment script.

While minification provides a nice break in file size, it is secondary to sending your javascript compressed. Compression can cut your Javascript to nearly 1/4 of the original size, and is most commonly done using using Apache’s mod_deflate module. There is more information on Apache settings on the Mongrel website.

Update - 03/01/2007

Prototype doesn’t actively support a specific packing strategy for various reasons, and patches submitted for making the code pass something like JSLint are likely to be ignored. Reasons for this, and some other strategies on reducing filesize of the library are discussed in Packing Prototype.

Update - 12/14/2007

Rails 2.0 includes a feature that makes much of what is described here obsolete. Check out our write-up of Rails Asset Cache.

Installation

The Scriptaculous unit testing library can be installed in your Rails application using the javascript_test plugin located in the Rails subversion repository. To install the plugin, navigate to the base directory of your application and run:

$ ./script/plugin install \\
http://dev.rubyonrails.org/svn/rails/plugins/javascript_test

Once the plugin is installed, you will have a new generator script to create tests for your Javascript files. To create a test skeleton file for a file such as public/javascripts/cookies.js:

$ ./script/generate javascript_test cookies
  create  test/javascript
  create  test/javascript/cookies_test.html
}) %>

Now we have a special directory within test to store our javascript test files. Each test suite will be an HTML file that includes the framework necessary for the tests to run.

Writing Tests

If you take a look at test/javascript/cookies_test.html, you’ll see a familiar setup to Ruby’s Test::Unit library. There are the typical setup and teardown methods, along with a dummy test to get you started.

new Test.Unit.Runner({
 
  // replace this with your real tests
  setup: function() {
  },
 
  teardown: function() {
  },
 
  testTruth: function() { with(this) {
    assert(true);
  }}
 
}, "testlog");

For the cookies.js library I’m testing, I want to make sure that my code can set and access cookies with new methods that I’m adding to the document object. I’ll start out by setting the cookie, and then assert that when I retrieve it, it is the same value I set. I’ll also add a snippet to the setup method that makes sure the cookie is deleted before each test.

new Test.Unit.Runner({
  setup: function() {
    // clear out cookie
    var expires = "expires=Thu, 01-Jan-70 00:00:01 GMT"
    document.cookie = 'foo' + "=; " + expires + "; path=/";
  },
 
  // test getting/setting cookies
  testSettingAndAccessingCookies: function() { with(this) {
    assertEqual(undefined, document.getCookie('foo'));
 
    document.setCookie('foo', 'bar');
    assertEqual('bar', document.getCookie('foo'));
  }}
}, "testlog");

This obviously isn’t the greatest test coverage, but you get the idea. Adding new tests cases is as easy is adding additional methods that are prefixed with test.

There are many additional assertions beyond assertEqual(), including among others:

• assert
• assertNull
• assertMatch
• assertVisible

Check the source in plugins/javascript_test/assets/unittest.js
for the full list.

Running the Tests

Running the tests is done in one of two ways. The first way is the very cool test:javascripts rake task that is bundled with the plugin. This task will launch an instance of the WEBrick server, and attempt to start up Safari, Firefox, IE, and Konquerer. It will run the javascript test in each of the available browsers on your system.

$ rake test:javascripts
  (in /Users/derek/work/demo)
  /test/javascript/cookies_test.html on Safari: SUCCESS
  /test/javascript/cookies_test.html on Firefox: SUCCESS
  Skipping Internet Explorer, not supported on this OS
  Skipping Konqueror, not supported on this OS

The tests results will pop up in a nice red=fail, green=pass HTML interface. There is no backtrace information given, so it’s smart to make small test cases so that you can easily find any specific problems.

While this is fine and dandy, it is rather slow during active development. The other testing method is to open the HTML test files directly in your browser and just hit refresh to rerun the tests.

There is one small setup you need to do for this to work. You need to make a symbolic link to the unit testing javascript library for your tests to use. From your Rails application base directory:

$ ln -s ../../vendor/plugins/javascript_test/assets/ \\
test/javascript/assets

Manipulating DOM Elements

When you’re writing Javascript, rarely does the code work in a vacuum. Most of the time you are manipulating some type of element in the DOM tree. To test this type of interaction, you will obviously need some mock HTML source for the test to operate on. The convention in these type of tests is to just add this HTML right to the test file itself above your tests.

<!-- our test DOM structure -->
<div id="widget_1">
  <h2>States</h2>
  <ul style="display: none">
    <li>Arizona</li>
    <li>California</li>
  </ul>
</div>
 
<!-- our javascript test code -->
<script type="text/javascript">
// <![CDATA[
...
// ]]>
</script>

You will notice this text showing up on the HTML page as your tests run. Don’t sweat it because this is normal. Just watch for red.

Writing Timed Based Tests

When using javascript animation effects, a lot of features happen over a period of time. When testing the state of elements in javascript (such as whether they are visible/hidden), we will often need to wait for the effect to take place before we make our assertion. The library includes a helpful way of doing this using the wait() method.

new Test.Unit.Runner({
  setup: function() {
  },
 
  // get/set cookies
  testShowWidgetBody: function() { with(this) {
    var widget = new Widget('widget_1');
    assertHidden(widget.body);
 
    // widget.toggle takes 500ms seconds to complete
    widget.toggle();
 
    // wait 550ms before asserting that it worked
    wait(550, function() { with(this) {
      assertNotHidden(widget.body);
    }});
  }}
 
}, "testlog");

There is much more to this library, but that’s all for now folks. Hopefully this gives you a good start so that you’re well on your way to testing your Javascript code as diligently as you test your Ruby code.

Now that Ajax has reared its ugly head, developers are awakening to the powerful behavior that Javascript can add to their applications. Javascript’s very unfamiliar object syntax is one of the reasons it had previously been avoided like the plague. Since Javascript has a prototype-based inheritance, creating objects is quite different than the class-based inheritance scheme we are used to.

Simple Javascript Objects

Creating an object in Javascript is actually quite simple using the new Object syntax, and we can add properties on the fly using the . operator.

var d = new Object();
d.name = 'Tripod';
d.legs = 3;
 
console.log("My Dog "+d.name+" has "+d.legs+" legs");

Methods are added to an object using the same syntax as properties. In fact methods are simply functions assigned as properties. Keep in mind that functions in Javascript are actually objects, and can be passed around and assigned just like any other data type. In this case, we will attach a function to the run property of our object.

d.run = function() {
  console.log('hobble... hobble');
}
d.run();

Another option for creating objects is using Javascript’s object literal syntax. This uses a key/value pair definition within curly braces to define the object.

var d = {
  name: 'Tripod',
  legs: 3,
  run: function() {
    console.log('hobble... hobble');
  }
}

Object Constructors

Although simple, these ways of creating objects becomes repetitive when we want to create another object. What we really want to do is create a template for an object that stores all of this information together so that we can reuse it. This is done in javascript by creating a constructor function. This function lets you pass in variables to define the state of your object similar to how you would in a class. A constructor looks just like any other Javascript function except for a few constructor commandments:

• The function name shall be capitalized (not required but highly recommended).
• The function shall be called through use of the new construct.
• The function shall make use of the this keyword.

function Party(people, beers) {
  this.people = people;
  this.beers  = beers;
}

We can now create a Party object using the new construct. This will create a reference to a new Javascript object, and pass that object into the function to be referenced with the this keyword.

var p1 = new Party(3, 9);
var p2 = new Party(11, 60);
 
console.log("party 1 has: " + p1.people + " peeps");
console.log("party 2 has: " + p2.people + " peeps");

We can now create lots of Parties in a more efficient method than before. This is great, but these objects are pretty useless without any behavior. Let’s add a method to our parties to see if any of them are kickin.

Party.prototype.status = function() {
  return this.beers/this.people > 5 ? 'kickin' : 'lame';
}
console.log("party 1 is: " + p1.status());
console.log("party 2 is: " + p2.status());

Earlier we created a method by assigning a function directly to the property of an object, but this time we have assigned it to Party’s prototype property. This is where Javascript gets a bit confusing. The Party constructor has an extra property that is always defined by default: the prototype object. This is like a parent object of all Party objects that gets shared between each instance. Since methods will remain the same for all Party instances, we don’t want to waste memory by creating copies for each instance. The prototype object gives us a space to share those properties between all instances. We can do a similar thing with any property that will remain constant in all instances.

Party.prototype.music = true;
console.log("party 1 tunes: " + p1.music);
console.log("party 2 tunes: " + p2.music);

Because it’s no party without tunes. Now we have a template to create a party that always has music, and we can check if it’s a party worth attending by using the status() method. The entire definition of our object template like so:

function Party(people, beers) {
  this.people = people;
  this.beers  = beers;
}
Party.prototype.music  = true;
Party.prototype.status = function() {
  return this.beers/this.people > 5 ? 'kickin' : 'lame';
}

It’s definitely not going to win a beauty pageant.

The Prototype Way

This is where the Prototype library steps in to help clean up a little of the mess. One of base features of Prototype is making the creation of an object template nicer using the Class.create() function. This function takes the mess above, and structures it in a way that is more familiar to us class-based programmers.

Party = Class.create();
Party.prototype = {
  music: true,
 
  initialize: function(people, beers) {
    this.people = people;
    this.beers  = beers;
  },
  status: function() {
    return this.beers/this.people > 5 ? 'kickin' : 'lame';
  }
}

This takes all of this logic and puts it into a nice construct that keeps it all together with a unified constructor function named initialize. Prototype does a little magic behind the scenes so that you can initialize your objects in the same way you previously did with the new operator.

var p1 = new Party(3, 9);

Let’s take a look at what Prototype is doing here by sneaking a peak at the source.

var Class = {
  create: function() {
    return function() {
      this.initialize.apply(this, arguments);
    }
  }
}

We see here that the Class object consists of a single
method, create(). When we call this method it returns us
a function object.

Remember earlier when we created the Party constructor function using Javascript’s native syntax? It was essentially a function used to set the properties of new objects.

This function returned by create() is actually this same constructor function. The difference is that it delegates setting the object properties to the initialize method.

1. You create a Party object with the new
   construct, and pass in the the properties we want to set. This executes
   the constructor function that was created when we called
   Class.create().
2. The constructor function calls Javascript’s apply
   function on initialize. The apply function lets you
   execute a method in the context of a different object. In this
   case we need to execute the initialize method, but we
   want it to use our newly constructed object from our constructor method
   as this when it executes.

While a little more complex behind the scenes, this code provides a nice abstraction that allows us to code in a style we are more familiar with. We welcome anything that makes our code a little easier to read or maintain.