May 2016. wsurvey_readFiles.js documentation.


These functions simplify file uploads using <input type="file" ...>

They are designed to make the contents of a file upload  accessible to javascript functions.

In particular, suppose you wish to use  ajax to transfer information to a php script; rather
than using a <form>. In such a case, you will need to explicitily access the contents of a file upload.
These functions make that easy.

They can also be used if you are going to use a <form> (with a <input type="submit"> button -- while not as necessary,
these functions do support some nice display options.

  -----------------

Function list

   uploadInfo=ws_readFiles_setup(useid,options) -- initial setup.
   ws_readFiles_clear(uploadInfo)               -- reset & clear file upload elements
   ws_readFiles(evt)                            -- event manager assigned to <input type="file"> element.
   ws_readFiles_unpack(storeName)                 -- unpack information stored  by ws_readFiles

  -----------------

Descriptions of functions:

 uploadInfo=ws_readFiles_setup(useid,options)    -- initial setup.

   Arguments:
        useid: either '', 1, or the id of an <input type="file" ...> element
               If '1' or '', then a default value ('readFiles') is used.

               An element with this id MUST EXIST.  It should be a <input type="file" ...> element.
               If no such element exists, an error (with an alert message) occurs.

        options: optional.  If specified, an associative array that can have the following fields:

            maxFiles    = maximum # of files that will be uploaded    (default is 25)
            maxFileSize = maximum file size, in mega bytes            (default is 10)
            infoId      =  id of container to display file information (size, etc)
                        If 0, do NOT display file information
                        If 1 or '' or not specified, use useid+'_info'.

                    If the '1' or '' is specified, and a useid+'_info'  element doesn't exist,  it will be created and appended after the useid container.
                    If infoid is specified, and it doesn't exist, an error occurs.

                    Note: it is recommended that you specify an infoid a container in your html (so you can nicely place it)

            storeName      = name (not id!) of a an element that will hold the uploaded information.

                         If not specified, useid+'_store' is the default.
                         If such an element does not exist, a <input type="hidden" name="..."> element is created.

                         This element is where the uploaded information is stored.  Thus, if it is within a <form>, and is
                         form element (such as <input> or <textarea>), its contents will be uploaded to the server upon form
                         submission.  Note that storage is as a base64 formatted string

                         If it isn't part of a form, then it need not be in a "form element" -- it is up to you to code your
                         javascript to read it -- the   ws_readFiles_unpack function helps with that!

      uploadInfo will contain summary information. It is meant to be used with ws_readFiles_clear

      Notes:

       *  maxFiles and maxFileSize can be specified in the attributes of the useid element
          If so, they are used instead of values specified in options

       * If specified, three global parameters are used: upload_max_filesize, post_max_size, memory_limit

         They are used in ws_readFiles as  additional limits (over and above the maxFiles and maxFileSize parameter).
         If anyone of them is violated, a warning message appears that the user must affirm (if not, the file upload is halted,
         so the fileinformation is not stored).
         Typically, these would be server side limits that are determined elsewhere (say, in a php file that queries the server
         and save the results in javascript accessible global variables).


  ws_readFiles_clear(uploadInfo,idirect)               -- reset & clear file upload elements

     Clear content from the storage area, and remove any information on uploaded files.
     Some browsers retain this stuff even on a refresh. So it is recommended that this be called after ws_readFiles_setup

     Arguments
        uploadInfo = where to clear from.
         This can have several different flavors
           a) if uploadInfo is a string, it should point to the 'useid' used in a ws_readFiles_setup call. For example: 'readfiles'
              Special case: uploadInfo='1' or uploadInfo='',  then uploadInfo is set to: 'readFiles'
              Special case: uploadInfo not specified: then uploadInfo is set to 'readFiles'

            For the above: the uploadInfo should have been used as the 'useid' (perhaps the default) in a ws_readFiles_setup call
            If such an element does not exist, or was not used in a ws_readFiles_setup call, an error occurs

           b) If ws_readFiles_clear is an a event object call (say, as set by a .on('click',data,ws_readFiles_clear)
            Then the data object must be a jQuery object pointing to the <input type="file" ...> element
            For example:
                data=$('#readFiles');
                q3=$('#clearButton').on('click',data,ws_readFiles_clear);

            c) The value returned by ws_readFiles_setup  -- this is RECOMMENDED. A more complete clear (including clearing the info container) is likely.

       Note that if you don't use defaults in ws_readFiles_setup, you can setup several different upload elements.
       In that case, make sure you use the right value of the uploadInfo (so as to clear the expected field!)


   ws_readFiles(evt)                            -- event manager assigned to <input type="file"> element.

      This is the "event handler" that does the work.
      Casual programmers will never need to use it.


  ws_readFiles_unpack(storeName)                 -- unpack information stored  by ws_readFiles

    Arguments:
       storeName: Name of element that "stores" the information, as specified in the options argument used in ws_readFiles_setup.
       Per usual, if '1', '', or if not specified: 'readFiles_store' is used!

     Uploaded files are stored (by ws_readFiles) in the storeName element, using a non-intuitive format.
     ws_readFiles_unpack will create an  array containing this information -- with one row per file.
     Each row is an associative array containing the following fields:
       'fileContent' : content of the file
       'filename' : filename
       'fileType'    : guess of mime type
       'fileDate'  : modification date   (Fri Apr 24 2015 17:27:40 GMT-0400 (Eastern Standard Time))
       'fileSize' : number of bytes





  -----------------

 Simple example of ueage (see wsurvey_fileUploadExample.php for a complete example):

    1) Create html code that includes a 
            <input type="file" id="readFiles" title="Chose a file to upload"  >
       or
            <input type="file"  id="readFiles"  multiple="multiple"  title="Chose  files to upload"  >
       for multiple file uploads.

      It is a good idea to also include something like
             <input type="button" value="clear" title="clear uploaded file information  onClick="ws_readFiles_clear()">
      And for pretty display:
            <div id="readFiles_info" title="summary of uploaded files" class="whatever"> </div>

    2) call ws_readFiles_setup with this id as the first argument. For example: ws_readFiles_setup()   to use the default of 'readFiles'

    3) When ready to do something, you can access the uploaded information using:

        qq=$('[name="readFiles_store"]);
        stuff=qq.val();
        nfiles=qq.data('nfiles');
        totbytes=qq.data('totBytes');

      stuff is specially formatted. To unparse it under javaacript, use ws_readFiles_unpack
      To send it to php, use 'stuff' as is. On the php side, the ws_readFiles_unpack function (in wsPhpLib.php) can be used to unpack it