Upload Ease: UploadEase Javascript Applet Helper Options

allowFolderUploads

Determines whether or not to allow folders to be selected for uploading.

Type:	Boolean
Values:	true, false
Default:	false

If true, folders will be displayed and selectable in the file and selection view.

If false, folders will not be displayed or selectable.

When folders are uploaded you may wish to set the pathsParameterName option in order to have full path name information also uploaded to the server (as this is not guaranteed to be passed in the HTTP request).

Top

appendParameterIndices deprecated

Controls the appending of indices to variable names passed to the server when files are uploaded.

Type:	Boolean
Values:	true, false
Default:	false

This parameter has been deprecated in preference of the more flexible variable naming syntax described in the setVariables() reference. This parameter may be removed in a future release.

Some languages provide a convenient syntax to be used for populating array variables in an HTTP request. In PHP for example, appending [] to a form variable name creates an array of values by that name in the script handling the request on the server. In such cases, there is no need to create individual request variables to hold each value. The default setting of this option (false) caters for this case.

For those languages that don't provide such features or if you specifically wish to, setting this option to true will append indices (starting from 1) to all uploaded file information variables (see the pathsParameterName, hashParameterName, & notesParameterName options).

Top

code

The Java class of the UploadEase applet.

Type:	String
Values:	Applet Class
Default:	com.firmsoft.uploader.UploadEaseApplet

This option specifies the class name of the Upload ease Java Applet, and should not need to be changed.

Changing it may result in Upload ease not being displayed on your webpage.

Top

codebase

The directory / folder containing the UploadEase Java archive.

Type:	String
Values:	Folder Path
Default:	java/

This option specifies the path used to find the UploadEase.jar file. By default the path is specified relative to the web page it's embedded in, and assumes you installed the UploadEase.jar file in a directory called "java". Depending on your website's layout, you may wish to make this path absolute ("/java/" - note the trailing "/").

Setting this option incorrectly may result in Upload ease not being displayed on your webpage.

Top

compressionExclude

A filter specifying filenames to exclude when compressing.

Type:	File Filter
Values:	Filter Specifier
Default:	none

If using compression, this options tells Upload ease which files to exclude when compressing. See the exclude option for more details on specifying exclude filters.

Top

compressionInclude

A filter specifying filenames to include when compressing.

Type:	File Filter
Values:	Filter Specifier
Default:	none

If using compression, this options tells Upload ease which files to include when compressing. See the include option for more details on specifying include filters.

Top

compressionMethod

Specifies the method to use to compress uploaded files.

Type:	String
Values:	none, gzip, zip
Default:	none

In order to improve upload speed and reduce bandwidth usage (for both client and server), you may wish to compress files before uploading them, which you can do by setting this option.

Currently supported compression methods are:

none (no compression)
gzip (GZip compression - files uploaded with .gz extension)
zip (Zip compression - files uploaded with .zip extension)

Top

cookiePolicy

Specifies the cookie policy used when uploading cookies to the server.

Type:	String
Values:	BROWSER_COMPATIBILITY \| NETSCAPE \| RFC_2109 \| IGNORE_COOKIES
Default:	RFC_2109

Depending on your server-side web technology you may need to change the policy used to upload cookies. The following specifications are provided (RFC 2109 specification is used by default):

BROWSER_COMPATIBILITY: compatible with the common cookie management practices (even if they are not 100% standards compliant).
NETSCAPE: Netscape cookie draft compliant.
RFC_2109: RFC2109 compliant (default)
IGNORE_COOKIES: Do not automcatically process cookies.

Top

copyCookies

Controls whether cookies are copied from the page and uploaded to the server.

Type:	Boolean
Values:	true \| false
Default:	true

As a convenience to developers Upload ease copies cookies from the page it's embedded in and uploads them to the server. Many security/authentication mechanisms use cookies to determine user identities and privileges. In most cases copying the cookies will save the developer having to understand the inner-workings of such mechanisms and setting the cookies manually. Of course if there is a need to this setting allows the developer to prevent the automatic copying of cookies, in which case they must be set manually if needed.

Top

exclude

Part of a filter pair that specifies filenames to exclude from viewing and selection.

