TBD: Need to coordinate this with the Troubleshooting page, minimize redundancy
TBD: This is very Prototype-heavy, very little script.aculo.us content
Table of Contents
- What is this wiki?
- What is Prototype?
- What is script.aculo.us?
- Under which license is it released?
- How do I download it?
Please check out the Prototype website.
script.aculo.us (which is never capitalized, even at the beginning of a sentence) is an add-on to Prototype that's primarily focussed on the UI: Nifty effects, drag-and-drop, etc.
Please check out the script.aculo.us website.
An MIT-style license; details on the license page.
From the downloads page: http://prototypejs.org/download
It lists both the latest version and archives of earlier versions.
- Read the API Docs
- Devour the websites and blogs
- Kick back with a good book
- Go to conferences
- Delve into the source
Prototype is comprehensive, but not overwhelming; you can read the entire set of API docs in about an hour. That hour will repay you many, many times over. Reading the docs is the single best way to know what's in Prototype and how you can use it to make great dynamic web pages.
There are lots of places — like here! — that provide tutorials, tips, and sample code:
- Tutorials section at Prototypejs.org
For those who prefer to their information on paper:
- Practical Prototype and script.aculo.us by Andrew Dupont
- Prototype and script.aculo.us by Christophe Porteneuve
- Prototype and Scriptaculous in Action by Dave Crane, Bear Bibeault, and Tom Locke with a foreward by Thomas Fuchs
Keep an eye on the Prototype blog for announcements of conferences where you can meet other Prototypicals like yourself!
If you do a web search containing the word "prototype" and a few key words related to your question, the odds are pretty high you'll find an answer.
This FAQ has a list of common issues people run into (with answers, obviously!) below.
There's just oodles of information in our Google groups. The main end-user group is
Prototype & script.aculo.us. Please read the rest of this FAQ before posting, though, and in
particular check out these two FAQ entries below — otherwise, we may laugh at and mock you. (Okay, not really.)
The previous end-user group, Ruby on Rails: Spinoffs, still has more than 4,300 threads of goodness in its archives. It's well worth searching those!
The core team also has their own group. It's probably worth checking the archives of that group, but note that it's only for discussion of the core development of Prototype, not for end-user questions.
The Prototype IRC channel is full of people who know the ins and outs of Prototype and are eager to help. Join us in #prototype on irc.freenode.net!
- Where can I report bugs?
- How can I contribute to this FAQ?
- What versioning system is Prototype using?
- How do I download the source code?
Full details on the prototypejs.org Contribute page — and thank you in advance! The Core team and contributors are always on the lookout for bugs they can squash.
Click here to edit this page — it's that easy. The initial version was compiled by Juriy Zaytsev (kangax) and T.J. Crowder based on community and core team input, but it's up to the community — you — to keep it up to date and improve it.
Check out the prototypejs.org Contribute page page for details.
Are there ever! Check out the list on our extras page.
- How do I do XYZ with Prototype?
- I'm trying XYZ, but it's not working -- help!
- Something doesn't work as expected. What should I do?
- IE throws an error: "Object does not support this property or method". What happened?
- My Ajax.Request doesn't work!
- I'm getting "this.blah is not a function". What happened?
- Prototype breaks my "for..in" loops!
- My applications slows down when I use Event.observe on 1000+ cells in a table.
- How do I make Prototype work together with jQuery?
- Is it possible to extend elements by criteria other than tagName (e.g. by className or an attribute)?
- The script.aculo.us wiki is down. Help!
- Are there any offline resources for prototype?
- Where can I find a packed/minified/compressed version of prototype/scriptaculous?
There are lots of folks who are happy to help you figure out what's going on.
Here's a good approach to getting your answer quickly:
- Check the API docs and the API notes here (Prototype, script.aculo.us) to be sure you're using things correctly. It's easy to overlook a parameter, etc., there's no reason not to double-check.
- Search for an answer, someone else has probably had the same problem and already gotten an answer — instant help!
- If those don't work, create a pared-down, self-contained example of the problem. There are two reasons for doing this: Firstly, about 90% of the time, if you sit down and create a pared-down test case highlighting the problem, you figure out what's wrong yourself. Really. More instant help! Secondly, even if you don't find the answer yourself, you end up with a nice contained example other people can look at and help with. Here's a self-contained test page you can start with.
- Still no luck? Probably time to think about asking a question over in the Prototype & script.aculo.us discussion group. To maximize the odds of people reading your question and wanting to help:
- Mention the key parts of the problem in the subject — e.g., "Element.update problem", not "Help!".
- In the text, start with a brief description of the problem, e.g. "I'm calling Element.update, but the element isn't being updated."
- Tell us what versions of Prototype and script.aculo.us (if relevant) you're using. (Don't say "the latest", it's a moving target.)
- Tell us what browsers you're seeing the problem on.
- Tell us what you've already tried to resolve the problem.
- Post your pared-down, self-contained example from Step 1 above, either directly in your message, or preferably via Pastie since Google Groups doesn't format code well.
- Re-read your post before you click Send. Please.
- Get the latest version of prototype.
- Make sure the document has a proper doctype and is valid: http://validator.w3.org.
- Consider these steps to narrow down the problem.
Prototype adds features to elements by "extending" them. Prototype can automatically extend elements on most browsers (by extending the element prototype), but on IE you have to extend each element instance individually. This can lead to code that works properly on other browsers lke Firefox or Chrome, but fails on IE with the error above.
To make sure an element is extended, just pass it through the $ function. So for instance:
// Fails (on IE): var div; div = document.createElement('div'); div.identify(); // <== Fails on IE, because the instance is not extended // Works (on all): var div; div = $(document.createElement('div')); // <= Note the use of $ div.identify();
Note that nine times out of ten, you don't have to do this because you've gotten the element reference from Prototype in the first place, and Prototype automatically extends all references it gives you before giving them to you. So for instance, if you use $$ to search for elements matching a given CSS selector, you don't have to extend any of the elements in the array it gives you — Prototype's already done that. It's only when you retrieve (or create) an element directly, without going through Prototype, that you need to be sure to pass it through $ (or Element.extend) before using Prototype's extensions.
There's more information can be found on the Prototype website, although it's a bit dated.
You're probably trying to retrieve content from a different origin than your script. Browsers will disallow requests that don't follow the Same Origin Policy.
This is most likely an execution context problem. Iterators (which are used in Enumerable methods) and event handlers (used in Element.observe) are executed within global context. Changing the execution context is as easy as using Function.bind or less frequently Function.bindAsEventListener. Here are a couple of articles to get you going:
The for..in construct iterates over all properties of an object, not all elements in an array. It's a subtle difference, but a key one. Don't use for..in to iterate over arrays. Instead, consider using Enumerable.each (Enumerable is mixed into Array) or old-fashioned indexed access.
"Event delegation" could increase performance (and reduce memory usage) in many cases; some resources:
The easiest way is to use jQuery's noConflict mode: Using jQuery with Other Libraries
Is it possible to extend elements by criteria other than tagName (e.g. by className or an attribute)?
Not in the current implementation. The extension mechanism is already complex enough; adding support for this would most likely lead to unnecessary complexity.
The old wiki is being replaced by the new one: http://github.com/madrobby/scriptaculous/wikis. Big brownie points if you help out by porting the content over!
- PDF version of Prototype API documentation
- CHM version of Prototype API documentation
- Prototype.js 22.214.171.124 Cheat Sheet