Validation

Requires Platform 4.5+

Validating Client Input Data

In Nexaweb 4.5, you can declaratively create logic to validate data that users input to fields on the client user interface.

Nexaweb 4.5 provides this functionality through the validator plug-in framework through the com.nexaweb.plugin.validation.validators.Validator class.

The validator plug-in framework provides the following validator tags, in addition to the ability for you to extend the Validator class by creating your own tags: 

In addition to the supplied validators, you can also create:

 Using Validators

This section provides an overview of how to use validators in your client application's UI.

Using validators requires the following major steps:

• Declare validator
• Define element to validate
• Create and specify the onSuccess MCO to run
• Create and specify the onFailure MCO to run
• Invoke validator on event in UI File 

Declaring Validators

You declare validators outside the rootpane of a UI file using the following basic structure:

<validator:stringLengthValidator xmlns="http://nexaweb.com/validator"
  id="passwordValidator" value="password.text"
  onSuccess="mco://myMco.validPassword()"
  onFailure="mco://myMco.invalidPassword()" />

Note: See Supplied Validators for a complete list of all attributes available for each validator.
 

Define Element to Validate

As validators provide a means for your UI to validate user input, you primarily invoke validators on textField or passwordField elements.

To define elements to validate, you must specify the following attributes for the element to validate:

For example:

<textField id="startDate" text="" /> 

In addition to specifying these textField element attributes, you can also specify in your textField element tag the textField event on which to invoke the validator. See the section in this document on Invoking Validators.

To complete the element definition, you must identify this textField in the value attribute of the declaration of the validator you want to invoke. See the Declaring Validators section of this document. 

Create and Specify the onSuccess and onFailure Events to Run

If you wish to display a message or some feedback to the user to reflect the success or failure of the validation of an element, you must peform the following major steps:

• Create an MCO or Macro to handle this event
• Declare the MCO or Marco in the UI file that includes the validator
• Invoke the MCO or Marco from the validator's onSuccess and/or onFailure attributes

For example:

<mco:declarations xmlns:mco="http://nexaweb.com/mco">
    <mco:mco id="loginMco" src="mcos.LoginMco"
  </mco:declarations>
  <nxml xmlns:validator="http://nexaweb.com/validator">
    <validator:requiredFieldValidator id="usernameValidator" 
     value="username.text" onSuccess="" 
     onFailure="macro://failureMacro.execute('Username required')" />
    <validator:requiredFieldValidator id="passwordValidator" 
     value="password.text" onSuccess="mco://loginMco.enableLogInButton()" 
     onFailure="macro://failureMacro.execute('Password required')" />
  </nxml>
  <dialog id="loginDialog" title="Login" modal="true" closable="false">
    <flowLayout />
    <label text="Username:" />
    <textField id="username" text="" focused="true" 
     onTextChange="validator://usernameValidator.execute()" />
    <label text="Password:" />
    <passwordField id="password" text="" 
     onTextChange="validator://passwordValidator.execute()" />
    <button text="Log In" enabled="false" onCommand="mco://loginMco.login()" />
  </dialog> 

Invoking Validator on Event in UI File

To invoke a validator, specify the following command as the value of an element event handler:

"validator://usernameValidator.execute()" 

where usernameValidator specifies the name of the defined validator tag to invoke.

You can invoke a validator on any valid event handler for the textField or passwordField elements.

For example:

<dialog>
  <textField id="username" text="" />
  <passwordField id="password" text="" />
  <button text="Login" onCommand="validator://loginValidator.execute()"/>
</dialog> 

Putting It All Together

The following annotated example shows the use of a validator in a UI file. 

 <!-- 1 --> 
<mco:declarations xmlns:mco="http://nexaweb.com/mco">
  <mco:mco id="loginMco" src="mcos.LoginMco">
</mco:declarations>

<!-- 2 --> 
<nxml xmlns:validator="http://nexaweb.com/validator">
  <validator:requiredFieldValidator <!-- 3--> id="usernameValidator" 
<!-- 4--> value="username.text" onSuccess=""
<!-- 5 --> onFailure="macro://failureMacro.execute('Username required')"/>
  validator:requiredFieldValidator id="passwordValidator" 
  value="password.text" onSuccess="mco://loginMco.enableLogInButton()" 
  onFailure="macro://failureMacro.execute('Password required')" />
</nxml>

<dialog id="loginDialog" title="Login" modal="true" closable="false">
  <flowLayout />
  <label text="Username:" />
  <textField <!-- 6-->id="username" text="" focused="true" 
<!-- 7 --> onTextChange="validator://usernameValidator.execute()" />
  <label text="Password:" />
  <passwordField id="password" text="" onTextChange="validator://passwordValidator.execute()" />
  <button text="Log In" enabled="false" onCommand="mco://loginMco.login()" />
</dialog>