Type:	File Filter
Values:	Filter Specifier
Default:	none

Upload ease uses "filename filters" to enable you to control such things as which files will be displayed for selection by the user, which files to compress, hash, and so on. These filters each come in two parts (a "filter pair"), comprising an include part and an exclude part.

For a filename to be accepted by a filter pair it must match the include part but not the exclude part. Each part may be specified as a set of filename extensions or a regular expression. In the case of filename extensions, these may be passed as a string of semi-colon (;) separated extensions (without the "."), or an array of same. For example:

  ...
  <script type="text/javascript">
    ...
    var ue = new ueAppletHelper( { options... } );
    ...
    
    ue.setParam('exclude', 'bmp;gif'); //<= extensions by string method
    ue.setParam('exclude', ['bmp','gif']); //<= extensions by array method
    ue.setParam('exclude', '/^.*\.(bmp|gif)$/i'); //<= RegEx method
    
    ...
  </script>
  ...

All three calls to setParam() result in the same exclude filter setting, which excludes filenames with bmp or gif extensions (ignoring case). Note that filtering by filename extension is always case insensitive.

Top

fileIndexBase

Set the base index for dynamically generated per file variable names.

Type:	Integer
Values:	Any integer
Default:	1

For programmer convenience, Upload ease can generate variable names dynamically when uploading variables such as file names, paths, hashes, per file form variables, and so on. Each uploaded file has an integer index associated with it for this purpose and by default the first index is 1.

This parameter can be used to set the first index to something other than 1. For example:

  ...
  <script type="text/javascript">
    ...
    var ue = new ueAppletHelper( { options... } );
    ...
    
    ue.setParam('fileIndexBase', 0); //<= use zero-based indices
    
    ...
  </script>
  ...

Top

fileIndexPlaceholder

Set the index placeholder for dynamically generated per file variable names.

Type:	String
Values:	Placeholder string
Default:	#

For programmer convenience, Upload ease can generate variable names dynamically when uploading variables such as file names, paths, hashes, per file form variables, and so on. Each such variable name may be set programmatically and a per file index used to make it unique, by substituting the "placeholder" for it in the variable name.

This parameter can be used to change the placeholder to an arbitrary string. For example:

  ...
  <script type="text/javascript">
    ...
    var ue = new ueAppletHelper( { options... } );
    ...
    
    ue.setParam('fileIndexPlaceholder', '@'); //<= change the index placeholder
    
    ...
  </script>
  ...

Top

hashAlgorithm

The hashing algorithm to use when generating file hashes.

Type:	String
Values:	MD2, MD5, SHA
Default:	none

The hashAlgorithm option controls whether file hashing is performed and if so which algorithm is used.

Hashing is useful when you need to be sure that files have not been changed or corrupted during upload, by comparing the pre-upload hash with a hash generated on the file once uploaded (using the same hashing algorithm).

Currently supported hashing algorithms are:

none (no hashing)
MD2 (MD2 hashing)
MD5 (MD5 hashing)
SHA (SHA hashing)

Note that the hashing algorithm names are not case sensitive.

Top

hashExclude

A filter specifying filenames to exclude when hashing.

Type:	File Filter
Values:	Filter Specifier
Default:	none

If using hashing, this options tells Upload ease which files to exclude when generating hash values. As hashing can be a time consuming operation it is important to only do it when necessary.

See the exclude option for more details on specifying exclude filters.

Top

hashInclude

A filter specifying filenames to include when hashing.

Type:	File Filter
Values:	Filter Specifier
Default:	none

If using hashing, this options tells Upload ease which files to include when generating hash values. As hashing can be a time consuming operation it is important to only do it when necessary.

See the include option for more details on specifying include filters.

Top

hashParameterName deprecated

The name of the hash variable passed when uploading.

Type:	String
Values:	Parameter Name
Default:	none

This parameter has been deprecated in preference of the more flexible variable naming syntax described in the setVariables() reference. This parameter may be removed in a future release.

When using hashing, this option specifies the name of the variable passed in the upload that contains the hash value for each file. Note that if the appendParameterIndices option is set to true then a numerical index will be appended to the variable name, starting from 1.

