Parameter Definitions

All NetCharts applets are based on a small set of parameters that control all aspects of the graphics displayed. For most applets, roughly a dozen parameters control all of the major functions. Since all parameters have default values, authors need only specify those required to define data values in order to generate a graphical display. As the application evolves, the author can modify additional parameters to yield different graphical results.

Parameters are easily defined using any of the following methods:

This flexibility in defining parameters allows application developers to determine how best to satisfy their needs. For example, URL-based parameter files can be used to centralize the parameters for a wide range of applications, while a parameter server can be used to modify the parameters, across all applications, in a continuous manner.

Applet <PARAM> Tags

The standard method for passing parameters to any applet is through the use of one or more <PARAM> tags, which are defined within the confines of the <APPLET> tag. Each <PARAM> tag is assigned a unique name and a value, which may be quoted. For example, the following HTML segment defines a piechart that has a white background, with a black shadow, a red header title and three pie slices with specific values and labels:

<applet code=NFPiechartApp.class width=400 height=400>

<param name=Background  value="(white, SHADOW)">
<param name=Header      value="('Piechart Demo', red)">
<param name=Slices      value="(12, 'Fred'),
			       (23, 'Sally'),
			       (15, 'Jim')">
</applet>
Notice that each parameter is defined within a separate <PARAM> tag and that the values can span multiple lines, provided that the value is a quoted string. Also note how the strings defined within the parameter value use single quotes to differentiate themselves from the entire value string. NetCharts parameter strings can use either single or double quotes to make such definitions convenient.

Parameter Script

Whereas the use of <PARAM> tags is common and convenient for a small number of parameters, many users find it more convenient to specify parameters as a script within a single <PARAM> tag. To that end, the NFParamScript parameter can be defined, where the assigned value can define any number of parameters. Generally such values are written across multiple lines to aid readability.

The NFParamScript reduces the amount of redundant typing needed and is easier to generate from within a CGI script. The following example defines the same piechart as the one above, although it uses a single NFParamScript in order to define all of the parameters.

<applet code=NFPiechartApp.class width=400 height=400>

<param name=NFParamScript   value='
    Background	= (white, SHADOW);
    Header     	= ("Piechart Demo", red);
    Slices	= (12, "Fred"),
		  (23, "Sally"),
		  (15, "Jim");
'>
</applet>
Notice how only a single <PARAM> tag is used, with a quoted, multi-line value definition. Also note how the single quote is used to demark the <PARAM> tag value and the double quote is used to denote a string value as a parameter attribute.

It is important to note that each parameter definition in an NFParamScript is terminated within a semi-colon.

If both individual <PARAM> tags and an NFParamScript is used to define parameters in the same applet, then the individual <PARAM> tags will be processed first. That is, the NFParamScript values will take precedence over the individual <PARAM> tag values, if the same parameter name is being defined.

Parameter File

Instead of placing all of the parameter definitions within an HTML file, you can specify an arbitrary URL to be accessed to retrieve the parameter definitions. Generally, the URL refers to a data file, but any URL can be used, including a CGI script or application that generates the parameters dynamically. For example, you may have multiple HTML files that reference the same chart. In that case, maintenance is reduced if the chart definition is stored in a single file or generated dynamically by a single CGI script. In the latter case, the CGI URL could even be customized to generate a custom chart for a given HTML file.

Regardless of the form of the URL, the resulting content-type should be a text/plain sequence of parameter definitions. That is, the URL should be a text file containing NetCharts parameter definitions. For example, the following HTML segment defines a piechart based on the parameters defined in the piechart.dat file on the anywhere.com web server.

<applet code=NFPiechartApp.class width=400 height=400>

<param name=NFParamURL
       value="http://anywhere.com/piechart.dat">

</applet>
Note, when a relative URL is given, the URL is interpreted relative to the Document Base of the HTML file containing the applet.

The NFParamURL parameter is processed after any individual <PARAM> tags, but before any NFParamScript. This allows the URL to contain standard attributes which may be overridden by the local parameter definitions defined in the NFParamScript.

Parameter Server

