WME Client-side Manipulative Architecture
	               
		       by Paul Wang


Here a growing list of items about the architecture is collected
for discussion.

We are mainly talking about manipulatives controlled by
javascript, javascript in svg, actionscript for Flash.

A manipulative

* consists of one or more scripts and follows the naming convention:

  MealOrder.js  contains the costructor function:

  function MealOrder(id, arg)    
  // id is the variable name to reference the new object instance
  // arg is an associative array of user-settable arguments

  If the constructor is called with no arguments, it will
  use its internal default settings stored in the static
  associative array:

        MealOrder.defaultArgs

  [Note: Function overloading is supported only in the sense that 
  you can pass any number of parameters to a single function then 
  you can use the arguments  property to deal with the actual number 
  of parameters passed in. You cannot, however, define the same function
  twice (e.g. once with one parameter and once with two parameters) 
  and expect JavaScript to select the instance with the appropriate 
  function signature (as Java or other more sophisticated languages do). 
  If you define the same function twice, JavaScript will use the function
  instance defined later in the script and ignore the earlier definition.]

* The constructor file documents the name-value to be contained in
  the arg array.  The info is in the static field:

  MealOrder.document

* The meaning of arguments for the person customizing the manipulative
  is provided in a static associative array.  For example,

  MealOrder.argMeaning= 
  {  'menu': 'names of meal items and their decimal prices ',
     'image': 'the picture to display with the menu'
  }

  This is needed to guide editing.

* has a class-wide displayType propoerty that can be set to
  either "block" or "inline".

  MealOrder.displayType = "block";                 // or "inline"


* has a class-wide "location" property where the script is located
  relative to the root location of the site.  This location also
  is where images for the manipulative are kept (uploaded)

  MealOrder.location = "javascripts/mealorder";    // relative url to root

* is self-contained and stored in its own
    directory.  (for example javascripts/mealorder or svg/rulers)

* has these public methods/properties:

Class-wide: static
    instances -- is an array of ids (strings) for 
                   all existing instances 

    displayType -- "block" or "inline"
    
    location -- folder location as file pathname 
                relative to site root

    setLocation("path") -- set the folder location as pathname
               relative to site root

    document -- A string for API and developer documentation

    help() --  A string for end-user help

    help("topic") -- A string for end-user help relating to topic

    defaultArgs -- An associative array for default arguments when
                   the constructor is called with no args.

    argMeaning= An associative array of param-name: meaning for
                user editable arguments.

Instance:
    reset()  -- re-intializes the manipulative instance

    getArg(name) -- returns the value of the named parameter.

    getArgs() -- returns an associative array of the values of all
                 parameters (in the same form as the array used
		 to call the constructor).

    setArg(name, value) -- sets the named parameter to the given value

    getProperties() -- returns an associative array of the values of all
    getProperty(name) -- for example the total of a meal order is a
       instance property. 
       
       instance.getProp('total')

    setProperty(name, value)

* can be deployed one or more times in a page.

* is customizable per teacher, per class, and per instance.

* is deployed in a page by creating an instance passing to
    the instance an argument (object) of parameter settings.
    The settings must include an id for the target <div> or <span> 
    element. 

* supplies instance methods that can be accessed from anywhere
  on the page for interaction with the manipulative.

* Teacher customizable manipulative parameters are set in the
  target TLP within javascript code identified with class="editable"
  (See the meal_obj.html example)

* Manipulative style control:  The html for a manipulative is always
  inside a <div> (block type)  or <span> (in-line type) with the
  class="wmDiv" attribute.  This allows CSS control such as

div.wmDiv button
{   background-color: orange  }