| 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 | |||||||||||||||||||||||||
|
|
|||||||||||||||||||||||||
| 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 : |
||||||||||||||||||||||||
| 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. |
||||||||||||||||||||||||
| 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 : 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:
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 |
|||||||||||||||||||||||||
|
|||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||