Much like specifying a Web URL from which parameter definitions are read, you may specify an arbitrary TCP server from which definitions will be processed. In this case, however, the definitions can be processed throughout the applet lifetime. That is, a parameter server can continuously update any or all of the chart parameters, providing for dynamic charting.

The value of the NFParamServer parameter has the following format:

name=NFParamServer  value="hostname:port/arguments"
If NFParamServer is defined, it will be processed after all other parameter definitions have been processed. At that time, a connection is made to the given host and port, which is assumed to be a TCP server capable of generating parameter statements. The TCP server can be written using any language or utility desired. It need only generate a stream of text data that is equivalent to an NFParamScript.

Everything following the "/" in the parameter string will be passed to the parameter server upon connection, terminated with a newline character. That allows the server to determine the specific data required for this connection. For example, the following HTML segment specifies a parameter server located at www.netcharts.com using port 2000. An initial line containing "DataSet=Monday, User=Fred" is sent to the parameter server on startup, presumably telling it which chart to generate.

<applet code=NFPiechartApp.class width=400 height=400>

<param name=NFParamServer
       value="www.netcharts.com:2000/DataSet=Monday, User=Fred">

</applet>

All parameter statements generated by the NFParamServer are processed by a background thread while the chart is being displayed. An "Update" command can be sent at any time within the data stream to cause the chart display to be updated. That is, parameter definitions received from the parameter server are batched together and the chart is refreshed whenever an "Update" command is received.

Dynamic Updates From Another Applet

Parameter definitions can be programmatically updated at any time throughout the life of a chart applet through the use of the loadParams() method. The loadParams() method accepts a string value, which consists of one or more parameter statements. As with the NFParamServer, the loadParam() definitions are batched together and the chart is refreshed whenever an "Update" command is given.

In the following Java example, the current applet accesses a piechart applet via the AppletContext() (a standard Java capability) and then executes the loadParams() method of the piechart applet to update the slice values and labels, as well as the piechart background color.

AppletContext ac = getAppletContext();
NFPiechartApp pie = (NFPiechartApp)ac.getApplet("piechart");

if (pie == null) {
	System.out.println ("Unable to access piechart");
} else {
	pie.loadParams ("Background = (blue);"
                       +"Slices = "
                       +"    (12, 'Fred'),"
                       +"    (23, 'Sally'),"
                       +"    (15, 'Jim');"
                       +"Update;"
                       );
}

Dynamic Updates From JavaScript

The loadParams() method of each NetCharts applet can be used to update chart parameters programmatically from JavaScript. The applet context is determined using the "document" object within JavaScript, as shown in the following example:

var app = document.piechart;

app.loadParams ("Background = (blue);");
app.loadParams ("Slices = (12,'Fred'),(23,'Sally'),(15,'Jim');");
app.loadParams ("Update;");

Applet Embedded In An Application

NetCharts applets can be easily embedded in any Java application. For example, the following Java code creates a Frame and displays a barchart within that frame.

Frame frame = new Frame ("Standalone Application");
frame.setLayout (new BorderLayout());

try {
	bar = new NFBarchartApp();
	bar.init ();
	bar.start ();
	bar.loadParams ("Background = (red);");
	bar.loadParams ("Update");
	frame.add ("Center", bar);

} catch (Exception e) {
	System.out.println (e.getMessage());
}

frame.resize (300, 300);
frame.show ();
For more details concerning charts embedded in applications, see
Embedded Application Control.

Applet Embedded In An Applet

NetCharts applets can be easily embedded in any Java applet. For example, the following Java code creates a barchart inside of the current applet.

Applet.java:
	setLayout (new BorderLayout());

	add ("North", new Label("Embedded Barchart",Label.CENTER));

	try {
		NFBarchartApp bar = new NFBarchartApp(this);
		bar.init();
		bar.start();
		bar.loadParams ("Header = ('Try This');");
		bar.loadParams ("Update;");
		add ("Center", bar);
	} catch (Exception e) {
		System.out.println (e.getMessage());
	}

Applet.html
	<applet code=embed.class width=400 height=400>
	<param name=NFParamScript value="Background = (red, SHADOW, 4);">
	</applet>
For more details concerning charts embedded in applets, see
Embedded Applet Control.