Viewer Control

(Excerpt from "The MathML Handbook" by Pavi Sandhu)

The WebEQ Viewer Control is a Java applet for displaying mathematical formulas in Web pages. The equations to be displayed are embedded in an HTML document in an applet tag, in either MathML or WebTeX format. The display of the applet requires a special set of class files that can either be installed locally on the client machine or downloaded directly from the server along with the document to be viewed. The location of these files is specified using the codebase and code attributes.

A typical Viewer Control applet tag has the following structure:

<applet codebase="classes" code="webeq3.ViewerControl" width="200" height="100">
  <param name="eq" value="mml_string">
</applet>

Here, mml_string is a string that specifies the MathML markup for the equation to be displayed. Alternatively, you can place the MathML markup in a separate file, whose location you can specify via an absolute or relative URL using the parameter src, as shown below:

<applet codebase="classes" code="webeq3.ViewerControl" width="200" height="100">
  <param name="src" value="url">
</applet>

The Viewer Control applet supports various parameters for controlling the appearance of an equation, such as its font size, color, and alignment. One of the parameters is controls, which can take the values true or false. If this parameter is set to true, as shown in the following code fragment, right-clicking the displayed equation opens a dialog that allows the user to change the font size of the equation:

<applet codebase="classes" code="webeq3.ViewerControl" width="200" height="100">
  <param name="src" value="url">
  <param name="controls" value="true">
</applet>

The following figure shows a Viewer Control applet displayed in IE, along with the font size control panel that appears when you right-click the equation.

WebEQ: Viewer Control applet showing pop-up menu

Figure: A Viewer Control applet displayed in IE that shows the pop-up menu for changing the font size of the displayed equation.

Actions in WebEQ

For authoring formulas to be displayed using the Viewer Control, you can use the WebEQ Editor, as explained under Authoring and editing MathML: WebEQ. Once you have created an equation using the Editor, you can export the equation as a WebEQ Viewer Control applet tag, which is suitable for pasting into an HTML document that can be displayed in a browser.

WebEQ provides support for three types of interactive actions in equations:

  • Mouseover: moving the cursor over an equation changes the background and foreground colors, to highlight it.
  • Link: this turns an equation into a hyperlink that points to a specified URL.
  • Toggle: clicking on an equation causes it to alternate between two different displays.

To create any of these types of actions, you choose the corresponding command from the Insert → Actions menu in the WebEQ Editor window (see the following figure). This opens a dialog with fields for specifying the various parameters that define the action. These actions are all implemented using the maction element of presentation MathML. In other words, a maction tag with the appropriate attribute values set is automatically added in the underlying markup for the equation you are authoring. This tag can then be interpreted by the Viewer Control when it displays the markup. Thus you can author interactive equations using the WebEQ Editor and display them in a Web page using the WebEQ Viewer Control.

Authoring equation in WebEQ Editor

Figure: Authoring an equation with an action in WebEQ Editor.

As we saw under Presentation markup: Other elements: Setting up actions, the maction element takes an attribute called actiontype, which defines the type of interactivity in the equation. In WebEQ, this attribute can take one of three values: mouseover, link, or toggle, which correspond to the three types of actions supported. In addition, for each type of action, some "pseudo-attributes" specify additional information about the action. These attributes are not part of the MathML specification. They are supported by WebEQ only for implementing specific actions and have the namespace prefix dsi. These attributes are listed in the following table.

Table: WebEQ pseudo-attributes.

Attribute Values Meaning
dsi:color #rgb | #rrggbb | html-color name Foreground color of equation.
dsi:background #rgb | #rrggbb | html-color name Background color.
dsi:href string URL to link to (for actiontype='link' only).
dsi:cue1 string Message displayed in the status line of the browser when the mouse is moved over the equation.
dsi:cue2 string Message displayed in the status line of the browser when the mouse is moved over the alternate equation (for actiontype='toggle' only).

Here is the applet tag for an equation with a mouseover action:

<applet codebase="classes" code="webeq3.ViewerControl" height="100" width="200">
  <param name="eq" value="
  <math>
    <mrow>
      <maction actiontype='mouseover' dsi:color='red' dsi:background='blue' dsi:cue1='Mouseover effect'>
        <mrow>
          <mi>x</mi>
          <mo>+</mo>
          <mn>1</mn>
        </mrow>
      </maction>
    </mrow>
  </math>" />
</applet>

When the cursor is moved over the applet, the equation's text color becomes red, the background color becomes blue, and a message is displayed in the browser's status bar. These properties are specified using the WebEQ pseudo-attributes that we saw in the table above.

