A ColdBox module that extends and enhances Brian Kotek and James Mohler's form utilities components.

This module parses form field names to automatically create naitive CFML structures and arrays.

For example:

• A form field named user.firstName will create a CFML structure named user with a key of firstName, holding the value of that field.

• A form field named user[1].firstName or user[1][firstName] will create an array named user. The first element in this array will be a structure with a key of firstName.

This module was tested in the following CFML engines:

• Lucee 5
• Adobe ColdFusion 2018
• Adobe ColdFusion 2021

Install FormUtilities using CommandBox:

box install formutilities

Configure FormUtilities in your Coldbox config/Coldbox.cfc file:

moduleSettings = {
    // default configuration
    formUtilities: {
        "autoParse" = true
    }
};

To manually use FormUtilities in your Coldbox application, inject the FormUtilities model into your handlers, models, or interceptors using the following Wirebox DSL:

property name="formUtilities" inject="FormUtilities@FormUtilities";

In order to take advantage of FormUtilities parsing, you need to name your form fields in a specific way. Here are some examples:

<!-- Simple Array -->
<input name="telephone[1]" value="111-111-1111" />
<input name="telephone[2]" value="222-222-2222" />
<input name="telephone[3]" value="333-333-3333" />

<!-- Simple Struct -->
<input name="address.street" value="1234 Elm St" />
<input name="address.city" value="Springfield" />
<input name="address.state" value="IL" />
<input name="address.zip" value="62701" />

<!-- Array of Structs (option 1) -->
<input name="order[1].item" value="Laptop" />
<input name="order[1].price" value="1000" />
<input name="order[2].item" value="Tablet" />
<input name="order[2].price" value="500" />

<!-- Array of Structs (option 2) -->
<input name="order[1][item]" value="Laptop" />
<input name="order[1][price]" value="1000" />
<input name="order[2][item]" value="Tablet" />
<input name="order[2][price]" value="500" />

<!-- Complex nesting -->
<input name="order[1].item[1].name" value="Laptop" />
<input name="order[1].item[1].price" value="1000" />
<input name="order[1].item[2].name" value="Tablet" />
<input name="order[1].item[2].price" value="500" />
<input name="order[2].item[1].name" value="Phone" />
<input name="order[2].item[1].price" value="300" />

Important Note Javascript starts array indexes at 0, but ColdFusion starts at 1. Your HTML form input names should start indexes at 1 to match CFML.

If you have disabled autoParse in your configuration, you can manually parse the rc scope using the buildFormCollections() method. The method accepts the following arguments:

Examples:

// Parse the rc scope and automatically update it
formUtilities.buildFormCollections( rc, true );

// Parse the rc scope without updating it and output the parsed data
var result = formUtilities.buildFormCollections( rc, false );
writeDump( result );

The buildFormCollections() method returns a struct with the following important fields:

• _formCollections: An array containing all resulting arrays and structures parsed from the original data
• _formCollectionErrors An array containing field names with errors that could not be parsed

When the parser builds structures and arrays, it automatically trims and canonicalizes the field values. It will not canonicalize regular form fields that aren't part of a structure or array, so you will need to take care of that yourself.

In addition to form processing, the CFC includes a utility method, compareLists() that compares two lists (an original list and a new list) and returns a structure indicating:

• Added Items: Elements present in the new list but not in the original.
• Removed Items: Elements present in the original list but not in the new one.
• Same items: Elements present in both lists.

Example:

var list1 = "apple,banana,orange";
var list2 = "banana,orange,grape";

// compare the two lists
var result = formUtilities.compareLists( list1, list2 );

writeDump( result );

// Output: { added = "grape", removed = "apple", same = "banana,orange" }

To run the unit tests on this module, fire up CommandBox and enter the following commands to start a CFML server of your choice. Included server configs are as follows:

start [email protected]
start [email protected]
start [email protected]

Then open a browser and navigate to http://localhost:port/tests/runner.cfm to automatically run the tests.