[I just did a quick search on the net to see if anyone has published anything on this (and no one has), so here we go.]
One of the problems with Javascript that is commonly complained about is type safety; I know having dynamic types is also a feature, but what happens when you want to make sure that something is of a certain type. Well, you can always try to convert the types to the necessary type or at least check the value of the type... using the getType method (available on the every object using the MS Ajax Javascript) also can help.
But wouldn't it be nice if there was simply a way to check the types in a very convenient way to validate the type (and throw an exception if something is off). Believe it or not (I'm sure you do) the MS Ajax Extensions have an unpublished method for doing this: Function._validateParams. if takes 2 arguments : arguments array, and an object describing the parameters you want to validate. Here's a simple example to get us started:
function myFunction(aName, somethingElse) {
var e = Function._validateParams(arguments, [
{name: "aName", type: String},
{name: "somethingElse", mayBeNull: true} ]);
if (e) throw e;
}
So let's dig into that second parameter... it's a JSON string. If you don't know what that looks like then now you know... I really don't want to get into a huge primer on JSON, but here's a couple siimple rules so you can read that... anything between "[" and "]" denotes an array; anything between "{" and "}" is an object with properties identified by "name:value" (there's more to it, but you can now read the JSON above...
The second parameter is an array of objects.. one object for each parameter. So let's tear apart the individual expected parameter object within the array. All of the parameter objects have a name field (this is so the validation script can identify the element by name from the arguments array). In the example above we have an additional field. The "aName" param has a type of String (BTW, this can be any type such as Function, Number, Sys.Component, etc.), so this parameter's type will be checked by the validation routine to ensure that only strings are passed in. The "somethingElse" field has a mayBeNull field (boolean) which indicates that null values are allowed in this field.
Here's the complete list of additional fields:
type - (Type) indicates the allowed type for this parameter (Some examples are Array, Function, String, Sys.Component, etc.)
mayBeNull -(boolean) indicates that a param may have null passed in
integer - (boolean) indicates that a param whose accepted type is number is also specifically tested to make sure it is an integer
domElement - (boolean) indicates that the object param is a domElement
optional - (boolean) indicates that the parameter is optional
elementType - (Type) - indicates the accepted type of all elements of an Array passed in (type must be Array in this case)
elementInteger - (boolean) indicates that all array elements are also specifically tested to make sure it is an integer
elementDomElement - (boolean) indicates that all array elements are a domElement
elementMayBeNull -(boolean) indicates that an array element may have null passed in.
Something that should be mentioned is that one of the things that happens is that the routine will make sure that the number of parameters passed to the function are within the correct range (parameters can be marked as being optional, so it checks to make sure that the number of parameters passed in is within the max and min number of parameters expected); beware if this fact; if you want to validate you need to validate all the parameters.
BTW, the routine returns an exception object to you if there was a problem with the parameters passed in. If you want to handle the exception in your function you can or you can simply throw it back to the caller.
Just so you can see how complex you can make things... let's look at one final more complicated example:
function myFunction(aNumber, somethingElse) {
var e = Function._validateParams(arguments, [
{name: "aNumber", type: Array, elementType: Number, elementInteger: true, elementMayBeNull: false},
{name: "somethingElse", type: Object, domElement:true, optional: true, mayBeNull: true} ]);
if (e) throw e; }
This last example was to show you that you can throw all kinds of options into the JSON. We still have 2 parameters that will be passed in aNumber and somethingElse. aNumber is an array of integers (Numbers), and all elements must have a value (BTW, the elementMustBeNull is really not required in this case; generally you would only use it if you wanted to allow nulls). somethingElse is domElement, but it doesn't have to be passed in or it can be null.
