When distributing components, it is often desirable to give the user a description of the component and some easy method of configuring it. Simgua possesses an extremely powerful method of dealing with these two issues: the calibration page.
In its essence, the calibration page is an HTML document (in effect a web page) that contains information about the component and allows the user to set component parameters by submitting an HTML form. A tutorial on the design of web-pages is beyond the scope of this document and we refer the novice reader to the tutorial web site http://www.utexas.edu/learn/html/index.html as a good introductory source on HTML development.
The calibration page HTML can be entered when the component is in its unencapsulated form. Simgua renders this code using a platform specific rendering engine that is very powerful. This means that though you can develop very plain and simple calibration pages, you can also include advanced features such as JavaScript and other dynamic content. To test the power of Simgua’s calibration pages, simply insert a link to your favorite webmail client into your calibration page and see how well Simgua displays it. It is important to note, that due to the differing rendering engines that are used on each operating system, you should test your calibration pages on each of these platforms to make sure they display correctly.
While displaying information about the component is as simple as writing a basic HTML file, allowing the user to enter component parameters is slightly more complex. This task can be achieved through the use of specially constructed HTML forms. To aid in the development of these forms, Simgua allows you to input a number of “keywords” into your calibration page that are automatically rewritten to create the necessary forms. Let us look at an example of a very basic configuration dialogue (the Simgua keywords are those surrounded by curly-braces):
<html>
<head></head>
<body>
<h2>Widget Configuration</h2>
{var set}
Rain Level: {input-double: rain} <br>
Use Joe’s Algorithm: {input-boolean: use_joe} <br>
{cancel} {save}
{end var set}
</body>
</html>
This will create a Simgua calibration page shown below that allows you to input a number specifying the rain level and whether or not to use “Joe’s” algorithm:
A basic Calibration dialog
When you run a simulation using this calibration page, two variables are available to your primitives within the component. One is a Double and is called “rain”; the other is a Boolean and is called “use_joe”. They are set to the values entered by the user when they edited the component’s calibration page.
Table of Keywords for the construction of Calibration pages
|
Keyword |
Description |
|
{var set} |
Opening form tag which needs to be placed before any input or command items. |
|
{end var set} |
Closing form tag which needs to be placed after any input or command items. A single pair of begin and end var set items needs to wrap your entire block of variables. Only one pair is necessary or should be used. |
|
{input-double: name} |
Allows the user to set a numeric variable called name. Simgua will carry out input validation to make sure the user entered a number. This entry field is represented as a text field in the calibration page. |
|
{input-string: name} |
Allows the user to set a textual variable called name. This entry field is represented as a text field in the calibration page. |
|
{input-boolean: name} |
Allows the user to set a True/False variable called name. This entry field is represented as a checkbox in the calibration page. |
|
{input-multi-item1,item2,…,itemn: name} |
Allows the user to select one of several options defined as a comma separated list. When the simulation is run, a variable called name will be declared as a string and will have the value of the item that was selected. This entry field is represented as a popup menu in the calibration page. |
|
{input-hidden: name} |
Creates a hidden input field. This is useful for developing more complex calibration pages that use non-standard user-interface controls. The variable is available to your model as a string. |
|
{cancel} |
Closes the calibration window without saving the variable selections. |
|
{save} |
Saves the variable changes and then closes the window. |
That’s really all there is to it! Simgua’s calibration page methodology is extremely powerful and allows you to develop very rich configuration interfaces for your components. A screenshot of a more full-feature configuration dialogue is shown below. This dialog uses JavaScript to provide dynamic content changes and even animations:
A Full-featured configuration dialog
In developing more full-featured pages two additional capabilities of Simgua will prove very important. The first is that in the input tags, you made add an additional semi-colon after the input name. Any text following that semi-colon will be inserted into the input’s HTML tag. The input is automatically given an ID and name equivalent to the name you specified, but you can insert additional styling information or JavaScript event calls. Second, you may embed external resources – images, JavaScript libraries, CSS sheets, etc. – within the component itself. Also, all Simgua applications comes with a “Shared” folder that contains copies of the Prototype and Scriptaculous JavaScript libraries.
It
is important to emphasize just how powerful the calibration page mechanism is.
You can develop complete sub-applications as part of your components’ calibration
pages. To illustrate this, Simgua comes with a simple toy component called “Super
Mario World” that allows you to play a game of Super Mario World all from
within Simgua!
You may need to play with Simgua’s calibration page mechanisms a bit before you fully get a true feel for their capabilities. We recommend you start by looking at the configuration dialogues for the components that are bundled with Simgua.