May 2016. wsurvey_form documentation.

 The functions in wsurvey_form.js will create a new window (or show an  existing container) and write content to it.
 In particular:
   a) it will write the contents of a <form> to this container (or new window)
   b) add callback event handlers to "submit" buttons on this form.
   c) When one of these "submit" submit button is clicked, a function is called that retrieves the fields (<input>, etc)
     on in this <form>

  List of functions:
        wsForm_setup(content,windowOptions,saveOptions)   :: write content to new window,
        wsForm_forceClose(gVarnamne)       :: close a window created by wsForm_setup
        wsForm_forceSubmit(gVarnamne)      :: get current values specified in a new window
        wsForm_info(gVarname)              :: create a table displaying information on the created window, and currently retrieved values. This may be useful for debugging.

Details:

  :::::   wsForm_setup

    wsForm_setup is designed to write an html form  to a new window, or to a container in the current window.
    The enduser can then click on a submit button to send the values of the form (after they have been modifed) back to the parent window
    Specifically, the values can be saved in a global variable; or a callback function can be called with these values

   Syntax:
        wsForm_setup(content,windowOptions,saveOptions)   :: write content to new window,
   Arguments:
      content: html string containing the form. More precisely, form elements (such as <input ...>) with or without a <form> ...</form>
      windowOptions: how to setup the window.
      saveOptions : how to save values returned from this window

   Details on arguments
     windowOptions is optional -- if not specified (or if ''), defaults will be used
       Recognized fields in windowOptions;
            winName : the name of the window. If such a window exists, it will be overwritten. Otherwise, a new window will be created. Default value is "viewer"
            localId :  id of container to write to in current window.    Default is '' (thus: the default is to use a window with a name of "viewer")

               Only one of "winName" and "localid" should have a non-'' value! If both are specified, winName is used (stuff is written to a  new window)
                 THUS: to use a localId -- you MUST specify winName=''
               Use of localid can be helpful if you want an "event driven" submission; or if you want to simplify collecting data from a form for an ajax submission.

          winOptions: Optional. a string containing window options (such as height, toolbar). Basically, the options available in window.open
                   Default values is a resizable window, with no toolbars.

     saveOptions is optional -- if not specified (or if ''), defaults will be used
       Recognized fields in saveOptions;
         callback: a string specifying  function to call when form values are saved.
                  If not specified,  values will be written to a global variable (see varname below)
                  Otherwise, this function must exist. It will be called with an object containing the values of the elements in the window.
                    See below for details on this object
           class: a class name of elements whose values should be returned. If not specified, "wsForm" is used
           names: a csv, or an array, of element "names" whose values should be returned. If not specified, no names are looked for.
          varname: name of global variable. This is used to store options, AND is used to store returned values. If not specifeid, "wsForm_options" is used
         submitId: id of a button that, when checked, will return values to the parent window. If not specified, "wsForm_submit" is used
     submitClass : class of a button (or buttons) that, when checked, will return values to the parent window. If not specified, "wsForm_submit" is used
                    You should specify, in the content, at least one element that has either an id equal to the submitId, or a class equal to submitClass

   How are values read and returned?
     The key to using wsForm is to specify, in the content written to the new window, elements that are to be read and returned.
     There are two ways of doing this:
         By specifying a matching name in   saveOptions.names
         By specifying a matching class in   saveOptions.class. CAUTION: there MUST be a name attribute in elements that have a class match.
     Basically, if an element in content matches one of the above, its value is returned. And this value depends on the type of the element.
     There are subtle differences between a "name" match and a "class" match, which are described below.

   How are values returned?
     Values are returned using the name of the element.
     Hence: elements with no name attribute are ignored (even if there is a class match)

     How is a value determined?
      It depends on the tagname, and type, of the element:
        <input>
             type="checkbox" :  If checked: returns its value (its value="..." attribute).
                                If not checked: returns null
                                Special feature: if a not checked, and noCheck attribute is specified, than its value is returned (instead of null)
             type="radio"    : If one of a set of radio buttons, that have the same name, is checked: return its value.
                               Otherwise, return null
                               Special feature: if none of the radio buttons are checked, and noCheck attribute is specified, than its value
                                                 is returned (instead of null)
             type="text", or other types : Returns the value (i.e.; text entered in a "text" field)
        <textarea>  : returns the value (stuff entered in the textara
        <select>  : returns an array of selected options (that are underneath the <select>
        <option>  : returns the value of the option if the option was selected. If not selected, returns null. This is odd, but it means you can
                    treat seperate <option> elements kind of like checkboxes
        <span>    : returns the .text() of the span
   All other tags: return null

    If a none of a radio button set is clicked, null is returned -- unless a noCheck attribute is present (in which case its value is returned).
    If a checkbox is not checked, null is returned -- unless a noCheck attribute is present (in which case its value is returned).

    Differences between name and class match
      Name match is straightforward:
         If no element has a name, nothing is done. That is, no value is returned for this name.
         Otherwise, a string is returned containing the value (or null, say if none of the radio buttons in a set were clicked)
         There is one exception:   for <select>, an array containing the selected values (one or more) is returned (0 length if no options were selected).
       Class match is more flexible, and more complex
          First, if an element has the class match (i.e; class="wsForm"), but no name attribute, it is ignored.
          Second, if an element matches a name and the class, only the name match is used (the class match is ignored)
          Third: values are returned in arrays. That means you can have more than one element with the same name, and each element's value
                 will be returned (as a seperate row in the array)
          This third feature can be a convenience -- if you want to read a list of items, and you don't care about the order, you can
             a) Specify the elements (say, checkboxes) with the same name and with the class
             b) The values of each of these elements will be returned in the array. Note that some of these might be nulls, or ''.

         Note: only one of a set of radio buttons (radio buttons with the same name) should contain the class.
              Otherwise, there will be seperate rows (with the same value) for each radio button with this class.

    How are returned values used?

      If you do not specify a callback function, then an object containing the values is stored in a global variable.
      In particular, under $(document).data(varname) -- where "varname" is the variable specified in saveOptions.
          By default, "wsForm_options" is used.
          This object is stored  in the 'values' field of this variable.
     Thus, to access these values (once the enduser has submitted them), use something like:
           dastuff=$(document).data('wsForm_options');
           formValues=dastuff['values'];
      And perhaps you would then use;
            gotdog=formValues['checkBox1'];    say, for <input type="checkbox" name="checkBox1" value="dogOwner">
            myName=formValues['myName'];        say, for <input type="text" name="myName" value="">
            myPets1=formValues['pets'][0] ;     say, for <input type="text" name="pets" class="wsForm" value="pet1">
            myPets2=formValues['pets'][1] ;              <input type="text" name="pets" class="wsForm" value="pet2">

      If a callback function is specified, the function (if it exists) is called with this object as the single argument
      (the object is also saved in $(document).data()


 :::::   wsForm_forceSubmit
     Force submit of a form in a new window (or in a container)
     Basically, simulate a click on a "submit button" (i.e.; a button with a id="wsForm_submit")
   Syntax:
        wsForm_forceSubmit(gVarname);
    where
       gVarname: the values specified in the saveOptions['varname'] (used when the window was created)
        If not specified (if wsForm_forceSubmit() is called), use the default value of "wsForm_options"

 :::::   wsForm_forceClose
     Force close of window (or hide container). A window is permanently closed, a container is hidden.
     Once a window is closed, wsForm_forceSubmit will not work (a javascript error will occur).
     However, for a container, wsForm_submit will work.

    Syntax:
        wsForm_forceClose(gVarname);
    where
       gVarname: the values specified in the saveOptions['varname'] (used when the window was created)
        If not specified (if wsForm_forceSubmit() is called), use the default value of "wsForm_options"

   :::::   wsForm_info
     Create an html table containing information on a window (or container), including values of currently retrieved values

    Syntax:
        atable=wsForm_info(gVarname);
    where
       gVarname: the values specified in the saveOptions['varname'] (used when the window was created)
        If not specified (if wsForm_forceSubmit() is called), use the default value of "wsForm_options"

    Hint: you can display atable in a "viewing" container, using : $('#showMe').html(atable)