Kevin Hoyt

I’ve been traveling and covering events here recently, but I’ve managed to squeeze out some time for a few upcoming technical posts. To start off the series I’m going to cover a question that came to me from a customer. The question had to do with customization of the various labels on the charting components. In this post we’ll take a look at customizing the chart data tip, horizontal axis labels and vertical axis labels.

Data tips are what appear in the charts when the mouse hovers over a specific portion of the display. You can turn data tips on and off using the “showDataTips” property which takes a Boolean value. For these examples you will want to set the “showDataTips” property to “true”. The behavior of the data tips as described by Flex Engineer, Ely Greenfield is:

The bare minimum data tip that gets displayed is the values of the data point. For most series types, this is just x and y values. Some tips have more than just the two (i.e. a floating column chart has x, yMin, yMax). These will get labels to differentiate appropriately (min, max).

If you provide the series with a value for the name property, it will appear above the values in bold. If you provide the axis objects of the chart with names, they will prepend the appropriate values in the data tip (in italics).

You can provide a “dataTipFunction” to the chart to write your own data tip value. The “dataTipFunction” gets passed an event object with a “hitData” structure on it which describes the data point for the data tip. You can return whatever string you want from this function. The data tip can display HTML, so the string can contain all the tags that Flash Player supports.

This customer had a column chart that displayed “price” on the vertical axis and “date” on the horizontal axis. The data provider for the chart included more data than just these two properties per object, some of which they wanted to display in the data tip. Given that level of customization, it seemed the best approach was to leverage the last option given by Ely - to write my own data tip function and return some HTML that formatted the data tips in the desired fashion, using the desired data points.

// Formats chart data tips based on item data
// Called whenever a data tip needs to be displayed
private function formatDataTip( point:Object ):String {

  // Format those items requiring additional customization
  var notice:String = point.hitData.item.advance + ” ” + point.hitData.item.unit;
  var price:String = fmtPrice.format( point.hitData.item.price );
  var when:String = fmtWhen.format( point.hitData.item.when );

  // Return the string to display in the data tip
  // Some HTML can be used to control basic formatting
  // In this case HTML controls multiple lines (<br>) and bold labels (<b>)
  return “<b>Date:</b> ” + when + “<br><b>Price:</b> ” + price + “<br><b>Advanced purchase:</b> ” + notice;
}

This function expects an Object that has the various properties that Ely mentions in his description, and returns a string that represents the formatted data. If you’re really interested in knowing all the properties that are included on the object, you might take a look at Christophe Coenraets object inspector. The main property on the data point object is the “hitData” property which is the object which is populating the chart, intact with all its original properties.

Rather than have one long return string, I’ve broken the elements out into their own variables. In the case of the data tips for this chart, I want to display not only the price and date, but I also want to display the advanced purchase time necessary to get the specified airfare. This property was part of the original service data, so now I just need to grab the property, format it, and display it with the rest of the properties.

Note that I use a couple formatter classes from the Flex MXML API to achieve the desired display. My favorite part about the formatters in this case is how the DateFormatter class will parse a date/time string into a Date object for formatting and display. The DateFormatter class does this internally without me ever having to think about it. I just supply the string and the formatter class does the rest.

The last part of the data tip function takes the freshly formatted values and combines them into a small snippet of HTML. The HTML in this case creates bold labels and orients the data vertically. You might choose to leverage different HTML for a different display. Note that the Flash Player supports a very limited set of HTML text formatting.

Now that we have robust control over the data tip display, how about those axis labels?

The column chart I am using for this example has two properties that allow customization of the label appearance. To customize the vertical axis, you’ll want to specify an AxisRenderer object for the “verticalAxisRenderer” property. To customize the labels on the horizontal axis you’ll want to use specify an AxisRenderer object for the “horizontalAxisRenderer” property. The AxisRenderer object has a “labelFunction” property that allows you to specify which function to call to format the label values.

<!– Chart to display date/price data as provided by XML-based service –>
<!– Specify the ColumnChart.dataTipFunction property to provide additional formatting –>
<mx:ColumnChart width=”100%” height=”100%” dataProvider=”{svcXML.result.data.airfare}” showDataTips=”true” dataTipFunction=”formatDataTip”>
  <mx:horizontalAxis>
    <mx:CategoryAxis dataProvider=”{svcXML.result.data.airfare}” categoryField=”when” />
  </mx:horizontalAxis>
  <mx:horizontalAxisRenderer>
    <mx:AxisRenderer labelFunction=”formatWhen” />
  </mx:horizontalAxisRenderer>
  <mx:verticalAxisRenderer>
    <mx:AxisRenderer labelFunction=”formatPrice” />
  </mx:verticalAxisRenderer>
  <mx:series>
    <mx:Array>
      <mx:ColumnSeries yField=”price” />
    </mx:Array>
  </mx:series>
</mx:ColumnChart>

The hardest part of this for me was in understanding how to represent it all in MXML. Properties can be specified on the MXML tag (class instantiation) itself, or they can also take the form of children elements. For example the following two sets of MXML have the same result.

<mx:Label text=”Macromedia” />

<mx:Label>
  <mx:text>Macromedia</mx:text>
</mx:Label>

With this in mind, I specified the “horizontalAxisRenderer” and “verticalAxisRenderer” properties as child elements to the ColumnChart. Since the properties expect an AxisRenderer object, I then take the next step of providing an instance of the AxisRenderer class as a child element of the property declarations. The “labelFunction” property on the AxisRenderer specifies what function to call to format the label.

// Formats the labels for the vertical axis of the chart (price)
// Called during the initial construction of the chart and whenever refresh is needed
private function formatPrice( label:String ):String {
  return fmtPrice.format( label );
}

// Formats the labels for the horizontal axis of the chart (date)
// Called during the initial construction of the chart and whenever refresh is needed
private function formatWhen( label:String ):String {
  return fmtWhen.format( label );
}

Unlike the “labelFunction” on the List control (and related controls), the data type expected by your custom label function is a string value of what’s to be displayed in the label prior to your customization. Subsequently, the return value of the custom label function should be the string you want to display.

Once again, since I’m displaying a date value on the horizontal axis, the DateFormatter class comes in very handy. The label function gets a string, not a Date object, but the DateFormatter doesn’t particularly mind; it parses and formats the string just as you might expect it to behave if you were passing an actual Date object.

I took one additional step for this customer in providing two different data services for the charts. The customer was working with XML, which is a perfectly valid service in Flex. Depending on the number of data points however, XML may become too verbose to use efficiently as a data service. In this case, the binary data transport of remote objects might be better suited to the task. I’ve provided both and let the customer determine what’s best for their architecture.

The code for the charts and the data services is available for download. There’s nothing fancy going on in the user interface beyond displaying the charts, so rather than my usual Captivate demo, the following is a screen shot of what the application looks like when it is running - and with it’s wonderfully formatted tips and labels nonetheless (smile).

This entry was posted on Tuesday, March 1st, 2005 at 9:37 am and is filed under Flex. You can follow any responses to this entry through the RSS 2.0 feed. You can skip to the end and leave a response. Pinging is currently not allowed.