ImageUpload - 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
ActiveX control for uploading image files . Loads into a web page and can be used to upload a single image , or , used together with other elements in the page , can upload other form data , including image files contained in other instances of ImageUpload and even data from other Merlix ActiveX controls .

You can drag and drop image files into this control .

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
  • Upload as JPG,GIF,PNG,BMP
  • Open +/- 50 formats
  • Drag and drop
  • FX
  • Rotate
  • Resize
  • Preview
  • Multiple instances
  • Upload through internal functions or post in browser .
  • Web Form simulator.
    		•
     
    Parameters
     Unless otherwise specified , all parameters can be assumed to be variants .
    URLFrom The preferred source location of the image to download when the control is first loaded in a web page . If this location fails then the URLFromAlt parameter will be used as the download location . The path can relative , virtual or absolute .

    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.

     
    URLFromAlt The alternative download location of the image to load in the control when the control is first loaded in a web page . This parameter is only used if the preferred URL parameter fails or the download is cancelled . The path can relative , virtual or absolute . No parent paths supported at present .
     
    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 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 .
    •  
    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 .
     
    ForceWidth Integer value, default 0. If you set this property to any positive integer value, any images loaded will be automatically resized to have a width equal to the value. This is intended for situations when you must have a specific width to an image that will be uploaded.
     
    ForceHeight Integer value, default 0. If you set this property to any positive integer value, any images loaded will be automatically resized to have a height equal to the value. This is intended for situations when you must have a specific height to an image that will be uploaded.
     
    MaintainAspectRatio Boolean(TRUE/FALSE). Default FALSE.
    Used to maintain the height or width ratio if you use either the forceheight or forcewidth parameters. For example, all images uploaded must be 200 pixels wide, so you set forcewidth to 200. When the image is resized and MaintainAspectRatio is true, the height of the resized image will have the same ratio to width as before the resize.

    Note it has no effect if the ForceWidth and Forceheight parameters are both greater than zero or both less than 1.
     
    ForceFilename String: default = ""
    Forces the filename (excluding extension) to a specific string. No matter what the name of the file selected on the client, it will always be what you want when it arrives at the server.
     
    ForceFormat String: default = ""
    Forces the uploaded image to always be the format you need. Possible values are "jpg","png","gif" and "bmp". For example, setting this property to "jpg", will ensure that the uploaded image is always .jpg format, no matter if the input image was a .bmp or any other format.
     
    FFGIFTransparent Boolean: default FALSE
    Specifies to make GIF's transparent when the force format property is set to "gif".
     
    FFJPGCompression Integer: default 85
    Min value: 1
    Max Value: 100
    Specifies the JPG compression level when the ForceFormat property is "jpg".
     
    FFPNGCompression Integer: default 85
    Min value: 1
    Max Value: 100
    Specifies the PNG compression level when the ForceFormat property is "png".
     
    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'"
     
    IncludeThumbnail Boolean(TRUE/FALSE): default FALSE
    If TRUE specifies to include a thumbnail of the uploaded image in the upload. The format of the thumbnail is the same as for the image being uploaded, and the width and/or height is set by the ThumbnailWidth and ThumbnailHeight parameters. The ThumbnailPrefix property is used to set the filename of the thumbnail.
     
    ThumbnailWidth Integer: default=0
    The width of the uploaded thumbnail. Only applies if IncludeThumbnail parameter is TRUE. If the ThumbnailWidth is specified but not the height then the height is scaled down by the ratio of the width change.
     
    ThumbnailHeight Integer: default=0
    Height of the uploaded thumbnail image. If this is zero then the height will be calculated as a ratio of the ThumbnailWidth parameter to real width.
     
    ThumbnailPrefix Text: default="_thumb"
    When the thumbnail is uploaded, the same filename is used, except the filename is added onto this value. Example:
    Filename of image uploaded is: "c:\files\ferrari.jpg"
    Filename of thumbnail using default prefix: "c:\files\thumb_ferrari.jpg"
     
     
    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 .
     
    GetActiveXFormData GetActiveXFormData(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 .
     
    getImageWidth getImageWidth()
    Returns the width of the image. If the image has been cropped using the selection tool in the control then the width of the cropped area is returned. If no image is loaded at all, then the return value is zero.
     
    getImageHeight getImageWidth()
    Returns the height of the image. If the image has been cropped using the selection tool in the control then the height of the cropped area is returned. If no image is loaded at all, then the return value is zero.
     
    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