Recipe 11.15 Alerting Users to Validation Errors

11.15.1 Problem

You want to alert the user when there is a validation error in the form data.

11.15.2 Solution

Use a message box.

11.15.3 Discussion

The MessageBox component is the perfect way to alert users when there is a form validation error. The MessageBox component can be found in Flash UI Components Set 2, which is available for free from the Macromedia Flash Exchange (http://www.macromedia.com/exchange/flash). You can add a message box programmatically using attachMovie( ), as you can with any other component. You only need to make sure that the component symbol is included in the Flash document's Library, as described in Recipe 11.1. The linkage identifier for the symbol is FMessageBoxSymbol.

this.attachMovie("FMessageBoxSymbol", "myMessageBox", 1);

Normally, you don't want a message box to be visible when the movie starts. Instead, you want to make the message box visible only if and when there is something about which to alert the user. Therefore, you should initialize a message box by setting its _visible property to false. You can do this either after attaching the movie clip or during the attachMovie( ) invocation by using an initialization object, as follows:

this.attachMovie("FMessageBoxSymbol", "myMessageBox", 1, {_visible: false});

Additionally, when you attach a message box programmatically, you must specify the buttons to include in the message box using the setButtons( ) method. The method expects an array of labels for the buttons. Typically, a message box has only one button—an OK button.

myMessageBox.setButtons(["OK"]);

You can programmatically set the message that the user sees with the setMessage( ) method:

myMessageBox.setMessage("Hello, friend.");

The following is an example of a message box used in conjunction with form validation. To test this code, you need to add both the PushButton and MessageBox component symbols to the movie's Library. You also need to make sure that your Form.as file includes all the necessary functionality. If in doubt, download the completed Form.as file from http://www.person13.com/ascb.

#include "Form.as"

// Create a text field and a push button.
_root.createTextField("email_txt", 1, 100, 130, 100, 20);
_root.attachMovie("FPushButtonSymbol", "btn_pb", 2, {_x: 100, _y: 160});

// Create the message box. Initialize it with _visible set to false. 
// Also, create an OK button.
_root.attachMovie("FMessageBoxSymbol", "messageBox", 3, 
                    {_x: 200, y: 200, _visible: false});
messageBox.setButtons(["OK"]);

// Set the text field so that it has a border and allows input.
email_txt.border = true;
email_txt.type   = "input";

// Create the form.
myForm = new Form(  );

// email_txt must have a valid email format.
myForm.addElement(email_txt);
myForm.setValidator("email_txt", "email");

btn_pb.onRelease = function (  ) {

  // Call the validate(  ) method of the form.
  var valid = _root.myForm.validate(  );

  // If the form validates, submit it. Otherwise, display the name of the problematic
  // form element in the message box.
  if (valid) {
    // Submit form.
  } else {
    _root.messageBox.setMessage("You must fill out a valid entry for " + valid);
    _root.messageBox._visible = true;

  }
};

11.15.4 See Also

Recipe 11.14