Changes between Initial Version and Version 1 of HowTos/HowToUseFormats

Timestamp:

11/16/09 23:24:01 (16 years ago)

Author:

cfgrok (IP: 64.30.223.5)

Comment:

Renamed page for alpha sorting on home page

HowTos/HowToUseFormats

@@ +1 @@
+= Formats =
+
+Often web sites are built for multiple front-end clients. One site may serve up pages to web browsers, mobile devices, Flex or AIR applications, or AJAX requests. Typically these clients all want the exact same data, but each will need to format the data in a slightly different manner. In the past, Model-Glue would typically require you to build multiple events to serve different flavored data results, or one event was used and the Controller fired a different result based on the other parameters.
+
+Model-Glue 3 formalizes this with a new requestFormat attribute. The requestFormat attribute is now a special value in the Event context. The <broadcasts>, <results> and <views> tags now support a format attribute. If specified, the enclosed message/result/include will only be executed if the requestFormat value matches.
+
+For example, imagine the following event created to look up and return employee data:
+
+{{{
+<event-handler name="page.employee">
+    <broadcasts>
+        <message name="needEmployee" />
+    </broadcasts>
+    <results>
+    </results>
+    <views>
+        <include name="body" template="employee.cfm" />
+    </views>
+</event-handler>
+}}}
+
+Now let's pretend we want to build an AJAX version of the site. We need to support both !JavaScript-enabled and disabled browsers so we want to keep the existing event. We would most likely simply add a new event.
+
+{{{
+<event-handler name="ajax.employee">
+    <broadcasts>
+        <message name="needEmployee" />
+    </broadcasts>
+    <results>
+    </results>
+    <views>
+        <include name="body" template="jsonemployee.cfm" />
+    </views>
+</event-handler>
+}}}
+
+Except for the event name, this is the exact same event except for the view. The view, jsonemployee.cfm, simply takes the Employee information and converts it to JSON. That's a lot of typing for one small change, and what happens if our message changes from needEmployee to needWageSlave? We have two places where we could forget to update our code. Model-Glue 3's format attribute helps solve this problem. Consider this new version:
+
+{{{
+<event-handler name="employee">
+    <broadcasts>
+        <message name="needEmployee" />
+    </broadcasts>
+    <results>
+    </results>
+    <views format="html">
+        <include name="body" template="employee.cfm" />
+    </views>
+    <views format="ajax">
+        <include name="body" template="jsonemployee.cfm" />
+    </views>
+</event-handler>
+}}}
+
+Now we can use the exact same event, but simply specify a different requestFormat. If we want to display the employee (assume ID represents the Employee's ID key), we could use this URL:
+
+{{{
+http://localhost/index.cfm?event=employee&id=6&requestFormat=html
+}}}
+
+Model-Glue will default the requestFormat value to html. So this URL will display the exact same result:
+
+{{{
+http://localhost/index.cfm?event=employee&id=6
+}}}
+
+If we wanted to use the event via !JavaScript, we could then use this URL instead:
+
+{{{
+http://localhost/index.cfm?event=employee&id=6&requestFormat=ajax
+}}}
+
+The format attribute also applies to the results tag. Let's continue to use our "Employee Detail" as an example. What if the employee ID requested doesn't exist? Our controller should probably fire off a result that our event can respond to:
+
+{{{
+<cfset arguments.event.addResult("BadEmployee")>
+}}}
+
+But as with the views, we probably want to handle the result differently based on the type of request being made. As with the views tag, we can simply add a format attribute to the results tag.
+
+{{{
+<results format="html">
+    <result name="BadEmployee" do="page.employees" />
+</results>
+<results format="ajax">
+    <result name="BadEmployee" do="page.ajaxerror" />
+</results>
+}}}
+
+In the block above we have two results with the same name. When our controller fires the "!BadEmployee" result, the only result tag that will actually run is the one that matches the current requestFormat value. For HTML we simply go back to an employee listing. For AJAX applications we could run a special event that returns an error code our front end AJAX code recognizes.
+
+Likewise, if a different message needs to be broadcast for the AJAX version of the event, the format attribute can also be used in the broadcasts tag. For example, suppose that the existing version of an event broadcasts a message indicating the need for a query resultset, and the AJAX version requires that the query be formatted by the QueryConvertForGrid() function for use with the <cfgrid> tag:
+
+{{{
+<broadcasts format="html">
+    <message name="needEmployees" />
+</broadcasts>
+<broadcasts format="ajax">
+    <message name="needEmployeesForGrid" />
+</broadcasts>
+}}}
+
+Remember that Model-Glue will default the requestFormat value to html. You can override this default in the !ColdSpring.xml file by specifying a property for requestFormatValue. You can also change the value within your code itself. For example, you may use an onRequestStart in your controller to sniff out an iPhone browser:
+
+{{{
+<cffunction name="onRequestStart" access="public" output="false">
+    <cfargument name="event" type="any">
+    <cfif findNoCase("iphone", cgi.http_user_agent) or findNoCase("ipod", cgi.http_user_agent)>
+        <cfset arguments.event.setValue("requestFormat","mobile")>
+    </cfif>
+</cffunction>
+}}}
+
+This code will examine the browser's user agent value and automatically set the requestFormat to mobile for both the iPhone and iPod Touch.
+
+Note: You may be wondering if there are required values for requestFormat. Absolutely not. You may name your formats any way you want. The values 'html' and 'ajax' were used just because they were the most familiar. You are free to use any values you want.