The applet tag for the same equation to act as a link is shown below:

<applet codebase="classes" code="webeq3.ViewerControl" height="100" width="200">
  <param name="eq" value="
  <math>
    <mrow>
      <maction actiontype='link' dsi:color='red' dsi:background='blue' dsi:cue1='integral' dsi:href='http://www.examples.org/webeq_link'>
        <mrow>
          <mi>x</mi>
          <mo>+</mo>
          <mn>1</mn>
        </mrow>
      </maction>
    </mrow>
  </math>" />
</applet>

The main differences between this markup and the previous one are that here, the actiontype attribute has the value link instead of mouseover and the extra attribute dsi:href is used to specify the destination URL.

To create a toggle action, the maction element has two arguments, which represent the two expressions to alternate between. In other words, the element has the following syntax:

<maction actiontype="toggle" dsi:cue1="message1" dsi:cue2="message2">
  expr1
  expr2
</maction>

Here is the applet tag for an equation with a toggle:

<applet codebase="classes" code="webeq3.ViewerControl" height="100" width="400">
  <param name="eq" value="
  <math>
    <mstyle displaystyle='true'>
      <mrow>
        <mrow>
          <mfrac>
            <mrow><mi>&pi;</mi></mrow>
            <mrow><mn>4</mn></mrow>
          </mfrac>
        </mrow>
        <mo>=</mo>
        <maction actiontype='toggle' dsi:cue1='Leibniz formula' dsi:cue2='first few terms in the series'>
          <mrow>
            <mrow>
              <munderover>
                <mo>&sum;</mo>
                <mrow><mi>n</mi><mo>=</mo><mn>1</mn></mrow>
                <mrow><mi>&infin;</mi></mrow>
              </munderover>
              <mrow>
                <mfrac>
                  <mrow>
                    <mo>(</mo>
                    <mo>-</mo>
                    <mn>1</mn>
                    <mo>)</mo>
                    <msup>
                      <mrow>
                        <mi>n</mi>
                        <mo>+</mo>
                        <mn>1</mn>
                      </mrow>
                    </msup>
                  </mrow>
                  <mrow>
                    <mo>(</mo>
                    <mn>2</mn>
                    <mi>n</mi>
                    <mo>-</mo>
                    <mn>1</mn>
                    <mo>)</mo>
                  </mrow>
                </mfrac>
              </mrow>
            </mrow>
          </mrow>
          <mrow>
            <mn>1</mn>
            <mo>-</mo>
            <mfrac>
              <mrow><mn>1</mn></mrow>
              <mrow><mn>3</mn></mrow>
            </mfrac>
            <mo>+</mo>
            <mfrac>
              <mrow><mn>1</mn></mrow>
              <mrow><mn>5</mn></mrow>
            </mfrac>
            <mo>-</mo>
            <mfrac>
              <mrow><mn>1</mn></mrow>
              <mrow><mn>7</mn></mrow>
            </mfrac>
            <mo>+</mo>
            <mn>...</mn>
          </mrow>
        </maction>
      </mrow>
    </mstyle>
  </math>" />
</applet>

The MathML markup in this example is shown without the normal indentation and linebreaking (to save space). Although the markup is verbose, remember that the entire applet tag along with the MathML markup inside it can be generated automatically using the WebEQ Editor. Hence, you will rarely need to author such expressions by hand. The purpose of this example is mainly to explain the structure of the underlying markup, so you can see how toggle actions work.

Inserting this applet into a Web page causes the display to switch between the two expressions shown in the next two figures. You can switch between the two views by clicking anywhere on the right-hand side of the equation. The message in the status line of the browser window also changes with the equation being displayed.

WebEQ: Web page with Viewer Control applet with toggle action

Figure: A Web page that contains a Viewer Control applet with a toggle action.

WebEQ: alternate display when clicking equation

Figure: The same Web page as in the figure above, but this one shows the alternate display you get when you click the equation.

Scripting the Viewer Control

WebEQ includes a set of APIs for scripting the Viewer Control applet. The APIs contain high-level functions that can be called by other Java applets or JavaScript programs to access or change various properties of the displayed equation. This allows you to create various types of interactive behavior; for example, changing the display of an equation when the user clicks a button or chooses an item from a menu. The following table shows a few of the functions included in the Viewer Control API.

Table: Functions included in the Viewer Control API.

