JavaScript Documentation

A call for better JavaScript documentation has gone out and I am 150% in favour of it. Most of the existing JavaScript code, tutorials, and examples available on the web are just messy mashups that work, but are not code you actually want to use in a website. Therefore I am adding the PromoteJS wordpress widget to my blog and I encourage you to do the same.

Learn JavaScript JS

The world needs better JavaScript documentation.

Let’s help others and help ourselves by writing and promoting quality JavaScript documentation.

Google Hosted jQuery

Google provides hosting for many of the most popular JavaScript libraries. I’m a big fan of jQuery so I’m going to show you how to use Google’s hosted version of jQuery and thereby removing resources from your web server and speeding up site performance.

Performance can be increased because your user is going to download the jQuery file from Google’s CDN network and not from your server. Also, it could be even faster if the user visited another website that also uses Google’s hosted jQuery. If that is the case then your user won’t need to download it again and will use the exactly same cached version.

There are two ways to do this.

The fastest and simplest is to link directly to the Google’ hosted jQuery file:

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>

The second approach has more features but there is a slight delay while the jsapi loads the correct version of jQuery. If you want the absolute best performance use the first version.

1) Signup to get your own API key

2) Add the following code to your layout:

<script type="text/javascript" src="http://www.google.com/jsapi?key=INSERT-YOUR-KEY"></script>
<script type="text/javascript">
google.load("jquery", "1.4.2");

  google.setOnLoadCallback(function() {
    // Put you init code here instead of using $(document).ready()
  });
</script>

You can also specify the latest version of the 1.4 branch:

google.load("jquery", "1.4");

MySQL Gem on Snow Leopard

Snow Leopard does not have the mysql gem installed, and my last solution for installing it only work in OS X prior to 10.6.4; therefore, when you see the following error:

Building native extensions. This could take a while...
ERROR: Error installing mysql:
ERROR: Failed to build gem native extension.


/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/ruby extconf.rb install mysql
mkmf.rb can't find header files for ruby at /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/ruby.h

Install the mysql gem with these steps:

  1. Download and install the latest version of MacPorts if not already installed
  2. Run the following commands to install mysql5 and the associated ruby gem

# sudo port install mysql5-server
# sudo env ARCHFLAGS="-arch x86_64" gem install mysql

Ruby Subversion Bindings

Subversion has bindings for a variety of languages: Java, Perl, Python and Ruby. Of these I am most interested in the Ruby bindings as I’m building a Rails application. Unfortunately the documentation is completely lacking and bits of it are scattered throughout the web. This is an attempt to provide the code and how-to for the most common tasks.

Before we get to the code, validate you have the Ruby Subversion bindings installed correctly by running irb from a terminal:

irb(main):001:0> require ‘svn/client’
=> true

Onto the source code. Start it off by including the required svn modules:

require "svn/core"
require "svn/client"
require "svn/wc"
require "svn/repos"

Then setup the context with your subversion credentials:

ctx = Svn::Client::Context.new()
ctx.add_simple_provider
ctx.auth_baton[Svn::Core::AUTH_PARAM_DEFAULT_USERNAME] = 'username'
ctx.auth_baton[Svn::Core::AUTH_PARAM_DEFAULT_PASSWORD] = 'password'

Now you can run any of the following commands on a remote subversion repository.

SVN Info

repos_uri = 'http://svn.website.com/project/trunk'
revision = 50
begin
  ctx.info(repos_uri, revision) do |path, info|
    puts("Url: #{info.url}")
    puts("Last changed rev: #{info.last_changed_rev}")
    puts("Last changed author: #{info.last_changed_author}")
    puts("Last changed date: #{info.last_changed_date}")
    puts("Kind: #{info.kind}")
  end
rescue Svn::Error => e
  # catch a generic svn error
  raise "Failed to retrieve SVN info at revision " + revision.to_s
end

SVN Checkout

repos_uri = 'http://svn.website.com/project/trunk'
output_dir '/home/billy/project_name'
revision = 50
begin
  ctx.checkout(repos_uri, output_dir, revision.to_i, nil)
rescue Svn::Error::CLIENT_UNRELATED_RESOURCES => e # revision doesn't exist
  raise "No such revision " + revision.to_s + " at " + repos_uri
end

SVN Log

repos_uri = 'http://svn.website.com/project/trunk'
ctx.log(repos_uri, 0, 'HEAD', 0, true, nil) do |changed_paths, rev, author, date, message|
  puts("Revision: #{rev}")
  puts("Author: #{author}")
  puts("Date: #{date}")
  puts("Message: #{message}")
  puts("---------------------------")
end

SVN List

repos_uri = 'http://svn.website.com/project/trunk'
ctx.list(repos_uri, "HEAD") do |path, dirent, lock, abs_path|
  if !path.blank?
    puts("Path: #{path}")
  end
end

That should get you started with the ruby bindings. If you want to know how to do anything else let me know in the comments.