FAQ

TBD: Need to coordinate this with the Troubleshooting page, minimize redundancy
TBD: This is very Prototype-heavy, very little script.aculo.us content

General

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

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:

Kick back with a good book

For those who prefer to their information on paper:

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?

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?

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:

  1. 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.
  2. Search for an answer, someone else has probably had the same problem and already gotten an answer — instant help!
  3. 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.
  4. 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:
    1. Mention the key parts of the problem in the subject — e.g., "Element.update problem", not "Help!".
    2. 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."
    3. 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.)
    4. Tell us what browsers you're seeing the problem on.
    5. Tell us what you've already tried to resolve the problem.
    6. 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.
    7. 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:

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:

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)


Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License