MetaBuilder for PhysletScriptors

MetaBuilder is a tool for setting up a PhysletScriptor for a given physlet. MetaBuilder's input describes the available methods and the embedded parameters for the involved physlets, along with labels, color coding and a tool tip for the colored rows of the future PhysletScriptor. To understand the syntax of MetaBuilder, it's a good idea to experiment with the built-in sample descriptors in the description field at start-up. In addition, here comes a systematic overview, but one could also start with some examples at the end of this text.
Furthermore, MetaBuilder can extract the descriptors from the html source of existing PhysletScriptors in order to modify and rebuild them.

MetaBuilder's input consists of one or more sections depending on how many different applets are involved. Each applet section starts with headerlines with a leading "@" that specify some default values like the applet's name or its embedded parameters (see below). They are followed by short paragraphs which correspond to the physlet's methods:

Descriptors for methods:

One paragraph in MetaBuilder (separated by single blank lines) yields one colored row in the future PhysletScriptor's selection table.
Each paragraph describes the syntax of a single physlet method (command name, parameters), along with its representation in the PhysletScriptor (color, labels, tooltip etc.).

Variations of a complex physlet method, like addObject(), can be represented by separate PhysletScriptor rows having some of it's parameters pre-defined. Such pre-defined parameters are denoted as HIDDEN in the MetaBuilder syntax, for they do not require input fields in PhysletScriptor. All other parameters will display input fields according to their type: double (d), integer(i), object(o), string(s), flag(f) - see below. The order of parameters is the same as in the method's signature.rder as they are listed line by line in MetaBuilder (the same order as for the visible input fields in a PhysletScriptor row).

Levels of parameters

In physlet methods, there are two levels of parameters. They won't be distinguished in PhysletScriptor's rows but MetaBuilder needs to observe their different syntax:

  1. Parameters of the first level are the actual signature (parameter list) of the method:

        setConstraintStr(id1,"-x*x+2",-3,3);

    In this case a string parameter (type s) will be inserted in quotation marks, all others go without. Use the "flag type" parameter (f) to let the user insert an arbitrary string without quotation marks at this level - the variable name id1, for example. 

  2. At a second, inner level, parameters can be contained in one string that is for itself a parameter of the first level:

      ...addObject("source","infinite,x=2,y=1");

    In this case inserted values are usually preceded by their parameter names. String values at this inner level have no additional quotation marks, but they are also preceded by a parameter name (...,"x=2, text=My text,..."). Parameters of the "flag type" are inserted without their parameter name (...,"infinite,x=2,...").

MetaBuilder paragraphs

