Doug Boude (rhymes with 'loud')

31 March 2010

Easy Way to Integrate ColdFusion into Non-ColdFusion Templates

Ajax to the Rescue!

Categories: Ajax goog placeblogger

Have you ever found yourself in a situation where you needed to implement some new feature using one scripting language within a template that is written in a different scripting language, or possibly no scripting language at all (pure HTML)? Of course, you could just turn the pure HTML template into a CFML template, and at times that is indeed the best route to go, as long as breaking every link pointing back to this page is acceptable. If the target template is written in another scripting language, however, transforming it into a CFML template would probably not be a viable option. Ah, but there is at least one way to still be able to integrate your Coldfusion functionality into any template (HTML OR those written in other scripting languages): Leveraging the power of Ajax.

Typically the first route our minds go when asked to integrate two discrete templates is to look for a way to "include" one within the other. HTML does provide a type of inclusion ability (called 'Server Side Includes' (SSI)), but this approach is typically used to include other HTML documents and would be challenging to make work with a Coldfusion template. Other scripting languages have the ability to include other templates written in the same language, but getting them to play nicely including Coldfusion would also prove challenging. You could also go the route of using an IFRAME within your template, but this approach also presents limitations and hurdles that you may not wish to deal with. The simple solution, and the simplest approach to making it work, again, is Ajax.

The Scenario

In this scenario, the target template is a static HTML site and the code you want to integrate is written in Coldfusion. Our goal is to dynamically display the contents of an upcoming events database table in our Events section of the company's HTML home page. Here's how I approached it:

1. Create a target within the static HTML page where you want the event data to appear. In my case, I created this bit of HTML:

<h3>Corporate Events</h3>
<div id="eventTarg"></div>

2. Create a CFM template to act as your data provider. Mine is called eventAjax.cfm, and contains several different methods since it is used by other applications as well;

3. "Wire up" your HTML page with your favorite Javascript library. Mine (currently) is Prototype, so my code snippets will reflect Prototype's syntax, but you should be able to easily relate it to your favorite flavor

That's it! Now, some details...

The Data Provider

Some may feel the need to write full blown web services to provide data to the consumer/caller, but personally I feel that most times this is major overkill when a RESTful approach works beautifully. Here is what my eventAjax.cfm looks like, showing only a couple of possible methods:

<cfsetting enablecfoutputonly="true" showdebugoutput="false" />

<cfparam name="meth" default="" />

<cfswitch expression="#meth#">
<cfcase value="getEventLinks">
  
  <cfquery name="qryGetLiveEvents" datasource="#dsn#">
   select id,name,descrip,eventfromdate,eventtodate
   from registrationevents
   where <cfqueryparam value="#now()#" cfsqltype="cf_sql_date" /> <= eventToDate
   AND publish = <cfqueryparam value="1" cfsqltype="cf_sql_tinyint" />
   order by eventFromDate
  </cfquery>

<cfset links = "no events currently scheduled" />

<cfif qryGetLiveEvents.recordcount gt 0>
   <cfoutput>
   <cfsavecontent variable="links">
    <p id="eventlinks" class="eventlink">
     <cfloop query="qryGetLiveEvents">
      <a href="registration.cfm?eventid=#id#" target="_blank">#name#</a><span class="eventText"> <em>(from #dateformat(eventfromdate,"mm/dd/yyyy")# to #dateformat(eventtodate,"mm/dd/yyyy")#)</em><br>#descrip#</span><br><br>
     </cfloop>
    </p>
   </cfsavecontent>
   </cfoutput>
  </cfif>
  <cfoutput>#links#</cfoutput>
</cfcase>

<cfcase value="updatePublish">
  <cfparam name="eventid" default=""/>
  <cfif not isnumeric(eventid)>
   <cfoutput>INVALID EVENT ID</cfoutput>
   <cfabort>
  </cfif>
  <cfquery name="qryUpdatePublish" datasource="#dsn#">
   UPDATE registrationevents
   SET publish = <cfqueryparam value="#newval#" cfsqltype="cf_sql_tinyint" />
   WHERE id=<cfqueryparam value="#eventid#" cfsqltype="cf_sql_integer" />
  </cfquery>
