Wednesday, October 10, 2007

Getting Started with Script.aculo.us and AJAX

I like the script.aculo.us library of JavaScripts, but really the guys over there REALLY need to put more effort into their documentation. I have always subscribed to the theory that a low entry barrier is good for any product. This holds true especially in the Java / JavaScript world and also should hold true for any open source project.

The "Getting Started" page is particularly heinous for someone that is trying to just take a dip into the Java Script libraries. Here's my re-write of that page and I hope to offer it as help for anyone trying to get started with the Java Script libraries.

First, download the script.aculo.us libs and drop them into a local javascripts directory. You should have the following libraries...
  • builder.js
  • controls.js
  • dragdrop.js
  • effects.js
  • scriptaculous.js
  • slider.js
  • unittest.js
Alright, here's the part that isn't in the instructions. You must also download the prototype.js library and also drop this library into java scripts/. You can download the prototype.js here.

NOTE: prototype.js is in the /lib directory and IS in the script.aculo.us zip JavaScript library file. Thanks Gregg B. for your feedback (see comments section)!

If not, you may see the following error:

uncaught exception: script.aculo.us requires the Prototype JavaScript framework >= 1.5.0

Next, add the following links into your html...

<script src="javascripts/prototype.js" type="text/javascript"></script>
<script src="javascripts/scriptaculous.js" type="text/javascript"></script>


Next, try the html reference in the example. Did it work? Of course not! Try adding the following reference to your html. NOTE: I leave the experimentation of trying the JavaScript example up to the reader. I may have received errors because I downloaded the latest prototype.js vs. using the prototype.js in the lib/ directory.


<div onclick="new Effect.CloseDown(this, arguments[1] || {});">

Click here if you've seen enough.

</div>


Your html should then look something like this...

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>

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

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

</head>

<body>

<div onclick="new Effect.CloseDown(this, arguments[1] || {});">

Click here if you've seen enough.

</div>

</body>

</html>


I recommend also reading
this article written by Michael Heilemann, and realize that the script.aculo.us documentation is not your friend. Thankfully, there are many articles that help the beginner get started with this JavaScript library.



iTunes_RGB_9mm

1 comment:

Rob Castellow (President / Consultant) said...

Hello All:
I received the following email after posting the following article on the Script.aculo.us Java script library. Gregg was really patient with my previous rant about script.aculo.us documentation and even provides a great link to a book on Amazon related on prototype, AJAX and scipt.aculo.us. Thanks Gregg!

Rob,

The prototype.js is included in the scriptaculous download. In fact, its typically recommended you use the included version as it is usually more up to date than the downloadable version from the prototype website.

And in fact, the documentation DOES tell you that you need the prototype library and tells you to include it on your pages

http://wiki.script.aculo.us/scriptaculous/show/Usage

The wiki documentation linked to above is actually quite good. There is also a nice book on both libraries:

http://www.amazon.com/Prototype-Scriptaculous-Action-Dave-Crane/dp/1933988037

You might want to edit your blog. I would have posted a comment but apparently you don't allow comments on your blog.

--
Gregg Bolinger