SAS/GRAPH Software: Reference

About Drill-down Graphs

A drill-down graph has designated areas or hot zones that are linked to a target output, such as other graphs or reports. The target output can be in a different location on the same Web page, or it can be on a different Web page. If the target output contains another graph, that graph can also have hot zones that link to additional targets. In this way, you can establish a series of links that drill down to more and more detailed information.

Drill-down on a Bar Chart shows a bar chart with three bars. Assume that the bars represent a company's regional sales, and that the third bar represents the western region. If the chart is a drill-down graph, with each bar linking to a report on the corresponding region's sales, then selecting the third bar drills down to a report on sales for the western region.

Drill-down on a Bar Chart

[IMAGE]

The hot zones in a drill-down graph can be the graphic areas (for example, the bars in a bar chart or slices in a pie chart) or the pattern boxes that identify legend entries. SAS/GRAPH defines the hot zones for you, based on the specifications you make on the graphics procedure that is used to produce the graph. You use the HTML= option to make hot zones in the graphic areas and the HTML_LEGEND= option to make hot zones in the legend. You provide the link information by storing the paths to target output in a special HTML variable, which is usually created in the data set that is used to generate the graph.

Only procedures that support the IMAGEMAP= option, or the HTML= or HTML_LEGEND= options, can be used for drill-down graphs, although you can also generate drill-down graphs using the DATA Step Graphics Interface (DSGI). Procedures that Support Drill-down Graphs lists those procedures and shows where the HTML variable that stores the linking information is specified for each of them.

Procedures that Support Drill-down Graphs
Procedure Location where HTML variable is supported

PROC GANNO Supports the HTML variable from the Annotate data set that is used to generate the graph.

PROC GCHART The following statements support the HTML= or HTML_LEGEND= option:

BLOCK statement

DONUT statement

HBAR, HBAR3D statements

PIE, PIE3D statements

STAR statement

VBAR, VBAR3D statements.

PROC GMAP The following statements support the HTML= or HTML_LEGEND= option:

BLOCK statement

CHORO statement

PRISM statement.

PROC GPLOT The following statements support the HTML= or HTML_LEGEND= option:

PLOT statement

PLOT2 statement.

PROC GREPLAY Replays a drill-down graph from the graphics catalog, so the HTML variable must be specified on the HTML= or HTML_LEGEND= option on the procedure that stores the original graph in the catalog.

PROC GSLIDE Supports the HTML variable from the Annotate data set that is used to generate the graph.

***Procedures that Support Drill-down Graphs***
Procedure	Location where HTML variable is supported
PROC GANNO	Supports the HTML variable from the Annotate data set that is used to generate the graph.
PROC GCHART	The following statements support the HTML= or HTML_LEGEND= option: BLOCK statement DONUT statement HBAR, HBAR3D statements PIE, PIE3D statements STAR statement VBAR, VBAR3D statements.
PROC GMAP	The following statements support the HTML= or HTML_LEGEND= option: BLOCK statement CHORO statement PRISM statement.
PROC GPLOT	The following statements support the HTML= or HTML_LEGEND= option: PLOT statement PLOT2 statement.
PROC GREPLAY	Replays a drill-down graph from the graphics catalog, so the HTML variable must be specified on the HTML= or HTML_LEGEND= option on the procedure that stores the original graph in the catalog.
PROC GSLIDE	Supports the HTML variable from the Annotate data set that is used to generate the graph.

Ways You Can Generate a Drill-down Graph

You can generate a drill-down graph using the SAS/GRAPH Web drivers or using ODS. The approach you should use depends on your Web-page or site design.

Using Web Drivers to Generate Drill-down Graphs

To link to individual graphs, it is easiest to use the Web drivers to generate the drill-down graphs. The Web drivers create all the files you need and require the fewest specifications in your SAS code. For an example, see Example 3: Using a Web Driver to Generate a Drill-down Graph.

The Web drivers do not assign anchor names to the output they generate. Thus, they are not useful for linking to multiple pieces of output that are stored or referenced in one HTML file. Also, you cannot use the Web drivers to generate drill-down graphs in a SAS program that also generates ODS output; they are designed as an alternative to using ODS.

Using ODS to Generate Drill-down Graphs

To link to both graphics and non-graphics output, or to link to multiple graphs that are stored or referenced in a single file, it is easiest to use ODS to generate the drill-down graphs. For an example, see Example 4: Using ODS to Generate a Drill-down Graph. Also, if you want to design the attributes of your Web page, ODS enables you to use style definitions. For example, you can set the fonts and color for text. For information on style sheets, see The Complete Guide to the SAS Output Delivery System.