</cfcase>

<cfdefaultcase>
<cfoutput>UNAUTHORIZED ACCESS</cfoutput>
</cfdefaultcase>
</cfswitch>

Reading through this code, it is pretty self-explanatory. Basically, when the ajax call is made, only values explicitly output using CFOUTPUT tags will be returned to the caller. My "getEventLinks" method is returning a pre-formed block of html that my client side javascript will simply dump into its target div.

Wiring up the HTML

Wiring up our HTML page consists of doing only two things:

1. include your javascript library;
2. create a function to be executed after the html has fully loaded;

My step 1 line looks like this:

<html>
...
<title>Company Name Here</title>
<script type="text/javascript" src="js/prototype.js"></script>
....
</html>

Step 2 is inline script written at the bottom of the template, just within the <body> tag. I don't believe it HAS to reside within the <body> tag, but that's where i chose to put it. It looks like this:

That's it! Now, everytime the page is loaded, Prototype will execute an ajax call to the template specified and will stuff the results into the targeted div 'eventTarg'. If no qualifying events are found, we'll simply get the phrase "no events currently scheduled".

Here is a screenshot of the html page loaded, using Firebug to see the ajax call that was made and the value returned:

firebug ajax call

Posted by dougboude at 3:52 PM | PRINT THIS POST! | Link | 5 comments

16 March 2010

Leveraging Response Headers in Ajax Calls

Categories: javascript Ajax goog placeblogger

If you're doing any sort of Ajax development, then you undoubtedly already are quite familiar with the different ways you can use an Ajax call. For instance, you can have the call return a fragment of fully formed html (such as a table populated with data). For a more advanced user, you may have your Ajax calls returning raw data in the form of JSON or XML and parse it on the client side. In either case, though, your single Ajax call is returning a single value. But what if you want several different discrete pieces of "stuff" returned in a single call? You could get creative, and do something such as this in your backend code:

<cfsetting enablecfoutputonly="true" />
<cfscript>
stReturnData = structnew();
stReturnData.htmlBlob = "<table><tr><td>bla bla bla</td></tr></table>";
stReturnData.statistics = structnew();
stReturnData.statistics.recordcount = 212;
stReturnData.statistics.redWidgets = 32;
stReturnData.statistics.blueWidgets = 54;
stReturnData.someQuery = qryIRanPriorToThis;

returnVal = serializeJSON(stReturnData);
</cfscript>

<cfoutput>#returnVal#</cfoutput>

The above would work perfectly fine. It would, however, require that you be willing to write some serious Javascript to access the individual pieces of data, and compels you to have to visualize how the data sets are structured and nested as a whole.

Again, nothing wrong with doing something like the above. But, when I find myself wanting to return more than one value with a single Ajax call, more often than not I will approach it by leveraging response headers.

Response headers are like the saddle bags on a Harley. If your Ajax response is the Harley, then the burley tatted dude (or dudette) riding it is your primary response value. This Harley, however, comes equipped with a pre-defined set of saddle bags that contain what I'm calling "peripheral" information, or metadata about the response, AND (this is most critical), the ability for you to add your own custom saddle bags before the response comes riding home to its caller!

I have never had a need to even look at or care about those pre-canned response headers. They contain name value pairs such as "Transfer-encoding:chunked", "content-type:text-html", "Date: Tue, 16 Mar 2010 15:43:35 GMT", and a couple of others. But, in order to satisfy needs such as I described above in the code sample, I DO add my own response headers and stuff them with values my Javascript needs.

Doing this in Coldfusion is very simple and easy (as are most tasks). Re-doing the example above, then, I'm going to choose one of the values to be my burley tatted rider (typically the value consuming the most bytes), and designate the rest to response headers, like so:

<cfoutput>#ReturnData#</cfoutput>

So now my Harley has several new, custom saddle bags attached, each containing the value I set in the "value" attribute of the cfheader tag, and my main rider, or the actual response value is my ReturnData (the blob of html).

Let's look at the Javascript needed to utilize this response. In this example we are going to use the Prototype library to create a new Ajax Updater. Updaters simplify the task of making an Ajax call and stuffing the response value directly into a target element. So let's say we have a div with an ID 'dataDiv' that will hold a table of data. The Ajax updater line will look like this:

new Ajax.Updater('dataDiv',getDataURL,{parameters:params,method:'get');

Now, the line above deals exclusively with the response value and ignores anything to do with the response headers. In order to access those headers, we have to tell our Updater to pass its response (Harley, rider, saddlebags, and all) to a function that we designate. This is called "using a callback function", and our line of code will now look like this:

new Ajax.Updater('dataDiv',getDataURL,{parameters:params,method:'get',onComplete:processSaddlebags);

The Updater will update its target div with the response value, then hand the Harley off to the processSaddlebags function, which will look something like this:

function processSaddlebags(ajaxResponse){
//let's set each of our response header values to a local variable...
var recordcount = ajaxResponse.getHeader('recordcount');
var redWidgets = ajaxResponse.getHeader('redWidgets');
var blueWidgets = ajaxResponse.getHeader('blueWidgets');
var objQuery = ajaxResponse.getHeader('someQuery');

//now we can do 'stuff' with these values!
alert('total number of records in our query: ' + objQuery['ROWCOUNT']);
//etc....
}

It should be noted at this point that a most MAHVELOUS way for you to get a clearer picture of what is happening when your code makes Ajax calls is to use the Firefox browser with the Firebug plugin. By doing this simple thing, Firebug will provide you with all the details of every Ajax call you make. Here's a screenshot of a sample Ajax call and the kinds of info you get back (notice the custom header 'total' that I added, and the fact that I'm outputting that value in the html as the "Total Records" value):

response headers

screenshot of firebug ajax call showing response headers

response value

screenshot of firebug ajax call showing the response value

Now, all that having been said, there are size limitations to the usage of response headers that you should keep in mind. I could not find a specific reference that talked about the size limit of response headers, but I did do some experimentation to try and approximate what that limit is. I stuffed as many characters as I could into a response header, and the value was truncated at 6,653 characters (including spaces). I created two custom headers with the same 6,653 characters in it, and both were returned, so I'm assuming the limitation is per header (though common sense tells me there is probably a cumulative maximum size as well). Knowing that there IS a limit, my recommendation is that you use headers for smaller pieces of data and never to convey something as large as a JSON data set unless you know that it will be limited in size.

That's it boys and girls! Now go out there and leverage those response headers!

Posted by dougboude at 12:47 PM | PRINT THIS POST! | Link | 2 comments

19 February 2010

Registered Ajax Responders Not Responding Properly

Ajax Fundamentals

Categories: javascript Ajax goog placeblogger

If you use the Prototype Javascript library and you chain your Ajax calls together at times, you may have run into the issue that I just dealt with regarding your registered responders not responding correctly! Since I spent more time than I care to share trying to figure out why my global responders weren't working like I thought they should, I thought I'd share what I learned. Hope it saves somebody some time! :)

Prelude

You may not be familiar with some of the terms I have used already, or some that I will use. If you feel you already have a good grasp on the lexicon surrounding Ajax and JS libraries, skip ahead to The Scenario; but if not, then allow me to clear up some of the fog before we press on. Please excuse me if I spend time on things that you may feel are "common knowledge", but in my experience there really is no such thing and I want to make sure every reader is thinking in the same context.

The Basic Nutshell of Ajax Chaining

In Prototype and other similar libraries, an Ajax call is typically of one of two flavors: simple request, and an update request.

Simple Requests

A simple request is one in which you ask your JS to make an http call to the server and hand you back the results that were delivered, whatever they be. At that point you will have written more Javascript to actually deal with those results manually. For example, let's say you display a select list containing possible food categories to your user. When the user selects a category, an Ajax request is made passing in the selected category, and a JSON representation of a record set containing foods in that category is returned. That JSON object is handed off to another function you wrote which will 'walk' through the foods and populate yet another select list with the specific items.

Update Requests