For example:

  ...
  <script type="text/javascript">
    ...
    var ue = new ueAppletHelper( { options... } );
    ...
    
    ue.setParam('hashParameterName', 'hashes[]'); //<= hashes array in PHP handler script
    //⇑ OR ⇓
    ue.setParam('appendParameterIndices', true); //<= append indices
    ue.setParam('hashParameterName', 'hash_'); //<= uploads hash_1, hash_2, ... variables
    
    ...
  </script>
  ...

Top

height

The height of the applet interface in pixels.

Type:	Integer
Values:	Height in Pixels
Default:	450

This option is used to set the height attribute of the applet's HTML element.

Top

id

The "id" attribute of the applet's HTML element.

Type:	String
Values:	ID Attribute
Default:	upload_ease

This option is used to set the id attribute of the applet's HTML element.

Top

imageRotateButtons

Determines whether button controls are provided to allow users to rotate images.

Type:	Boolean
Values:	true, false
Default:	true

This option is used to control whether or not button controls are displayed to enable users to rotate images prior to uploading. If true, buttons are displayed to allow clockwise & anti-clockwise rotations in 90° steps. If false, the rotation buttons are not displayed.

Top

images

Specifies the creation of thumbnails, resizing, etc of uploaded images.

Type:	String
Values:	Image Specifiers
Default:	none

The images option controls the generation of constrained images (if any), such as thumbnails, for image files.

We recommend using the ImageHelper object to aid developers in adding contrained images to uploads.

Top

include

Part of a filter pair that specifies filenames to include from viewing and selection.

Type:	File Filter
Values:	Filter Specifier
Default:	none

Upload ease uses "filename filters" to enable you to control such things as which files will be displayed for selection by the user, which files to compress, hash, and so on. These filters each come in two parts (a "filter pair"), comprising an include part and an exclude part.

For a filename to be accepted by a filter pair it must match the include part but not the exclude part. Each part may be specified as a set of filename extensions or a regular expression. In the case of filename extensions, these may be passed as a string of semi-colon (;) separated extensions (without the "."), or an array of same. For example:

  ...
  <script type="text/javascript">
    ...
    var ue = new ueAppletHelper( { options... } );
    ...
    
    ue.setParam('include', 'jpeg;jpg;png'); //<= extensions by string method
    ue.setParam('include', ['jpeg','jpg','png']); //<= extensions by array method
    ue.setParam('include', '/^.*\.(jpe?g|png)$/i'); //<= RegEx method
    
    ...
  </script>
  ...

All three calls to setParam() result in the same include filter setting, which includes filenames with jpeg, jpg, or png extensions (ignoring case). Note that filtering by filename extension is always case insensitive.

Top

maxFileSize

Specifies the maximum size of a single file that can be uploaded.

Type:	Integer
Values:	>= 0
Default:	0

This option specifies the maximum size (in bytes) of a file that can be uploaded. Note that the size of the file is determined before compression, if applicable. If an attempt is made to upload a file that exceeds this limit an error will be reported in the "Errors" tab.

The default value (0) indicates no limit.

Top

maxFileCount

Specifies the maximum number of files that can be marked for upload by the user.

Type:	Integer
Values:	>= 0
Default:	0

The maxFileCount option sets a limit on the number of files a user may select for uploading. Any files selected beyond this limit will result in an error being reported to the "Errors" tab.

The default value (0) indicates no limit.

Top

maxFilesPerRequest

Specifies the maximum number of files that can be uploaded in a single HTTP request.

Type:	Integer
Values:	>= 0
Default:	0

The maxFilesPerRequest option sets a limit on the number of files that Upload ease will attempt to upload in a single HTTP request. If the number of files to upload exceeds this limit, multiple HTTP requests will be made until all files have been uploaded.

The default value (0) indicates no limit.

Top

maxUploadSize

Specifies the maximum size of an entire upload (bundle group).

Type:	Integer
Values:	>= -1
Default:	-1

This option specifies the maximum combined size (in bytes) of all files contained in a single upload (bundle group). Note that the file sizes are determined before compression, if applicable. If an attempt is made to upload files whose combined size exceeds this limit an error will be reported in the "Errors" tab.

