ColdBox and Ajax Sitting on a Tree! K-I-S-S-I-N-G

As you can see from the corny title, ColdBox and ajax love each other. There are several techniques and ways you can integrate the framework with any Ajax library, either to return xml/json/wddx or html. The best example for coldbox-ajax integration is the ColdBox Reader Sample Application by Oscar Arevalo. It is very rich with Ajax techniques and renderings. This guide shows some tips and tricks on how to integrate ajax to coldbox applications.

Recommended Ajax CF Library: Rob Gonda's AjaxCFC

Overview

You can decide to return any type of data back to the caller via rendering xml/jsnon/wddx or actual html blocks. ColdBox can do html natively and for the other ones, you will have to create some extra files for it.

Returning HTML

HTML rendering is easy, because that is what ColdBox does, render HTML. So to do a simple ajax call to the framework, you just call it as if you where doing it from the browser.

Example

I have an event called: ehBlog.dspEntry that renders the vwEntry.cfm template. So in a typical call I would just call it as:

http://localhost/index.cfm?ehBlog.dspEntry&entry_id=1234

When you call it from an AJAX enabled application, you would do the exact same thing, either POST/GET to the above URL and the received content (HTML) div replaced wherever you want. And that is IT!! Easy right!!

Ajax HTML Layout

Well, this is where layouts come in play. I usually create a default layout for my ajax applications that take care of certain cleanup of the returned messages or if you want, you can create a specific layout for a specific folder. Below is how to do it.

In the configuration file:

<Layouts>
  <DefaultLayout>Layout.Ajax.cfm</DefaultLayout>
</Layouts>

<!-- For a Folder -->
<Layouts>
  <Layout name="ajax" file="Layout.Ajax.cfm>
    <Folder>ajaxviews</Folder>
  </Layout>
</Layouts>

The actual Layout.Ajax.cfm

<!--- Remove CF Output --->
<cfsetting showdebugoutput="false">
<!--- Remove the COldBox Debugging --->
<cfset event.showdebugpanel("false")>
<!--- Render a messagebox --->
<cfset WriteOutput(getPlugin("messageBox").renderit())>
<!--- Render a View --->
<cfset WriteOutput(renderView())>

The first thing I do is remove the coldfusion debugging if available. Then I use the special magic function in the event object to disable the coldbox debugger: showdebugpanel( boolean ). Then I just output a messagebox if available and then I output my view to be rendered. That's it. The interesting methods here are that I tell coldbox to remove the debugger panel if I am in debugging mode. This layout is then used to render any view that is brought via Ajax. This opens a world of ideas on how it can be so flexible for your view renderings.

Ajax DATA (xml/JSON/wddx)

The other layout you can build to return data to your application is the same as in the example above. What? is that possible. Yes, because what you return is data, then basically you create an Ajax proxy view. What in the world is this? well, its a view that just proxies your result to the caller and you can see a sample of that below:

<!--- vwAjaxProxy.cfm --->
<cfcontent type="text/xml" reset="true"><cfoutput>#event.getvalue("data")#</cfoutput>

We render data that exists in the event object, placed there by the handler executed. It is then returned as text/xml via cfcontent. So to show a very basic wddx sample created from a handler, look below. (You can use any serialization plugin or library out there. That is your choice)

<cffunction name="doGetXML" access="public" returntype="void">
  <cfargument name="event" type="any" required="true">
  <cfset var data = structnew()>
  <cfset var dataSerialized = "">
  <cfset data.time = now()>
  <cfset data.content = "Luis Majano is weird!">
  <cfwddx input="#data#" output="dataSerialized" action="cfml2wddx">
  <cfset event.setValue("data",dataSerialized)>
  <cfset event.setValue("ajax",true)>
  
  <!--- Set view with no layout --->
  <cfset event.setView("vwAjaxProxy",true)>
  <!--- or set the view to render in the ajax layout--->
  <cfset event.setView("vwAjaxProxy")>
</cffunction>

You can decide to have a layout for the proxy or you can just render the proxy as is. Then I would place the debugging off statements in the view and use the event.setView('vwAjaxProxy',true) to render it.

The second parameter to the setView method tells the framework to skip layout rendering and just render the view. Very handy!!

The Cache Debug Panel

As you know, ColdBox provides you (The Developer) with many great tools and visual representations of your application. One of these is the cache panel monitor specially built for monitoring cache operations in Ajax Applications. You can read more about this by Clicking Here

Here is a screenshot of the latest Cache Monitor:

Wrapping it Up

As you can see from the samples above, AJAX integration is a breeze. You can keep calling the framework url's but you determine the output that it returns. I have had great results in using the first method of returning HTML blocks. However, to return data is just one more extra step and you can combine it with popular libraries such as Rob Gonda's AjaxCFC, which I recommend, to do your translations. So enjoy mixing up these two great technologies.