March 2017.

 wsurveyShowAlert:  wSurvey javascript functions to show alerts in popup containers; and to show status messages in popup containers.

 Note: several of these functions work much better if  a <!DOCTYPE > is specified (at the top of the html document). For example:
    <!DOCTYPE HTML>

  June 2020: consider using ws_showContent instead -- it is more flexible.

 ::::::   Summary of functions :::::::::::
   init_showStuff(maxmove,clearEsc,noMin,noWindow,escList)  -- intialize containers, and click handlers used by showAlertOnTop and showStatusMessage
 
   showAlertOnTop(amess,aopts,doAppend,dofade,cancelFade,dofunc)  -- display a message in an "alert box"
   hideAlertOnTop()                         -- hide an alert box
   minimizeAlertOnTop(aid)          --  minimize alert box
   maximizeAlertOnTop(this)         --  maximize alert box
   resizeAlertOnTop(specs)         -- resize & reposition alert on top
   showAlertBoxMoveStart(evt)                -- handler used to enable move & resize of alert box
   showAlertMessageInNewWindow(aid,atitle,cssFiles,windowName)  -- copy contents of alert box to a new browser window
   getAlertMessage(aid)                      -- return string containing content of showAlertBox. aid is optional (default is alertBoxMessage)
   showMessageHistory(viewName)             -- open new window with list of messages written
   showAlertOnTop_doEsc(evt,akey)           -- enable ESC key (to close showAlertOnTop box

   showStatusMessage(amess,aduration,dohold,boxnum)  -- display a message in a status box. writeStatusMessage is a synonym.
   showStatusMessage2(amess,aduration,dohold,boxnum)  -- display a message in a status box

 ::::::::::::::  Details  ::::::::::::::::
    init_showStuff(maxmove,clearEsc,noMin,noWindow,escList)  -- intialize containers, and click handlers used by showAlertOnTop and showStatusMessage

    showStatusMessage and showAlertOnTop require containers (such as <div>s) with specific ids.
    They also work best when click handlers are assigned to them.

    init_showStuff will create these containers (if they do not exist).
    And it will assign appropriate click handlers.
    And it will create a few necessary classes.

    THUS: if you use init_showStuff -- you should NOT specify the containers (init_showStuff will do it for you).

    Maxmove is optional. If specified, it should be an integer.
       It specifies the maximum pixel move -- anything bigger causes a "move" or "resize" to close.

       This is to deal with a March 2016 Firefox bug: rapid movements can break the "mouseup" and "mousedown"
       event handlers (causing the box to keep moving or resizing even after you take your hand off of the mouse!)

       Alternatively: do not specify, or specify a '0', and a non-visible <textarea> is added.
       For some odd reason, this seems to cure the problem!

    clearEsc is optional. If specified, and equal to 1, then hitting the esc key will close the alert box and the status messages box.
       This is coarse, it uses a document keyup handler. So it may not work nicely with other document keyhandlers.

    noMin is optional. If specified, and equal to 1, the "mininmize this box" icon is not shown.
          Note: for "minimize this box" to work, a maximizeAlertOnTopButton must be specified (see maximizeAlertOnTop function)

    noWindow is optional. If specified, and equal to 1, the "show this message in a new window" icon is not shown
    
         noWindow can be a 3 element array. Values can be 0/1 (anything other than '1' is a 0). For all three, 0 is the default

           [0] : 1 = Do NOT show 'display in new window' button
           [1] : 1 = DO show button to 'maximize this display in this window'
           [2] : 1 = DO show button 'reset size and position to current values'

         Special case: noWindow (either specified by  itself, or as part of an array) can be a csv of "locations of css files". These will
         be included in the new window using: <link rel="stylesheet" type="text/css" href="alink">
         For example:
              noWindow[0]='myCss.css',project1/otherCss.css'
         will yield:
             <link rel="stylesheet" type="text/css" href="myCss.css" />
             <link rel="stylesheet" type="text/css" href="project1/otherCss.css" />
         This can be useful if content written to showAlertOnTop refers to css styles specified in a custom css file

         Typically, after a move or resize::
              showAlertOnTop calls (while the showAlertOnTop container is open) will write to the new position,
              but once the showAlertOnTop container closes (i.e.; when the "x" is hit), when it is next reopened the defaults (the old size and position) are used.
         Using the "reset " button will change these default to whatver the size and position are when the "reset " occurs

         Note: to set the original size and position  ....
           a) Open showAlertOnTop.
           b) Set size and position either with the options when opening showAlertOnTop, or with a call to resizerAlertOnTop
           c) Call showAlertOnTopSetPosition
           You can then close (using hideShowAlertOnTop, and then reopen with showAlertOnTop (with on options) -- it will reopen in the new position.
           Example:
              showAlertOnTop('test in default position ');
              confirm('Ready to move?');                                  // just to show you where the default position is
              resizeAlertOnTop('height=393,width=624,left=50,top=50')  ; //  smaller box in upper right
              showAlertOnTopSetPosition();                              // no argument needed
              hideAlertOnTop()  ;                                      // close it.. to prove it works ...
              confirm('Ready to redisplay?');                           // you see it is closed!
              showAlertOnTop('test in new positon ');                   // and it now reopens in the new position

         Note:
           the  reset aize and position button  is a snowflake
           the  maximize button is a maltese cross

    
    escList is optional. It is only used if clearEsc=1. If used, it should be a csv of container ids.
    These containers will be closed when esc is hit -- with the first esc closing the first id in the csv, the 2nd escape
    closing the 2nd id, and so on.  THIS ASSUMES that the container with this id is visible! 
     Thus:
        i ) extract the first id in the list. If it is visible, close it and stop
        ii )If it is not visible (or does not exist), check the 2nd id. If it is visible, close it and stop
        iii) Continue use this for 3rd ,4th, etc ids
        iv) If none of the ids are visible, then close the showAlertBox
     Typically, these ids point to containers (<div>s etc) written to the showAlertBox. Thus, you can use estList to
     first close a sub box, then close another sub box, and then close the alert box (i.e; have 2 ids in the CSV)


    Notes:
         init_showStuff is typically called by an onLoad function , or by a $( document ).ready().

   Example:
         init_showStuff(0,1,1,1,'iseriesHelpDisplayDiv') ;          


  ----------------

  showStatusMessage(amess,aduration,dohold,boxnum)  -- display a message in a status box
                                                     -- writeStatusMessage is a synonym for showStatusMessage
     where:
          amess: a message to display. Typically, a one or two line message (but it can be any length). This is the only required argument
          aduration: milliseconds-- time to fade. If 0 or not specified, no fade. If -1, immediate close (used by dohold=2 or 3)
          dohold=1 : add a "halt fadeout" button. Default is to NOT add such a button.
                 2: add a "close this" x button
                 3: add both

          boxnum: Either 1 or 2 -- specifies which (of two) "status messages boxes" to write to.
                  Trick: If -1 or -2, append to these boxes (otherwise, replace content)
                  The default is boxnum=1;

     For showStatusMessage to work,  init_showStuff should be called beforehand.
     Or,   the following containers MUST exist(that have the following ids)
            statusMessageBox   --  container used for messages (when boxnum=1).
            statusMessageBox2  --  container used for messages (when boxnum=2)

     If a required container does not exist  an  error message  is shown and a '' is returned

     These containers are typically small (ie; 10% of screen height & width) boxes with a absolute location
     (i.e.; upper left corner of screen),   and with overflow specified.
     statusMessageBox is often larger than statusMessageBox2

     Notes:
          * a statusMessageBox_mess and statusMessageBox2_mess containers are created and inserted into the above
             (they contain the actual message)
          * The messageStash global array varible, if it exists, is used to store all messages.
          * if showStatusMessage is called in quick sequence, then later calls will overwrite messages
            specified in an earlier call (and will stop any prior fadeout)

  ----------------

  showStatusMessage2(amess,aduration,dohold,boxnum)  -- display a message in a status box

    Same as showStatusMessage, but uses boxnum=2 as the default.

  ----------------

  showAlertOnTop(amess,aopts,doAppend,dofade,cancelFade,dofunc)  -- display a message in an "alert box"

      where:
           amess  : message to display. Can be lengthy.
           aopts  : either a background color (i.e.; 'cyan'), or an object specifying a number of options. See below for details
        doAppend  : if 1 append to current contents, else overwrite (the default). Or, see showAlertOnTopAppend  for an alternative
          dofade  : if >0, is fadeout in milliseconds. If 0 (the default), no fadeout
       cancelFade : if 1, a "cancel fadeout" button is inserted (next to the close this box button). Default is 0
          dofunc  : A string containing a function call (including needed arguments). The function is called when the fadeout is completed.
                   The default is not to call any function

     For showAlertOnTop to work,  init_showStuff should be called beforehand.
     Or, the following containers MUST exist (that have the following ids)

        alertBoxDiv     (optionally, with a class="alertBox")
        alertBoxDivHeader (optional -- used to write "headers")
        alertBoxMessage (optionally, with a class="alertBoxInner")

        alertBoxMessage MUST be embedded within alertBoxDiv

     If no arguments, return true if alertBox is currently visible. False otherwise
        example:
           if (showAlertOnTop()) alert("alert box is open. Use it!! ");
        
     Details on aopts:

       If aopts is not specified, or is '', then no background mask is used behind the "alert container".

       If aopts is a string, it should specify a color to use in the background mask.

       If it is an object, it can have the following fields:
            color : color to use in background mask
            xoff : horizontal offset in pixels (-values mean move left, + value move right
                 Special case: xx% means "place xx% (of width) from left edge of parent window
            yoff : vertical offset in pixels (-values move up, + values move down
                 Special case: xx% means "place xx% (of height) from top edge of parent window
            hinc : height increment in pixels (-values mean shrink
                 Special case: xx% means "make xx% (of height) of parent window
            winc : width increment in pixels (-values mean shrink
                 Special case: xx% means "make xx% (of width) of parent window
            header: string used in the header. If not specified, header element (with id alertBoxDivHeader) is cleared whenever showAlertOnTop is called
           nocloser: if 1, do NOT display "close this box" button
            close:  if 1, immediately close (call hideAlertOnTop). If was visible return true, else return false

           The xoff,yoff,hinc,and winc are applied to the current size of the alertBoxDiv container

      Details on dofunc

         If dofunc specified, should be a string containing a string that is executed as is
         (called using a javascript eval -- typically a function call )
         dofunc is called when the a fade is done (if no fade specified, dofunc is ignored)

         So: when the fade completes, a hideAlert is done (just to completely close), and then (if specified) the dofunc is done

      The background mask

          A background mask is used to partially cover content behind the "alert box" -- so that nothing can be
          clicked until the alert box is closed.
          You can specify an explicit background mask by embedding the alertBoxDiv in a container with a
          class="showAlertOnTopMask".  Typically, this will have a  large z-index (around 50), so as to block content behind the alert box.
         Note that z-index of 60 or so is given to alertBox elements: so the mask's z-index should be less than 60

         If no such container exists, and if a background color is specified (i.e.; aopts='cyan'), then a container is created with
         a class of showAlertOnTopMask, and an opacity of 0., and a z-index of 20.

    Examples:
       showAlertOnTop('<hr width="80%">Welcome to my world','cyan',1,2000,1,"viewLocalBoxes_wsEmail('"+acctName+"','2LIST')" );
       if (showAlertOntop('',{'close':1})) alert('it was open but not now!');

    Note:
       To reopen a box, displaying the contents it had when closed, you can use:
          showAlertOnTop('','',1)     -- append nothing to current contents
  ----------------

  showAlertOnTopAppend(message,color)
     Shortcut to showAlertOnTop -- append mode.

  showAlertOnTopAppend1(message)
     Shortcut to showAlertOnTop-- default options. This can be useful when used as a callback (other arguments are ignored)

  hideAlertOnTop() or hideAlertOnTop(this)   -- hide an alert box

     hideAlertOnTop()
     The alert box (with id="alertBoxDiv") is hidden, as is any "background mask" (with a class="showAlertOnTopMask")

     hideAlertOnTop(this)
        This should be used as the click handler of an element (i.e.; of  button)
            A doreload attribute is looked for.
           If there is a doreload="1" attribute, then the current document is reloaded  -- using location.reload(true)

  ----------------

 fadeAlertOnTop(this) -- temporary fade of alert box
      Mostly deprecated. Used as:
         <input type="button"  alue="Dim" title="dim/undim message box" isfaded="0"  onClick="fadeAlertOnTop(this)">
      Clicking button will fade alert box, clicking again will unfade.

  ----------------

 minimizeAlertOnTop(aid)  -- minimize alert box
 maximizeAlertOnTop(this)  -- maximize alert box

    In  minimizeAlertOnTop(aid): aid is a string containing the id of a button that will be used to maximize the alert box.

        This button (or other element) MUST exist. If it does not, an error message is displayed.

        This button should have an click handler that calls maximizeAlertOnTop(this)

     Example:
      In the alertBoxDiv (but not in alertBoxDivMessage):
          <input type="button" id="alertBoxDivMinimize" value="Min"  title="minimize"
              onClick="minimizeAlertOnTop(\'maximizeAlertOnTopButton\')">

      And somewhere else (say, in a top row of buttons that is always visible)
         <input type="button" title="Maximize" style="display:none"  value="redisplay" id="maximizeAlertOnTopButton" onClick="maximizeAlertOnTop(this)" >

      When the "Min" button is clicked, the alert box is "minimized"; and the maximizeAlertOnTopButton is shown.

 ----------------
 resizeAlertOnTop(specs)  -- resize alert on top

   specs: object specifying resize options (in pixels or % of screen)
      height:  height
      width:  width
      xoff:  top left corner x offset
      yoff:   top left corner y offset
     Example: resizeAlertOnTop({'height':'94%','width':'94%','xoff':'2%','yoff':'2%'} );

   Or,   a csv of field=value, field2=value
      Example: resizeAlertOnTop('height=94%,width=94%,xoff=2%,yoff=2%')

   Or, '' for default values :   height=94%, width=94%, xoff=2%, yoff=2%
      Example: resizeAlertOnTop('');

   Or '1' to return csv of size info (in pixels) :  such as 'height=671, width=555, xoff=22, yoff=51 '
   This string can be used to "un-resize" in a future call to resizeAlertOnTop

  Notes: the message in the alertBox will not be changed. And, if the alert box is not visibile, it will stay not visible

 ----------------

 showAlertMessageInNewWindow(aid,atitle,cssFiles,dispWindow)  -- display content of alert box (or some other container) in a new window

       aid : if specified, the id of the container (whose contents will be displayed).
             If not specified, or '0', use 'alertBoxMessage'
    atitle: if specified, a <title> for this new window. 
   cssFiles: a csv of paths to .css files to be included in the new window using <link rel="stylesheet"  >  elements. 
             If not specified, no  css files included
   dispWindow: target of display. If not speciifed, _blank is used
 
function showAlertMessageInNewWindow(aid,amess,csslist,myWindow) {

   Note: this calls displayStringInWindow (in wsurveyUtils1.js)

 ----------------

 showAlertBoxMoveStart(evt) -- intialize "move" and "resize" alert box actions

 This is called by init_showStuff. So if you use init_showStuff, you should NOT call this!

   Typically, this is used with something like:
     zdata={'todo':'pos'};
     $('#alertBoxShiftPosition').mousedown(zdata,showAlertBoxMoveStart);
     zdata={'todo':'size'};
     $('#alertBoxShiftSize').mousedown(zdata,showAlertBoxMoveStart);

   Where  alertBoxShiftPosition and  alertBoxShiftPosition  are buttons (or other elements) that are located inside of alertBoxDiv
   (but NOT inside of alertBoxMessage). These buttons typically have an absolute position, at the end of the box
   For example:
      .alertBoxResizeIcon {
          position:absolute;
          left:98%;
          top:97%;
          z-index:66 ;
          background-color:gold;
      }


  ----------------
 showMessageHistory(viewName)             -- open new window with list of messages written

    viewName, if not specified (or if '1'), is 'viewer'. It is the name of the window to open, that will contain list of messages.

    showMessageHistory displays content of the global messageStash array.
    messageStash is used by showStatusMessage and by viewAlertOnTop -- everytime one of these is called, the contents
    of what is written (and a timestamp) are saved to messageStash.

    Hence, if messageStash does not exist, showMessageHistory will display nothing.

    Note:
      structure of each row of messageStash:
         [0] - the message
         [1] - short name used to describe messages (i.e.; status_0)
         [2] - a timestamp

      Note: showMessageHistory invokes /wsurvey/phpLib/showMessageStash.php

  ----------------

   showAlertOnTop_doEsc(evt,akey)   -- enable ESC handler.
   
 This is a rather primitive function that enables the ESC handler for showAlertOnTop. If used, hitting the ESC key will
 close the showAlertOnTop "alert box" (which might be a moveable container).

 Useage: In the initialization function of your html document, insert:

    $(document).keyup(showAlertOnTop_doEsc) ;

 Note: showAlertOnTop_doEsc function makes no attempt to work with other keystroke handlers.

  ----------------

   writeToDebug1(amess,ido,noshow)  -- write a "debug" message
      where:
         amess = message towrite
         ido   = if 1, toggle display of the debug container (message is ignored
                 if 2, add a  "show hidden info" icon
         noshow : if 1, the message is hidden (it is "hidden info")

      For this to work, a container (i.e.; a <div>) with id="debug1" must exist, which must be embedded in a container with id="debug1_div".