("|" is a delimiter, don't use it anywhere else but in the tool tip section!)

methodName (required):
JavaScript method name without signature (the parameter list in parenthesis)

retVar (optional):
If this is not an empty string, PhysletScriptor will precede the correspondent JavaScript statement by a declaration like
retVar3 = document.OpticsApplet...
These variables for return values are numbered automatically.
If the method returns an object id,
retVar can be chosen as "id". In this special case, all the generated variables (id1, id2, ...) will be added to the object selection input fields in other PhysletScriptor rows that demand objects as arguments.

#rowColor (required):
The color of the respective PhysletScriptor row as RGB value in hex format (#FF0000 for red). It will be very helpful for the user of a PhysletScriptor if methods of different physical meaning or different technical usage a grouped by a well-considered color code.
 

>>> tt >>> (tool tip, required):
everything between the ">>> tt >>>" delimiters becomes a tool tip that is displayed in PhysletScriptor, when the user's mouse pointer hovers over the field "(i)" at the beginning of every colored row. Tool tips may contain html-tags. Line breaks in this section are automatically replaced by "<br>". The delimiters ">>> tt >>>"
must be placed in separate lines.

displayName (required):
The label of the link in PhysletScriptors second row, where the user will click at to insert the correspondent scriptline.

parameterDescriptionLine (optional):
Corresponding to the two levels of parameters (see above), there are two constructions for parameter descriptors:

  1. Parameters of the first level
  2. parameterType|parameterName|defaultValue|LabelString

     

  3. Parameters of the second, inner level
  4. $|(parameterName)
    .|parameterType|parameterName|defaultValue|LabelString
    .|parameterType|parameterName|defaultValue|LabelString 

    Descriptors of second level parameters are preceded by a dot . Their corresponding first level string container starts at a line marked with a dollar sign "$", that optionally  comprises a (parameterName) for clarity, but the latter is ignored by MetaBuilder. A block of second level parameters ends with its last dotted line. Before and after this block can be other parameter descriptors - either first level lines or second level blocks.

parameterType:

symbol

meaning input elements in PhysletScriptor rows syntax first level syntax second level

i

integer text, 3 char. inserted directly preceded by "parameterName="

d

double text, 5 char. inserted directly preceded by "parameterName="

s

string either text, 30 char. or drop down selector (see defaultValue quotation marks added at scripting time preceded by "parameterName="

f

flag either text, 30 char. or drop down selector (see defaultValue) inserted directly inserted directly

b

boolean drop down selector: true/false inserted directly as true/false preceded by "parameterName="

o

object drop down selector: all available id# variables in the script output of PhysletScriptor inserted directly as id#  ** meaningless **

parameterName:
The parameter name as specified in the physlet documentation.

defaultValue (can be an empty string):
This is also the final value for HIDDEN input fields. Visible fields jump back to this value after every refresh of PhysletScriptors selection table. Special for string (s) and flag (f) parameters: If defaultValue is a comma separated list, these values are displayed as options in a drop down selector for this parameter with the first value being the default. In this case, there will be no text field for free input! The list feature doesn't make sense for HIDDEN fields, for only the first value will be evaluated!

labelString:
The label preceding every visible inputfield. It makes sence to close them with a colon (:). LabelString accepts html-tags, so <br> will force a line break in the table row of parameters.
A HIDDEN field is generated when
labelString is "-". 

Header lines

Header lines start with "@". They must be situated in arbitrary order before the method descritors and must not be separated by blank lines.
The trailing "|" is optional to avoid erroneous white spaces. Examples for possible header lines are:

@physletName|OpticsApplet|
@code|
optics.OpticsApplet.class|
@codebase|../classes|          or    @codebase|http://www.myschoolserver.edu/physlets/classes|
@code|
optics.OpticsApplet.class|
@archive|Optics4_.jar,STools4.jar|
@appletWidth|400|
@appletHeight|300|
(
@appletSize|400|300|            deprecated, width in pixels first )
@scriptHeader|setAutoRefresh(false);setDefault();|    
@scriptFooter|setAutoRefresh(true);|     every script will start or end with these methods for every instance of this applet

Embedded parameters are described each in a single line:
@embedParam|parameterType|parameterName|defaultValue|LabelString|

The meaning of the place holders is analogue to the method descriptors, see above. In this context only i, d, b, f are meaningful for parameterType. This specifies the type of the input field for this embedded parameter in PhysletScriptor. s is meaningless because no extra quotation marks are needed. Note: Type f can be combined with a comma separated list as defaultValue: This will restrict the choice to some possible values.

Examples for method descriptors:

setRGB|-    "-" means no variable for a return value like in "id1=document..."
#00FF00    
gives a light green row in PhysletScriptor
Set the red, green, and blue<br>color values...   
a tooltip with two lines, with a line break after "blue"
object's color    
text to click at to script this method row
o|id||Paint this object:                    
1st parameter: an object, named id, default senseless
i|r|255|with intensities 0..255 for red:     
2nd parameter: an integer, named r, default 255
i|g|255|green:                               
3rd parameter: the label "green:" precedes the input element
i|b|0|blue:                                  
4th parameter

(i)

object's color

 Paint this object: with intensities 0..255 for red:  green:  blue:  

-> Output:


addObject|id  an object id should be retained in a variable starting with "id..."
#FFDA92
mirror with focal length f at position x. The gra...
Mirror
s|name|mirror|HIDDEN    
1st param: a string parameter, called name, default value: "mirror", no input field
$                     
  2nd param: a list of three parameters embedded in a string (second level)
.|d|x|4.5|x:               
real number parameter x, default 4.5, labeled "x:" in the selection table
.|d|f|1|focal length:
.|f|method|,spherical|chose "spherical" to show aberrations:
   
a "flag parameter" has no parametername in the JavaScript output.  The list of possible values (nothing or spherical) is given as a comma separated list as default - the actual default for the input field is at the first place: the empty string

(i)

Mirror

 x:  focal length:  chose "spherical" to show aberrations:  

-> Output:


setDragable|-
#FFFF99
Make an object dragable. A dragable object will usually change its physical
make dragable
o|id||This object:                 
a object parameter -> drop down selection with all available id variables
b|isDragable|true|will be dragable:    
a boolean parameter -> drop down selection true/false

(i)

make dragable

 This object: will be dragable:  

-> Output: