Using JavaScript to Control the Applet

PV-WAVE Advantage > JWAVE User Guide > Generic JWAVE Applet > Using JavaScript to Control the Applet

If you do not wish to program Java applications, you can use JavaScriptTM to provide a wide range of client-side control for the generic JWAVE applet. JavaScript is a scripting language that allows you to create a user interface for HTML pages.

note	There are many manuals available on JavaScript in bookstores and online.

The example under HTML File with JavaScript demonstrates how you can add JavaScript controls to an HTML page for passing parameters and data between the generic applet and the server.

For instance, JavaScript can be used to create client-side Web pages with a graphical user interface. The GUI can be used with the generic JWAVE applet, for example, to change plot characteristics such as line color, axis range, plot symbols, and so on. When used with the generic JWAVE applet, JavaScript can be used to create complex client-side applications rapidly and efficiently.

note	Rogue Wave has provided several applet demonstrations, including the one used in this example, with your JWAVE installation. For information on running the demonstration applets, see "Running Applet Demonstrations".

In this section, we discuss:

The HTML file with JavaScript

The JWAVE wrapper function

Demonstration applets

HTML File with JavaScript

There are a few differences between this example HTML file and the one shown in HTML Code. The biggest difference is that this HTML file contains JavaScript commands. JavaScript is an object-based scripting language that can be embedded into HTML files.

In this example, we use JavaScript to call methods that are defined in the JWAVE generic applet.

note	For detailed information on the generic applet methods that can be used with JavaScript, refer to the Javadoc page on JWaveApplet (in the jwave package). For information on Javadoc, see "Using the JWAVE Javadoc Reference".

HTML file with JavaScript calls

<HTML>

<HEAD>

<TITLE>JWaveApplet Example 2</TITLE>

</HEAD>

<SCRIPT LANGUAGE=JavaScript>

