Flash Applets Tutorial
In this tutorial it is discussed how to create a Flash applet with the interface necessary for inclusion in a WeBWork problem, as well as the construction of the corresponding PG file. We pay special attention to the problem of setting up the functions that define the interface between the applet and the WeBWork page that displays the problem.
Applets included in WeBWork problems can come in several flavors: the applet may simply display a graph, perhaps with some interactivity, to aid students in visualizing the solution for a problem. It could be used to guide students in the process of finding a solution (in which case it has to "remember" the stage the student is in). Or, in more complex examples, it might require an answer to be entered in the applet, for example by typing it or by manipulating a graphic in certain way.
The complexity of the interface will depend on the purpose and complexity of the applet. In this tutorial, we will start with a very simple example that requires students to enter the answer in a simple problem. We will then proceed to more complex examples.
The examples require ActionScript 3 and have been tested in Flash CS5 (but should work in Flash CS4).
Debugging is one of the most challenging aspects of developing Flash applets for WeBWork. The following tools are suggested:
- The debug version of the Flash player is required to use Firebug/Flashbug. It can be downloaded here.
DebugBox, an ActionScript class that displays a box where debug messages can be displayed. (Add downloading site). Important notice: The
DebugBoxclass uses the
TextAreacomponent to display messages. This requires that this component is present in the Library of the
.flafile. To add the component to the Library, open the menu 'Windows-Components' and drag
TextAreato the Library.
- A "local tester" for the interface. This allows testing the interface whithout having to upload the applet to WeBWork. (Add downloading site)
Note: Even for developers not using Firefox, it may be useful to use the debug version of the Flash player. At least exceptions thrown by ActionScript will cause a popup to be displayed. If using Chrome, it may be necessary to choose the correct plugin in the page
Functions Expected by the Interface
In this page we do not discuss the details of the
ExternalInterface class, but describe the methods that WeBWork expects to be made available by the applet. For implementation details see the examples section.
applet_ready, as in the example below:
For simple applets, it is recommended that this function call takes place in response to the
ADDED_TO_STAGE event, not in the applet's constructor. More complex applets that need additional media or resources should use a more sophisticated loading method.
The names of the functions defined in the applet are not hard-coded by WeBWork. It is possible to configure them in the PG file. The following are the names shown have been conventionally used, but developers are allowed to change them.
setConfig(xmlString):uint. This function is called to give the applet the opportunity to initialize problem data. Typically, a problem is generated in the PG file by randomization, and this information must be passed to the applet. The data must be encoded in a XML string. A deep understanding of XML is not required, since ActionScript makes it easy to read and write XML data. See the documentation of the XML class and the Working with XML tutorial. Suppose, for example, that the problem generates the function [math]x+\sin(x)[/math]. Then,
<xml><function>x+sin(x)</function></xml>and, in the applet code,
xmlString.functionwill refer to the string
x+sin(x). The function should return a nonzero value if the configuration was successfully set, and 0 if not (for example, if
xmlStringdoes not contain valid XML data).
xmlStringwill be exactly the same string that was returned in a previous call to
getXML(). The applet should use
xmlStringto put itself in the state it was right before the student was done interacting with the applet (for example, when the problem is submitted). The initial state of the applet can be configured in the PG file. This function should not be used to set problem data. This should be done in
Stringthat represent's the student's answer. This string should not use XML, but a format compatible with WeBWork's answer checking macros.
The following functions can be optionally defined:
getConfig():String. This function is not actually used by the interface, but may be useful for debugging purposes. It should return a
Stringcontaining valid XML, representing the configuration data that was passed to the applet by the
setConfig(xmlString)function. The applet might simply keep
xmlStringin a variable and return it in this function.