AS3 Form – Basic use
With this tutorial, you will be able to understand the basic philosophy of AS3 Form and first practical use case :
- Form creation
- Error definition
- Graphic linkage
- Sensors system
- Optional fields
- Specific fields : Email / Password
- Form condition : MatchCondition
- notSent fields
- Form validation
- Error display
- Values collection
Here's the result we want to have :
( hey it's a flash ! You can interact ! )
First of all, here's our general class template :
{
[Embed(source='assets/formdemo.swf', symbol='formSample1')]
private static const FORM_VIEW : Class ;
private var view : Sprite ;
private var form : Form ;
public function BasicSample()
{
buildView() ;
buildForm() ;
}
/**
* Add the form view to the scene.
* The view is designed in Flash IDE and not generated by the API
*/
private function buildView():void
{
view = new FORM_VIEW() ;
view.x = view.y = 10 ;
addChild(view) ;
}
/**
* Form construction
*/
private function buildForm():void
{
// let's link the OK button :
SimpleButton(view.getChildByName("btnOk")).addEventListener(MouseEvent.CLICK, validateForm ) ;
}
/**
* Form validation
*/
private function validateForm(e:MouseEvent):void
{
}
}
We simply Embed the view and link the OK button to validation function. Nothing special there...
Let's write the buildForm method content :
First, we create the form :
Then we set error messages that will be dispatched by the form :
form.messager.add("email_invalid", "Your email is invalid") ;
form.messager.add("password_too_small", "Your password is too small") ;
form.messager.add("password_empty", "Your password is empty") ;
form.messager.add("password_confirm_empty", "You must confirm your password") ;
form.messager.add("password_confirm_too_small", "Your password confirm is too small") ;
form.messager.add("password_confirm_invalid", "Password and confirmation does not match") ;
Errors can also be defined by passing an single XML Object :
Now we can define our first field : Name.
The name is an optional standard input field so the declaration is this one :
form.getField("name").optional = true ;
view["tfName"] is our reference to TextField we want.
The label field is written directly inside the input. We can do it this way :
Email field is a little bit more complex. We will use EmailField type ( EmailField extends InputField ).
It's not optional, so error messages must be defined.
Each field has 3 default error message : empty, too small or too large.
They can be defined this way :
field.setMinSizeError("min_error") ;
field.setMaxSizeError("max_error") ;
//or just
field.setErrors("min_error", "max_error", "empty_error") ;
Specific fields can have specific errors for example, our email field declaration is :
InputField(form.getField("email")).setDefaultLabel("Type your email*...") ;
// errors
form.getField("email").setEmptyError("email_empty") ;
EmailField(form.getField("email")).setInvalidMailError("email_invalid") ;
We want to turn red TextField's color on error, so we define a sensor for the email field :
Included default sensors are BitmapFilter sensor, MovieClip sensor and TextField color sensor, but you can easily write your own extending AbstractSensor
PasswordField is another specific type :
form.addField( new PasswordField( view["tfPassword"], 6), "password") ;
form.getField("password").setEmptyError("password_empty") ;
form.getField("password").setMinSizeError("password_too_small") ;
InputField(form.getField("password")).setDefaultLabel("Type your password*...") ;
form.getField("password").addSensor( new TextFieldColorSensor( view["tfPassword"] , 0xFF0000 ) ) ;
// password confirmation is just another password field
form.addField( new PasswordField( view["tfPasswordConfirm"], 6), "confirm") ;
form.getField("confirm").setEmptyError("password_confirm_empty") ;
form.getField("confirm").setMinSizeError("password_confirm_too_small") ;
InputField(form.getField("confirm")).setDefaultLabel("Confirm your password*...") ;
form.getField("confirm").addSensor( new TextFieldColorSensor( view["tfPasswordConfirm"] , 0xFF0000 ) ) ;
We don't need to export the password confirm value, so we write :
AS3 Form can handle extra form validation conditions
In this case we want matching passwords :
Conditions can also have sensors :
form.getCondition("match").addSensor( new TextFieldColorSensor( view["tfPasswordConfirm"] , 0xFF0000 ) ) ;
At least, we empty and reset form labels :
Form declaration is now ready . It was a bit long, but it will save a lot of time on validation process.
Forms are boring, and will always be... so as an intermission here's a funny lolcat.
Stop laughing, take a breath, and now we're ready for the validation process !
Let's fill the validateForm function :
To validate the whole form and get the error, here's what you must write :
On this call, every field and condition will be checked. Sensors will react on errors and an Array containing all of the errors will be returned.
You can specify how many errors you wan't to handle on each validation this way :
From then, error and values collection is piece of cake :
(the cake is a lie, the cake is a lie, the cake is a lie...)
To get a returned error, just extract it from the array and write the content where you want :
view["tfError"].text = error.message ;
To collect the values if no errors, simply write :
or
Here's the whole block :
{
// validate the form values. The param tells how many errors you want on a validate ( 0 for all errors )
var errors : Array = form.validate(1) ;
// no errors, form is ok
if ( errors.length == 0 )
{
// get form values :
// if includeEmpty param is set to true, optional fields left blank will also be writen to the object
var values: Object = form.values() ;
// write result into error field
view["tfError"].text = "Values OK :" ;
for ( var i : String in values )
{
view["tfError"].appendText( "\n" + i + " : " + values[i] ) ;
}
}
else
{
// get the first returned error
var error : FieldError = errors[0] ;
// show the message in the error field :
view["tfError"].text = error.message ;
}
}
That was quite easy.
You can find the whole source code here :
http://code.google.com/p/as3form/source/browse/#svn%2Ftrunk%2Fsrc%2Fnet%2Fbabeuf%2Fform%2Fsamples
In the next tutorial, I will talk about other form fields types such as combos, checkboxes and radio buttons.
Thanks for reading !