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
General
- What is this wiki?
- What is Prototype?
- What is script.aculo.us?
- Under which license is it released?
- How do I download it?
What is this wiki?
This is the unofficial Prototype & script.aculo.us wiki, please see the home or about pages for more, or this page for what we mean by "unofficial".
What is Prototype?
Prototype is a JavaScript Framework that aims to ease development of dynamic web applications.
Please check out the Prototype website.
What is script.aculo.us?
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.
Under which license is Prototype released?
An MIT-style license; details on the license page.
How do I download it?
From the downloads page: http://prototypejs.org/download
It lists both the latest version and archives of earlier versions.
How Can I Learn About Prototype?
- Read the API Docs
- Devour the websites and blogs
- Kick back with a good book
- Go to conferences
- Delve into the source
Read the API Docs
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.
Devour the websites and blogs
There are lots of places — like here! — that provide tutorials, tips, and sample code:
- Tutorials section at Prototypejs.org
- http://alternateidea.com/tags/prototype
- http://andrewdupont.net/categories/web/development/javascript/prototype
- http://tobielangel.com/tags/prototype
- http://mislav.caboo.se/js
- http://thinkweb2.com/projects/prototype
Kick back with a good book
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
Go to conferences
Keep an eye on the Prototype blog for announcements of conferences where you can meet other Prototypicals like yourself!
Delve into the source
We're all l33t JavaScript c0d3rz, right? So if you're not sure what a particular method does, grab the source (details on the "Contribute" page), and take a look!
How Can I Get Help?
With a web search
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.
From the "Common Questions and Answers" list below
This FAQ has a list of common issues people run into (with answers, obviously!) below.
On our Google groups
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.
On IRC
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!
How Can I Contribute to Prototype?
- 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?
Where can I report bugs?
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.
How can I contribute to this FAQ?
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.
What versioning system is Prototype using?
They recently transitioned to git, details on the prototypejs.org Contribute page.
How do I download the source code?
Check out the prototypejs.org Contribute page page for details.
Are There Any Add-Ons or Extensions?
Are there ever! Check out the list on our extras page.
Common Questions and Answers
- 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?
How do I do XYZ with Prototype?
If you're not sure how to approach a task, reading the docs is the best way to figure it out. If that doesn't work, though, some other ideas can be found here.
I'm trying XYZ, but it's not working — help!
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.
Something doesn't work as expected. What should I do?
- 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.
IE throws an error: "Object does not support this property or method". What happened?
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.
My Ajax.Request doesn't work!
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.
I'm getting "this.blah is not a function". What happened?
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:
Prototype breaks my "for..in" loops!
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.
More about poor, misunderstood JavaScript arrays here: Javascript associative arrays considered harmful
My applications slows down when I use Event.observe on 1000+ cells in a table.
"Event delegation" could increase performance (and reduce memory usage) in many cases; some resources:
- http://icant.co.uk/sandbox/eventdelegation
- http://cherny.com/webdev/70/javascript-event-delegation-and-event-hanlders
- http://mislav.caboo.se/js/handling-events-on-elements/
How do I make Prototype work together with jQuery?
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 script.aculo.us wiki is down. Help!
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!
Are there any offline resources for prototype?
Yup:
- PDF version of Prototype API documentation
- CHM version of Prototype API documentation
- Prototype.js 1.6.0.2 Cheat Sheet
Where can I find a packed/minified/compressed version of prototype/scriptaculous?
Right here: http://groups.google.com/group/prototype-core/files
(Scroll down for edit link, page controls)