NAME

Applet.pl - Provides code for inserting GeogebraWebApplets into webwork problems

SYNPOSIS

###################################
# Create the applet object
###################################
$appletName = "PointGraph";
$applet = GeogebraWebApplet(
    appletName         => $appletName,
    ...
);

###################################
# Insert applet into body
###################################

BEGIN_TEXT
\{ $applet->insertAll(includeAnswerBox => 1, reinitialize_button => 1) \}
END_TEXT

DESCRIPTION

This file provides an object to store in one place all of the information needed to call an applet.

The module GeogebraWebAppletBase has defaults for inserting Geogebra web applets.

The module Applet stores common code for the different types of applets.

Default JavaScript functions placed in header

These JavaScript functions are defined for use by any JavaScript placed in the text of a PG question.

getApplet(appletName)    -- finds the applet path in the DOM

getQE(name)              -- gets an HTML element of the question by name or by id.  Be sure
                            to keep all names and ids unique within a given PG question.

getQuestionElement(name) -- long form of getQE(name)

List of options for the Applet class:

These options can be set using the accessor methods defined in the class.

Usage:  $current_value = $applet->method(new_value or empty)

These can also be set when creating the class.  For example:
    $applet = GeogebraWebApplet(
        appletName => $appletName,
        width      => 400,
        height     => 250
    );

The AppletObjects.pl macro file must be used to load the derived packages of the Applet package.

appletName   The name of the applet

params       A reference to a hash containing name/value pairs to configure the applet.
             For example: { name => 'value', ... }

width        (default: 550) Width of the html element that will contain the applet.
height       (default: 400) Height of the html element that will contain the applet.

type         The type of the applet (must be 'geogebraweb')

header       Stores the text to be added to the header section of the html page.  Calling
             $applet->header('reset') sets the header to '', and calling
             $applet->header('text to add', 'more text', ...) appends the arguments to the
             current value of header.

objectText   Stores the text which places the applet on the html page.  The accessor function
             is named 'object'.  Calling $applet->object('reset') sets the objectText to '',
             and calling $applet->object('text to add', 'more text', ...) appends the
             arguments to the current value of objectText.

configuration  Configuration contains those customizable attributes of the applet which
               don't change as it is used.  When stored in hidden answer fields it is
               usually stored in base64 encoded format.

initialState   The state consists of those customizable attributes of the applet which
               change as the applet is used by the student.  It is stored by the calling
               pg question so that when revisiting the question the applet will be
               restored to the same state it was left in when the question was last
               viewed.

getStateAlias  (default: 'getXML') Alias for command called to read the current state of
               the applet.  The state is passed in plain text xml format with outer
               tags: <xml>...</xml>

setStateAlias  (default: 'setXML') Alias for the command called to reset the state of
               the applet.  The state is passed in plain text in xml format with outer
               tags: <xml>...</xml>

getConfigAlias (default: 'getConfig') Retrieves the configuration from the applet.
               This is used mainly for debugging.  In principal the configuration
               remains the same for a given instance of the applet -- i.e. for the
               homework question for a single student.  The state however will change
               depending on the interactions between the student and the applet.

setConfigAlias (default: 'setConfig') Names the applet command called with the contents
               of $self->setConfig to configure the applet.  The parameters are passed
               to the applet in plain text using <xml>.  The outer tags must be
               <xml>...</xml>.

initializeActionAlias  (default: 'setXML') The name of the JavaScript subroutine
                       called to initialize the applet (some overlap with config/ and
                       setState).

submitActionAlias  (default: 'getXML') Applet subroutine called when the submit button of
                   the pg question is pressed.

submitActionScript (default: '') Javascript code to be execute when problem answers are
                   submitted.  For example:
                       qq{ getQE('answerBox').value = getApplet("$appletName").getAnswer() }

answerBoxAlias    (default: 'answerBox') Name of answer box to return answer to.

onInit            (default: '') This can either be the name of a global JavaScript function
                  that will be called to initialize the applet, or JavaScript code that will
                  be executed to initialize the applet.  For Geogebra web applets if this is
                  the name of a global JavaScript function defined in the problem, it should
                  NOT be named ggbOnInit.  (For WeBWorK versions 2.15 and before the global
                  JavaScript function had to be named ggbOnInit, and this parameter was
                  boolean in usage.)

debugMode         (default: 0)
                  Set to 1 to enable javascript console debugging messages.
                  Set to 2 to enable more verbose javascript console debugging messages.

List of methods made available by the Applet class:

insertHeader    Inserts text in header section of HTML page
insertObject    Inserts <article></article> tag in body of the HTML page
insertAll       (defined in AppletObject.pl) Installs applet by inserting both header
                text and the object text

    Usage:    $applet->insertAll(
                      includeAnswerBox     => 0,
                      reinitialize_button  => 0
              );

More details

