/wheels/model/errors.cfm

  1<!--- PUBLIC MODEL OBJECT METHODS --->
  2
  3<cffunction name="addError" returntype="void" access="public" output="false" hint="Adds an error on a specific property."
  4	examples=
  5	'
  6		<!--- Add an error to the `email` property --->
  7		<cfset this.addError(property="email", message="Sorry, you are not allowed to use that email. Try again, please.")>
  8	'
  9	categories="model-object,errors" chapters="object-validation" functions="addErrorToBase,allErrors,clearErrors,errorCount,errorsOn,errorsOnBase,hasErrors">
 10	<cfargument name="property" type="string" required="true" hint="The name of the property you want to add an error on.">
 11	<cfargument name="message" type="string" required="true" hint="The error message (such as ""Please enter a correct name in the form field"" for example).">
 12	<cfargument name="name" type="string" required="false" default="" hint="A name to identify the error by (useful when you need to distinguish one error from another one set on the same object and you don't want to use the error message itself for that).">
 13	<cfscript>
 14		ArrayAppend(variables.wheels.instance.errors, arguments);
 15	</cfscript>
 16</cffunction>
 17
 18<cffunction name="addErrorToBase" returntype="void" access="public" output="false" hint="Adds an error on the object as a whole (not related to any specific property)."
 19	examples=
 20	'
 21		<!--- Add an error on the object --->
 22		<cfset this.addErrorToBase(message="Your email address must be the same as your domain name.")>
 23	'
 24	categories="model-object,errors" chapters="object-validation" functions="addError,allErrors,clearErrors,errorCount,errorsOn,errorsOnBase,hasErrors">
 25	<cfargument name="message" type="string" required="true" hint="See documentation for @addError.">
 26	<cfargument name="name" type="string" required="false" default="" hint="See documentation for @addError.">
 27	<cfscript>
 28		arguments.property = "";
 29		addError(argumentCollection=arguments);
 30	</cfscript>
 31</cffunction>
 32
 33<cffunction name="allErrors" returntype="array" access="public" output="false" hint="Returns an array of all the errors on the object."
 34	examples=
 35	'
 36		<!--- Get all the errors for the `user` object --->
 37		<cfset errorInfo = user.allErrors()>
 38	'
 39	categories="model-object,errors" chapters="object-validation" functions="addError,addErrorToBase,clearErrors,errorCount,errorsOn,errorsOnBase,hasErrors">
 40	<cfreturn variables.wheels.instance.errors>
 41</cffunction>
 42
 43<cffunction name="clearErrors" returntype="void" access="public" output="false" hint="Clears out all errors set on the object or only the ones set for a specific property or name."
 44	examples=
 45	'
 46		<!--- Clear all errors on the object as a whole --->
 47		<cfset this.clearErrors()>
 48		
 49		<!--- Clear all errors on `firstName` --->
 50		<cfset this.clearErrors("firstName")>
 51	'
 52	categories="model-object,errors" chapters="object-validation" functions="addError,addErrorToBase,allErrors,errorCount,errorsOn,errorsOnBase,hasErrors">
 53	<cfargument name="property" type="string" required="false" default="" hint="Specify a property name here if you want to clear all errors set on that property.">
 54	<cfargument name="name" type="string" required="false" default="" hint="Specify an error name here if you want to clear all errors set with that error name.">
 55	<cfscript>
 56		var loc = {};
 57		if (!Len(arguments.property) && !Len(arguments.name))
 58		{
 59			ArrayClear(variables.wheels.instance.errors);
 60		}
 61		else
 62		{
 63			loc.iEnd = ArrayLen(variables.wheels.instance.errors);
 64			for (loc.i=loc.iEnd; loc.i >= 1; loc.i--)
 65				if (variables.wheels.instance.errors[loc.i].property == arguments.property && (variables.wheels.instance.errors[loc.i].name == arguments.name))
 66					ArrayDeleteAt(variables.wheels.instance.errors, loc.i);
 67		}
 68	</cfscript>
 69</cffunction>
 70
 71<cffunction name="errorCount" returntype="numeric" access="public" output="false" hint="Returns the number of errors this object has associated with it. Specify `property` or `name` if you wish to count only specific errors."
 72	examples=
 73	'
 74		<!--- Check how many errors are set on the object --->
 75		<cfif author.errorCount() GTE 10>
 76			<!--- Do something to deal with this very erroneous author here... --->
 77		</cfif>
 78		
 79		<!--- Check how many errors are associated with the `email` property --->
 80		<cfif author.errorCount("email") gt 0>
 81			<!--- Do something to deal with this erroneous author here... --->
 82		</cfif>
 83	'
 84	categories="model-object,errors" chapters="object-validation" functions="addError,addErrorToBase,allErrors,clearErrors,errorsOn,errorsOnBase,hasErrors">
 85	<cfargument name="property" type="string" required="false" default="" hint="Specify a property name here if you want to count only errors set on a specific property.">
 86	<cfargument name="name" type="string" required="false" default="" hint="Specify an error name here if you want to count only errors set with a specific error name.">
 87	<cfscript>
 88		var returnValue = "";
 89		if (!Len(arguments.property) && !Len(arguments.name))
 90			returnValue = ArrayLen(variables.wheels.instance.errors);
 91		else
 92			returnValue = ArrayLen(errorsOn(argumentCollection=arguments));
 93	</cfscript>
 94	<cfreturn returnValue>
 95</cffunction>
 96
 97<cffunction name="errorsOn" returntype="array" access="public" output="false" hint="Returns an array of all errors associated with the supplied property (and error name if passed in)."
 98	examples=
 99	'
