Mathlets: A Guide for Authors and Other "Power Users"

This guide provides specific information for authors and other users interested in embedding the applets from the Mathlets package into their own materials.

[This document is subject to change, as applets are added to the collection and features are added to existing applets.]

Embedding an Applet

Since the applets in the current version of the Mathlets package have been written to use features of Java5, they require a recent version of the Java Plug-in. The applets make heavy use of "scripting" (JavaScript access to Java applet methods), for which early versions of the Java2 Plug-in did not have adequate support, but Java Plug-in version 1.5 or later (required anyway for Java5) has adequate support. There is also an issue regarding whether to use the HTML3-style <applet> tag to embed applets, or instead use the HTML4-compliant <object>. Although technically the <applet> tag is deprecated in HTML4, the Java Plug-in (version 1.3 or later) can force the browser to recognize the <applet> tag, so these applet pages continue to use the <applet> tag.

To embed an applet in an HTML document, then, use the HTML <applet> tag -- for example, the tag to embed the Tangent Lines applet looks like this:

archive="tangents.jar, mathlets2.jar, locales.jar"
height=375 width=700>

All applet tags need the height and width attributes, but you will have to determine these based on the layout of your Web page. (In these applet pages, I use CSS style sheets to provide a consistent set of dimensions to the applets.) Since the applets in the Mathlets package are subject to copyright restrictions, you cannot transfer the applets to your local server (without written permission from the author). Instead, you must run the applets from their home server. In order to make it easier to embed the applets without long URL's for each applet file, set the codebase attribute exactly as shown above. The name tag is not absolutely necessary for the applet, but makes much of the JavaScript described below much simpler. (The id tag may be used instead of the name tag.) Each applet tag should be given a different value for the name attribute. The tag will also need both the code and archive attributes. The code attribute will contain an applet-specific class file name, and the archive attribute will contain an applet-specific JAR file name and the file names mathlets2.jar, which refers to the JAR file which contains shared classes for the Mathlets package, and locales.jar, which contains the Java properties files for all locales currently available in translation. The applet-specific code and archive names are listed in the parameter tables -- see below.

Using Parameters I: Applet Parameters in HTML

If you just use the applet tag as described above, the applet will appear in the Web page, but will be "blank" -- no graph, no functions in the text input fields, etc. To load an example into the applet when the Web page is displayed on your browser, you must send parameters to the applet, to specify the values of the different fields. This is done using the HTML <param> tag, which must appear between the <applet> and </applet> tags. The sample below shows how to load a simple example with exponential functions into the Tangent Lines applet:

archive="tangents.jar, mathlets2.jar, locales.jar"
height=375 width=700>
<param name="f" value="exp(x)">
<param name="fp" value="exp(x)">
<param name="x" value="1.0">

