FileShipX - 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
The FileShipX ActiveX/Mozilla Control (hereafter referred to as "the control") is an ActiveX control which displays a Windows "Shell/Explorer" type interface in a web browser , which allows files in the explorer view in the browser to be selected and uploaded . Folders cannot be uploaded , as this would introduce the possibility of over-recursion , so it is limited to uploading just the files which are selected .

The control is implemented for two browser platforms, one for the Internet Explorer ActiveX platform and another for the Mozilla/Netscape Gecko plugin platform. The Netscape version does not support the active scripting and events that the ActiveX version does, so if you plan to deploy the dual browser implementation it is best not to use script. Use the advanced script features for closed Internet Explorer specific Intranet style applications.

 
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 .
  • 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"
    •  
    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 File filter applied to files prior to uploading .

    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"

    •  
    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/mylicense.axl"
    "axcontrol.URLLicense = '/controls/mylicense.axl'"
     
     
    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.
     
     
    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