An update request is one in which you are asking your JS to make an http call to the server and stuff the results, whatever they be, directly into a DOM element (a DIV tag, a SPAN tag, etc.). Let's make a slight change to the example cited above. In this scenario, we already have a DIV tag in our html that we have designated as the place where our select list should appear. So, instead of having our server code return a raw JSON representation of the data, we write our server code to produce the HTML for the fully populated select list ("<select name='selFoods'><option value='1'>Crescent Rolls</option><option value='2'>Dog Biscuits</option>....</select>"). It is this string that our Ajax call receives, and this returned value is stuffed directly in to the DIV tag we designated as the recipient. Make sense?

Registering Responders

It is quite typical (and useful) to show to your users some kind of "working" image to indicate that the Ajax call is in progress. We may also wish to disable certain items on the user interface while calls are in progress, or overlay an opaque div to prevent the user from clicking anything. The thing we want to do and/or display while an Ajax call is in progress is what we refer to as our "Responder". Within our Javascript, we will tell our library something along the lines of "hey, anytime an Ajax call is created (started), I want you to do this; and anytime you see an Ajax call finish, I want you to do this". The act of telling our library what we want to happen automatically regardless of the Ajax call is called "registering responders". You define (register) them one time, and they just work. :)

Why Would I Ever Want to Chain My Calls?

I'm glad I asked! Let me just give you a working example to help illustrate why we might do this on occasion, and how we do it.
In my application, I am allowing a user to upload a data file. When the upload of the file is complete, I then need to kick off a series of things to occur, and I want to update a DIV with the current status of each call as they happen. The first call is to validate the uploaded file, so I write an Ajax simple request that tells the server where the file was uploaded and what kind of file it is supposed to be. This call will either return a true or false, depending on whether the file passed or not. If it failed, I want to tell the user that the file was bogus and cease any further processing. If it passed, I want to kick off another Ajax simple request that tells my app to go ahead and proceed with step 1 of the file processing. That call will return success or failure along with status messages, and then will kick off the third step in the processing.

Now, the way we "connect", or "chain" these calls together is by taking advantage of the fact that our library knows when a call is finished. When we write the JS for call 1, we tell it "when you receive a response from the server, pass that response on to Call 2 for evaluation". Call 2 is written to check the success status, and if all is well will make an Ajax simple request which itself has been told to pass its results on to Call 3. Here's an abbreviated example of what I'm talking about (some code ommitted for brevity):

See how they're all connected? Chain Chain Chaaaaaaainnnnnn... yeah.

The Scenario

In my scenario, I have a file upload process that is composed of three different Ajax requests, all chained together in a conditional, synchronous fashion (I know there are other ways to approach it, but this is the one that fit my needs the best). I have registered global responders to show/hide an animated spinner to indicate when a request has started and finished (I 'show' it when the request starts, I 'hide' it when its finished). Now, in my mind, these global responders should toggle that gif every time a request starts or stops, so in this scenario, it should show/hide three different times. But, that isn't how it worked. The gif would show during the initial call, and hide after that call was finished; Then it never showed again, despite the fact that there were multiple additional calls made! Here is how I registered my responders:

    Ajax.Responders.register({
        onCreate: function() {
            showUploadWorking();
        },
        onComplete: function() {
            hideUploadWorking();
        }
        });

After much experimentation, it occurred to me that perhaps even though the responder was global, maybe I needed to be concerned with manually 'watching' the active request count variable. I don't understand why I SHOULD have to, but that did turn out to be the solution. Here is the properly working responder registrations:

    Ajax.Responders.register({
        onCreate: function() {
            showUploadWorking();
        },
        onComplete: function() {
            if(Ajax.activeRequestCount == 0){
                hideUploadWorking();
            }
        }
        });

Notice the only difference is in the onComplete function...I am 'watching' the activeRequestCount variable (which as you may have guessed is simply a counter telling us how many requests are currently not yet finished) and conditionally hiding my responder.

Doug out :0)

Posted by dougboude at 11:20 AM | PRINT THIS POST! | Link | 1 comment

20 May 2009

Basic Ajax Select List Filter in PHP

Categories: PHP Ajax

I am a ColdFusion guy, without a doubt. At my new job, however, I have inherited the maintenance and enhancement duties of a large PHP application as well. One of the enhancements I was asked to make was to produce a select list of names that could be filtered on the fly as the user typed into a text box. Being somewhat new to PHP and having had to figure out a good approach to creating this feature, I thought I'd share it in case it helps someone else.

