Chris Jordan's Blog: CFJS Demo Page

CFJS Demo Page

A quick note on syntax

There are two different branches of CFJS: the jQuery branch and the non-jQuery branch. The syntax for the two differ only slightly. In the jQuery plug-in version all functions are proceeded by either $. or by jQuery. like so:

var list = "1,2,3,4";
document.write($.ListLen(list));
document.write(jQuery.ListLen(list));

Both of these lines of code would output the same result. On the other hand, the non-jQuery branch of CFJS has its own namespace, namely CFJS. So all function calls are proceeded by CFJS, like this:

var list = "1,2,3,4";
document.write(CFJS.ListLen(list));

That's the only difference between the two branches really. Otherwise, I keep them in sync with each other.

How does it work?

Almost without exception, the functions provided in CJFS work just like their ColdFusion counterparts.

One exception to this rule is the Round() function. Round() works slightly different in this implementation verses ColdFusion. ColdFusion only rounds to whole numbers. The CFJS version of Round() allows an optional argument for the number of decimal places of precision.

For example:

var num=13.3714;
document.write($.Round(num,0)+"<br/>")
document.write($.Round(num,1)+"<br/>")
document.write($.Round(num,3)+"<br/>")
document.write($.Round(num,10)+"<br/>")

produces the following output:

13
13.4
13.371
13.3714000000

Using ColdFusion the example would look like this:

<cfscript>
num = 13.3714;
writeOutput(round(num));
</cfscript>

and the output to this would be:

So hopefully, everyone will agree that the round function is somewhat improved in CFJS over what we would get with ColdFusion's functionality.

What's so useful about lists, anyway?

Let's look at another example. Say for instance that you've got a function that will return several different codes upon failure, and you're writing a function that interacts with the output of this function. You don't care what the reason for the failure is, you just want to know if it failed.

So you could write code that looks like this:

FailureCode = someMethod(someArg);
if(FailureCode == "C" || FailureCode == "CV" || ...){
// respond here...
}

You might be able to see where the above code could get ugly given even just a handful of FailureCodes, and if a new code were ever added you'd have to add yet another iteration of "|| FailureCode == ..." to your code.

So you might instead write something like:

FailureCode = someMethod(someArg);
switch(FailureCode){
    case "C":
    case "CV":
    case "G":
    case "GI":
    case "X":
    case "D":
        // respond here...
        break;
}

Of course, here we're taking advantage of the "fall through" behavior of the switch statement by only including a single break statement after our last possible FailureCode. But all that still seems kind of clunky to me, and the introduction of another FaulreCode means that I've got to write an additional case statement.

Why not simply write the following:

var FailureCodes = "C,CV,G,GI,X,D";
var FailureCode = someMethod(someArg);
if($.ListFindNoCase(FailureCodes,FailureCode){
// respond here...
}

Remember, the above example works in regular ColdFusion as well as in CFJS. We're just taking advantage of the fact that any non-zero value is truthy (both in ColdFusion and in JavaScript). So if we found FailureCode in the list of FailureCodes then it's true and we can respond accordingly.

To me this syntax is also superior because if an additional FailureCode is added, we simply add it to the list. Also, this list could be obtained from a table in a database containing failure codes so potentially you wouldn't have to edit code, but rather just update the FailureCode values in a table.

Lists as Arrays and looping

How about another example using a list as an array, and looping over that list. This is something that's pretty common.

I personally like being able to treat any string as an array by just treating it as a list with delimiters. It's darned handy. The following is a complete and working function that I wrote and used at one of my clients to validate a U.S. Vehicle Identification Number (VIN)

You can see in this code that CFJS gets a bit of a workout. It uses couple of different list functions, Len, IsNumeric and Mid. Pay particular attention to the for loop. Notice that even though JavaScript traditionally starts looping at zero, my loop starts at one. This is because I'm using a list as my array, and list positions start at one and not at zero. This behavior is carried over from ColdFusion. So, even though these lists are treated as zero indexed arrays under the hood, you don't need to change anything about the way you program with lists.

The exception to this rule is when using CFJS array functions.

CFJS Array Functions

One other caveat when dealing with CFJS is when dealing with the Array functions. Because we're dealing with JavaScript arrays and not ColdFusion arrays, you as a developer need to be aware that JavaScript indexes its arrays starting at zero and not at one like ColdFusion does.