Working With Forms

Appcelerator provides several capabilities that facilitate the creation of HTML forms. To help demonstrate these capabilities, we will use a simple login form example.

<div>Username:</div>
<input type="text" id="username" fieldset="my_form" validator="required"
	decorator="required"/>
 
<div>City:</div>
<input type="text" id="city" fieldset="my_form" validator="required"
	decorator="custom" decoratorId="city_decorator"/>
<span id="city_decorator">You must enter a valid city!</span>
 
<div>Sign:</div>
<input type="text" id="sign" fieldset="my_form" validator="my_custom_sign"
	decorator="my_custom_sign"/>
 
<div>
   <input type="button" fieldset="my_form" activators="username,city,sign"
		on="click then r:save.data.request"/>
</div>

The following sections will describe each of the attributes used in the above example.

The fieldset attribute is used to link INPUT elements (or divs, spans, etc.) for the purpose of sending a message. In the example above, all of the INPUT elements are linked via the “my_form” fieldset. When a message is produced by an element within the fieldset (e.g., a button click that generates a message), Appcelerator will include the values of all fieldset members in the message payload.

Fieldsets can also be used to bind INPUT elements (or divs, spans, etc.) to an incoming message. This means one can use a single message to set the value of multiple elements at once. For example:

<script>
$MQ("l:load", {person: {first_name: 'Joe', last_name: 'Smith'}});
</script>
<div fieldset="user_info" on="l:load then bind[person]">
    <input fieldset="user_info" name="first_name" />
    <input fieldset="user_info" name="last_name" />
</div>

Validators validate user input and decorators handle the display of error messages or visual cues when a field is invalid. Appcelerator comes with several pre-built validators and decorators, and you can build your own using our Javascript API.

In addition to creating your own decorator via Javascript, you also create a simple custom decorator using the following syntax:

<input type="text" id="city" fieldset="my_form" validator="required"
	decorator="custom" decoratorId="city_decorator"/>
	<span id="city_decorator">You must enter a valid city!</span>

In the example above, we use decorator=“custom” and decoratorId=“city_decorator”. This tells Appcelerator to look for an element with the ID of “city_decorator” and use it as the custom decorator for the field. Appcelerator automatically takes care of the hiding/showing of the custom decorator element.

As mentioned earlier, you can also create fully custom validators and decorators using our Javascript API. Below are examples of each using our form example above (i.e. we are implementing the “my_custom_sign” decorator and validator).

App.Validator.addValidator("my_custom_sign", function(value)
{
	if (value != "scorpio")
		return false;
	else
		return true;
});
 
App.Decorator.addDecorator("my_custom_sign", function(element, valid, decId)
{
	// call helper method that will do formatting for us
	App.Decorator.checkInvalid(element, valid, decId, "only scorpio is valid pal");
});

On the decorator side, you can also display a visual cue (e.g., set the border color to red). Here’s a simple example using a pre-defined CSS class that defines the red border.

App.Decorator.addDecorator("my_custom_sign", function(element, valid, decId)
{
	if (!valid)
	{
		Element.addClassName(element,"error");
	}
	else
	{
		Element.removeClassName(element,"error");
	}
});

Finally, here’s a list of our pre-built validators and decorators:

Activators work in conjunction with validators to control the state of a button. You can add the activators attribute to HTML INPUT buttons. The attribute should contain a comma-delimited list of INPUT element ids that must be valid before the button will be enabled. Each INPUT element defined in an activator list must have a validator defined.

One can prevent a form from submitting by adding the following attribute to a form tag: disablesubmit=“true”.

It is also possible to use the value action on a form to get an effect similar to using bind, as described above. For Example:

<form on="l:set.info then value[person]" disablesubmit="true">
	<input name="first_name" />
	<input name="last_name" />
</form>
<script>
	$MQ('l:set.info', {person:{first_name:'Joe',last_name:'Smith'}});
<script>