The default value (-1) indicates no limit.

Top

mayscript

Determines whether the Java applet may communicate with JavaScript in the browser.

Type:	String
Values:	yes, no
Default:	yes

This option determines whether the Upload ease applet may communicate with JavaScript in the browser, and should be left at its default value.

Changing it may result in Upload ease not functioning as intended, particularly with respect to callbacks to JavaScript.

Top

name

The "name" attribute of the applet's HTML element.

Type:	String
Values:	Name Attribute
Default:	UploadEase

This option is used to set the name attribute of the applet's HTML element.

Top

notesParameterName deprecated

The name of the variable used to pass file notes when uploading.

Type:	String
Values:	Parameter Name
Default:	none

This parameter has been deprecated in preference of the more flexible variable naming syntax described in the setVariables() reference. This parameter may be removed in a future release.

Upload ease provides functionality for users to be able to enter notes on a per file basis that are sent with the upload HTTP request. This functionality is enabled when the notesParameterName option is set. Note that if the appendParameterIndices option is set to true then a numerical index will be appended to the variable name, starting from 1.

If this option not set then the button control that allows users to add per file notes will not be displayed and no notes can be added.

Top

onUploadDone deprecated

The name of a JavaScript function to call when an upload completes.

Type:	String
Values:	JavaScript Function Name
Default:	none

This parameter has been deprecated in preference of the more consistent callback specifier syntax described in the setCallbacks() reference. This parameter may be removed in a future release.

When an upload completes, you may wish to refresh the page, update a page element via AJAX, or perform some other action. This option enables you to do just that. By setting it to the name of a JavaScript function, Upload ease will call that function each time an upload completes. For example:

  ...
  <script type="text/javascript">
    ...
    
    function doSomething() {
      alert('Upload complete!'); //<= do something here
    }
    
    ...
    var ue = new ueAppletHelper( { options... } );
    ...
    
    ue.setParam('onUploadDone', 'doSomething'); //<= tell applet what function to call
    
    ...
  </script>
  ...

Top

pathsParameterName deprecated

The name of the filenames variable that passes pathname information for files uploaded in folders.

Type:	String
Values:	Parameter Name
Default:	none

This parameter has been deprecated in preference of the more flexible variable naming syntax described in the setVariables() reference. This parameter may be removed in a future release.

Although individual filenames are preserved in HTTP requests and accessible from the server-side handler, pathname information for files uploaded in folders are not. Should you need this information it is accessible by setting this option to a variable name of your choice. Note that if the appendParameterIndices option is set to true then a numerical index will be appended to the variable name, starting from 1.

For example:

  ...
  <script type="text/javascript">
    ...
    var ue = new ueAppletHelper( { options... } );
    ...
    
    ue.setParam('pathsParameterName', 'paths[]'); //<= paths array in PHP handler script
    //⇑ OR ⇓
    ue.setParam('appendParameterIndices', true); //<= append indices
    ue.setParam('pathsParameterName', 'path_'); //<= uploads path_1, path_2, ... variables
    
    ...
  </script>
  ...

Top

rememberLastFolderVisited deprecated

Controls whether the UploadEase applet remembers and returns to the last folder visited when next run.

Type:	Boolean
Values:	true, false
Default:	false

This parameter has been deprecated in preference of the more flexible setLastFolderVisitedCookie() helper method and may be removed in a future release.

This option controls whether Upload ease attempts to remember and return to the last folder visited the next time a user uses it. For many applications users will create and maintain their files in a certain folder and return there each time when they need to synchronise or update the website. To save even more time, setting this option to true will save the user from having to navigate down the folder hierarchy each time only to get to the same place.

Note that this functionality requires the end user to have cookies enabled in their browser. If they don't Upload ease will simply behave as if this option was set to false.

Top

rememberLastFolderVisitedCookieName deprecated

The name of the browser cookie to use to remember the last folder visited.

Type:	String
Values:	Cookie Name
Default:	ueRememberLastFolderVisited

This parameter has been deprecated in preference of the more flexible setLastFolderVisitedCookie() helper method and may be removed in a future release.