Method Description
setEquation(String neweq) Changes the value of the eq parameter to neweq.
setBGColor(String newcolor) Sets the applet background color to newcolor, where newcolor is of the form "#rrggbb", "#rgb", or a predefined color keyword (as defined in the HTML 4.0 specification).
setFGColor(String newcolor) Sets the applet foreground color to newcolor, where newcolor is of the form "#rrggbb", "#rgb", or a predefined color keyword.
setSize(int size) Changes the point size of the characters in a single instance of theWebEQ applet. The point size is set to the largest number on the list (36, 30, 24, 18, 16, 14, 12, 10, 8) that is less than or equal to size.
preferredHeight( ) Returns the height of the rendered equation. This is also the value to which the height parameter in the applet tag should be set.
preferredWidth( ) Returns the width of the rendered equation. This is also the value to which the width parameter in the applet tag should be set.

Let's look at some examples of using these functions to implement some simple interactive behavior.

The following example sets up a Web page (see the following figure) with a text area in which a user can type in any MathML expression When the user clicks the "Display" button, the Viewer Control renders the MathML as an applet embedded in the page.

Example: An HTML document for rendering a specified MathML expression.

<html>
  <head>
    <title>WebEQ Viewer Control</title>
    <script language="javascript">function showMath( ) {var expr = document.MMLForm.MMLString.value; document.mathapplet.setEquation(expr);}</script>
  </head>
  <body bgcolor="white">
    <h1>WebEQ scripting example</h1>
    <p>Enter MathML string:</p>
    <p><form name="MMLForm"><textarea name="MMLString" rows="10" cols="30"></textarea></form></p>
    <p><form><input type="button" name="MMLSend" value="Display" onclick="showMath()"></form></p>
    <applet codeBase="../../classes" code="webeq3.ViewerControl" align="middle" width="400" height="50" name="mathapplet" mayscript>
      <param name="parser" value="mathml">
      <param name="eq" value="">
    </applet>
  </body>
</html>

WebEQ: Web page rendering MathML expression as Viewer Control applet

Figure: A Web page that renders an arbitrary MathML expression as a Viewer Control applet.

The example above works in the following way. When the user clicks the "Display" button, the JavaScript function showMath is called. This function consists of two statements. The first statement retrieves the MathML expression typed by the user and assigns it as the value of the variable expr, as shown here:

var expr = document.MMLForm.MMLString.value;

The second statement updates the display of the Viewer Control applet, called mathapplet, by using the function setEquation, as shown here:

document.mathapplet.setEquation(expr);

You can also use the setEquation function to create interactive demos for showing the steps involved in solving specific mathematical problems. This is illustrated in the following example, which shows an HTML document consisting of a Viewer Control applet and a button. When this document is first loaded into a browser, a mathematical problem is displayed by the applet (see the following figure). Each time the user clicks a button, the applet display is updated to show the next step in the solution of the problem. This continues until the problem is completely solved. After this, clicking the button again causes the original problem to reappear.

The following example works like a toggle action but with a repeating cycle that can be of any arbitrary length. This type of behavior is useful for educational Web sites, for example, to demonstrate the solution of problems in an assignment.

Example: An HTML document for showing the steps in solving a problem.

<html>
  <head>
    <title>WebEQ Viewer Control</title>
    <script language="javascript">
    var i=1;
    function nextStep() {
    i++;
    if (i==1) {
    document.mathapplet.setEquation(mml_string1);}
    if (i==2) {
      document.mathapplet.setEquation(mml_string2);} 
    if (i==3) { 
      document.mathapplet.setEquation(mml_string3);}
    if (i==4) { 
      document.mathapplet.setEquation(mml_string4);
      i=-1;}
    }
    </script>
  </head>
  <body bgcolor="#ffffff">
    <h2>Finding a derivative using the product rule</h2>
    <p>Click the Next button to see the next step.</p>
    <applet codebase="classes" code="webeq3.ViewerControl" height="50" width="400" name="mathapplet" mayscript>
      <param name="parser" value="mathml" />
      <param name="color" value="#dddddd" />
      <param name="size" value="18" />
      <param name="align" value="left" />
      <param name="eq" value="mml_string1" />
    </applet>
    <form><input type="button" value="Next" onclick="nextStep();"></form>
  </body>
</html>

WebEQ: interactive Web page showing steps in solution of calculus problem

Figure: An interactive Web page that shows the steps in the solution of a calculus problem.

