 |
RESOURCES | |
|
Demos | |
|
Downloads | |
|
|
|
|
CLIENT GRAPHS | |
|
Control for ActiveX | |
|
Applets for Java | |
|
|
|
|
METAGRAPHICS | |
|
MetaViewApplet | |
|
|
|
|
|
|
Return to SAS/GRAPH Web Graphs | ||||||
| ||||||
| ||||||
| ||||||
|
The SAS/GRAPH Applets for Java enable you to embed interactive graphics in a Web page. When you open the Web page in a browser, you can interactively change numerous features of the graph, including its use of colors, legends, and axes. The plan for future releases of the applets is to allow you to save these changes back to your SAS/GRAPH code so that a modified graph can be regenerated any time the original data are updated, but that capability has not yet been implemented.
Software Requirements
Using SAS/GRAPH to Generate Client Graphs
for ActiveX or Java
Software Requirements for the SAS/GRAPH Applets for JavaTo generate a SAS/GRAPH Applet for Java, you can:
The SAS/GRAPH Applets for Java are rendered by JavaScript code in an
HTML file. To view the graph, you open the HTML file in a Web browser
that supports Java 1.1.4 or higher. The suggested browsers include the
following:
SAS/GRAPH Features that are Supported by the JAVA DriverSAS/GRAPH Technical Support publishes Technical Note TS-601, which contains current information on the JAVA device driver's support for SAS/GRAPH statements, options, and formats. That information includes:
To access that information, search for Technical Note TS-601 on the SAS Institute Technical Support Web site. Drill-down Modes in the SAS/GRAPH Applets for JavaThe GraphApplet and MapApplet for Java provide several drill-down modes. These modes enable you to click on a graph element to go to information that is related to that element. Note. SAS/GRAPH Contour Plots do not support the drill-down modes. The SAS/GRAPH Control for ActiveX can support two of the modes, but only when the control is generated with the SAS/IntrNet DS2GRAF macro. For information on using SAS/IntrNet to generate the control, see The GraphApplet HTML Generator.
The Drill-down Modes Are Data-DrivenThe drill-down modes in the SAS/GRAPH Applets for Java are data-driven, which means that the target addresses that they go to are constructed dynamically, based on the data values contained in a selected graph element. This contrasts with the drill-down capabilities of GIF images, which are based on pixel areas that are linked to target locations that are statically defined in an HTML file. These pixel-area links cannot be dynamically constructed while the graph is being viewed in a browser. Although the GraphApplet and MapApplet support the pixel-driven drill-down feature in their URL drill-down modes, they also provide several data-driven modes. Because these modes are data-driven, they can provide more flexibility than the URL mode, and you may want to use them in your client graphs. The following drill-down modes are available:
To specify a drill-down mode in a SAS/GRAPH program, use the ODS HTML statement's DRILLDOWNMODE parameter. Specify the drill-down mode, and also specify any other parameter(s) you need to complete the specification:
ods html parameters=("DRILLDOWNMODE"="Script"
"DRILLFUNC"="jsfunc")
Here, the DRILLDOWNMODE parameter specifies the Script mode. Because the applet needs to know what script to call, the DRILLFUNC parameter specifies the script name. Here, DRILLFUNC identifies a callback method named jsfunc(). You can use a single PARAMETERS= specification for all the parameters, or use separate PARAMETERS= options. For example, the following specification is equivalent to the one above:
ods html parameters=("DRILLDOWNMODE"="Script")
parameters=("DRILLFUNC"="jsfunc")
For more complete examples, see the discussions for the modes: Local Drill-down Mode, Script Drill-down Mode, and HTML Drill-down Mode. ODS Syntax for Specifying a Drill-down ModeTo specify one of the data-driven drill-down modes in a SAS/GRAPH program, use the ODS HTML statement's PARAMETERS= option. PARAMETERS= has the following general form:
ods html PARAMETERS=("parameter-name1"="parameter-value1"...
"parameter-name-n"="parameter-value-n")
Alternatively, You can use separate PARAMETERS= options for each parameter, as in
ods html PARAMETERS=("parameter-name1"="parameter-value1")
...
PARAMETERS=("parameter-name-n"="parameter-value-n")
The following drill-down parameters are available (other ODS parameters
are also available, but only the drill-down parameters are listed here):
Drill-down Tags that Identify Variable Roles in a GraphThe Java Graph and Java Map applets construct drill-down information by identifying the role each variable has in a graph and using each variable's value in an appropriate way, based on its role. The way that an applet uses a value depends on the graph type and the current drill-down mode. To identify a variable's role in a graph, the applets use special drill-down tags that name the role and identify the graph variable that is performing that role. For example, the tag G_INDEP identifies the role of independent variable, and the tag G_DEP identifies the role of dependent variable. The following table shows the valid drill-down tags that are used by the applets. For the Local and HTML drill-down modes, you can specify these tags as needed when defining drill-down behavior. For the Script drill-down mode, the applet itself uses these tags as arguments that it passes to the specified callback method, and the programmer who writes the callback method can retrieve them. The drill-down tags are identified here. The way that the tags are used for each drill-down mode is explained in the section that discusses that mode.
By default, unformatted values are substituted for the drill-down tags, unless an optional ",f" parameter is specified for the tag, which instructs the substitution to use formatted values. For example, G_INDEPV,f specifies the formatted value for the independent variable. If there is no formatted value for the specified tag, the unformatted value is passed in its place. Formatted values cannot be used with the Local drill-down mode. You may also specify an optional ",n" parameter. Normally the substitution string is URL-encoded for browsers that do not support embedded white space in URL strings. If the ",n" parameter is specified, then the resulting URL string is not encoded. No intervening white space should be added between the ",f" and ",n" parameters. Local Drill-down ModeLocal drill-down mode is only supported by the GraphApplet for Java and is the first drill-down mode that the applet attempts to use if a specific mode was not specified when the graph was generated. When Local drill-down mode is in effect, selecting a chart element drills down to a target graph that is based on the data for the selected element. The way that the target graph is generated depends on the behavior that is defined for the Local drill-down mode. If a specific behavior is not defined, then the GraphApplet tries to use the default behavior for Local drill-down mode. To override the default and define behavior for Local drill-down mode, use the DDLEVELn parameter on the ODS HTML statement. Default Behavior for Local Drill-down ModeThe default behavior for each Local drill-down level is to generate a drill-down target that has the same graph type as the original graph. The applet generates one drill-down level for each non-axis variable represented in the original graph. Each target graph is generated using the same dependent variable as the original graph, and it organizes data subsets according to the values of the next available chart variable. To determine which variables are available, the applet first looks for independent variables, then group variables, and then subgroup variables. Within these categories, it uses the variables for that role in the order that they were created. That is, if two group roles were to exist, the order of those two roles is the order the variables were created in the HTML script.After you drill down to the last available level, the Local drill-down fails and the applet attempts to implement the Script drill-down mode. If that fails, then the applet attempts to implement the URL drill-down mode, and finally it attempts to implement the HTML drill-down mode. For example, the following SAS/GRAPH program generates a bar chart that shows a company's midyear sales by sales region for two consecutive calendar years. In the GCHART specification, GROUP= groups the sales data by year so that a separate set of bars is generated for each Year, and SUBGROUP= subdivides the bars by State, so that each state's sales are represented in the bars for its region. 
/* This program generates one HTML file. Specify *
* a valid file name for that file. The following *
* line is the only line you need to change to *
* run this program. */
filename odsout 'external-html-file' ;
/* close the listing destination */
ods listing close;
/* create data set SALES */
data sales;
length Region $ 4 State $ 2;
format Sales dollar8.;
input Region State Sales Year Qtr;
datalines;
West CA 13636 1999 1
West OR 18988 1999 1
West CA 14523 1999 2
West OR 18988 1999 2
East MA 18038 1999 1
East NC 13611 1999 1
East MA 11084 1999 2
East NC 19660 1999 2
West CA 12536 1998 1
West OR 17888 1998 1
West CA 15623 1998 2
West OR 17963 1998 2
East NC 17638 1998 1
East MA 12811 1998 1
East NC 12184 1998 2
East MA 12760 1998 2
;
/* assign graphics options for ODS output */
goptions reset=all device=java
xpixels=450 ypixels=400;
/* open the html destination for ODS output */
ods html file=odsout;
/* Create a chart that uses HTML variable */
title1 'Company Sales, Mid Year';
proc gchart data=sales;
vbar3d region / sumvar=sales
group=year
subgroup=state;
run;
quit;
/* close the html destination and
open the listing destination */
ods html close;
ods listing;
In the example program, the ODS HTML statement does not specify any drill-down parameters, so the GraphApplet implements the default behavior for Local drill-down. The GCHART procedure specifies two variables that are not used as axis variables in the chart: one on GROUP=, and a second on SUBGROUP=. Thus, the GraphApplet can use the group variable Year to generate a 3D bar chart for the first drill-down level, and it can use the subgroup variable State to generate a 3D bar chart for the second drill-down level. The applet can use the dependent variable Sales for both levels.
Thus, from the initial chart, if you click on either bar that represents
sales for the East region, you drill down to a new chart that shows the
1998 and 1999 sales for the East region. If you then click on the bar
that represents 1999 sales, you drill down to a chart that shows the
1999 sales for each state in the East region.
The GCHART specification provided two variables that could be used to implement two default drill-down levels. There is not a variable available to implement a third drill-down level. Thus, from the second level, if you click on the bar that represents sales for North Carolina (NC), then the Local drill-down fails because it does not have a variable to provide the data groups for another drill-down level. Because the ODS HTML statement in the SAS/GRAPH program did not use the DRILLDOWNMODE parameter to explicitly specify the Local drill-down mode, the default Any is in effect. Thus, the applet then attempts to use Script drill-down mode. When that fails, the chart uses the URL mode, and finally the HTML drill-down mode. Thus, it opens a new browser and passes the file name NC.html to that browser. If the directory that contains the applet's HTML file contains a file named NC.html, then that file is opened in the new browser; otherwise the browser indicates that it cannot find the page. Defining Behavior for Local Drill-down ModeTo define behavior for Local drill-down mode, use the DDLEVELn parameter on the ODS HTML statement. When you use the parameter, there is no limit to the number of drill-down levels you can define. Specify the parameter using the following general form:
ODS HTML PARAMETERS=("DDLEVELn"="string")
For example, the previous section discussed the default Local drill-down behavior for a graph that was generated by the following GCHART code: proc gchart data=sales; vbar3d region / sumvar=sales group=year subgroup=state; By default for the first drill-down level, the applet generates a target graph of the current graph type (BAR3D), charting the next independent variable (Year) against the current dependent variable (Sales), and using the independent variable's values to form data subsets. The following string specification on DDLEVELn specifies that behavior:
"DDLEVEL1"="{CHART}{bar3d}{G_INDEP}{Year}{G_DEP}{Sales}|{G_INDEPV}"
To change the default behavior so that the first drill-down level generates a pie chart that shows the sales for each state, grouped by state, you would specify the following DDLEVELn parameter on the ODS HTML statement:
ods html
parameters=("DDLEVEL1"="{CHART}{pie}{G_INDEP}{State}{G_DEP}{Sales}|{G_INDEPV}")
The left (chart-description) side of the string can contain any variable specification that is valid for the chart type (see the Valid drill-down Tags). If you do not specify a variable tag for a given variable role, then that variable is not carried over from the previous graph. The only two exceptions are the G_INDEP and G_DEP tags, which are inherited from the previous graph even if they are not specified. You can explicitly remove a tag by specifying a $ for its value, which is the same as setting it to None from the applet menu. You cannot set the G_INDEP and G_DEP variables to None, because they must always be present in the graph. The right (sub-setting) side of the string must contain a value tag for a valid independent variable (G_INDEPV, G_SUBGRV, G_GROUPV and G_DEPTHV). All other tags are ignored. Combining tags on the right side requires that both values match for a given observation to be included in the new drill-down level. For example, specifying {G_INDEPV} on the right side requires that only the value of the independent variable in that observation equal the selected chart value to be included in the new chart. Specifying {G_INDEPV}{G_SUBGRV} requires that both the independent and subgroup variable values match the selected values to be included in the new chart. Script Drill-down ModeWhen Script drill-down mode is in effect, selecting a chart element invokes a JavaScript callback method. The applet passes to that method the variable name, formatted value, and unformatted value of every variable that is used in the selected chart element. The callback method can retrieve any or all of that information and use it to program a response to the drill-back action. In a SAS/GRAPH program, to specify Script drill-down mode and the callback script to invoke, use the DRILLDOWNMODE and DRILLFUNC parameters on the ODS HTML statement:
ods html parameters=("DRILLDOWNMODE"="Script"
"DRILLFUNC"="MapDrill")
Here, a method named MapDrill is specified as the callback method. The MapDrill method must be defined in the same HTML file that references the client graph. When the drill-down action is initiated, the applet invokes the specified callback method using the netscape.javascript.JSObject.call() method, which is defined as follows public Object call(String methodName, Object args[] )
The JavaScript callback can return any valid Java object, but currently this return value is ignored by the applet. When the callback method is invoked, it is passed several arguments:
JavaScript allows you to define any number of arguments for a method. It does not, however, allow you to type these arguments or force the method to be invoked with that number of arguments. In fact the caller can invoke the method with any number of arguments (including zero). For example, the following JavaScript method can be invoked with 0, 1, 2, or any number of arguments: function jsfunc( arg1 arg2 )
{
}
Here, the arguments arg1 and arg2 are named arguments, and all other supplied arguments are unnamed. Named arguments can be accessed as unnamed arguments or by their names (for example, arg1 and arg2 above). Every JavaScript method has an arguments field, which is a JavaScript array that can be accessed by preceding the array with the function name. For example, jsfunc.arguments.length specifies how many arguments were passed to a method named jsfunc(). Each argument can be accessed by its array index, as in jsfunc.arguments[i], where i is the index of the argument to access (zero based). Named arguments are just shortcuts to the corresponding unnamed argument, for example arg2 above corresponds to jsfunc.arguments[1]. If a function is called with fewer arguments than are declared, the remaining named arguments are undefined. Using the JavaScript callback mechanism, it is possible to construct powerful and flexible drill-down capabilities. Here's an example of a callback that simply echoes the arguments passed to the callback method mycallback. function mycallback()
{
// Skip first argument, which is the applet reference
for( i = 1; i < mycallback.arguments.length; i++ )
alert( mycallback.arguments[i] ) ;
}
To demonstrate the Script drill-down behavior, the following SAS/GRAPH program generates a map of the United States. The program uses the ODS HTML statement's DRILLDOWNMODE parameter to specify the Script drill-down mode, and its DRILLFUNC parameter to specify a script named MapDrill as the script to invoke in response to a drill-down action. The program also uses PUT statements to create the specified callback method, which simply opens an alert box to display the value for the Statename variable at the selected map area. Thus, when you load the output HTML file in a Web browser and click on a state in the map, the state's two-letter abbreviation is displayed in an alert box.
/* This program generates one HTML file. Specify *
* a valid file name for that file, and a libname *
* for the SAS Maps library. */
/* The following two lines are the only lines you *
* need to change to run this program. */
filename odsout 'external-html-file' ;
libname maps 'SAS-data-library';
/* Create a data set that contains the US states*/
proc sql;
create table work.mydata as
select unique state from maps.us;
quit;
/* Add state abbreviations to the new data set */
data work.mydata;
length Statename $2;
set work.mydata;
Statename=trim(left(upcase(fipstate(state))));
run;
/* Specify the JAVA driver and the graph size */
goptions reset=all device=java
xpixels=325 ypixels=225 ;
/* Specify the HTML output file, the Script *
* drill-down mode, and the callback method */
ods html file=odsout
parameters=("DRILLDOWNMODE"="Script"
"DRILLFUNC"="MapDrill");
/* Specify a map title and generate the map */
title1 "State Abbreviations";
proc gmap map=maps.us data=work.mydata all;
id state;
choro statename / nolegend;
run;
quit;
/* Close the HTML destination and *
* open the listing destination */
ods html close;
ods listing;
/* Create the MapDrill script that is specified on *
* the ODS HTML statement's DRILLFUNC parameter. *
* Write the script to the same file that contains *
* the HTML output from the GMAP procedure. */
data _null_ ;
file odsout mod; /* modify rather than replace file */
put ' ' ;
put '<SCRIPT LANGUAGE="JavaScript">' ;
put 'function MapDrill( appletref )' ;
put '{' ;
put ' ' ;
put '/* Open an alert box to show state abbreviation */' ;
put 'alert("State = " + MapDrill.arguments[11]);' ;
put ' ' ;
put '}' ;
put '</SCRIPT>';
run ;
In the example program, the following statements and options directly affect the HTML output:
A Note on Java Applet SecurityAs a security feature, Java applets are not allowed to invoke JavaScript methods unless the HTML page in which the applet is embedded allows such access. To allow the applet to invoke JavaScript methods, the MAYSCRIPT attribute must be added to the applet tag. For example the following applet tag allows such access. <APPLET NAME="MYAPPLET" WIDTH=400 HEIGHT=400 MAYSCRIPT
CODE="GraphApplet.class">
Sorry your browser does not support Java Applets
</APPLET>
The JAVA device driver automatically adds the MAYSCRIPT attribute to the <APPLET> for you when the HTML output is created. HTML Drill-down ModeWhen HTML drill-down mode is in effect, selecting a chart element attempts to open a Web page with a URL address that is constructed by using the selected graph element's data values in a defined drill-down pattern. The drill-down pattern can be specified in the SAS/GRAPH program that produces the Java graph. In a SAS/GRAPH program, to specify HTML drill-down mode and the drill-down pattern to use for constructing the URL, use the DRILLDOWNMODE and DRILLPATTERN parameters on the ODS HTML statement:
ods html parameters=("DRILLDOWNMODE"="HTML"
"DRILLPATTERN"='http://www.state.{&Statename}.us')
Here, the URL will be built using the value of the variable Statename for the selected graph element. Variable Statename must be a variable that is among the variables used to generate the Java graph.
When HTML drill-down mode is specified with the DRILLPATTERN parameter, the applet maintains the idea of an HTML pattern. This is a string that defines a pattern into which appropriate substitutions are made, based on data values that are contained in the graph element that is selected to initiate the drill-down action. After the appropriate substitutions are completed, the applet attempts to load the resulting URL string in a browser. By default with HTML mode, a new browser window is opened and the URL is loaded in the new window. To control whether the URL is loaded into the current window or into a new window, use the DRILLTARGET parameter, which accepts a string argument that specifies the standard HTML targets ("_blank", "_self", "_parent", "_top" and any valid named target).
The HTML patterns are constructed by combining text with the valid HTML drill-down tags, which are used in the form {&tagname}. For example, the G_INDEP tag would be used in the form {&G_INDEP}. If you use a variable's name for a tag, the variable name is case sensitive and must be specified exactly as it is defined in the SAS data set that is used to generate the graph. For example, if the variable was defined to the SAS data set as STATE, you must specify the tag as {&STATE}, but if the variable was defined as State, you must specify the tag as {&State}.
The output string for an HTML pattern is formed by echoing any specified text and substituting values for the drill-down tags. Each specified drill-down tag must be one of the valid HTML drill-down tags; otherwise it is ignored. By default, unformatted values are substituted for the drill-down tags, unless the optional ",f" parameter is specified for the tag, which instructs the substitution to use formatted values. You may also specify the optional ",n" parameter. Normally the substitution string is URL-encoded for browsers that do not support embedded white space in URL strings. If the ",n" parameter is specified, then the resulting URL string is not encoded. No intervening white space should be added between the ",f" and ",n" parameters. The default pattern is:
"{&G_INDEPV,f}{&G_GROUPV,f}{&G_SUBGRV,f}.html"
If a tag does not apply or is inappropriate to the current graph or
graph options, then the tag is ignored. For example, pie charts do not
support group and subgroup variables, so for pie charts, the default
string substitution ignores the {&G_GROUPV,f} and {&G_SUBGRV,f}
tags and uses the pattern "{&G_INDEPV,f}.html".
To demonstrate the HTML drill-down behavior, the following SAS/GRAPH
program generates a map of the United States. The program uses the
DRILLDOWNMODE parameter on the ODS HTML statement's PARAMETERS= option
to specify the HTML mode. To define the HTML pattern, PARAMETERS= also
uses the DRILLPATTERN option, which builds a URL string with text and
one HTML tag, {&statename}. When the pattern is resolved,
{&statename} is replaced with the selected state's two-letter
abbreviation. When you load the output HTML file in a Web browser and
click on a state in the map, a URL to the selected state's home page is
loaded into a new browser window.
/* This program generates one HTML file. Specify *
* a valid file name for that file, and a libname *
* for the SAS Maps library. */
/* The following two lines are the only lines you *
* need to change to run this program. */
filename odsout 'external-html-file' ;
libname maps 'SAS-data-library';
/* Create a data set that contains the US states*/
proc sql;
create table work.mydata as
select unique state from maps.us;
quit;
/* Add state abbreviations to the new data set */
data work.mydata;
length statename $2;
set work.mydata;
statename=trim(left(lowcase(fipstate(state))));
run;
/* Specify the JAVA driver and the graph size */
goptions reset=all device=java
xpixels=325 ypixels=225 ;
/* Set DRILLDOWNMODE mode to HTML so that selecting a state *
* generates a string that represents a URL to an HTML page. *
* DRILLPATTERN makes a pattern http path that is based on *
* the value of variable STATENAME for the selected state. */
ods html file=odsout
parameters=("DRILLDOWNMODE"="HTML"
"DRILLPATTERN"='http://www.state.{&statename}.us');
title1 "State Home Pages";
proc gmap map=maps.us data=work.mydata;
id state;
choro statename / nolegend;
run;
quit;
/* Close the HTML destination and *
* open the listing destination */
ods html close;
ods listing;
In the example program, the following statements and options directly affect the HTML output:
|
|