To generate a drill-down graph with ODS, your main responsibility is to create the required HTML variables and assign to those variables the appropriate linking information in the form "URL#anchor-name".

URL The location and name of the HTML file that contains the target. When you use ODS, the URL is composed of information you specified on the ODS HTML statement options BASE=, PATH= or GPATH=, and BODY= (for more information, see How ODS Constructs Links and References).

anchor name The target's location within the HTML file. An anchor name must be unique within an HTML file. You can let ODS assign default anchor names, or you can specify anchor names in the ODS HTML statement's ANCHOR= option. If a target is located at the top of the HTML file that contains it, the anchor name is optional on the HREF value because, by default, a Web browser displays information that is at the top of the HTML file.

ODS always assigns anchor names to the output it generates; that way, the output can be used as the target to a link, no matter where the output is located. It does not matter whether the output is all written to the same HTML file or to separate HTML files. The default system for assigning anchor names always starts with IDX for the first piece of output that is generated after the HTML destination is opened and increments that name (IDX1, IDX2, ...) for each piece of output that is written until the HTML destination is closed. If the HTML destination is opened again during the current SAS session, the default naming scheme starts over again, beginning with IDX.

The value that you assign to an HTML variable must be the HREF value that is needed for the HTML link. Therefore, to define a link for a drill-down graph, you must know what URL is needed to access the target output and what anchor name ODS assigns to that output.

While planning your Web page, you have to decide whether to let ODS assign default anchor names, or whether to control anchor names yourself using the ODS HTML statement's ANCHOR= option. Generally, the default anchor names will suffice for simple drill-down graphs or when each link target contains only a single piece of output in its own HTML file. You may want to control anchor names when you use multiple procedures to generate the target output because it will be easier to keep track of the anchor names. You may also want to control anchor names when you open a body file to append output to it; in this case, controlling anchor names prevents ODS from using the same default anchor names as were used when the file was first created.

Customizing a Web Page for a Drill-down Graph

To get complete control over Web page design, you can customize a Web page for use with a drill-down graph by writing your own HTML files, letting SAS/GRAPH generate the drill-down graph. To customize a Web page, you must know how to

write the HTML tags needed to design the Web page
implement HTML links
use an image map to implement a drill-down graph.

However, you do not have to know how to create an image map, because SAS/GRAPH does that for you. For details, see Customizing Web Pages for Drill-down Graphs. For an example, see Example 5: Customizing a Web Page with a Drill-Down Graph.

General Requirements for Generating a Drill-down Graph

Generally, to create a drill-down graph, you provide the link information needed to connect the graph to its related output. Your SAS program must do the following:

create an HTML variable to hold HTML link locations. Typically, for each drill-down level, you create one HTML variable to store the links for the graphic areas; to create links from the legend, you can use that same variable or a separate variable to store links for the legend values. For example, to implement the graph in Drill-down on a Bar Chart, you need only one HTML variable for the bars in the chart.
assign values to the HTML variable(s). These values are the link locations that connect the graph to its target output.
run a SAS/GRAPH procedure to create the drill-down graph(s). This procedure must use an HTML= option, an HTML_LEGEND= option, or both to associate the HTML variable(s) with the graph. Or, if the drill-down capability is being implemented from an Annotate data set, the Annotate data set's HTML variable must specify the link locations (for an example, see Using Annotate Graphics in a Drill-down Graph).
If you are using the HTML or WEBFRAME device drivers, or if you are writing your own HTML files, you must also use the IMAGEMAP= option to create a data set that can be used to generate an image map for the drill-down capability.
run the procedures that create the target output. The target output must be directed to the locations identified by the HTML variable.

Because an HTML variable stores the HTML link locations for target output, you must understand HTML links in order to assign values to it. You should also know what an image map is, because SAS/GRAPH uses image maps to attach HTML links to drill-down graphs (see Image Maps in Drill-down Graphs).

HTML Links in Drill-down Graphs

In HTML files, links are specified as HREF attributes on tags that support linking. The HREF value must point to the location of the link target, which is identified by a URL or a URL and an anchor name in the form

HREF="URL#anchor-name"

URL	The location and name of the HTML or GIF file that contains the target.
anchor name	The target's location within the HTML file. An anchor name must be unique within an HTML file. If a target is located at the top of the HTML file that contains it, the anchor name is optional on the HREF value because, by default, a Web browser displays information that is at the top of the HTML file.

In Drill-down on a Bar Chart, the bars represent regional sales, and the third bar represents the western region. If the third bar drills down to a report, and if that report is stored in your file system at the top of a file named west.html, then the following HREF points to the report:

 HREF="west.html"