The default name for the cookie used to remember the last folder visited by a user is ueRememberLastFolderVisited. If you wish to change it just set this option accordingly.

Top

restartFileIndices

Controls whether file parameter indices are reset for each bundle.

Type:	Boolean
Values:	true \| false
Default:	true

In Upload ease 1.3 we introduced the concept of upload "bundles" in order to relate multiple HTTP requests made during a single upload session. Prior to 1.3 the file parameter indices uploaded in each request started at fileIndexBase and incremented sequentially for the number of files in each individual request, even if there was more than one. To maintain backward compatibility we have kept this as the default behaviour by defaulting the restartFileIndices parameter to true.

If you would prefer file parameter indices to continue to increment sequentially from bundle to bundle (within the same bundle group) then set the restartFileIndices parameter to false.

Top

scriptable

Controls whether JavaScript can communicate with Java applets (Internet Explorer only).

Type:	Boolean
Values:	true, false
Default:	true

This option determines whether JavaScript can communicate with the Upload ease Java Applet, and applies to Internet Explorer only. It should be left at its default value.

Changing it may result in Upload ease not functioning as intended.

Top

sessionID

Specifies the session ID sent with upload requests.

Type:	String
Values:	Session Identifier
Default:	none

The sessionName and sessionID options together specify a name/value pair that is sent in the upload as a cookie. This is often used on the server side to restore session state between requests. For example, if you use a session to authenicate access then your upload script can restore the session by checking this cookie. See the setSession Helper method for more information.

Top

sessionName

Specifies the name of the session variable sent with upload requests.

Type:	String
Values:	Session Name
Default:	none

The sessionName and sessionID options together specify a name/value pair that is sent in the upload as a cookie. This is often used on the server side to restore session state between requests. For example, if you use a session to authenicate access then your upload script can restore the session by checking this cookie. See the setSession Helper method for more information.

Top

showHiddenFiles

Determines whether or not hidden files should be shown in the file viewer and selectable.

Type:	Boolean
Values:	true, false
Default:	false

By default Upload ease does not display files in the file view pane that the system considers to be "hidden". Setting this option to true causes such files to be displayed and selectable for upload.

Top

tokens

Used to specify the licence tokens for the upload target.

Type:	String
Values:	Licence Token(s)
Default:	none

Upload ease uses licence tokens in order to ensure that a valid licence has been purchased for uploading to the location specified by the uploadURL option. Once you have integrated and tested the software with your website on your local computer (no licence token necessary), you can purchase tokens on this website for your domain or server/IP.

Please visit the licensing information page for more information on licence types, terms, and conditions.

Top

uploadURL

The URL locating the resource that will handle the upload.

Type:	String
Values:	URL
Default:	none

In order for uploaded files to be received and stored on your web server you'll need a handler capable of processing multipart/form-data requests. While this may sound complicated, most server-side platforms provide convenient ways to process such requests. See the upload processing examples for more information.

The uploadURL is used to access the server-side script/resource in the same way as if the page were accessing any other resource on the website, so if you specify a relative URL then it must be relative to the page the applet was used in. A URL starting with a "/" would be relative to the website's document root. You may of course specify a URL to another domain, IP, or website, but please ensure you have purchased the correct licence tokens to do so.

Top

width

The "width" attribute of the applet's HTML element.

Type:	Integer
Values:	Width in Pixels
Default:	600

This option is used to set the width attribute of the applet's HTML element.

allowFolderUploads	hashExclude	notesParameterName
appendParameterIndices	hashInclude	onUploadDone
archive	hashParameterName	pathsParameterName
code	height	rememberLastFolderVisited
codebase	id	rememberLastFolderVisitedCookieName
compressionExclude	imageRotateButtons	restartFileIndices
compressionInclude	images	scriptable
compressionMethod	include	sessionID
cookiePolicy	maxFileSize	sessionName
copyCookies	maxFileCount	showHiddenFiles
exclude	maxFilesPerRequest	tokens
fileIndexBase	maxUploadSize	uploadURL
fileIndexPlaceholder	mayscript	width
hashAlgorithm	name