Boomerang Upload - Manual


Contents

Overview Brief overview/description of control .
Features List of control features .
Parameters Overview of parameters .
Methods Overview of methods .
Events Overview of events .
Usage How to use the control in web pages .
Installation How to install the control if you need it on your machine for testing .
Tricks Tips and tricks .
 
Overview

Boomerang Upload is a multi-file upload ActiveX control and Netscape plugin for ActiveX enabled web browsers like Internet Explorer, and browsers that load Netscape plugins, like Mozilla and Opera . The control allows a person to select some files and upload them . Files can be uploaded by internal upload functions using FTP or HTTP , or files can be posted through the browser using script . The control can act as a form , where it can read the input fields from regular HTML web forms , as well as read data from other Merlix ActiveX controls , and then upload all the data in one request . The same upload scripts can be used to handle uploads from this control , as the ones used to handle uploads from Internet Explorer or Netscape .

Note that currently the Netscape version of the control does not support scripting and events and is loaded purely from embed tags.

 
Features
  • Multiple file uploading
  • Detailed upload progress
  • Drag and drop files for uploading
  • Folder Recursion
  • Limit on file size, number and extension .
  • Limit on total size of files which can be uploaded .
  • Save and re-use list of upload files .
  • Same internal internet functions as Internet Explorer .
  • Upload through internal functions or post in browser .
  • Form simulator.
  •  
    Parameters
     Unless otherwise specified , all parameters can be assumed to be variants .
    URLTo Preferred upload destination . This URL will be tried first when uploading files . Can be HTTP for FTP protocol . HTTPS currently supported by using browser post features . If HTTP URL , then it can be a virtual , relative (no "../" parent paths) , or entire URL string including querystring fields which will be sent to the upload script along with the upload.
     
    URLToAlt Alternative upload destination . Is the same as URLTo parameter , but used only if the URLTo parameter generates some error while trying to upload .
     
    RedirectTo The HTTP address of the script to redirect the browser to upon upload completion . The script where the browser is redirected to can access the "UPLOADREPLY" form field and display it to the user . The "UPLOADREPLY" field contains whatever was returned by the upload script .
    Examples :
  • "http://www.mysite.com/upload/showresponse.asp"
  • "/upload/showresponse.asp"
  • "showresponse.asp" For upload results redirecting, two fields are sent in the form collection.
  • "UPLOADREPLY" - Whatever the upload script replied to the control with.
  • "UPLOADPROTOCOL" - "http" for HTTP uploads and "ftp" for FTP uploads. FTP redirect introduces one other field, called "UPLOADREPLYDATA" which is just some delimited text data you can use to make your own upload reply.
  •  
    RedirectFTP Boolean(TRUE/FALSE): default=FALSE
    Specifies to redirect the FTP Upload results to, most likely, an http script such as ASP or PHP. If FALSE, a dialog is displayed to the user directly after the FTP upload showing some predefined upload results. If TRUE, both a delimited string of the upload results and a pre-formmated string of HTML upload results is sent to the RedirectTo parameter script. When you use the FTP redirect, three fields are sent to your redirect script.
  • UPLOADREPLYDATA - Contains delimited text data you can use to make your own results.
  • UPLOADREPLY - Contains pre-formatted HTML of the upload results you can just write into the response.
  • UPLOADPROTOCOL - 'ftp' when upload is FTP. The "UPLOADREPLYDATA" field is only sent for the FTP upload. HTTP upload results are always made by the upload handler, passed back to the control, redirected to the redirect script, and then shown by the browser.
  •  
    OverwriteFiles String: possible values('yes','no','prompt')
    The default is 'prompt'.
    Normally you can leave this blank and the user will just get a 'Overwrite existing files' prompt just before the upload. If they click yes, then a field called 'OVERWRITE' is sent with the HTTP upload and you can overwrite the files in your upload script if you deem it necessary.

    Set OverwriteFiles to 'No' to make the upload always send the OVERWRITE field as FALSE, and set it to 'Yes' for TRUE.
    This works together with your HTTP upload script. The script reads the 'OVERWRITE' field from the request. For example, in ASP.NET, you could say,
    If request.form("OVERWRITE") = "TRUE" Then request.Files(0..X).SaveAS(OriginalNames) Else request.Files(0..X).SaveAS(OriginalNames + [1]) etc... End If
    See the ASP upload example script for this SDK to see how this works properly.
     
    Filter Filter used for file select dialog box . Allows for multiple entries . Also , no files that do not comply with the filter will be uploaded .

    Each entry is separated by a "|" character , and there are two entries per filter part . Each filter part describes some filter to apply . Look at the examples below to see how this works .

    Examples :
  • "All Files(*.*)|*.*"
  • "All Files(*.*)|*.*|Bitmaps(*.bmp)|*.bmp|Jpegs(*.jpg;*.jpeg)|*.jpg;*.jpeg"
  • "Bitmaps(*.bmp)|*.bmp"
  • "Text Files(*.txt)|*.txt|HTML Files(*.html;*.htm)|*.html;*.htm"

    A user can always overide the filter by typing their own filter in a file open dialog , but the control still applies the filter to files before uploading . Make sure you include the (*.*) filter part if you want the any kind of files to be selectable .
  •  
    MaxFiles Maximum number of files which may be uploaded . Set to zero to allow unlimited number of files to be uploaded .
     
    MaxTotalSize Maximum number of bytes which can be uploaded in one upload session . If the combined size of the files is to large before the upload starts , then files are filtered out until the size is less than the parameter value . Set to 0 to allow unlimited total upload size .
     
    MaxFileSize Files with size attribute greater than this parameter value will not be uploaded . Value is specified as bytes . Set this parameter to 0 to allow files of any size to be uploaded .
     
    PostWithBrowser TRUE/FALSE field indicating whether the control should upload data via the browser , or use it's internal upload functions .
     
    UploadControlsEnabled TRUE/FALSE field which specifies to enable or disable the ability of the control to be used to start an upload . Typically this is set to TRUE when you want to place the control on it's own in a web page and upload some data , and set to FALSE when you want to use the control more as an input element along with other input elements and ActiveX controls when collecting data in a web form . You would then have to create your own "SUBMIT" button and call the controls submit() method in script .
     
    URLLicense A path to your license file. If not specified the control will search for license info at www.activexobjects.com. If specified, the control downloads this file and checks for license info from the file.

    Examples:
    "/controls/axlicense.dat"
    "axcontrol.URLLicense = '/controls/axlicense.dat'"
     
    URLLanguage A path to the language file.
    Examples:
    "language/german.txt"
    "axcontrol.URLLanguage = '/language/german.txt'"
    ""
     
    btnAddVisible Boolean: TRUE/FALSE - DEFAULT TRUE
    If set to "false", turns off the display of the "Add" button, which is used to select a file or files.
     
    btnAddFolderVisible Boolean: TRUE/FALSE - DEFAULT TRUE
    If set to "false", turns off the display of the "Add Folder" button. Users wil not be able to add a list of files by recursing a folder and sub folders.
     
    btnUploadVisible Boolean: TRUE/FALSE - DEFAULT TRUE
    If set to "false", turns off the display of the upload button. This should only be used if you only support Internet Explorer as the Netscape Plugin has no other way of uploading files.
     
    btnSelectAllVisible Boolean: TRUE/FALSE - DEFAULT TRUE
    If set to "false", turns off the display of the "Select All" button. Users will not be able to select all the files in the list at one time.
     
    btnRemoveVisible Boolean: TRUE/FALSE - DEFAULT TRUE
    If set to "false", turns off the display of the remove button.
     
    btnOpenVisible Boolean: TRUE/FALSE - DEFAULT TRUE
    If set to "false", turns off the display of the open button.
     
    btnSaveVisible Boolean: TRUE/FALSE - DEFAULT TRUE
    If set to "false", turns off the display of the save button.
     
    btnAboutVisible Boolean: TRUE/FALSE
    Boolean value which you can use to turn off the about button. The about button displays an advert for ActiveXObjects.com and this might be inconvenient for your site. It is visible by default, so you can turn it off by setting the value to false.
     
    toolbarVisible Boolean: TRUE/FALSE
    Specifies to make the toolbar invisible. If this is set to "false", then you must make your own toolbar either using buttons, images or hyperlinks.

    The different buttons/methods are:
    Button Name Function/Implementation Description
    btnAdd btnAddClick() Invokes the "AddFiles" function. A "file-open dialog" is displayed and a user can select multiple files from a single folder.
    btnAddFolder btnAddFolderClick() Invokes the "addFolder" function. A "Select Folder" dialog is displayed and the user can choose a folder for which all files and optionally files in sub-folders will be added to the list of files for uploading.
    btnRemove btnRemoveClick() Removes selected files from the list of files for uploading.
    btnSelectAll btnSelectAllClick() Selects all files in the files view.
    btnOpen btnOpenClick() Opens a previously saved list of upload files.
    btnSave btnSaveClick() Saves the current list of files so that the files can be re-uploaded at another time when they have been edited or changed.
    btnUpload btnUploadClick() Causes the control to upload all files currently loaded in the files list.

    Example of calling the method for button "btnAddFolder" , assuming you have a JScript variable called xBoomerang and you are using a custom toolbar.

    <script language='javaScript' type='text/javaScript'>
      xBoomerang.btnAddFolderClick();// Shows "Add folder" dialog.
    </script>
    
    And linking directly to the onclick handler of a button input, but you must have a global xBoomerang object variable for that, otherwise call it through another function...
    <input type="button" onClick="javaScript: xBoomerang.btnAddFolderClick();" >
    

     
     
    Methods
     
    Submit Submit()
    Starts the submission or upload . If you need to add other data to the upload request , you can trap the OnSubmit event and add form fields and other data there .
     
    cancelSubmit cancelSubmit()
    Can be used to cancel submission from within the OnSubmit event handler of the ActiveX control.
    Example: You check your form and see that the user did not enter their surname but you want that, so you use the cancelSubmit event to prevent the upload from happening until the surname field has been filled in.
      if (myform.SURNAME.value = "") {
        alert("Please enter your surname");
        myActiveX.cancelSubmit();
        return false;
      }
    
     
    HasFormData HasFormData()
    Returns TRUE if the ActiveX control has valid upload data , and FALSE otherwise . You can use this method to check if data was entered in the control . If the data is required , then you can prompt the user to enter some data , and prevent the upload starting until the data has been entered .
     
    AddHTMLForm AddHTMLForm(AForm)
    Makes the control scan a web form for it's data , and adds the data to the upload request .
     
    AddFormField AddFormField(AName,AValue)
    Adds a form field to the upload request . For example , you could trap the onSubmit event handler and add a field called "dateSubmitted" . This method frees you from having to have a corresponding HTML form input element to add data to an upload request .
     
    ClearForm ClearForm()
    Clears all existing form fields from the upload request . Use this for extra safety and in cases where you may have added some fields and then have an option which allows the process to be cancelled .
     
    GetActiveXControlData GetActiveXControlData(AnActiveX)
    Reads upload data from other Merlix ActiveX controls and adds it to the upload request data . Use this method when you have multiple Merlix ActiveX controls on one page and you want to submit the data in all of them at the same time . The way to do that is to add all the data to one of the controls and then call the submit method for that control .
     
    Init Init()
    RESERVED: Do not use ...
     
     
    Events
     
    Example for using Events You need to define the event handler in javaScript...
      function myXControl_OnXReady() {
        myXControl.URLTo = "myUploadScript.asp";
        myXControl.RedirectTo = "RedirectScript.asp";
        myXControl.URLLicense = "axlicense.dat";  
      }
    
    Then you need to attach it to your ActiveX control using script.
      myXControl.attachEvent("OnXReady",myXControl_OnXReady);
    
    Now when the control needs to call an event, it will call your javaScript function and you can handle the event with script.
     
    OnSubmit OnSubmit(AContinue)
    Gets fired each time an upload starts . If you create a script handler for the event , then you can set the AContinue parameter to false to abort the upload .
     
    OnXReady OnXReady()
    Fired approximately 1 second after the control has recieved it's client site, and not before the document is loaded. Not a noticeable performance hit, and ensures smooth loading of all parameters and data. To see how this works, view the source code for one of the many cross browser demo's at the ActiveXObjects.com site.
     
     
    Installation
     
    To install the control for testing and usage on your machine , just run one of the demo's for the control at the www.ActiveXobjects.com website . The control will then be installed on your machine and you can use it for testing if you are building your website on a local machine . The control is always fully functional in the "localhost" or "default" domains .
     
     
    Usage
     
    Implement the control in your web page just as you would any other ActiveX control, with the exception of providing data and parameter settings via the OnXReady event in javaScript. There are many demos at the ActiveXObjects.com site that show how to do this, including how to handle the situation of cross browser usage, controls as forms and other method handling and calls.

    Here is a basic example of using the control
    
    Define the object
    <OBJECT
       id='Boomerang1'
       name='Boomerang1'
       classid='clsid:880A66FC-DFCB-4950-87DC-0B49BA501517'
       codebase = 'http://www.activexobjects.com/codewarehouse/activex/1890/BoomerangUpload.cab#version=2,0,0,0'
       width    = '100%'
       height   = '100%'
       align    = 'center'
       vAlign   = 'center'
       hspace   = '2'
       vspace   = '2'
       StandBy  = 'Please wait for Boomerang Upload control to download. Once installed it will load quickly.'
     >
      Handle non-activex browsers by putting in a form where
      files can be uploaded one at a time.
       <!--
         ALTERNATIVE CONTROLS FOR NON-ACTIVEX BROWSERS
           If a browser cannot load the activex control, it will load whatever html code
           is here in inner part of the object tags. If it can load the object, it will ignore
           the code in the inner part of the object tags.
       -->
       <form name="frmUpload" id="frmUpload"
             action="/demox/fileupload.asp"
             method="POST"
             enctype="multipart/form-data"
          >
          <table class="tcontent" style="border-style: solid;border-width:1px;border-color:black" width="100%">
            <tr>
              <td>
                <input type="file" name="file1">
              </td>
            </tr>
            <tr>
              <td>
                <input type="file" name="file2">
              </td>
            </tr>
            <tr>
              <td>
                <input type="submit" name="btnSubmit" value="Upload File/s" class="button">
              </td>
            </tr>
          </table>
        </form>
    
     </OBJECT>
    Use javaScript to setup the Boomerang control
     <script language='javaScript' type='text/javaScript'>
       // Preferably initialise properties for control
       // when it has indicated that it is fully loaded and ready .
       var xUA = navigator.userAgent.toLowerCase();
       var isIE = xUA.indexOf('msie')!=-1;
       if (isIE && document.all)// Only script here for ie
       {
         var xBoomerang = document.all.Boomerang1;// read object out of document
         function Boomerang1_OnXReady() { // event handler function. Boomerang is ready
           if (xBoomerang) { // safety !!!
             // set properties
             // Max number of files allowed to upload
             xBoomerang.MaxFileCount          = "16";
             // +/- 0.5 MB Max File Size Allowed
             xBoomerang.MaxFileSize           = "500000";
             // +/- 2MB Total size of files accepted
             xBoomerang.MaxTotalSize          = "2000000";
             xBoomerang.UploadControlsEnabled = true;// Allow user to upload from upload button
             // Post using internal control HTTP functions
             xBoomerang.PostWithBrowser       = false;
             xBoomerang.Filter                = "All Files(*.*)|*.*";// 2MB
             // Where the control uploads files to ...
             xBoomerang.URLTo                 = "upload/fileupload.asp";
             // Alternative. Blank here but could be FTP
             xBoomerang.URLToAlt              = "";
             // After upload, control will send results here
             xBoomerang.RedirectTo            = "upload/fileuploadreply.asp";
           }
         }
         // Attach object events . This is important! The control must initialize.
         if (xBoomerang) {
           // When control initializes it will call the Boomerang1_OnXReady function
           xBoomerang.attachEvent("OnXReady",Boomerang1_OnXReady);
    
         }
       }
     </script>
     <noscript>
    This would get called if the browser did not support javaScript.
     <!--
     Inform users of need to enable javaScript if you think it necessary for
      your web page . The noscript tag is generally shown when scripting is disabled,
      but not when a scripting language is unsupported. Hence, always use javaScript.
     -->
       This page requires that you enable client scripting.
     </noscript>
     
    
     
     
    Tips And Tricks
     
    Using HTTPS You can upload the data via HTTPS using the control . Set the PostWithBrowser parameter to TRUE and it should upload as per usual .
     
    Abort Upload Cancel the upload by trapping the OnSubmit event , and setting the AContinue parameter to FALSE . This way you can do validation before uploading .
     
     
    Copyright ©2003 Merlix LLC / Graphix Omnimedia Group - All rights reserved . www.graphix.com