DDEnable

Syntax graph.DDEnable(Category, Series, URL [,Target] [;Categories, Series, URL [,Target]]*)

Description Adds drill-down effects to any data item(s) that are in the specified categor(ies) and series.

Drill-down effects include linking to a different web page or executing a JavaScript function. The drill-down effect will occur whenever a user clicks his or her mouse over a specific data item. More information about drill-down effects is available in "Drill-down Effects" in Chapter 7 of the PopChart Server User Guide.

You can use any combination of static text and data macros to create unique drill-down effects for every data item in your graph.

For example, suppose that whenever a user clicks on the graph, you want the graph to drill-down to a web page generated by your web application server at http://webapp.mycompany.com/drilldown. However, you also want to be able to tell the web application what data item the user just clicked on. One way of doing this would be to pass the following macro to the Graph.DDEnable method:

http://webapp.mycompany.com/drilldown?category=%_CATEGORY_NAME&series=%_SERIES_NAME.

So, for example, if a user clicks on the data item in the South category and the Summer series, the user would drill-down to this URL: http://webapp.mycompany.com/drilldown?category=South&series=Summer.

Example 5.14 illustrates how to make use of macros in a Graph.DDEnable statement. See the paragraph that follows it to learn what the example does.

Each Graph.DDEnable method can specify any number of drill-down effects. The parameters for each drill-down effect should be separated by a semi-colon (or the item delimiter, which is specified in the Main. ItemDelimiter method).

Note: If you are loading data via the graph. LoadFile command, be sure to call DDEnable after you call graph. LoadFile. Otherwise, PopChart Server will be unable to associate your drill-down effect with the correct data item.

Specifies the category or categories of the data item(s) for which drill-down effects should be enabled. This value can be an integer, a range of integers, or the name of a category that has been specified in a Graph. AppendByRow method.

If the value of this parameter is an integer, it refers to the nth category listed in the Graph. SetCategories method, where n is the integer specified. So, for example, if Fred is the second category name listed in the Graph. SetCategories method, and we pass 2 as the value of the categories parameter, we are referring to the Fred category.

If you wish to access a category number that is the same as another category's name, you will need to use the pound # sign before the category number. This lets PopChart Server know that you are referring to a category number instead of a category name.

For example, if category number 5 is named 3, then the statement graph.DDEnable(3,1,index.html) will add a drill-down effect to category number 5, not 3, as it assumes you are referring to the category name. However, if you include a pound # sign before the number 3—graph.DDEnable(#3,1,Hello)—then PopChart Server will override the category name and instead add the drill-down effect to category number 3.

A range of categories is denoted by an integer, followed by a hyphen, followed by another integer. The first integer represents the first category that should have this drill-down effect, while the last integer indicates the last category that should have the drill-down effect. All categories in between will also have the drill-down effect. Line 5 of Example 5.12 gives an example of a range of categories.

Because X-Y and Time graphs do not use categories, the value of this parameter for those graphs is the number of the data point in the specified data series to which you want to add a drill-down effect. Example 5.13 illustrates this difference.

If you choose 0 as the category number, the drill-down effect will be added to the appropriate series name(s) in the legend.

Note: Make sure that you don't turn Sort Data for your appearance file (by checking Properties > Graph Properties > General > Sort Data) when you use drill-down effects with X-Y and Line graphs. Otherwise, the drill-down effects may occur at the wrong data point.

Specifies the series of the data item(s) for which drill-down effects should be enabled. This value can be an integer, a range of integers, or the name of a series that has been specified in a Graph. SetSeries method.

If the value of this parameter is an integer, it refers to the nth series listed in the Graph. SetSeries method(s), where n is the integer specified. For example, if Fruit is the name of the series described in the second Graph. SetSeries method, and we pass 2 as the value of the series parameter, we are referring to the Fruit series.

If you wish to access a series number that is the same as another series' name, you will need to use the pound # sign before the series number. This lets PopChart Server know that you are referring to a series number instead of a series name.

For example, if series number 5 is named 3, then the statement graph.DDEnable(1,3,index.html) will add a drill-down effect to series number 5, not 3, as it assumes you are referring to the series name. However, if you include a pound # sign before the number 3—graph.DDEnable(1,#3,index.html)—then PopChart Server will override the series name and instead add the drill-down effect to series number 3.

