Sunday, November 20, 2005

Prototype.js : Form

This is the first post of many about the Prototype AJAX library. For me it fills the same void that commons-lang fills in Java, which is that it includes functions to perform the common tasks that you seem to do over and over again. In this post I will cover the Form object, and all of it's methods. This post, and all posts about the Prototype library will be broken down into two sections, a summary of the API followed by detailed descriptions and examples of each function.

API Summary

void Form.disable(form)
void Form.enable(form)
void Form.focusFirstElement(form)
HTMLElement[] Form.getElements(form)
HTMLInputElement[] Form.getInputs(form, typeName, name)
void Form.reset(form)
String Form.serialize(form)

API Details

Form.disable(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
Nothing.

Given a form ID or reference to a form element, will disable all fields, which will make them appear as greyed out.

Form.disable('theForm');
Form.disable(formRefVar);


Form.enable(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
Nothing.

Given a form ID or reference to a form element, will enable all fields.

Form.disable('theForm');
Form.disable(formRefVar);


Form.focusFirstElement(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
Nothing.

Places focus on the first field of the specified form. This is useful when, for example, you have a login page and you want to save the user an extra click by putting the focus on the username field so that the user can immediate start typing. This would typically be triggered in an initialization function triggered by a document onload event.

Form.focusFirstElement('theForm');
Form.focusFirstElement(formRefVar);


Form.getElements(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
An array of HTMLElement DOM objects.

Given a form ID or reference to a form element, will return a list of form field DOM obejcts. Note that there is no guarantee that the fields returned will be in the same order that they are on the page.

var fields = Form.getElements('theForm');
var fields2 = Form.getElements(formRefVar);


Form.getInputs(form, typeName, name)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.
typeName - Filter for specific input type, null or an empty string for any.
name - Filter for a specific input name attribute, null or an empty string for any.

Returns:
An array of HTMLInput DOM objects.

Given a form ID or reference to a form element, will return a list of HTMLElementInput obejcts. Note that it only returns elements that use the input tag, and will not return textarea or select fields. You can specify the input type and/or name as a filter. If both the type and name are specified, both need to match for a field to be returned.

var allInputs = Form.getInputs('theForm');
var checkboxes = Form.getInputs('theForm', 'checkbox');
var firstname = Form.getInputs('theForm', null, 'firstname');


Form.reset(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
Nothing.

Resets the form to it's initial values. This is the same as when a user clicks on an HTML reset button.

Form.serialize(form)

Params:
form - The ID attribute of the form tag, or a reference to the form DOM element.

Returns:
A URL encoded querystring.

Loops though all of the form controls and returns a querystring value based on the current control values. This is useful when you need to pass the form values to some page other then the target of the form, as you might do in an AJAX query.

// send the form values to somepage.jsp
var params = Form.serialize('theForm');
document.location = 'somepage.jsp?' + params;





This concludes the first installment of Prototype documentation. Please feel free to comment on this entry and suggest further information that should be added.

9 comments:

Anonymous said...

Very insightful. I had actually been trying to figure out how to grab the values from all of the checkbox inputs on a form using Prototype.

Nice job, what's next?

Robert Hanson said...

What's next? Well, it's hard to say. My blog postings tend to follow what I am doing/researching for work. The last few months have been quite hectic with 2 major site launches, so my postings have slowed to a crawl. I am working on getting back into it, and hopefully back to 3+ postings per week.

But I seem to have avoided the question. Currently I am working on rebuilding a tool that we have been using in-house for many years, hopefully to allow for public access. It is all about Java, Spring, Hibernate(?), and Velocity(?) on the back end. On the front end I am planning on having a very rich user interface using Scriptaculous, Prototype, and maybe DWR. So I figure that entries for the next few months will will be about those topics, including why I didn't select other technologies like JSF.

Anonymous said...

Hey,

Can i use the Form.serialize for posting a html form. or is it just for GET alone.

regards
ashok

Robert Hanson said...

> Can i use the Form.serialize for
> posting a html form. or is it just
> for GET alone.

The serialize function just returns a string, from there it is up to you how you use it. By itself it doesn't do any POST'ing or GET'ing.

As far as passing that string to the server with JavaScript, as far as I know you will only be able to issue a GET. I could be wrong though since I have never needed to POST programatically with JavaScript.

I have though had occasions where I needed to pre-process the form values before sending to the server via a POST. For that I use the onsubmit even handler for the form, which allows me to modify the data or even cancel the submit in the case of a failed validation check. I am throwing this out there just in case if this is what you are trying to do.

Anonymous said...

Hello,

I've been trying to sbmit a form with Form.serialize(form) as parameters. If I debug this with an alert looks fine, all fields are sent, but I can't catch the checkboxes. Seems like prototype renders only the LAST checkbox!

Do you have any ideas?
Thanks in advance, saludos desde Mexico amigo!

Robert Hanson said...

It has been quite a while since I have used Prototype on a regular basis, but I have some ideas.

I am guessing (perhaps wrongly), that you have multiple checkboxes with the same name. It this is the case, AND the alter'ed URL looks good, then it is likely to be on the server. Some server-side languages behave differently when you have multiple options with the same name.

In Java/JSP you need to call an alternate method, in Perl you need to use the CGI module and grab the params in list context.

Like I said, I might be wrong about your specific case, but if the alert'ed URL looks right, then it probably isn't a Prototype issue.

Anonymous said...

Hi, I am new to Prototype. How can I enable and disable a specific element in a form.

Robert Hanson said...

Hi Anonymous, you might want to check out the link below. It has quite a bit more information on using Prototype than you will find here.

http://www.sergiopereira.com/articles/prototype.js.html

In checking out that site, you should be able to use this:

Form.Element.Methods.disable('elementId')

Anonymous said...
This comment has been removed by a blog administrator.