Picture if you will, a select list filled with names and immediately below it a text box for filtering that list. Better yet, here's what mine looks like:

select list with ajax name filter

As the user begins typing in the text box, the select list begins to be filtered, re-filtering as each letter is added or removed.

I'm using the Prototype javascript library to perform the ajax calls, and a PHP script I call "adminAjax.php" that listens for and responds to those ajax calls. First off then, the HTML and JS that sets up the user interface:

basically, I have one div that will hold the select list ("namelist"), and some js that, on page load, will bind the 'filterByName' function to the keyup event on the 'fltName' textbox. So, with every character entered or removed from that textbox, the current value will be passed to the filterByName function. Here's the filterByName function:

function filterByName(strname){
var params = new Hash();
params.set('namestring',strname);
params.set('actionval','getSelect');
new Ajax.Updater('namelist','adminAjax.php',{parameters:params,method:'get'});
}

Okay, now on to adminAjax.php.

I'm using this template exclusively for ajax responses, so what I did was to create a switch/case statement that routes to the appropriate function based on the incoming 'actionval' parameter. Important to note: in my case, I chose to create the entire select list on this end and then return the completed HTML. The Updater that made the Ajax call will then place the returned HTML into the target div for us. Here's the code:

<?
//make sure we have a default value for the actionval parameter...
if(!isset($_GET['actionval'])){$_GET['actionval']='none';}

switch ($_GET['actionval']){
  case 'getSelect':
   $retval = getSelect();
   echo $retval;
   break;
  case 'some_other_action':
   $retval = bogusCall($_GET['someParam']);
   echo $retval;
   break;
}

//end of our switch router! Now for the functions that feed it...

function getSelect(){
  include("settings.php");
  $Query = "SELECT userid,firstname,lastname from myTable ";
  $Query .= " where firstname <> '' and lastname <> '' ";

  //filtering on lastname/firstname...?
  if(isset($_GET['namestring']) && strlen($_GET['namestring'])>0){
   $aStr = split(",",$_GET['namestring']);
   $len = strlen(trim($aStr[0]));
   $flen = (count($aStr) > 1)?strlen(trim($aStr[1])):0;
   $Query .= "AND SUBSTR(lastname,1,".$len.") = '".trim($aStr[0])."' ";
   if($flen > 0){
    $Query .= "AND SUBSTR(firstname,1,".$flen.") = '".trim($aStr[1])."' ";
   }
  }
  $Query .= "order by lastname,firstname";

$Result=mysql_db_query($DBName,$Query,$Link);

        if(mysql_numrows($Result) == 0){
          $strField = "<br><br>No Records Found. Please Change Filter Values and Try Again.";
        } else {//we have some records...let's build the select list HTML.
   $strField ='<select name="selUsers" id="selUsers" size="20" style="width:200px;" >';
   while($row = mysql_fetch_assoc($Result)){
    $strField .= '<option value=\''.$row['userid'].'\'>'.$row['lastname'].', '.$row['firstname'].'</option>';
   }
   $strField .='</select>';
        }
        mysql_close();
  return $strField;
}

That's it!

You may be thinking what I was originally thinking, something along the lines of "wouldn't it just be faster to have given the page a json representation of all the names, then used JS to filter it on the client side?" Well, the answer (at least in my case) is NOPE. I am working with about 3,000 names, and my first approach was to do it using the JSON data. This worked fine in Firefox, but IE...of course it ran painfully slow. Using the Ajax approach and just creating a new select list as the filter value changes works surprisingly fast in all browsers!

Hope this helps.

If you would like a good set of starter snippets, you can grab the zip file here.

Posted by dougboude at 2:02 PM | PRINT THIS POST! | Link | 1 comment

<<	September, 2010					>>
S	M	T	W	T	F	S
			1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30

My Score: 9,001

Read (and recommend)

Reading

The Scenario

The Data Provider

Wiring up the HTML

Prelude

The Basic Nutshell of Ajax Chaining

Simple Requests

Update Requests

Registering Responders

Why Would I Ever Want to Chain My Calls?

The Scenario