A range of series is denoted by an integer, followed by a hyphen, followed by another integer. The first integer represents the first series that should have this drill-down effect, while the last integer indicates the last series that should have the drill-down effect. All data series in between will also have the drill-down effect. A range of series looks exactly like the range of categories specified in Line 5 of Example 5.12.

Either the web page that the data item(s) will drill-down to, or a JavaScript function.

If the URL parameter is a web page, the link will be relative to the location of the web page that contains the PopChart image. Or, by prefixing the URL with http://, you can specify an absolute path to a web page.

If the URL parameter is a JavaScript function, it must be prefixed with javascript:. The function must also have been declared within the web page that contains the PopChart image.

The URL can also contain macros, which represent values that are data item specific. In this manner, you can create a global drill-down destination for the graph (see Example 5.14). Table 5.6 lists the available drill-down macros.

Table 5.6 Drill-down 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_NUMBER	The number of the data series that the data item belongs to.	All, except X-Y and Time Plot
%_POINT_NUMBER	The number of the data item in the data series (e.g, the first plot point=1).	X-Y and Time Plot
%_SERIES_NAME	The name of the data series that the data item belongs to.	All
%_SERIES_NUMBER	The number of the data series that the data item belongs to.	All

The target within the web page (specified by the URL parameter) to which the data item(s) will drill-down. This parameter is optional and should not be used when drilling-down to a JavaScript function.

Example 5.12 Adding Drill-down Effects

graph.SetCategories(Produce; Poultry; Pastries)

graph.SetSeries(March;190;161;96)

graph.SetSeries(April;295;150;113)

graph.SetSeries(May;374;142;117)

graph.DDEnable(Pastries, May, pastry.html)

graph.DDEnable(3, 3, pastry.html)

graph.DDEnable(2-3, March, http://www.foodsales.com/march.html)

graph.AddPopupText(Poultry, 3, javascript:alert('Poultry sales are falling!'); 2, 1, poultry.html, march)

Lines 5 and 6 in Example 5.12 are the same command. The first just uses category and series names, while the second uses numbers. In both cases, the data item in the Pastries category and the May series will "drill-down" to the web page pastry.html when a user clicks on it.

Line 7 shows how to incorporate a range of data items. Data items in the March series and in categories 2-3 (Poultry and Pastries) drill-down to the web site http://www.foodsales.com/march.html.

Line 8 illustrates several drill-down features. First of all, it shows how more than one drill-down effect can be added with just one Graph.DDEnable command. Secondly, it shows how a JavaScript function may be used in place of a URL. In this case, the data item in the Poultry category and the May series will execute the function alert('Poultry sales are falling!') when the user clicks on it. Finally, the second drill-down effect shows how a target may be specified. In this case, the data item in the Poultry category and March series will drill-down to the target march in the web page poultry.html.

Example 5.13 Drill-down Effects for an X-Y Line Graph

graph.Series(Blue; 7,10; 30,0; 23,30)

graph.SetSeries(Red; 0,10; 5,0; 10,7)

graph.DDEnable(3, Blue, http://www.blue.com)

Example 5.13 shows how Graph.DDEnable differs for X-Y and Time graphs. In this case, the third data point in the Blue series (23,30) drills-down to the website http://www.blue.com.

Example 5.14 Adding a Global Drill-down Destination

graph.DDEnable(1-99,1-99,http://www.myappserver.com/newscript?Series=%_SERIES_NUMBER&Category=%_CATEGORY_NUMBER)

Example 5.14 shows how you can use graph.DDEnable() to create a global drill-down destination. We aren't sure how many series or categories are in the graph, so we simply set the range from 1 to 99, assuming that there will be no more than 99 series or categories. We could easily set this range higher if we are dealing with a larger data set.

The example also illustrates the use of macros in a graph.DDEnable() statement. Macros are textual keywords that represent values that are data item specific. Macros begin with a percentage mark and an underscore (%_). The macros in this statement, %_CATEGORY_NUMBER and %_SERIES_NUMBER, refer to the data item's category and series number, respectively. So, for example, if the a certain bar is in series 2 and category 9, the drill-down URL for the bar would be http://www.myappserver.com/newscript?Series=2&Category=9.