The example above works as follows. Each time the user clicks the "Next" button, the JavaScript function nextStep is called. This function increments the value of the counter i by 1 and calls the setEquation function to change the equation displayed in the Viewer Control applet. The various steps in the solution are hard coded as MathML expressions. A different MathML string is specified as the argument of the setEquation function for each value of i. Hence, with each click of the button, the applet displays successive steps in the equation until the original equation reappears and the cycle starts again.

In this example, the MathML expression that corresponds to the mathematical problem to be solved is denoted by mml_string1, and the three steps involved in the solution of the problem are denoted by mml_string2, mml_string3, and mml_string4. In a working implementation of this example, these would be replaced with the MathML strings for the specific mathematical expressions to be displayed.

WebEQ and the DOM

The DOM is a W3C recommendation designed to simplify the processing of XML documents. The DOM defines a set of objects and methods for selecting and modifying any part of the XML document tree. These objects and methods are specified as abstract interfaces that any application can implement. For example, many Web browsers define an object hierarchy that is based on the DOM. The DOM is useful because it provides a standard way of working with XML documents that is independent of any specific platform, programming language, or application.

The WebEQ API implements many of the standard interfaces defined in the W3C specification of the DOM. WebEQ also implements some parts of the MathML DOM, which is defined in the MathML 2.0 specification. The MathML DOM extends the generic DOM by adding some extra interfaces for handling specific types of MathML expressions.

Using the objects and methods defined in the WebEQ DOM API, you can navigate the MathML tree to select a specific node and change its attributes. You can also add or delete nodes to interactively modify a part of the displayed equation. This is illustrated in the next example, which shows an HTML document that contains a Viewer Control applet. You can update the color of the equation by choosing a color from a pull-down menu. The next figure shows how this document looks when viewed in a browser.

Example: An HTML document with a menu for changing the color of an equation.

<html>
  <head>
    <title>Using the WebEQ DOM API</title>
    <script language="javascript">
      function colorText() {
        var i = document.form1.menu1.selectedIndex;
        var item = document.form1.menu1.options[i];
        var fgcolor = item.text;
        var appletNode=document.equation
        var mathDocument=appletNode.getMathMLDocument();
        var mathnode= mathDocument.getFirstChild();
        var mstylenode=mathnode.getFirstChild();
        mstylenode.setAttribute("mathcolor", fgcolor);
      }
    </script>
  </head>
  <body bgcolor="white">
    <h1>Using the WebEQ DOM</h1>
    <p>Use the menu to change the color of the equation.</p>
    <table>
      <tr>
        <td>
          <form name="form1">
            <select onChange="colorText()" name="menu1">
              <option>black</option>
              <option>red</option>
              <option>blue</option>
              <option>green</option>
              <option>yellow</option>
            </select>
          </form>
        </td>
        <td>
          <applet codebase="classes" code="webeq3.ViewerControl" width="250" height="50" align="middle" name="equation" mayscript>
            <param name="parser" value="mathml" />
            <param name="eq" value="
              <math>
                <mstyle mathcolor='black'>
                  <mrow><mi>x</mi><mo>+</mo><mn>1</mn></mrow>
                </mstyle>
              </math>" />
          </applet>
        </td>
      </tr>
    </table>
  </body>
</html>

WebEQ DOM API for accessing specific node of equation and change attributes

Figure: Using the WebEQ DOM API to access a specific node of an equation and change its attributes.

In the example above, the select tag is used to indicate a pull-down menu, with each item in the menu specified using an option tag. When the user changes the currently displayed item in the menu, an onChange event occurs, which calls the JavaScript function colorText. This function reads the currently selected color and assigns it as the value of the variable fgcolor. The function then uses the following three methods from WebEQ's implementation of the DOM to pick out a specific element in the MathML expression and change it:

  • getMathMLDocument( ): returns the complete MathML expression tree, when applied to the Viewer Control applet node.
  • getFirstChild( ): returns the first child of the node it is applied to.
  • setAttribute(attr, value): changes the attribute value of a particular node.

By applying these methods in sequence, the colorText function first selects out the mstyle tag that encloses the MathML expression. It then sets the value of the mathcolor attribute of this element to that stored in the fgcolor variable. This causes the color of the equation displayed in the Viewer Control applet to be updated to the item that the user selects in the menu.

   

<< back next >>

 

 

 


 

Copyright © CHARLES RIVER MEDIA, INC., Massachusetts (USA) 2003
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "The MathML Handbook" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


CHARLES RIVER MEDIA, INC., 20 Downer Avenue, Suite 3, Hingham, Massachusetts 02043, United States of America