Each applet has a list of allowed parameters, given in the parameter tables. The three parameters shown above set the three text input fields in the applet (for f (x), f '(x), and x, respectively) to the values shown, to draw the graph of f (x) = ex and its tangent lines, starting with the tangent line at x=1. The parameters are not all necessary when using param tags -- if a parameter is missing, that input field is left in its default value (usually blank), and the applet draws its graph as best it can given the information it does have.

Using Parameters II: Click and Load with JavaScript

The "Click and Load" interface for the Mathlets provides another way of loading examples into the applet, by associating a sequence of JavaScript commands with a link in the HTML text. The commands are associated with the onClick event handler in an <a> (anchor) tag (or any other tag for which the onClick attribute is valid). Since such an anchor can appear anywhere within the HTML text, it is a good idea to provide a way for the browser to return to the location of the applet within the Web page. To do this, include an internal anchor target immediately before the <applet> tag:

<a name="applettop"></a>

This associates the name "applettop" with the position of the applet, and this name can be used in a URL in other links to refer to this position in the Web page. At another position in the Web page, another anchor tag can now be used to set up a link which loads an example into the applet and returns the browser to the position of the applet in the page. Here is an example of such a link:

<a href="#applettop"
link text for sine example</a>

Note first the href field in the anchor tag -- the URL here simply refers to the position of the target anchor at the position of the applet tag in the page. The onClick attribute contains the JavaScript commands which load the example into the applet. Recall that the applet was given a name in the name attribute of the applet tag -- in this example the name "tan".

Each applet in the Mathlets package includes four commands which are available for JavaScript calls: jsClear, jsSetField, jsDraw, and jsGetField. The first three of these will be described in examples here; jsGetField will be discussed later.

To call, for example, the jsClear command in the tan applet, it is important to know that the tan object is contained in the JavaScript document object. So the call to the jsClear method looks like:


The jsClear command does not take any parameters, but the pair of parentheses must still be used. The jsClear command has the effect of setting all input fields in the applet to default values (usually blank). It generally does not redraw the graphs yet -- that activity is carried out by the jsDraw command. The jsDraw command also does not take any parameters.

However, before redrawing the graphs, you may want to set some of the input fields to new values using the jsSetField command. The jsSetField command takes two parameters, both strings. Note in the example, though, that the strings are delimited with single-quotation marks -- this is because the normal double-quotation marks are used to delimit the text for the onClick attribute. The two strings give the name of an applet parameter, and its value. The names of the applet parameters are the same as those used in the HTML param tags as described above, and are given in the parameter tables as described below. In the example, the three parameters in the Tangent Lines applet are set to show tangent lines for the sine function, starting with the tangent line at x=0.

Don't forget to separate successive JavaScript commands with a semicolon, as seen in the example above.

Using Parameters III: The Other Direction

The jsGetField command can be used to transfer information in the other direction: from the applet to the HTML page. In particular, this command can be used to transfer the contents of an applet's input field to an HTML form input field. The jsGetField command takes only one parameter, a string giving the name of the applet parameter, and it returns a string value with the contents of the corresponding applet input field. Indeed, along with the jsSetField command, the contents can also be transferred from the HTML form input field back into the applet input field. The example below works with the Tangent Lines applet above, and shows an HTML form with an input field and two buttons, a "Get" button to transfer from the applet to the form, and a "Put" button to transfer from the form to the applet.

<form name="tanform">
<input type=text name=field1 value="" size=30>
<input type=button name=get1 value="Get"
<input type=button name=put1 value="Put"

Note the name attribute in the form tag, and how that name is used in the JavaScript commands in the onClick attributes for the two buttons. The name given to the text input field in its name attribute is also used in the JavaScript commands to identify that field and either retrieve or change its contents. Note also that the "Put" button's onClick commands include a call to the applet's jsDraw command, to redraw the graph with the new values.

Complete Example

The example below uses all of the HTML and JavaScript code described in the samples above using the Tangent Lines applet, with one minor exception: since this page resides with the applets, the codebase attribute for the applet tag is unnecessary, so it is not used here.

link text for sine example

f (x)=
f '(x)=

As in the example code given above, the exponential function example is loaded with the page, using param tags, and the link text below the applet loads the sine function example using the JavaScript interface. The form input fields can be used to transfer information into and out of the corresponding applet input fields, when the buttons are clicked.

For a more complete sample using both param tags and the JavaScript interface, see the extended exploration of exponential functions and their derivatives.

An Alternative to JavaScript Click and Load

Since the "scripting" necessary to use the click-and-load interface described above is now widely supported, there is little need for an alternative, but nonetheless it seems pertinent to point out an alternative which uses only HTML parameters. In a separate HTML file, set up an applet tag with the necessary param tags to load the example -- for example, suppose the file sine.html contains the following HTML code:

height=300 width=600>
<param name="f" value="sin(x)">
<param name="fp" value="cos(x)">
<param name="x" value="0.0">

Now, in your Web page, use an anchor tag with the target attribute to load the file sine.html into a new browser window when the link is clicked:

<a target="_blank" href="sine.html">link text for sine example</a>

This has the advantage of not using the JavaScript interface while still not closing the Web page in which the link appears, but has the disadvantages of reloading the applet for each example, possibly cluttering the screen with lots of browser windows, and requiring a separate HTML file for each example. This approach is not used in the Mathlets pages.

Using Parameters IV: XML

There is yet another way you can pass parameters into an applet when it is loaded into the browser: store the parameter information in a separate XML file, then use the xmlstateurl HTML parameter to pass a URL for that XML file into the applet. For example, suppose the file fields.xml, stored in the same directory as the applet's web page, contains the following information:

<?xml version="1.0" ?>
<field name="f">exp(x)</field>
<field name="fp">exp(x)</field>
<field name="x">1.0</field>

Then an applet tag such as the one below will load the fields given in the XML file into the applet just as though they had been passed to the applet as HTML parameters:

archive="tangents.jar, mathlets2.jar, locales.jar"
height=375 width=700>
<param name="xmlstateurl" value="fields.xml">

As a matter of precedence, if you use both an XML file and HTML parameters, any HTML parameters whose names match fields given in the XML file will override the values given in the XML file. You can see a complete XML state file in the Java console by Control-Shift-clicking on the applet's "Clear" button -- the complete XML state includes several optional attributes as well as field tags for every parameter available to the applet. The applet also implements public getXML() and setXML() methods which JavaScript can use to modify an applet's state. These methods are used in the applet pages to implement applet state persistence -- that is, JavaScript calls to these methods save the applet's state in a browser "cookie" file so that if you navigate to another page and return to the applet page, the applet will return to the state in which you left it.

Parameter Tables

Each applet page includes a link at the bottom of the page for "Applet info" -- this link takes you to a page which shows the applet's class name, archive name, version information, copyright information, and a complete table of parameters available in the applet by any of the means above. Here is a typical applet parameter table:

Applet class name: Tangent.class
Applet archive name: tangents.jar
Code features: params/Swing/Graphics2D/il8n/Java5/colorchange/xmlstate
Copyright 1999-2008 Thomas E. Leathrum

xDoubleInput field
fExpressionInput field
fpExpressionInput field
curve-colorRGB0x0000ffColor menu item
tangent-colorRGB0xff0000Color menu item
vertical-colorRGB0x00ff00Color menu item
xminDouble-10.0Input field (2-D Bounds)
xmaxDouble10.0Input field (2-D Bounds)
delxDouble1.0Input field (2-D Axis Marks)
yminDouble-10.0Input field (2-D Bounds)
ymaxDouble10.0Input field (2-D Bounds)
delyDouble1.0Input field (2-D Axis Marks)
languageStringenLocale info (no JavaScript access)
countryStringLocale info (no JavaScript access)
xmlstateurlURL XML state/parameters file (no JavaScript access)

There are three groups of "common" parameters: locale and state parameters, parameters for graph coordinate settings in two-dimensional graphing applets, and parameters for graph coordinate settings and view angle and graphing grid settings in three-dimensional graphing applets. All applets support the locale and state parameters; however, the locale and state parameters are not available to the JavaScript commands described above (once the locale is set, it should not be subject to change; the state is loaded only at the time the applet is initialized). In some applets, no other common parameters at all are used, and in other applets, some modifications are made to the common list. These changes are indicated in the tables of applet parameters. The three lists below give the three groups of common parameters.

The tables give the names of the parameters, their types (choices are: "Double" = real number in decimal notation, "Integer" = integer value possibly including sign, "Boolean" = boolean value either "true" or "false", "String" = case-sensitive character string, "Expression" = expression string to be parsed and evaluated by the applet), the value of the field at the time the table is generated by clicking the "Applet info" link (an empty or erased field is treated as undefined for real valued fields), and a brief description of the role of the parameter in the applet.

Parameter names are case-sensitive, but in these applets are generally lower-case. Parameter values generally are not case-sensitive (except for parameters of type "string", which are always case-sensitive).

Locale and State Parameters
Use of the state parameter xmlstateurl is described above. The locale parameters set the Java runtime's locale (see the Java documentation for the Locale class). Based on the locale, different strings are loaded for labels and buttons in the applet (from data given in the properties files in the locales.jar package). These parameters are supported by all applets, but are not available to the JavaScript interface commands.
In the tables below, the parameter values given are the default values, typically the values to which the fields are set when you click the "Clear" button or call the jsClear() JavaScript method.
Name Type Default Description
language String "en" ISO 2-letter language code
country String "" ISO 2-letter country code
xmlstateurl URL "" URL of XML state file to load
2-D Graphing Common Parameters
These parameters set values for the fields shown in the pop-up window which appears when the "Bounds" button under the graph is pressed.
Name Type Default Description
xmin Double -10.0 minimum value on x-axis
xmax Double 10.0 maximum value on x-axis
delx Double 1.0 distance between marks on x-axis
ymin Double -10.0 minimum value on y-axis
ymax Double 10.0 maximum value on y-axis
dely Double 1.0 distance between marks on y-axis

3-D Graphing Common Parameters
These parameters set values for the fields shown in the pop-up window which appears when the "Bounds" or "View/Grid" buttons under the graph are pressed.
Name Type Default Description
xmin Double -10.0 minimum value on x-axis
xmax Double 10.0 maximum value on x-axis
delx Double 1.0 distance between marks on x-axis
ymin Double -10.0 minimum value on y-axis
ymax Double 10.0 maximum value on y-axis
dely Double 1.0 distance between marks on y-axis
zmin Double -10.0 minimum value on z-axis
zmax Double 10.0 maximum value on z-axis
delz Double 1.0 distance between marks on z-axis
viewa Double 45.0 view angle a (in degrees)
viewb Double 45.0 view angle b (in degrees)
xgrid Double 1.0 graph grid spacing in x direction
ygrid Double 1.0 graph grid spacing in y direction