Home Blog CV Projects Patterns Notes Book Colophon Search

Scriptaculous Pylons Helpers

14 Aug, 2007

I haven't tried to use the scriptaculous helpers much but since I'm writing a book on Pylons I thought I better give them a go.

Here are three URLs which might help you too:

The bottom line is that before you can really make use of the helpers you need to understand how scriptaculous works on its own first so I'd strongly recommend you don't touch the helpers until you have some basic examples working. Apart from anything else they seem to do strange things with Mako and escaping which means they probably won't work anyway!

If you do want to have a play you'll need to add the scripts themselves:

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

or if you want to use the helpers:

${ h.javascript_include_tag(builtins=True) }

Then you can write some code like this:

<select id="TopicSet-1.TopicID" name="TopicSet-1.TopicID" onchange="
new Ajax.Updater(
    'diseases-select',
    '/newstudy/disease_dropdown_fragment',
    {
        asynchronous:true,
        evalScripts:true,
        parameters:{'TopicSet-1.TopicID': $('TopicSet-1.TopicID').value},
    }
);
">
<option value="" selected="selected">Please select...</option>
<option value="1">Blood</option>
<option value="2">Cardiovascular</option>
<option value="3">Congenital Disorders</option>
</select>

In scriptaculous $ is shorthand for document.getElementByID so $('TopicSet-1.TopicID') returns the element with the ID TopicSet-1.TopicID. Notice that it is fine to have elements with a . in their id. This is really handy when it comes to using FormEncode where you might want nested data structures of fields.

The call to Ajax.Updater() does an AJAX request to a URL /newstudy/disease_dropdown_fragment which returns some HTML content which replaces the element with id diseases-select.

The controller action looks like this:

def disease_dropdown_fragment(self):
    set_dropdown_values(c.connection(), c, request)
    return render("/core/derived/disease_dropdown_fragment.mako")</code>

It just calls a function to get some values then returns the rendered HTML directly. This approach is much quicker and easier than trying to return a JSON data structure and assemble HTML client-side.

The AJAX updater itself is documented on the scriptaculous wiki.

You can also easily add visual effects. For example, to highlight the div we've just updated you can add this to the list of options (just before the asynchronous:true, would be fine):

onComplete:function(){ new Effect.Highlight('diseases-select');},

Remember you need the , at the end though. Here is some more information on visual effects.

That's just about it, there are other examples of scriptaculous around on the web but my advice is to not try to use the Pylons helpers until you are very confident using the JavaScript directly, otherwise you might get confused.