When you perform server-side validations with ValidateThis the framework will return a Result object to you. You can use this Result object to provide you with a lot of information about reasons for a validation failure. This page describes many of the methods available in the Result object which return information about what happened during a server-side validation.
The following methods can be called to return information about what happened during a server-side validation.
The getIsSuccess() method will tell you whether the validations passed or not.
None.
The getIsSuccess() method returns a boolean, which will be true if the validations passed and false if the validations failed.
<cfset result = application.ValidateThis.validate(myObject) /> <cfif result.getIsSuccess()> <--- do stuff that happens when the validations pass here ---> <cfelse> <--- do stuff that happens when the validations fail here ---> </cfif>
The getFailures() method will return all of the metadata available about every failure that occurred during a server-side validation. This can be useful when you want to do some additional processing using this metadata. There are other methods in the Result object, described below, which can deliver pre-processed information, ready for output.
It accepts the following arguments:
The getFailures() method returns an array of structures, with each structure containing information about a single validation failure. The keys available in the structure include:
Note that you will likely only use the first three of these keys. The last two (objectType and theObject) are generally only used when looking at failures that involved the use of the isValidObject validation type with a complex graph of objects.
<cfset result = application.ValidateThis.validate(myObject) /> <cfset allFailures = result.getFailures() /> <cfloop array="#allFailures#" index="failure"> <--- do something with an individual failure here ---> </cfloop>
The getFailureMessages() method will return all of the failure messages that were generated during a server-side validation. This can be useful when you simply want to output all of the messages in a single block.
It accepts the following arguments:
The getFailureMessages() method returns an array of strings, with each string being a single failure message.
<cfset result = application.ValidateThis.validate(myObject) /> <cfset allFailureMessages = result.getFailureMessages() /> <cfoutput> <ul> <cfloop array="#allFailureMessages#" index="failure"> <li>#failure#</li> </cfloop> </ul> </cfoutput>
This would output an unordered list of all of the failure messages that were generated during a server-side validation.
The getFailuresAsString() method will return all of the failure messages that were generated during a server-side validation as a single string. This is similar to the getFailureMessages() method described above but instead of an array of messages you get a single string with each message delimited by a delimiter (which defaults to an html
tag).
It accepts the following arguments:
The getFailuresAsString() method returns a single string, consisting of all failure messages appended using the delimiter.
<cfset result = application.ValidateThis.validate(myObject) /> <cfset allFailureMessages = result.getFailuresAsString() /> <cfoutput>#allFailureMessages#</cfoutput>
This would output all of the failure messages, with a line break between each one.
The getFailuresByField() method will return all of the metadata available about every failure that occurred during a server-side validation, in a structure with one key per clientFieldname. This can be useful when you want to do some additional processing for each field of your form (e.g., output the failures for a given field beside that field).
It accepts the following arguments:
The getFailuresByField() method returns a structure of arrays of structures, with the key to each item in the outer structure being a clientFieldname, with each item containing an array identical to the array described for the getFailures() method above.
<cfset result = application.ValidateThis.validate(myObject) /> <cfset fieldFailures = result.getFailuresByField() /> <cfloop array="#fieldFailures['userName']#" index="failure"> <--- do something with an individual failure here ---> </cfloop>
This would allow you to do something with all of the failures for the userName field.
The getFailureMessagesByField() method will return the failure messages generated during a server-side validation, in a structure with one key per clientFieldname. This can be useful when you want to do something with the messages for each field of your form (e.g., output the messages for a given field beside that field).
It accepts the following arguments:
The getFailureMessagesByField() method returns a structure with one key per clientFieldname. Each item in the structure will either be an array of failure messages, or a string in which each failure message has been concatenated using the specified delimiter.
<cfset result = application.ValidateThis.validate(myObject) /> <cfset fieldMessages = result.getFailureMessagesByField(delimiter="<br />") /> <cfoutput>#fieldMessages['userName']#</cfoutput>
This would output all of the failure messages generated for the userName field, with a line break between each one.
The getFailuresByProperty() method behaves exactly the same as the getFailuresByField() method, except the they keys in the structure use the propertyName instead of the clientFieldname. It is not likely that you will need to use this when generating output on an html page, but it could be useful if you are using the Result object for further processing within your model.
Please see the getFailuresByField() method for more information.
The getFailureMessagesByProperty() method behaves exactly the same as the getFailureMessagesByField() method, except the they keys in the structure use the propertyName instead of the clientFieldname. It is not likely that you will need to use this when generating output on an html page, but it could be useful if you are using the Result object for further processing within your model.
Please see the getFailureMessagesByField() method for more information.
The following methods exist in the Result object to make integration with other frameworks easier.
The getFailuresForUniForm() method returns a structure of failure messages in a format that can be sent directly to the cfUniform form tag. This makes integration with cfUniform a snap. It is actually equivalent to calling getFailureMessagesByField() and specifying
as the delimiter, but it's nice to have a shortcut.
The following methods exist in the Result object to provide an interface that is equivalent to the ModelGlue.util.ValidationErrorCollection object:
During your validation processing you can manually add failures to the Result object, as well as add failures from one Result object to another Result object.
Use the addFailure() method to manually add a failure to a result.
It accepts the following arguments:
Void
<cfset theFailure = {propertyName="userName",clientFieldname="userName",message="That's not a good user name."} /> <cfset result.addFailure(theFailure) />
This would add a failure to the Result object stored in the result variable with a message of That's not a good user name. that corresponds to the property/fieldname of userName.
Use the addResult() method to add the failures from another Result object into the current Result object.
It accepts the following arguments:
Void
<cfset result.addResult(anotherResult) />
This would take all of the failures in the anotherResult object and add them to the Result object stored in the result variable.
During development you can use the getDebugging() method of the the result object to see which rules / conditions have been evaluated by the BOValidator and whether they passed or failed. By default, debugging is disabled.
Use the getDebugging() method to view information about which rules and conditions have been evaluated.
none
The getDebugging() method returns an array of structs. For development use only, the data structure is subject to change.
<cfset result = application.ValidateThis.validate(theObject=myObject, debuggingMode="info") /> <cfdump var="#result.getDebugging()#" />
You can also enable debugging globally using the "debuggingMode" key of the ValidateThisConfig struct. Note that the global settings can be overridden per validation call as shown above.
<cfset ValidateThisConfig = {debuggingMode="info"} /> <cfset application.ValidateThis = createObject("component","ValidateThis.ValidateThis").init(ValidateThisConfig) /> <cfset result = application.ValidateThis.validate(theObject=myObject) /> <cfdump var="#result.getDebugging()#" />
There are three possible modes for debugging;
Please note that the output from the getDebugging() method is for help during development and is subject to change. Please don't write code which depends on it.
The following methods have been deprecated. Please use the suggested alternatives.
Use the getFailuresByProperty() or getFailuresByField() method instead.