Prototype JavaScript framework - Form.Element

enable

2006-12-09T16:55:00Z

enable(element) -> HTMLElement

Enables a previously disabled form control.

Example

See the interactive example in the Form.disable() method, which is basically it.

disable

2006-12-09T16:48:00Z

disable(element) -> HTMLElement

Disables a form control, effectively preventing its value to be changed until it is enabled again.

This method sets the native disabled property of an element to true. You can use this property to check the state of a control.

Example

See the interactive example in the Form.disable() method, which is basically it.

Notes

Disabled form controls are never serialized.

Never disable a form control as a security measure without having validation for it server-side. A user with minimal experience of JavaScript can enable these fields on your site easily using any browser. Instead, use disabling as a usability enhancement - with it you can indicate that a specific value should not be changed at the time being.

clear

2006-12-09T16:47:00Z

clear(element) -> HTMLElement

Clears the contents of a text input.

Example

This code sets up a text field in a way that it clears its contents the first time it receives focus:


$('some_field').onfocus = function() {
  // if already cleared, do nothing
  if (this._cleared) return

  // when this code is executed, "this" keyword will in fact be the field itself
  this.clear()
  this._cleared = true
}

getValue

2006-12-09T16:46:00Z

getValue(element) -> string | array

Returns the current value of a form control. A string is returned for most controls; only multiple select boxes return an array of values. The global shortcut for this method is $F().

How to reference form controls by their name

This method is consistent with other DOM extensions in that it requires an element ID as the string argument, not the name of the form control (as some might think). If you want to reference controls by their names, first find the control the regular JavaScript way and use the node itself instead of an ID as the argument.

For example, if you have an input named "company" in a form with an ID "contact":

var form = $('contact');
var input = form['company'];

Form.Element.getValue(input);

// but, the preferred call is:
$(input).getValue(); // we used the $() method so the node gets extended

// you can also use the shortcut
$F(input);

Note

An error is thrown ("element has no properties") if the element argument is an unknown ID.

serialize

2006-12-09T16:45:00Z

serialize(element) -> string

Creates an URL-encoded string representation of a form control in the name=value format.

The result of this method is a string suitable for Ajax requests. However, it serializes only a single element - if you need to serialize the whole form use Form.serialize() instead.

Notes

Serializing a disabled control or a one without a name will always result in an empty string.

If you simply need an element's value for reasons other than Ajax requests, use getValue() instead.

select

2006-12-09T16:44:00Z

select(element) -> HTMLElement

Selects the current text in a text input.

Example

Some search boxes are set up so that they auto-select their content when they receive focus.


$('searchbox').onfocus = function() {
  Form.Element.select(this)
  // You can also rely on the native method, but this will NOT return the element!
  this.select()
}

Focusing + selecting: use `activate`!

The activate method is a nifty way to both focus a form field and select its current text, all in one portable JavaScript call.

focus

2006-12-09T16:40:00Z

focus(element) -> HTMLElement

Gives keyboard focus to an element.

Example


Form.Element.focus('searchbox')
// Almost equivalent, but does NOT return the form element (uses the native focus() method):
$('searchbox').focus()

present

2006-12-09T12:04:00Z

present(element) -> boolean

Returns true if a text input has contents, false otherwise.

Example

This method is very handy in a generic form validation routine. Try to submit the following form first without filling out the information, then again after typing some text in the fields:

User Details

Please fill out the following fields:

<label for="username">Username</label> <input name="username" type="text" id="username" />

<label for="email">Email Address</label> <input name="email" type="text" id="email" />

all the fields.').style.color = 'red' } return false } </form>

Here is the complete JavaScript code for the above example:


$('example').onsubmit = function(){
  var valid, msg = $('msg')

  // are both fields present?
  valid = $(this.username).present() && $(this.email).present()

  if (valid) {
    // in real world we would return true here to allow the form to be submitted
    // return true
    msg.update('Passed validation!').style.color = 'green'
  } else {
    msg.update('Please fill out all the fields.').style.color = 'red'
  }
  return false
}

activate

2006-12-09T12:02:00Z

activate(element) -> HTMLElement

Gives focus to a form control and selects its contents if it is a text input.

This method is just a shortcut for focusing and selecting; therefore, these are equivalent (aside from the fact that the former one will not return the field) :


Form.Element.focus('myelement').select()
$('myelement').activate()

Guess which call is the nicest? ;)

Form.Element

2006-12-05T21:45:00Z

This is a collection of methods that assist in dealing with form controls. They provide ways to focus, serialize, disable/enable or extract current value from a specific control.

In Prototype, Form.Element is also aliased Field and all these methods are available directly on INPUT, SELECT and TEXTAREA elements that have been extended (see “How Prototype extends the DOM”). Therefore, these are equivalent:


Form.Element.activate('myfield')
Field.activate('myfield')
$('myfield').activate()

Naturally, you should always prefer the shortest form suitable in a situation. Most of these methods also return the element itself (as indicated by the return type) for chainability.

Prototype JavaScript framework - Form.Element

enable

Example

disable

Example

Notes

clear

Example

getValue

How to reference form controls by their name

Note

serialize

Notes

select

Example

Focusing + selecting: use activate!

focus

Example

present

Example

activate

Form.Element

Focusing + selecting: use `activate`!