| ASP.NET Validation Package |
| Documentation |
| FAQs |
| Demos |
| Try it or buy it |
| Search |
Featured On ...
and more ...
Validator Control
Full path
Declaration
Hierarchy
Click on the selected class to view any properties or methods that may be accessible through an instance of this class through inheritance.Overview
The Validation control is the primary user control for the ASP.NET Validation Package. It is responsible for validating all validation entries that it holds on the server side, as well as delivering client-side code to the client browser where possible.Normally this class would be subclassed by a validation summary user control, however, it can also be used by itself if there is a desire to separate the validation summary from the Validator control. If the validation summary is not inherited from the Validator control, the Validator control must still be added somewhere in the control hierarchy. You don't need to create a user control extending the Validator control to do this, simply add the Validator control as follows.
At the top of the ASP.NET control or page, register a tag prefix that points to the MadWidgets.Validation namespace:
Then add the control somewhere on the same page or control:
If the validation summary is extending the Validator control, simply register the tag prefix for the validation summary control, then add it to the page or control exactly as you would any other control.
By itself, the Validator control does not render any visible content, but it does send Javascript to the client, so it should be located on the page in a position where Javascript can be leagally placed, e.g. within the <head> element or anywhere within the body of the page.
Where a method requires an "object" as a parameter, the object may be either a server control representing a form field or the name of the form field (not the id). Where a radio button is passed in as the "object," the radio button's group is actually validated and not the radio button itself. This means that if you attempt to validate two radio buttons from the same set, you will actually be validating the same object. The validation value of a radio button list as well as any form item list is the value found in the "value" attribute of the element or elements selected.
Public properties
- this[int i]
- ClientSideCodeEnabled
- Count
- CrossPath
- DefaultHighlightElement
- DimCrossPath
- ErrorMessage
- ForceClientSideWhenEmpty
- GroupPosted
- HighlightClass
- InitialHighlightClass
- IsPostBack
- IsValid
- JavascriptPath
- SummaryTitle
- TickPath
- UseTicks
Public static properties
Public methods
- Add(ValidatorEntry ve)
- AddError(string sMessage)
- AddError(object o, string sMessage)
- GetEntriesForGroup(string sGroupName)
- GetEntriesForPostedGroup()
- RemoveAllEntries()
- RemoveEntriesContainingObject(object o)
- Validate()
- WasGroupPosted(string sName)
- WasGroupPostedForObject(object o)
Public static methods
- GetGroupForObject(object o)
- GetObjectId(object o)
- GetValidationValue(object o)
- RegisterGroupForButton(object o, string sGroupName)
- RegisterGroupForObject(object o, string sGroupName)
- StringToClientSide(string sText)
Public events
Public properties
this[int i]
Returns the ValidatorEntry object located at the specified zero-based index position.
ClientSideCodeEnabled
When set to false, client-side code will not be written to the page. Consequently the Validator control will support only server-side validation. When set to true (default), client-side code will be written to the page when the Validator control holds at least one ValidatorEntry object and when the client supports ECMAScript 1.2 or higher. Examples of clients that do not support ECMAScript 1.2 or higher are early web browsers, web crawlers and some non-visual browsers. Most modern browsers support ECMAScript 1.2.
ClientSideCodeEnabled returns true only when client-side code will be written to the page, regardless of the state that it might have been previously set to.
If this property is not set explicitly, it returns the value of the validatorClientSideEnabled set in the appSettings section of the web.config file when this property has been specified in the file. If this property has not been specified in the web.config file, it returns true.
Count
Returns the number of ValidatorEntry objects being held by the Validator control.
CrossPath
Gets and sets the server path to the cross image that appears in any textual fields that are being validated on the client. If this property is not set explicitly, it returns the value of the validatorCrossPath set in the appSettings section of the web.config file. The cross image is placed in the field as the user is typing and the field does not pass validation.
DefaultHighlightElement
Gets and sets the client-side highlight element signature supplied in the contructor.
The highlight element signature can be one of two things: a client-side element identifier (not a field name) or a pattern identifying an element in the parent tree of the first validated field.
The pattern takes the following form:
<tagName[elementProperty=propertyValue]> or <tagName>
Where tagName is the name of an HTML tag, elementProperty is the name of a property that can be found on the element identified by tagName and propertyValue is the string value of that property. Note that the property value in the pattern must not be surrounded with quotes.
Using the first element in the validation entry (e.g. the first object added to the ValidatorEntryMultiple instance), the client-side validation code navigates up the parent hierarchy until it finds an element whose property matches that of the pattern. This process is done once during the loading of the page and before any CSS classes are swapped. The element that is found during this process is marked as the highlight element. During validation failure and success, the HighlightClass and original class found on the element are swapped respectively.
If the pattern does not contain the elementProperty=propertyValue section, a match of the first element whose type matches tagName will occur.
If no match occurs, no error occurs. The validation code will simply not use a highlight element for that validation entry.
DimCrossPath
Gets and sets the server path to the dim cross image that appears in any textual fields that are being validated on the client. If this property is not set explicitly, it returns the value of the validatorDimCrossPath set in the appSettings section of the web.config file. The dim cross image appears after a couple of seconds of inactivity in the field in which the validation failed after the user finished typing and remains there until the field passes validation.
ErrorMessage
This property overrides the ErrorMessage get and set properties from the IValidator interface but are not used. Both get and set throw a NotSupportedException.
ForceClientSideWhenEmpty
Forces client-side code to be written to the page when there are no ValidatorEntry objects held by the Validator control. This property will not force client-side code to be written to a client that does not support ECMAScript 1.2 or higher.
GroupPosted
Returns the name of the validation group that was posted back to the server if validation groups are used. If validation groups are not used, null will be returned from this property after a postback. Null is always returned from this property if the form was not posted back.
HighlightClass
Gets and sets the CSS class that is used on the highlight element when a the object associated with the highlight element fails validation. If this property is not set explicitly, it returns the value of the validatorHighlightClass set in the appSettings section of the web.config file. This property requires client-side code to be delivered to the client for it to be useful.
InitialHighlightClass
Gets and sets the CSS class that is used on the highlight element immediately after page load when a the object associated with the highlight element fails validation. If this property is not set explicitly, it returns the value of the validatorInitialHighlightClass set in the appSettings section of the web.config file. This property requires client-side code to be delivered to the client for it to be useful.
This property is only used immediately after page load on the client. Once a user modifies a validated object (e.g. a form field) or if the submit button is pressed, the CSS class used for highlighting is the one specified in the HighlightClass property.
IsPostBack
Returns true if the current page was requested as a result of a form postback. The difference between this property and the property of the same name on the UserControl class is that this one works when the form that is being posted is not a server form.
IsValid
Overrides the IsValid property from the IValidator interface. This property returns true if, during the page validation phase, all ValidatorEntry objects are in a valid state (as determined by the IsValid property of the ValidatorEntry object). If validation groups are used, this property will return true if the ValidatorEntry objects associated with the group all evaluate to valid. The state of all other ValidatorEntry objects is ignored in this case.
If an attempt is made to set the state of this property, a NotSupportedException is thrown.
JavascriptPath
Gets and sets the server path to the javascript file "Validator.js," which is shipped with the ASP.NET Validation Package. If this property is not set explicitly, it returns the value of the validatorJavascriptPath set in the appSettings section of the web.config file. This property is required to be set before the page is rendered.
SummaryTitle
Gets and sets the title for the validation summary. If this property is not set explicitly, it returns the value of the validatorSummaryTitle set in the appSettings section of the web.config file. This property is required only if you are using the validation summary control shipped with the ASP.NET Validation Package.
TickPath
Gets and sets the server path to the tick image that appears in any textual fields that are being validated on the client. If this property is not set explicitly, it returns the value of the validatorTickPath set in the appSettings section of the web.config file. The tick image appears in the field as the user is typing if the field passes validation and remains there for a couple of seconds after the user has finished typing. It also appears if the user submits the form and the field passes validation.
UseTicks
Gets and sets a flag telling the Validator control whether ticks and crosses are desired on the client within textual validation form fields as users edit them. If this property is not set explicitly, it returns the value of the validatorUseTicks set in the appSettings section of the web.config file when this property has been specified in the file. If this property has not been specified in the web.config file, it returns true.
Public static properties
Current
Returns the current validator object, wherever it may have been placed within the control tree. This method will return null if a Validator control does not exist within the control tree.
Public methods
Add
Adds a ValidatorEntry object to the Validator control.
AddError
Adds an arbitrary error message to the Validator control. This can be done when an error occurs on the server and the error is not directly associated with any of the ValidationEntry objects held by the Validator control. The error message appears in the validation summary in the same way that a validation message would appear except that it carries no "show me" anchor to an object on the page after postback. A ValidatorEntryPreset object is used to hold the error message and this can be accessed through the property indexer for the Validator control.
AddError
Adds an arbitrary error message to the Validator control that is linked to a validated object on the client. This might need to be done if you have not created a subclass of ValidatorEntry in order to make a server-side validation, but have rather simply made the validation yourself after postback. The object that the error can be linked to can be any object that is visible within the form when the page is delivered back to the client. The error message appears in the validation summary in the same way that a validation message would appear and will have a "show me" anchor linked to the object to which it is linked. A ValidatorEntryPreset object is used to hold the error message and this can be accessed through the property indexer for the Validator control.
GetEntriesForGroup
Returns an IList containing all ValidatorEntry objects belonging to the validation group name supplied. If the validation group name is null, all ValidatorEntry objects being held by Validator control are returned. You should not remove entries from this list.
GetEntriesForPostedGroup
Returns an IList containing all ValidatorEntry objects belonging to the validation group that was posted back to the server. If the name of the validation group posted cannot be determined or if validation groups are not being used, all ValidatorEntry objects being held by Validator control are returned. You should not remove entries from this list.
RemoveAllEntries
Removes all ValidatorEntry objects from the Validator control.
RemoveEntriesContainingObject
Removes all ValidatorEntry objects that contain an object including any entries that have a child entry containing the object. The search is performed as deep as necessary within the collection of ValdatorEntry objects.
Validate
Forces the Validator control to validate all ValidationEntry objects. If this is called after a validation group postback (when GroupPosted != null), only those entries belonging to the group are validated. If a server form is present on the page within the control tree, Validate() will be called by the page during normal event processing.
WasGroupPosted
Returns true if the named validation group was posted back. For convenience, the validation group name associated with any given object can be obtained through the GetGroupForObject( . . . ) method.
WasGroupPostedForObject
Returns true if the group associated with the given object was posted back. The object need not necessarily be a form element or an object that is being validated. If a parent control of an object contains the attribute "validationGroup" for example, then the name of any sub elements of that parent will return the group name assigned to the attrribute. Alternatively, if the object has been explicitly registered as belonging to a validation group and that group was the one posted back, this method will return true.
Public static methods
GetGroupForObject
Returns the group associated with an object. The object need not necessarily be a form element or an object that is being validated. If a parent control of an object contains the attribute "validationGroup" for example, then the name of any sub elements of that parent will return the group name assigned to the attrribute. Alternatively, if an object has been explicitly registered as belonging to a group, that group name will be returned for the object.
GetObjectId
Returns the object id that is used on the client for client-side validation. In most cases this is the name of the field (not the id). Note when retrieving the object id of a radio button list item, the id returned will be the group name of the list. This is true for select lists as well. Checkbox lists are currently not supported, although they can be upon request. The object passed into this method must be a server control or the name of a form field.
GetValidationValue
Returns the value of the object after a post. This is essentially equivalent to Request.Form[GetObjectId(o)]. Note that multiple select lists may return a comma separated list of values associated with the field where more than one item has been selected prior to posting.
RegisterGroupForButton
Registers a form button as belonging to a specific group when the validation groups are being used. This must be done for non-server forms and can optionally be done for server forms. When server forms are being used and the form's submit button(s) is a sub element of a control that possesses the attribute "validationGroup," then the value of this attribute will be used as the group name for the button by default. Registering the group name for the button overrides this automatic behaviour.
RegisterGroupForObject
Registers an object as belonging to a specific group when the validation groups are being used. This must be done for non-server forms and can optionally be done for server forms. When server forms are being used and the object is a sub control of a control that possesses the attribute "validationGroup," then the value of this attribute will be used as the group name for the sub control by default. Registering the group name for the sub control overrides this automatic behaviour.
StringToClientSide
Returns the input string converted to a client-side Javascript string for input into a client-side Javascript. This is a help method only used primarily internal to the Validator control.
Public events
PostValidate
Occurs just after to the Validator control has finished validating. Assign a ValidatorEventHandler delegate to the event whenever an action needs to be performed immediately after validation and before any other event occurs.
PreValidate
Occurs just prior to the Validator control validating. Assign a ValidatorEventHandler delegate to the event whenever an action needs to be performed prior to validation but after Page_Load.
© 2002 - 2009 Copyright, Disclaimer and Privacy Statement