Here, only a filename is given. The file west.html is, therefore, assumed to be in the same storage location as the HTML file where the link is initiated. The anchor name is omitted because the report is at the top of file west.html, so the anchor name isn't needed. However, if the report is not at the top of the file, the HREF must specify the anchor name.

In an HTML file, anchor names are assigned on the NAME attribute of an <A> (anchor) tag. In the following example, the anchor name west is assigned to the table that follows it:

<A NAME="west" ></A>
<P>
<TABLE><TR><TD>
Western Sales
</TD></TR></TABLE>

If the report is stored in a file named reports.html, as is the case for Drill-down on a Bar Chart, then the following HREF points to the report at the west location:

 HREF="reports.html#west"

More HREF= values are shown in Assigning Values to HTML Variables.

For information on how ODS constructs HTML links and references, see How ODS Constructs Links and References.

Image Maps in Drill-down Graphs

Image maps are defined in HTML files and are used to implement drill-down capability for GIF images (Java applets and ActiveX controls use their own internal mechanisms). An image map defines the graphic areas that you can select to link to other locations. For example, in Links in Drill-down Graphs, the third bar in the image barchart.gif links to a report that is stored in the file reports.html, which is located at anchor name west. To implement the drill-down capability, an image map must define that third bar as a hot zone by identifying its coordinates and linking those coordinates to the report's location.

Links in Drill-down Graphs

[IMAGE]

In an HTML file, an image map is defined within <MAP> tags, which are used to encompass <AREA> tags that define the areas that will serve as hot zones for the links. Each <AREA> tag has the following attributes:

a SHAPE attribute to identify the area either as a rectangle (RECT) (for example, any of the bars in Links in Drill-down Graphs) or a polygon (POLY) (for example, a three-dimensional bar from a bar chart)
a COORDS attribute to identify the coordinates of the hot zone
an HREF attribute to define the link location of the target output.

For example, the chart shown in Links in Drill-down Graphs is stored in file barchart.gif, which is referenced in an HTML file named sales.html. To give barchart.gif drill-down capability, sales.html must contain HTML tags to define an image map that is assigned to barchart.gif. The image map must have <AREA> tags that identify the coordinates of each of the three bars in the chart, and that define a link target for each bar. The image map is assigned to the graph on the USEMAP attribute of the <IMG> tag that references the graph's GIF file.

In the following image map, the HREF attributes link each bar to an HTML file named reports.html. The target output for each bar is directed to a different anchor location; the anchor names for the target output are central, south, and west. File reports.html is in the same location as the file that contains the image map, because no other location is identified.

<MAP NAME="BARCHART">
<AREA SHAPE=RECT COORDS="424, 143, 470, 256"
      HREF="reports.html#central">
<AREA SHAPE=RECT COORDS="366, 175, 412, 256"
      HREF="reports.html#south">
<AREA SHAPE=RECT COORDS="308, 106, 354, 256"
      HREF="reports.html#west">
</MAP>
<P>
<IMG SRC="barchart.gif" USEMAP="#BARCHART">

When you select a bar in the graph, the browser uses the image map to find the correct report to link to, as shown in Links in Drill-down Graphs.

The image map for a particular graph must be defined in the same HTML file that contains the <IMG> tag that references that graph. However, the map can be located anywhere in the file. For example, the image map can be defined at the very end of the HTML file, even though the <IMG> tag for the graph that uses the map is at the top of the HTML file.

SAS/GRAPH automatically generates image maps; you do not have to know how to create an image map, and you do not have to supply values for its SHAPE or COORDS attributes. When you use ODS, SAS/GRAPH writes the image map directly in the HTML file that contains the reference to the drill-down graph. When you use the Web drivers to generate the drill-down graph, SAS/GRAPH stores the image map information in an Imagemap data set (see About the Imagemap Data Set).

Whether you use ODS or the Web drivers to implement a drill-down graph, you must supply HREF values that identify the locations of the target output. You provide these values by assigning them to an HTML variable and specifying that variable on the graphics procedure that produces the drill-down graph. For details, see Creating HTML Variables.

About the Imagemap Data Set

To create a drill-down graph using the SAS/GRAPH Web drivers, you specify the IMAGEMAP= option on the PROC statement of the procedure that generates the drill-down graph. The following graphics procedures have the IMAGEMAP= option:

GANNO

GCHART

GMAP

GPLOT

GREPLAY

GSLIDE

Note: With ODS, you do not use the IMAGEMAP= option, and SAS/GRAPH does not create an Imagemap data set. [cautionend]

The name of the data set can be any valid SAS data set name. The code that specifies it should resemble the following:

proc gchart data=regsales imagemap=salemap;
  vbar3d region / sumvar=sales
   patternid=midpoint
   html=links name='htmldril';

Here, the IMAGEMAP= option names the data set SALEMAP. The HTML= and/or HTML_LEGEND= option must also be used on the procedure to identify the HTML variable that contains the linking information (see Creating HTML Variables).

The IMAGEMAP= option creates an Imagemap data set, which contains information about the hot zones in the graph. If you generate your output with the HTML or WEBFRAME device drivers, the driver automatically uses the data set to implement the drill-down capability. If you customize your own Web pages (see Customizing Web Pages for Drill-down Graphs), you specify the Imagemap data set as an argument on the IMAGEMAP macro that writes the image map to your HTML file:

%imagemap(salemap, vbar);

This call to the macro assumes that VBAR is the fileref for the HTML file that references the drill-down graph. For more information on the IMAGEMAP macro, see About the IMAGEMAP Macro.

The Imagemap data set contains the following variables:

GRAPH a character variable (length 8) that contains the name of the graph. The name of the graph is the name of the catalog entry.

LENGTH a numeric variable (length 4) that contains the length of the LINK variable.

LINK a character variable (maximum length 1024) that contains the values from the input data set variables specified by the HTML= and HTML_LEGEND= options. This information specifies the action taken when the corresponding polygon or legend entry is selected. It may be an actual HREF value or other information that the application can use to associate the area with the desired reference.

NXY a numeric variable (length 4) that contains the number of coordinates (x,y pairs) in the area. If SHAPE='RECT', then NXY has a value of 2; the first pair of coordinates are the lower- left corner and the second pair of coordinates are the upper- right corner. If SHAPE='POLY', NXY contains the actual number of points in the polygon. The POLY shape is a polygon with a maximum of 100 vertices.

SHAPE a character variable (length 4) that describes the shape of the areas in the graph. The value of SHAPE is either 'POLY' or 'RECT'. For example, for a bar chart or a legend, the value of SHAPE is RECT; for a pie chart or map, the value of SHAPE is POLY.

X1...X100 numeric variables (length 4) that contain the x coordinates of the shape.

Y1...Y100 numeric variables (length 4) that contain the y coordinates of the shape.

Creating HTML Variables

HTML variables are used with ODS to create graphs with drill-down capability. The HTML variable is a character variable that stores the HTML link locations for target output. You must create the HTML variables by adding them to the data set that is used to produce the drill-down graph. Typically, you create the HTML variables in a DATA step.

The following code fragment creates the HTML variable RPT and assigns it a length of 40 characters so that it can store a long string:

 /* create data set REGSALES */
data regsales;
  input Region State Sales;
/* create the HTML variable */
  length rpt $40

Assigning Values to HTML Variables

Drill-down graphs use image maps to define hot zones in GIF graphs and to identify each hot zone's link target. A hot zone is defined on an <AREA> tag, and the zone's link target is specified as a value on the <AREA> tag's HREF attribute (see Image Maps in Drill-down Graphs). SAS/GRAPH automatically creates the image maps for you, but you must provide the HREF values by first assigning those values to an HTML variable and then specifying that variable on an HTML= or HTML_LEGEND= option on the procedure that produces the drill-down graph.

The HTML variable must be a character variable, so the value you assign to it must be a string. Always begin the string with href= followed by the link location in the form "URL#anchor-name". The following code assigns a valid value to an HTML variable named RPT:

RPT='href="reports.html#west"';

Note: To form valid HTML, the URL and anchor name must be enclosed in double quotation marks, as shown in the example. [cautionend]

Using the RPT variable's value in an image map, SAS/GRAPH can build an <AREA> tag that resembles this:

<AREA SHAPE="RECT" COORDS="424,143,470,256"
      HREF="reports.html#west">

To specify an HREF value correctly, you must know in advance the correct location to specify for the link target. This requires you to plan your SAS program. You need to decide such issues as

whether to write the link-target output to one or to multiple files.
whether your users will access the output through the Web or through your file system. To provide access through the Web, you need to provide complete URLs for the links. To provide access through your file system, you only need to provide file specifications.

Valid Forms for the HTML Variable's Values shows the forms you can use to assign values to an HTML variable.

Valid Forms for the HTML Variable's Values
Value Assigned to an HTML Variable Implications

'HREF="<path>reports.html"'
'HREF="<path>reports.html#west"'
Tells the browser to look in the file reports.html. If <path> is not provided, the file must be in the same location as the HTML file that initiates the link.
For the value that has #west, go to the output with the anchor name west.
Users must have access to your file system in order to access the link target.

