Prototype is a great JavaScript library that extends the possibilities of the client scripting language, adds the missing functions you've always dreamed of, and offers new mechanisms to manipulate the DOM. The project website is http://prototypejs.org/.
The Prototype files are bundled with the symfony framework and accessible in every new symfony project, in web/sf/prototype/. This means that you can use Prototype by adding the following code to your action:
$prototypeDir = sfConfig::get('sf_prototype_web_dir');
$this->getResponse()->addJavascript($prototypeDir.'/js/prototype');or by adding it in the view.yml file:
all:
javascripts: [%SF_PROTOTYPE_WEB_DIR%/js/prototype]Note Since the symfony Ajax helpers, described in the next section, rely on Prototype, the Prototype library is already included automatically as soon as you use one of them. It means that you won't need to manually add the Prototype JavaScript to your response if your template calls a _remote helper.
Once the Prototype library is loaded, you can take advantage of all the new functions it adds to the JavaScript core. This book's purpose is not to describe them all, but you will easily find good documentation about Prototype on the Web, including at the following websites:
- Particletree: http://particletree.com/features/quick-guide-to-prototype/
- Sergio Pereira: http://www.sergiopereira.com/articles/prototype.js.html
- Script.aculo.us: http://wiki.script.aculo.us/scriptaculous/show/Prototype
One of the functions Prototype adds to JavaScript is the dollar function, $(). Basically, this function is a simple shortcut to document.getElementById(), but a little more powerful. See Listing 11-7 for an example of its use.
Listing 11-7 - Using the $() Function to Get an Element by ID in JavaScript
node = $('elementID');
// Means the same as
node = document.getElementById('elementID');
// It can also retrieve more than one element at a time
// And in this case the result is an array of DOM elements
nodes = $('firstDiv', 'secondDiv');Prototype also provides a function that the JavaScript core really lacks, which returns an array of all the DOM elements that have the class passed as argument:
nodes = document.getElementByClassName('myclass');However, you will seldom use it, because Prototype provides an even more powerful function called double dollar, $$(). This function returns an array of DOM elements based on a CSS selector. So the previous call can also be written as follows:
nodes = $$('.myclass');Thanks to the power of CSS selectors, you can parse the DOM by class, ID, and parent-child and previous-next relationships even more easily than you would with an XPath expression. You can even access elements with a complex selector combining all these:
nodes = $$('body div#main ul li.last img > span.legend');One last example of the syntax enhancements provided by Prototype is the each array iterator. It provides the same concision as in PHP, added to the ability to define anonymous functions and closures in JavaScript. You will probably use it a lot if you code JavaScript by hand.
var vegetables = ['Carrots', 'Lettuce', 'Garlic'];
vegetables.each(function(food) { alert('I love ' + food); });Because programming in JavaScript with Prototype is much more fun than doing it by hand, and because it is also part of symfony, you should really spend a few minutes to read the related documentation.