Graphing with ColdFusion
In the past, when ColdFusion developers needed to represent data in a horizontal line graph, they had to dynamically set the width attribute of the HTML <img> tag based on data received from a query. They performed some calculation to keep the image from going out of control and could then "fake" a bar graph, kind of like this:
<!---run a query called GetResponse ----> <cfset imgwid=GetResponse.recordcount/10> <!----The width of the bargraph.gif picture, which is a one-pixel-wide plain image, is dynamically set based on the number of answers in the column---> <img src="images/bargraph.gif" width=#imgwid# height=10 border=0>
This worked okay. But it wasn't very flexible or scalable, and it wasn't very pretty. The only alternative was to purchase, learn, and integrate third-party add-ons.
A new and exciting feature of ColdFusion 5 is perhaps a result of Allaire's merger with Macromedia in the spring of 2001. The new release not only expands the underlying architecture of ColdFusion by integrating processes with the Java Server JRun, but it has enhanced the presentational power of ColdFusion as well. ColdFusion is now also integrated with an OEM version of the Macromedia Generator server. ColdFusion leverages the power of both of these servers, versions of which install with ColdFusion. With two new ColdFusion tags, <CFGRAPH> and <CFGRAPHDATA>, you can compose bar charts, line charts, and pie charts dynamically. (Note that you must have chosen to install support for CFGRAPH when you installed ColdFusion in order to create graphs.)
In this article, we'll examine how you can create compelling graphs from your data using two new ColdFusion tags. Here are the types of graphs that you can now create:
As you may know, Macromedia Generator is a standalone server whose job it is to produce Flash movies on the fly. Because Generator is Java-based, it uses Macromedia JRun Server as its Java runtime.
You make graphs in ColdFusion 5 using the <CFGRAPH> tag, which encapsulates all of the work for you. The full list of <CFGRAPH> attributes is very long because the tag takes different attributes depending on which type of graph you want to make. We will therefore just reference a few here to get started. See Table 1 for the basic attributes that you need to start working with graphs.
ColdFusion graphs are available in .gif, .jpg, and Flash formats. All you have to do to create a graph in one of these formats is give a different value for the fileFormat attribute of the <CFGRAPH> tag. The default format is Flash.
Table 1 Basic <CFGRAPH> Tag Attributes
Specifies the type of graph to create.
Bar, HorizontalBar, Pie, or Line are acceptable values.
The query containing the data to be graphed.
The query column whose values you want to graph.
The query column containing the description for this data point. This appears on the horizontal axis of bar and line graphs, and in pie charts.
Let's say that we've got a query that returns the names of products and their prices. Note that using <CFGRAPH>, you may graph only integers or real numbers. Therefore, you must convert date-time values or currency values before you can use them. Listing 1 shows the syntax of the <CFGRAPH> tag in conjunction with a query to create a horizontal bar graph.
Listing 1: A Simple Bar Graph
<!---prices and products from database -------> <cfquery name="getPrices" datasource="CoreStore"> SELECT ProductName, Price FROM Products; </cfquery> <cfgraph type = "horizontalbar" query = "getPrices" valueColumn = "Price" itemColumn = "ProductName" title = "Our Products"> </cfgraph>
This graph displays the values of the Price column with the ProductName as the item label. The value of the title attribute is displayed above the graph.
This template is run through ColdFusion, SQL Server, JRun, and Generator and is returned to the browser. The entire process takes about 40 milliseconds. You could create a vertical bar graph in just the same way by specifying Type="bar".
The different types of graphs that ColdFusion makes available are well suited to different needs. For instance, a line graph or an area graph (which is just a line graph with the space colored in) is best for demonstrating change over time. An example that you're likely familiar with is the representation of the stock market in any given day. Bar and horizontal graphs are most often used for comparisons. For instance, you might query your database to find the total number of each product sold in a given month. By casting that data into a bar graph, you can quickly see which are the best and worst performers. Finally, you should choose pie graphs when you want to show percentage parts of a total. This is great for, say, an online poll when you want to show how many respondents chose each answer.
The CFGRAPH tag will accept data only from a database query recordset. Sometimes this is not convenient, however, or it does not serve the needs of your application. For that reason, the CFGRAPHDATA tag was created. This tag is a subtag of the CFGRAPH tag, which means that it can be used only inside a CFGRAPH block, or ColdFusion will throw an error. With the CFGRAPHDATA tag, you can specify a data point to be displayed in your graph. Data point is a term that is not necessarily self-evident, so let's clarify quickly. A data point is a discrete entity represented on a graph. For instance, a bar graph displaying the totals sold each of four different products contains four data points. So, this tag allows you to display data manually.