There are three different "images" of the applet. The first is the applet itself. The object that actually does the work. The second is a perl image of the applet (henceforth the perlApplet) which is configured in the pg file and allows a WeBWorK question to communicate with the applet. The third image is a JavaScript image of the applet (henceforth the jsApplet) which is a mirror of the perlApplet but is available to the JavaScript code setup and executed in the virtual HTML page defined by the pg file of the WeBWorK question. One can think of the jsApplet as a runtime version of the perlApplet since it can be accessed and modified after the virtual HTML page has been created by the PG rendering process.

The perlApplet is initialized by $newApplet = GeogebraWebApplet(appletName => 'myApplet', ...); The jsApplet is automatically defined in ww_applet_list["myApplet"] by copying the instance variables of $newApplet to a corresponding JavaScript object. So $newApplet->{appletName} corresponds to ww_applet_list["myApplet"].appletName. (This paragraph is not yet fully implemented :-().

Currently all messages read by the applet are xml text. If some of the code needs to be printed in the HTML header than it is converted to a base64 constant and then converted back to text form when it is read by a JavaScript subroutine.

The perlApplet has methods that help place the jsApplet code on the HTML page and create the link to the applet itself. In particular instance variables such as "setStateAlias", "getStateAlias" connect the WW default of "setState" to subroutine name chosen by the applet designer. The aim is to make it easier to connect to applets previously designed to work with JavaScript in an HTML page or other systems.

The jsApplet acts as an intermediary for commands directed at the applet. It is not necessary for the minimal operations of configuring the applet and maintaining state from one viewing of the WW question to address the applet directly. The methods such as "setState", "getState", "setConfig" which are part of the jsApplet take care of the book keeping details. It is also possible to make direct calls to the applet from handcrafted JavaScript subroutines, but it may be convenient to store these as additional methods in the jsApplet.

Instance variables in the JavaScript applet ww_applet_list[appletName]

Most of the instance variables in the perl version of the applet are transferred to the
JavaScript applet

Methods defined for the JavaScript applet ww_applet_list[appletName]

This is not a comprehensive list

setConfig  -- Transmits the information for configuring the applet.

getConfig  -- Retrieves the configuration information -- this is used mainly for debugging
              and may not be defined in most applets.

setState   -- Sets the current state (1) from the appletName_state HTML element if this
              contains an <xml>...</xml> string.
           -- If the value contains <xml>restart_applet</xml> then set the current state to
              ww_applet_list[appletName].initialState
           -- If the value is a blank string set the current state to
              ww_applet_list[appletName].initialState

getState   -- Retrieves the current state and stores in the appletName_state HTML element.

Requirements for applets

The following methods are desirable in an applet that preserves state in a WW question. None of them are required.

setState(str)   (default: setXML)
                -- Set the current state of the applet from an xml string.
                -- Should be able to accept an empty string or a string of the form
                   <XML>...</XML> without creating errors.
                -- Can be designed to receive other forms of input if it is coordinated with
                   the WW question.

getState()      (default: getXML)
                -- Return the current state of the applet in an xml string.
                -- An empty string or a string of the form <XML>...</XML> are the standard
                   responses.
                -- Can be designed to return other strings if it is coordinated with the WW
                   question.

setConfig(str)  (default: setConfig)
                -- If the applet allows configuration this configures the applet from an xml
                   string.
                -- Should be able to accept an empty string or a string of the form
                   <xml>...</xml> without creating errors.
                -- Can be designed to receive other forms of input if it is coordinated with
                   the WW question.

getConfig       (default: getConfig)
                -- This returns a string defining the configuration of the applet in an xml
                   string.
                -- An empty string or a string of the form <XML>...</XML> are the standard
                   responses.
                -- Can be designed to return other strings if it is coordinated with the WW
                   question.
                -- This method is used for debugging to ensure that the configuration was
                   set as expected.

getAnswer       (default: getAnswer)
                -- Returns a string (usually NOT xml) which is the response that the student
                is effectvely submitting to answer the WW question.

Initialization sequence

When the WW question is loaded a JavaScript load event handler calls each of the applets used in the question asking them to initialize themselves.

The applets initialization method is as follows:

-- Wait until the applet is loaded and the applet has loaded all of its auxiliary files.
-- Call the setConfig method in the JavaScript applet
   (configuration parameters are "permanent" for the life of the applet).
-- Call the setInitialization method in the JavaScript applet.  This often calls the
   setState method in the applet

Submit sequence

When the WW question submit button is pressed the form containing the WW question calles the JavaScript "submitAction()" which then asks each of the applets on the page to perform its submit action which consists of

-- If the applet is to be reinitialized (appletName_state contains
   <xml>restart_applet</xml>) then the HTML elements appletName_state and
   previous_appletName_state are set to <xml>restart_applet</xml> to be interpreted by the
   next setState command.
-- Otherwise getState() from the applet and save it to the HTML input element
   appletName_state.
-- Perform the JavaScript commands in submitActionScript (default: '').
   A typical submitActionScript looks like:
       getQE(this.answerBox).value = getApplet(appletName).getAnswer()