Data Labels

If you've viewed the example PopChart image that we've been customizing throughout this documentation (see Example 4.7 on page 4-19) in a web browser, you probably noticed that the values for each bar appear in a box above the bar as you move your mouse over that bar.

This small box is called a data label. Data labels help indicate the value(s) of certain data items. Any graph can have them. And now, with PopChart Server 4.0.5, you have complete control over what exactly appears in the data label box.

Note: If you need a box to pop up over just one or a few data items, you should use PopUp text (refer to "PopUp Text").

Turning Data Labels on

Most of the time, you will turn data labels on in your appearance file. In fact, by default, rollover data labels are turned on automatically for any graph that you create in PopChart Builder. To turn them on or off, you can right click on a graph, select Data Labels, and choose an appropriate setting for Show Data Labels.

You can also turn them on or off in PopChart XML. To do so, use the DataLabels element. Set its Visible attribute to True to enable them, or False to disable them. If there is no DataLabels tag, or there is no Visible attribute, data labels are assumed to be on.

Roll-over Versus Always On

There are two ways of displaying data labels: always on, and roll-over. Always on means that the data labels will always be visible over every data item. Roll-over means that a data label will appear only as a user "rolls" his or her mouse over the data item it is associated with. Rollover data labels is the default setting.

You can select the data label display method in the Show Data Labels box of PopChart Builder.

You can select the data label display method in PopChart XML by setting the ShowOnRollover attribute of the DataLabels element. Setting it to true sets the display method to rollover (default), and setting it to false sets the display method to always on, as is the case with the following tag.

Note: Rollover data labels is supported in GIF and PNG images via image maps. There are several consequences of this. First of all, you cannot use rollover data labels in GIF or PNG images without the PopChart Embedder. Also, feedback for rollover data labels in GIF and PNG images may be slow no matter how you embed your PopChart images. Finally, you will be unable to customize the appearance of your rollover data labels.

Changing the Data Label Format

A new feature in PopChart Server 4.0.5 is the ability to customize the format of your data labels.

Data Labels can now be customized using macros. For example, in previous versions you only had one option for displaying data labels: the number only. Now, using macros, instead of having a data label that says 43, you can have one that says Price: $43. When combined with showing data labels on rollover, customized data label formatting may virtually eliminate the need for PopUp Text.

Macros are text keywords that stand for a data-specific value, such as a series or category name, or a data value. By using macros, you can make it so that each data label contains information pertinent only to the data item it is associated with.

Table 7.2 lists the available data label formatting macros.
Table 7.2 Data Label Macros
Macro Description Graphs

%_CATEGORY_NAME The name of the category that the data item belongs to. All, except X-Y and Time Plot

%_CATEGORY_TOTAL The sum of all data values in the category to which the data item belongs. Area, Bar, Line, Pareto, Pie, Radar

%_CLOSE_VALUE The close value for a high-low data item. Stock

%_GRAPH_TOTAL The sum of all data values in a bar, line, pie, or radar graph. Area, Bar, Line, Pareto, Pie, Radar

%_HIGH_VALUE The high value for a high-low data item. Stock

%_LOW_VALUE The low value for a high-low data item. Stock

%_OPEN_VALUE The open value for a high-low data item. Stock

%_PERCENT_OF_CATEGORY The data value represented as a percentage of the sum of all data values in its category. Area, Bar, Line, Pareto, Pie, Radar

%_PERCENT_OF_TOTAL The data value represented as a percentage of the sum of all data values in the graph. Area, Bar, Line, Pareto, Pie, Radar

%_SERIES_NAME The name of the data series that the data item belongs to. All

%_TIME_VALUE The time value for a Time Plot data item. Time Plot

%_VALUE The value of the data item. Area, Bar, Line, Pareto, Pie, Radar

%_XVALUE The x value for an X-Y data item. X-Y

%_YVALUE The y value for an X-Y or Time Plot data item. X-Y, Time Plot

Table 7.2 Data Label Macros
Macro	Description	Graphs

%_CATEGORY_NAME	The name of the category that the data item belongs to.	All, except X-Y and Time Plot
%_CATEGORY_TOTAL	The sum of all data values in the category to which the data item belongs.	Area, Bar, Line, Pareto, Pie, Radar
%_CLOSE_VALUE	The close value for a high-low data item.	Stock
%_GRAPH_TOTAL	The sum of all data values in a bar, line, pie, or radar graph.	Area, Bar, Line, Pareto, Pie, Radar
%_HIGH_VALUE	The high value for a high-low data item.	Stock
%_LOW_VALUE	The low value for a high-low data item.	Stock
%_OPEN_VALUE	The open value for a high-low data item.	Stock
%_PERCENT_OF_CATEGORY	The data value represented as a percentage of the sum of all data values in its category.	Area, Bar, Line, Pareto, Pie, Radar
%_PERCENT_OF_TOTAL	The data value represented as a percentage of the sum of all data values in the graph.	Area, Bar, Line, Pareto, Pie, Radar
%_SERIES_NAME	The name of the data series that the data item belongs to.	All
%_TIME_VALUE	The time value for a Time Plot data item.	Time Plot
%_VALUE	The value of the data item.	Area, Bar, Line, Pareto, Pie, Radar
%_XVALUE	The x value for an X-Y data item.	X-Y
%_YVALUE	The y value for an X-Y or Time Plot data item.	X-Y, Time Plot

PopChart Builder

To customize your data labels in PopChart Builder, select a graph, right click on it, and select Data Label Properties. The Data Label Format (All Graphs Except Pie) text box lets you change the data label format. A list of available macros is shown below the Value keywords pull-down menu below. You can insert any of these macros into the text box by selecting the macro and clicking on the Insert button.

In PopChart Builder, you can also change the data label format for an individual data series. Simply edit the value in the Data Label Format text box of the Series Properties > Data Labels pane.

PCScript

To customize your data label with PCScript, use the graph. SetDataLabelFormat() method. This method accepts a string of text and macros.

For example, by default the data label format is simply %_VALUE. This will display only the data value in the data label. If you wanted the data label to display the data series name, followed by a colon, followed by a dollar sign, followed by the data value (e.g Price: $43), you could change the data label format to %_SERIES_NAME: $%_VALUE. The PCScript command below sets this format for you:

graph.setDataLabelFormat(%_SERIES_NAME: $%_VALUE)

PopChart XML

You can also customize your data label in PopChart XML by setting the FormatString attribute of the DataLabels element, as shown below.