100		<!--- Get all errors related to the email address of the user object --->
101		<cfset errors = user.errorsOn("emailAddress")>
102	'
103	categories="model-object,errors" chapters="object-validation" functions="addError,addErrorToBase,allErrors,clearErrors,errorCount,errorsOnBase,hasErrors">
104	<cfargument name="property" type="string" required="true" hint="Specify the property name to return errors for here.">
105	<cfargument name="name" type="string" required="false" default="" hint="If you want to return only errors on the above property set with a specific error name you can specify it here.">
106	<cfscript>
107		var loc = {};
108		loc.returnValue = [];
109		loc.iEnd = ArrayLen(variables.wheels.instance.errors);
110		for (loc.i=1; loc.i <= loc.iEnd; loc.i++)
111			if (variables.wheels.instance.errors[loc.i].property == arguments.property && (variables.wheels.instance.errors[loc.i].name == arguments.name))
112				ArrayAppend(loc.returnValue, variables.wheels.instance.errors[loc.i]);
113	</cfscript>
114	<cfreturn loc.returnValue>
115</cffunction>
116
117<cffunction name="errorsOnBase" returntype="array" access="public" output="false" hint="Returns an array of all errors associated with the object as a whole (not related to any specific property)."
118	examples=
119	'
120		<!--- Get all general type errors for the user object --->
121		<cfset errors = user.errorsOnBase()>
122	'
123	categories="model-object,errors" chapters="object-validation" functions="addError,addErrorToBase,allErrors,clearErrors,errorCount,errorsOn,hasErrors">
124	<cfargument name="name" type="string" required="false" default="" hint="Specify an error name here to only return errors for that error name.">
125	<cfscript>
126		arguments.property = "";
127	</cfscript>
128	<cfreturn errorsOn(argumentCollection=arguments)>
129</cffunction>
130
131<cffunction name="hasErrors" returntype="boolean" access="public" output="false" hint="Returns `true` if the object has any errors. You can also limit to only check a specific property or name for errors."
132	examples=
133	'
134		<!--- Check if the post object has any errors set on it --->
135		<cfif post.hasErrors()>
136			<!--- Send user to a form to correct the errors... --->
137		</cfif>
138	'
139	categories="model-object,errors" chapters="object-validation" functions="addError,addErrorToBase,allErrors,clearErrors,errorCount,errorsOn,errorsOnBase">
140	<cfargument name="property" type="string" required="false" default="" hint="Name of the property to check if there are any errors set on.">
141	<cfargument name="name" type="string" required="false" default="" hint="Error name to check if there are any errors set with.">
142	<cfscript>
143		var returnValue = false;
144		if (errorCount(argumentCollection=arguments) > 0)
145			returnValue = true;
146	</cfscript>
147	<cfreturn returnValue>
148</cffunction>