// Update the plot

  function updatePlot() {

    if (! document.JWavePlot.isStarted()) {

      // Wait for applet to start before trying to updatePlot

      setTimeout(”updatePlot()”, 250);

      return;

    // Must get a session before we can set anything

    document.JWavePlot.openSession();

    // Set background and data line colors

    document.JWavePlot.setNamedColor('BACKGROUND', 'LightGray');

    document.JWavePlot.setNamedColor('LINE', 'Blue');

    // Set line style (dashed)

    document.JWavePlot.setParam('LINESTYLE', 2);

    // Turn off plot symbols

    document.JWavePlot.setParam('SYMBOL', 0);

    // Update the plot (and close the transient session)

    document.JWavePlot.execute();

<BODY onLoad=”updatePlot()”>

<H1>JWaveApplet Example 2</H1>

<APPLET NAME=”JWavePlot”

     CODE=”com.visualnumerics.jwave.JWaveApplet”

     CODEBASE=”../../”

     ARCHIVE=”JWave.jar, JWaveConnectInfo.jar”

WIDTH=450

        HEIGHT=500>

  <PARAM NAME=”FUNCTION”           VALUE=”TESTPLOT”>

  <PARAM NAME=”EXECUTE_ON_START”   VALUE=”NO”>

  <PARAM NAME=”TRANSIENT_SESSIONS” VALUE=”YES”>

</APPLET>

</BODY>

</HTML>

Let’s look at the JavaScript function, updatePlot, that is embedded in the HTML file.

First, the “if” clause with the setTimout function ensures that the plot does not update until the applet is ready.

The next call in this function is:

document.JWavePlot.openSession();

This call follows the JavaScript object convention, where document is the object name referring to the browser window itself. JWavePlot is the name by which JavaScript recognizes the applet (specified with the applet’s NAME tag), and openSession is a method defined in the generic JWAVE applet, JWaveApplet (specified with the CODE tag).

We need to call openSession to open a connection with the JWAVE Manager on the server. Normally, the applet connects and executes immediately upon startup. But we want to delay the execution until the parameters are set. That is, we want to open a session, set the parameters, and then execute the JWAVE wrapper.

The next few JavaScript calls set color values and parameters to be sent to the JWAVE wrapper function on the server.

document.JWavePlot.setNamedColor('BACKGROUND', 'LightGray');

document.JWavePlot.setNamedColor('LINE', 'Blue');

document.JWavePlot.setParam('LINESTYLE', 2);

document.JWavePlot.setParam('SYMBOL', 0);

The function setNamedColor sets a parameter name and a color value. In the JWAVE wrapper function on the server, these parameters are interpreted by corresponding GETPARAM functions, and their values are retrieved. Once retrieved, those parameter values can be plugged directly into PV‑WAVE functions. In this case, TESTPLOT is going to plug the parameters set in the HTML file into the PV‑WAVE PLOT command.

The final call in our JavaScript function is:

document.JWavePlot.execute();

The execute method sends parameters to the server and executes the JWAVE wrapper function. This in turn generates a plot, which is sent back to the client and displayed.

Finally, we use a couple of PARAM tags to prevent the applet from executing the JWAVE wrapper immediately when the applet starts. First, we need to set the EXECUTE_ON_START parameter to NO. This parameter prevents the JWaveApplet from executing when the applet starts. Then, having told the applet what not to do, we need to tell the applet what to do when it is loaded. This is the purpose of the onLoad parameter that is set in the applet’s BODY tag. The onLoad parameter tells the applet to execute the JavaScript function updatePlot when the HTML page loads. And, to reiterate, this JavaScript function does the following:

Opens a connection to the JWAVE server.

Sets four different parameters that are used to send values to PV‑WAVE.

Executes the JWAVE wrapper on the server.

note	Because JavaScript supports form objects, you can use JavaScript to create interactive GUIs for your client applets without any Java programming. For information about more complex JavaScript demonstrations created by Rogue Wave, see "Running Applet Demonstrations".

JWAVE Wrapper

To take the actions requested by the client, the JWAVE wrapper must retrieve and “unpack” the parameters and data sent from the client.

The functions used to unpack data sent from the client are: GET_NAMED_COLOR and GETPARAM. PLOT commands are then constructed using the unpacked values.

You can find the following JWAVE wrapper in:

(UNIX) RW_DIR/jwave-3_6/lib/user/testplot.pro

(WIN) RW_DIR\jwave-3_6\lib\user\testplot.pro

where RW_DIR is the main Rogue Wave installation directory.

JWAVE wrapper function, TESTPLOT

FUNCTION TESTPLOT, client_data

; get colors

black = '000000'xL

white = 'FFFFFF'xL

back_color = GET_NAMED_COLOR(”BACKGROUND”, Default = black)

axis_color = GET_NAMED_COLOR(”AXES”, Default = white)

line_color = GET_NAMED_COLOR(”LINE”, Default = white)

psym_colors = GET_NAMED_COLOR(”SYMBOLS”, Default = [white], $
/Color_Set)

; get data

data = GETPARAM(client_data, 'DATA', /Value, $
Default = FINDGEN(10))

; get plot attributes

linestyle = GETPARAM(client_data, 'LINESTYLE', /Value, $
Default = 1)

psym = GETPARAM(client_data, 'SYMBOL', /Value, Default = 6)

; Plot axes

PLOT, data, /NoData, Background = back_color, $
Color = axis_color

; plot lines

IF linestyle GE 0 THEN $

OPLOT, data, Linestyle = linestyle, Color = line_color

; plot symbols

IF psym NE 0 THEN $

OPLOT, data, PSym = ABS(psym), Color = psym_colors

RETURN, 0

END

GETPARAM Function

GETPARAM (a JWAVE-specific PV‑WAVE function) is designed to retrieve non-color related parameters and values. In the example shown in JWAVE Wrapper, the first GETPARAM call retrieves data values to plot. The next two GETPARAM calls are used to set the linestyle and symbol style for the plot.

The Value keyword is used to specify that an actual value be returned by GETPARAM, and the Default keyword specifies a default value to use in case no value is received from the client. Therefore, the GETPARAM call:

data = GETPARAM(client_data, 'DATA', /Value, $
Default = FINDGEN(10))

returns the actual data values to be plotted, which can be used in a PLOT command, such as:

PLOT, data, ...

note	Detailed information on the parameters and keywords of the GETPARAM and GET_NAMED_COLOR functions are available in the PV‑WAVE online help system and in Appendix A: JWAVE Wrapper API.

GET_NAMED_COLOR Function

If a color is specified by the client with the generic applet’s setNamedColor method, that color can be retrieved by PV‑WAVE with the GET_NAMED_COLOR function.

The GET_NAMED_COLOR function converts a named color specified on the client into a color index that PV‑WAVE can understand. For instance, the returned value from GET_NAMED_COLOR can be used with the PLOT command’s Background keyword.

For example, GET_NAMED_COLOR might return a color index for the background color of a 2D plot.

back_color = GET_NAMED_COLOR(”BACKGROUND”, Default = black)

data = GETPARAM(client_data, 'DATA', /Value, $
Default = FINDGEN(10))

PLOT, data, Background = back_color

Running Applet Demonstrations

Rogue Wave has provided a set of demonstration HTML files that use JavaScript controls.

note	To run these applets, you must have a working installation of JWAVE and the JWAVE Manager must be running on the server. To run these demonstrations, you must also have a browser that supports JDK 1.1.

You can find these demonstration files in:

(UNIX) $RW_DIR/classes/jwave_demos/JWaveApplet

(WIN) RW_DIR\classes\jwave_demos\JWaveApplet

You are free to copy any of the form and JavaScript functions in these demonstration applets for your own use. The examples include:

applet_demo1.html—This HTML page contains a single JWaveApplet that calls JWAVE to make a plot. All plot parameters (and data) are set/generated by the JWAVE wrapper function. This applet is similar to HTML Code.

applet_demo2.html—This HTML page contains a single JWaveApplet that calls JWAVE to make a plot. There is some simple JavaScript in this page that initializes some parameters (colors and linestyle) used by the JWAVE wrapper function. The wrapper function generates its own data. This applet is identical to the example under HTML File with JavaScript.

applet_demo3.html—This HTML page contains a single JWaveApplet that calls JWAVE to make a plot. There is some JavaScript in this page that sets parameters used by the JWAVE wrapper function. The parameters set by JavaScript are controlled by HTML FORM tags. There are some JavaScript helper functions provided in this page to help the FORM tags interact with JWAVE. The wrapper function still generates its own data.

applet_demo4.html—There are two JWAVE applets running in this HTML page. They share a connection to a single PV‑WAVE session, and thus can share data on the server side. One applet is invisible, and uses the JWaveExecute class to create some data on the server. The resulting data stays on the server. It is stored by the Data Manager. The second applet uses the JWaveView class to make a plot of the data created by the first applet.

applet_demo5.html—There are two JWAVE applets running in this HTML page. They share a connection to a single PV‑WAVE session, and thus can share data on the server side. One applet is invisible, and uses the JWaveExecute class to create some data. The resulting data stays on the server (stored by the Data Manager). The second applet uses the JWaveView class to make a plot of the data created by the first applet, using one of two wrapper functions that each create a particular type of plot.