May 1 2016

wsurvey_choser documentation.

wsurvey_choser is a javascript libarary that is part of the wSurvey package.

It contains functions that will create html code containing a set of checkboxes that allows the end-user (the person
looking at the browser) to  "chose values".

    The enduser can chose zero, one, or more values (by clicking on checkboxes).
    Selected values are returned (via a callback) as an array

 Useage: at the top of the HTML, include:

    <script type="text/javascript" src="/wsurvey/publicLib/jquery-1.11.3.min.js"></script>   // or you can use some other version of jquery!
    <script type="text/javascript" src="/wsurvey/jsLib/wsurveyUtils1.js"></script>
    <script type="text/javascript" src="/wsurvey/jsLib/wsurveyChoser.js"></script>

 See wsurvey_choser_demo.htm for an example of useage


 Functions:

::::::    content=wsChoser_create(items,options,myCallback,displayOptions)   -- creates content to be displayed

          items: array of choice specifications, each row an object with id,message,comment, title, and group fields
          options: display options (optional)
          myCallback : string  -- name of function to call on submit (optional)
          displayOptions: object -- how to display generated content (optional)

       What is returned in content:
         HTML content listing these choices, with buttons to choose.
         The submit button for this table will call the callback, with an array of ids that were chosen as the first argument,
         and callArgs as the second argument.
         The programmer should display this content -- say using $('#showme').html(content) ;

    wsChoser_style(atype,prefix,afactor)  -- format content using some pre-defined styles

         atype: which pre-defined style to use
         prefix : optional -- should match the prefix defined in options (in  wsChoser_create)
         afactor :  scalar, or array, of options (depends on the atype)

    choices=wsChoser_submit(prefix,afunc,arg2)  -- return an array of the values of the selected (checkbox checked) choices

         prefix : optional -- should match the prefix defined in options (in  wsChoser_create)
         afunc: call back function (a string naming the function, or a function reference)
         arg2 : optional. Argument passed to afunc as 2nd argument (first is array of selected choices)

        choices is an array containing the values (the id fields) of the selected choices



  ::::::::::::::::::::::: function details ::::::::::::::::::::

 wsChoser_create(items,options,myCallback,displayOptions)   -- creates content to be displayed

 Arguments
   items:  The choices
     MUST an   array.
     Each row is a specific choice, structured as an associative array, with fields:  message, id, comment, title, group
     None of the fields are required (defaults will be used).

     The following fields are supported:

        id:  value returned when this checkbox is checked. If not specified, use "choice_n"
        comment:  text placed next to message (smaller, oblique, font). If not specified, nothing written
        group: the "group number" this is in. If not specified, the current group number (which starts at 1) is used
        message:  text displayed next to checkbox (in a <label>). Default is "choice n" (n is the choice number)
        messageChosen: text displayed in the "list of current choices" (if showInfo=1 below)
        selected:  0 or 1. If 1, this is pre-selected.
        title: mouseover title for the message and checkbox. If not specified, 'choice # n') is used


   options: an associative array of formatting and other options
      Fields are (case insensitive):
          callArg : string -- it will be passed to the callback function. If not specified, '' is used
          checkAll : optional. If 1, include checkall buttons next to groupHeader.
                           This is used to select (or unselect) all choices within a group
                      If 2, also include "select all" and "unselect all" buttons (at top)
          groupHeader: array of descriptive headers for each group. Should be same number of rows as rows in items. If too few, "Group n" (n=1...N) is used
          howDisplay:  Can be  TABLE, or LIST
              If TABLE, the following are used:
                  ncols: # of columns per row. Default is 3
                  headerWidth: width of first column (the header column). If not specified, or '', no width attribute added to top row's first column
              If LIST, the following are used:
                  bullet: a list-style-type. Examples: decimal, disc, square, lower-roman.
                  Note: bullet will override a list-style-type specified via a css class.
          orderedChoices : optional. If 1 or 2, the order of choices is maintained, and can be manipulated (see below for details)
          prefix : a string used to identify this set of choices. Use this if you have multiple calls to wsChoser_create (i.e.; several
                   different choser lists open at the same time). Otherwise, you can not specify (and use the default of 'wsChoser')
          showSubmit : a 0 or 1. If 1 (the default) include  a submit button  at top
                       Otherwise, the script should have some way of calling wsChoser_submit (say, using a seperate  <input> button)
          showInfo:  a 0 or 1. 0 is the default. If 1, dispaly a running count of number of choices currently chosen,
                      and a toggle'able box of the the messageChosen values of these choices
                   Notes:
                     *  showInfo will be ignored if displayOptions (below) is not specified (or equals '')
                     *  showInfo  REQUIRES specifying 'where' in the displayOptions.


    callback: string. The name of a function to call when submit button hit.  Do NOT specify a function reference -- it must be the name
              First argument send to this fucnction will be array containing IDS that of selected choices. Second argument is callArg
              Notes: you can use wsChoser_submit instead of specifying a callback.
                     if you specify showSubmit=0, then callBack, and callArg, have no effect

    displayOptions: object of 'how to display content' options. Recognized (case insensitive field) are:

        Note: although displayOptions is optional, we recommend using it (rather than writing content to a container after
              calling wsChoser_create)

        'where'  : string or function reference. Optional. If not specified, or '', nothing is done.
             If a function reference (i.e.; where=showAlertOnTop) the function is called with the content
             If an id (i.e.; where='myStuff', then content is displayed in this container. eg;  $('#myStuff').html(content)
             Note: showInfo will be ignored if display is not specified (or equals '')
        'style' and 'styleOptions':
           Style to use. Style can be 'horiz,'box','colorRows', or 'grayRows'
           styleOptions should be an object, that depends on the style

           Basically, these are used in a call to wsChoser_style -- so see the wsChoser_style documenation (below) for the details.

  What is returned:
     HTML content listing these choices, with buttons to choose.
     The submit button for this table will call the callback, with an array of ids that were chosen as the first argument,
     and callArgs as the second argument.

     Note: if displayOptions is set, you can ignore what is returned.
     
     WE RECOMMEND setting displayOptions!  If you don't, several features (such as orderedChoice) are NOT supported.

  Structure of content:
     If howDisplay='table'
        A TABLE with two columns, with each row specifying a seperate group
          The first column contains the group's header
          The second column contains a table of ncols rows, each cell contains one choice
     If howDisplay='list';
        A <dl><dt><dd> structure, with the <dt>containing the group's header, and the <dd> containing a <ul> list of choices (one per <li>)

  Using group
     The group field of each row in items is used to divide the choices into seperate groups
     If used, it must be an integer value greater than 0
     Each group is displayed in a different area (for example, in a different <dt><dd> area if LIST is chosen)

     You can specify group for each choice, and they can be in any order.
     If you do NOT specify a group, the most recently specified group value will be used. To start, this is 1 (that is,
     the group of the first row, if no group field is specified, will be 1)
     This feature simplifies entry of groups: if the choices are sorted by group, you only need to specify a group field
     for the first row of the group
 
     While you can specify group numbers of any value, to avoid trouble used values from 1... #groups (and don't skip any)
     Note that group #1 will use the first groupHeaders (row 0 of groupHeaders), etc.
 
  Ordered choices

    By default, wsChoser returns an unordered array. That is: the order in the array is indeterminate (actually, is
    based on order in items).
    You can allow the end-user to specify the order -- so that the first element in the array is "chosen first", etc.

    CAUTION: ordered choices REQUIRES specifying 'where' in the displayOptions. 
    
    This is done by setting the ordererChoice option to 'H' or 'V'.
      'H' : show the list of ordered choices using a horizontal list
      'V' : show the list of ordered choices using a vertical list

    With either choice:

      * the top row of the display will contain a list of currently selected choices, in the order  they will be returned.
      * instead of checkboxes, buttons are displayed by each choice.
         o These start as green triangles: click on one and the   choice is added to the end of the list
         o After clicking, the button becomes a red updside down triable. Click on to remove the item from the list
      * Within the list, left and right arrows are displayed by each choice. These can be used to move the choice
        closer to the top, or the bottom, of the list
      * A gold arrow is displayed at the front of the list -- click on this to continue moving the most recently moved item

    Notes:
      * showInfo does NOT work when orderedChoices is used.

  Classes and IDs used in the content.
 
   You can use these to customize the look of your content (after a call to wsChoser_create).
      These can be used if you want finer control than achieved with the style option of displayOptions,
       or by directly calling wsChoser_style.

   The following assumes that the default prefix is used. If you set a different prefix (in the options), substitute
   "wsChoser" with the prefix you specified. For example, if prefix='myPals', then instead of wsChoser_top use myPals_top

    IDs:

      wsChoser_top       : the id for the main container. The <table> or the <dl>
      wsChoserHeader_ig  : The <div> where each group's header is written. ig is the group number (starting at 1) 
                            For lists, this is in each <dt>
                            For tables,  this is in each first column cell (<td>) of the main table
      wsChoserContent_ig : The container containing each group's choices.
                             For lists, this is the <div> inside of the <dd>
                             For tables, this is the id of each choice table (<table>)

     wsChoserChoice_id   : The container that contains the input element. id is the id of the choice (i.e.; 'choice_1')
                             For lists, this will be in a <li> (that has a <div> with a  wsChoserChoiceOuter class)
                             For tables, this will be in a <td> (that has  a <div> with a wsChoserChoiceOuter class)
     wsChoserLabel_n     : The <input> element. n is the nth choice (starting with choice 1 in group 1, and NOT resetting between groups)
                             Its main use is to match the <label> that contains the message (for each choice)

      wsChoser_topHeaderList : if orderedChoices is specified. This is the container (at top of table or list) where the ordered
                              choices are displayed. You might want to change its title attribute.

      wsChoser_OrderedUlHeader : if orderedChoices is specified.  The span (left hand <td>)  that contains the header for the list of ordered choices.
                                 You can change its .html. The default is "<em>Current:</em>".

      wsChoser _orderedUlToggle :  if orderedChoices is specified.  The <input> for toggling view of wsChoser_OrderedUlContent. You can
                                    change its styling (its content is dynamically updated as choies are selected and unselected)

      wsChoser_OrderedUlContent : if orderedChoices is specified.  The div (left hand <td>) that contains the list of currently selected choices.
                                 You can change its formatting (its content dynamically changes as you select and unselect choices, or change their ordering).

    Classes:

     wsChoserGroup_odd and   : container that contains a group (alternating).
     wsChoserGroup_even        For lists, this is a <dt>.
                               For tables, this is a <tr> (in the main table)
 
     wsChoserHeader          : container that holds header info for each group.
                                For lists, this is a <div> inside of each <dt>
                                For tables, this is a <div> in the first column of the main table

     wsChoserContent        : class for the containers that holds the "choices"
                               For table, this is a <table>; a seperate table in the 2nd column  (<td>) of each  row (<tr>)
                                  Note that this <table> also contains an id of wsChoserContent_ig
                               For list, this is a <div> inside of a <dd>
 
     wsChoserContentRow_odd and  : For tables, these are assigned to alternating rows (<tr>)in each of the choice tables
     wsChoserContentRow_even       For lists, this is the <div> inside the <dd>. Unlike with tables, only one of these per <dd>.
                                      Its value will match the <dt> class.
                                      Eg: <dt class="wsChoserGroup_odd" ...> ... <dd..> <div class="wsChoserContentRow_odd> ...
                                      Note that this <div> also contains an id of wsChoserContent_ig
 
     wsChoserChoiceOuter    : the container that contains the <input> -- a <div> inside of  either a <li> or a <td>
 
     wsChoserChoices        : assigned to each <input>
 
     wsChoserGroup_ig       : assigned to <input>s in the same group. "ig" is group number (starting at 1)
 
     wsChoserComment        : assigned to the <span> that contains the comment for each choice
 
    Hints:
      When using a table...
 
           * to add "cell spacing" use:
             .wsChoserContent {
                border-spacing: 5px;
                border-collapse: separate;
             }
           * to add "cell padding" use:
               .wsChoserContent td {
                  padding:10px;
               }
 
     When using a list:
 
           * show as vertical list, each choice with a border
               .wsChoserChoiceOuter {
                  border:11px solid brown;
                  list-style-type: none ;
               }
 
            * to create a horizontal list that wraps
                #wsChoser_top ul  {
                   overflow:auto;
                   list-style-type: none ;
                }
             and ..
                wsChoserChoiceOuter  {
                  float: left;
                  margin: 10px  ;
                  width:25%;
                  height:1.5em;
                  border: 1px solid #aaa;
                  padding: 0 20px;
                  overflow-y:auto;
                }
 
          Alternative: use the wsChoser_style funtion (see below)!
 
  Example of items:
    items=[];                the choices
          items.push({'id':'choice1','message':'Bob jones','comment':'North Dakota rep'});   first choice in group 1    (choice #1)
          items.push({'id':'choice2','message':'Bill Smith','selected':'1'});                    second choice in group 1 -- preselected
          items.push({'id':'choice3','message':'Joe Shalbotnick'});                               third choice in group 1
          items.push({'id':'choice4','message':'Sally May','comment':'maintance admin','title':'contact for issues','group':2});     first choice in group 2
          items.push({'id':'choice5','message':'Amy Simons','comment':'(director)'});        second choice in group 2  (choice #5)
 
   Example of options:
        options={'howDisplay':'table',
          'ncols':3,
          'groupHeaders':['my work friends','my other friends'],
         }
 
 Example:
    mytable=wsChoser_create(items,options,'','myContent');
    showAlertOnTop(mytable);
    $('.wsChoserContentRow_odd').css('background-color:lime');            this colors the rows of the "content" tables (one content table per group)
    $('.wsChoserContentRow_even').css('background-color:cyan');
 

::: choices= wsChoser_submit(prefix,acallback,arg2)

     prefix : optional -- should match the prefix defined in options (in  wsChoser_create)
            If not specified, wsChoser is used.
     acallback: call back function (a string naming the function, or a function reference)
     arg2 : optional. Argument passed to afunc as 2nd argument (first is array of selected choices)

    choices is an array containing the values (the id fields) of the selected choices

   This will create an array that contains the values (the id fields) of the selected (checkbox checked) choices. 
   This array will be returned (as choices).
   
   In addtion, if acallback is specified, it will be called with this array as the first argument, and arg2 as the second.
   
   Note that using this function is a somewhat more powerful alternative to the (default) of showSubmit=1 in the wsChoser_create options.
      * arg2 can be anything (it does not have to be a string or number)
      * acallback can be a function reference (it does not have to be a string that contains the name of an existing function)
   However, wsChoser_submit "forces" a submit -- it does not wait for the end user to hit a submit button.

   One trick is to:
      * specify options['showSubmit']=0   to suppress creation of a submit button
      * add a button that calls wsChoser_submit, or that calls a function that calls wsChoser_submit, to the content
      * Be sure that the prefix matches the prefix used in the wsChoser_create (i.e.; use the default if you never have more than one
        set of "choices")


::::  wsChoser_style(atype,prefix,afactor)  -- format content using some pre-defined styles

        atype: which pre-defined style to use
        prefix : optional -- should match the prefix defined in options (in  wsChoser_create)
                    If not specified, wsChoser is used.
        afactor : used to in some of the "atype"s

   Example of usage:
     content=wsChoser_create(items,options,callback);
     $('#viewChoser').html(content);
     wsChoser_style('box');

   Currently supported types:

       For tables:

          coloredRows :  blue headers, light green main table rows, light gray choice table rows
              afactors is not used

          grayRows :  blue headers, light green main table rows, light gray choice table rows
             afactors supported:
              'height': -- height of row. If not specified, 1.3em; if '*', 2.7em. Else use value
              Example {'height':'3em'}
              If just {'height':'*'}, a height of 2.7em is used

       For lists:

          box       :  vertical list, with no bullets. Each choice in a bordered box
             afactors supported:
                 'width': width of box (default is 50%),
                 'height': height of box (default is 1.3em)

                 If width not specified, box covers entire line.
                Otherwise, width should be width of entry. For example: {'width':'50%'} yields a box half the width of the row

          horiz     : horizontal list that wraps --
             afactors supported:
               'scroll':  If 1 then, 2.3px height with auto scroll. Otherwise, about 1.5em high with no scroll bars,
               'width': width of each cell. If not specified, variable number of cells per row. For example; '22%' yields about 3 items per row
               'color1' and 'color2': odd/even group colors,