WebPropertyGrid supports client-side validation for its property values.
This allows you to add custom logic to examine the values entered by the user, and perform some action before sending the data to the server.
This ability makes your web application more responsive, and takes unnecessary load off your web server.
To support this feature, WebPropertyGrid uses the following client-side method:
function cwpgOnValueChange(controlId, propertyName, propertyValue)
This is a callback method that needs to be implemented by you.
WebPropertyGrid will automatically detect the presence of this method, and call it whenever a user modifies a property value.
The parameters are:
- controlId - the control identifier of the WebPropertyGrid instance.
- propertyName - the full path name to the property being changed.
- propertyValue - the new value for the property being changed.
If the new property value is acceptable, return
null and WebPropertyGrid will perform no additional action.
If the value is unacceptable, return a
string that contains the error message you wish to display to the user.
WebPropertyGrid keeps track of all the error strings returned from this callback method, and exposes the following method to obtain the number of properties that have errors for the WebPropertyGrid control specified by the
controlId parameter:
function cwpgGetValidationErrorCount(controlId)
In this sample, a CustomValidator uses this method to cancel the form submission and display a warning message to the user until they correct the errors for some simple JavaScript data type properties.
The validation logic used in your application is up to you.
Another method exposed by WebPropertyGrid that is not necessary used only for client-side validation is:
function cwpgSetFocus(controlId, beginEdit)
This allows you to programmatically set the keyboard focus to a specific WebPropertyGrid control specified by the
controlId parameter, and optionally begin a new property edit operation by setting the boolean
beginEdit parameter to
true.
In this sample, this method is called whenever a submission is canceled, allowing the user to have keyboard focus set to the control with the errors.
When a successful submission occurs, the property values written to the server are displayed below:
Pressing the "Reset" button restores the property to their original values.