Debug Settings

Add this to the end of your site’s URL to fire up the debug settings.

/loader.cfm?csmodule=utilities/debug-settings

Cacheing

Don’t want your element to cache while you’re developing it?!  Add this single line to the top of your renderhandler.

request.element.isStatic = 0

Want to clear the cache?  Go for it; stick this querystring on your working URL.

?resetutils

Site Administration

Need access to the Site Administration?  Of course you do, you’re the developer!  Replace the current page with this and you’re there.

loader.cfm?csModule=admin/site-menu&showSiteConfig=1

Custom Element Details

Get details about a custom element straight from the DB.  cfdump the results of this query.  I’m querying element 1342 in this instance, notice the WHERE clause.

<cfquery name="myQuery" datasource="#request.site.datasource#">
    SELECT d1.ID,
        d1.FormName,
        d1.Method,
        d1.Action,
        d1.DateCreated,
        d1.DateLastModified,
        d1.OwnerID,
       
        d2.ID as inputID,
        d2.fieldName,
        d2.shared,
        d2.type as inputType,
        d2.dateCreated as inputCreated,
        d2.description,
        d2.dateLastModified as inputLastModified,
        d3.itemPos,
        d3.TabID
        FROM formControl d1, formInputControl d2, formInputControlMap d3
        WHERE d3.fieldID = d2.ID
        AND d1.ID = d3.formID
        AND d1.ID in (1342)
        order by d1.ID, d3.itemPos
    </cfquery>

You’re making a form and the out-of-the-box field types just aren’t cutting it.  Most web developers are familiar with this scenario.  The biggest culprits are phone numbers, addresses, and credit cards.

Let’s look at how you can quickly inject you’re own JavaScript validation into a CommonSpot form to handle any kind of validation that you want.

The Solution

We’ll make use of custom field types in order to accomplish our goal. First, we’ll make a custom render handler for our custom field type.  You may be thinking we should jump straight into the Site Admin, but that dialog is going to ask us to chose a custom render handler from a drop down list, so first we need to make the render handler so there’s something to choose from!

Fire up the FTP program of your choice, and navigate to the “customfields” folder in root.  I’ll be making a US Zip Code validator for this example so I’ll call my file “zip_render.cfm”.  If you want to register custom properties to your custom field type go ahead and create a “zip_props.cfm” in this folder now too.

Now that there’s something to choose; open Site Admin -> Field Masks & Custom Field Types -> Register New Field Type.  You should see something like this:

Type: The type of the field you’re creating.  It’s also what is displayed when choseing custom fields from the list.  I’ll call mine “Zip”.

Description: A human friendly description.  I’ll use “A valid US Zip code” for now. It can be a good idea to put what will and won’t match in here if you have the energy.

Property Module: Choose “zip_props.cfm” (whatever you called your file) if you made a Property Module or choose from the list of Standard Property Modules.  “Text” will work fine for me.

Render Module: Choose “zip_render.cfm” (whatever you called your file) from the list of Custom Render Modules.

Hit OK!

Now when you go to create/edit your form you’ll have a new field type available:

Now all we have to do is add the custom validation. Here’s my custom render handler (zip_render.cfm):

<cfscript>
	// the fields current value
	currentValue = attributes.currentValues[fqFieldName];
	// the param structure which will hold all of the fields from the props dialog
	xparams = parameters[fieldQuery.inputID];

	request.youproject.utils.loadJQueryHeaders();
</cfscript>

<cfoutput>
	<script Language="JavaScript"  type="text/javascript">
		// javascript validation to make sure they have text to be converted
		#fqFieldName#=new Object();
		#fqFieldName#.id='#fqFieldName#';
		#fqFieldName#.tid=#rendertabindex#;
		#fqFieldName#.msg="Please enter a valid zip code.";
		#fqFieldName#.validator="#fqFieldName#_validater()";
		// push on to validation array
		<cfif xparams["REQ"]>
			vobjects_#attributes.formname#.push(#fqFieldName#);
			$(document).ready(function(){
				$("###fqFieldName#_label").wrap("");
			});
		</cfif>

		function #fqFieldName#_validater() {
			regex = new RegExp("(^\\d{5}$)|(^\d{5}-\\d{4}$)");
			return regex.test($("###fqFieldName#").val());
		}
	</script>
	<tr>
		<td nowrap="nowrap" align="left" width="25%" valign="baseline">
			<font face="Verdana,Arial" color="##000000" size="2">
                        <label for="#fqFieldName#">#xparams["LABEL"]#:</label>
                </font>
		</td>
		<td align="left" width="75%" valign="baseline">
			<input type="text" id="#fqFieldName#" name="#fqFieldName#" value="#currentValue#">
		</td>
	</tr>
</cfoutput>

Not too complicated but, let’s go over it real quick so you can expand and adapt this simple case to suit your needs.

“fqFieldName” is holding the CommonSpot generated name of your form field.  If you don’t include an input field for it, it won’t get saved when the user hits submit.

The JavaScript object of the same name (fqFieldName) is holding the specifics for our valdiation.  There’s the message to display on fail (msg) and the function to call on validation (validator).

I’ve wrapped the last bit in a conditional so that my custom validation is only added to the form’s validation array if I mark the field as required in the element.

The HTML for the display for the form field is left to you, the developer.

As always, Questions and Comments are welcome!