'HREF="http://www.company.com/web/reports.html"'
'HREF="http://www.company.com/web/reports.html#west"'
Tells the browser to go to the Web site address http://www.company.com and look in the file web/reports.html. For the value that has #west, go to the output with the anchor name west.
Users must have access to the Web.

'HREF="#west"' Go to the output with the anchor name west. The target output must be referenced or contained in the same HTML file as the drill-down graph that contains the link. For example, if the drill-down graph is in file sales.html, then the target output must be referenced or contained in sales.html.
Because this target output is in the same file as the drill-down graph, this link will work whether the output is viewed within your file system or across the Web.

***Valid Forms for the HTML Variable's Values***
Value Assigned to an HTML Variable	Implications
'HREF="<path>reports.html"' 'HREF="<path>reports.html#west"'	Tells the browser to look in the file reports.html. If <path> is not provided, the file must be in the same location as the HTML file that initiates the link. For the value that has #west, go to the output with the anchor name west. Users must have access to your file system in order to access the link target.
'HREF="http://www.company.com/web/reports.html"' 'HREF="http://www.company.com/web/reports.html#west"'	Tells the browser to go to the Web site address http://www.company.com and look in the file web/reports.html. For the value that has #west, go to the output with the anchor name west. Users must have access to the Web.
'HREF="#west"'	Go to the output with the anchor name west. The target output must be referenced or contained in the same HTML file as the drill-down graph that contains the link. For example, if the drill-down graph is in file sales.html, then the target output must be referenced or contained in sales.html. Because this target output is in the same file as the drill-down graph, this link will work whether the output is viewed within your file system or across the Web.

Typically a drill-down graph has multiple hot zones, each of which links to different output. This means your HTML variable needs different values, based on the criteria used to produce the graph. For example, if the bars in a bar graph represent sales regions, then the values of the HTML variable will be based on those sales regions.

To assign values to the HTML variable, you can include the variable in the DATA step's INPUT statement and specify the values in the DATALINES statement. Or you can specify the values programmatically, perhaps in a conditional block such as an IF/THEN statement.

In Links in Drill-down Graphs, assume that the three bars represent regional sales for a company's central, southern, and western regions.

Links in Drill-down Graphs

[IMAGE]

To link each bar to a report on that region's sales figures, you need one HTML variable to store the HREF links. The HTML variable needs to point to a different location for each of the three regions. If you decide to write all the reports to a file named reports.html that your users will access through your file system, and if the reports have anchor names central, south, and west, you might write a DATA step that resembles the following:

/* create data set REGSALES */
data regsales;
   length Region State $ 8;
   format Sales dollar8.;
   input Region State Sales;
   length rpt $40; /* the HTML variable */

/* assign HREF values to HTML variable */
if Region='Central' then
     rpt='HREF="reports.html#central"';
  else if Region='South' then
     rpt='HREF="reports.html#south"';
  else if Region='West' then
     rpt='HREF="reports.html#west"';

  datalines;
West CA 13636
West OR 18988
West WA 14523
Central IL 18038
Central IN 13611
Central OH 11084
Central MI 19660
South FL 14541
South GA 19022
;

Values in the REGSALES Data Set shows the values in the data set REGSALES.

Values in the REGSALES Data Set

[IMAGE]

To use the HTML variable to create hot zones on the bars of the drill-down chart, you must specify it in the HTML= option of the graphics procedure that produces the graph.

GRAPH	a character variable (length 8) that contains the name of the graph. The name of the graph is the name of the catalog entry.
LENGTH	a numeric variable (length 4) that contains the length of the LINK variable.
LINK	a character variable (maximum length 1024) that contains the values from the input data set variables specified by the HTML= and HTML_LEGEND= options. This information specifies the action taken when the corresponding polygon or legend entry is selected. It may be an actual HREF value or other information that the application can use to associate the area with the desired reference.
NXY	a numeric variable (length 4) that contains the number of coordinates (x,y pairs) in the area. If SHAPE='RECT', then NXY has a value of 2; the first pair of coordinates are the lower- left corner and the second pair of coordinates are the upper- right corner. If SHAPE='POLY', NXY contains the actual number of points in the polygon. The POLY shape is a polygon with a maximum of 100 vertices.
SHAPE	a character variable (length 4) that describes the shape of the areas in the graph. The value of SHAPE is either 'POLY' or 'RECT'. For example, for a bar chart or a legend, the value of SHAPE is RECT; for a pie chart or map, the value of SHAPE is POLY.
X1...X100	numeric variables (length 4) that contain the x coordinates of the shape.
Y1...Y100	numeric variables (length 4) that contain the y coordinates of the shape.