Upload files & images with ease!
Upload files & images with ease!
Upload files & images with ease!
Following is a list of helper methods, with descriptions of what they do and how to use them.
Constructs an ueAppletHelper object.
| Parameter | Type | Description |
|---|---|---|
| params | Object | Initialisation Parameters |
| debug | Boolean | Debug flag |
The ueAppletHelper object makes it easy to add Upload ease to your web page,
handling any changes between versions and differences in applet deployment across
browsers. It is the simplest way to ensure maximum compatibility going forward,
and minimises the integration effort in using the Software on your web site.
Inside your script element you can instantiate the ueAppletHelper thus...
<body>
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... }, true );
...
</script>
...
</body>
... where options is a comma separated list of
configuration parameters. All configuration parameters can
be provided here for convenience, but can also be set with the other helper
methods as described below.
To aid in debugging your implementation a flag is provided to turn on debugging
output. If true, debugging information is written into a separate window,
including warnings if unknown option variables are set, and the applet HTML
embedded into your web page (when the write method is called).
Adds an image specifier from an ImageHelper object or a specifier string.
| Parameter | Type | Description |
|---|---|---|
| image | ImageHelper Object or String | Image Specifier |
The addImage method can be used to conveniently add an
image specifier to the current list of image specifiers for the uploader applet,
either from an ImageHelper object or a string in image specifier format.
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
var ih = new ue.ImageHelper( { width: 100, height: 100 } ); //<= create ImageHelper
ue.addImage(ih); //<= add image from ImageHelper
ue.addImage('400x300:pad=#fff'); //<= add image from specifier string
...
</script>
...
Adds an image defaults specifier from an ImageHelper object or a specifier string.
| Parameter | Type | Description |
|---|---|---|
| image_defaults | ImageHelper Object or String | Image Specifier |
The addImageDefaults method can be used to conveniently set defaults
for subsequent images added to the upload list, either from an ImageHelper
object or a string in image specifier format. This is useful when you have a
number of images that use the same non-default value for a given image option,
and you don't want to have to specify it for each image.
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
var ih = new ue.ImageHelper( { pad: '#000' } ); //<= create ImageHelper specifying black padding
...
ue.addImageDefaults(ih); //<= images added after this will be padded in black
...
</script>
...
Appends one or more licence tokens to the current list of tokens.
| Parameter | Type | Description |
|---|---|---|
| tokens | String or Array | Licence token(s) |
The addToken method appends one or more tokens to the
list of tokens used by the applet to validate the licence for uploading to
the specified domain or server.
Multiple tokens can be specified by passing a string separating them with a semi-colon (;), an array of strings, or by making multiple calls.
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.addToken('licence_token');
...
</script>
...
Appends a value to an AppletHelper option.
| Parameter | Type | Description |
|---|---|---|
| name | String | Parameter Name |
| value | See Parameter Detail | Parameter Value |
The appendParam method allows you to append values to certain
AppletHelper options.
Usage example:
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.appendParam('include', 'gif'); //<= appends 'gif' to the file include filter
...
</script>
...
Creates a new ImageHelper object for specifying extra images to be uploaded.
| Parameter | Type | Description |
|---|---|---|
| options | Object | Image Options |
An ImageHelper object can be used to conveniently create and
configure an image specifier, used to tell the Upload ease applet to create and upload
thumbnails or other images derived from images selected for uploading.
Once configured, simply call the ueAppletHelper method
addImage() to append it to the list of extra images to be generated
for uploading.
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { applet options... } );
...
var ih = new ue.ImageHelper( { image options... } ); //<= create ImageHelper
...
ue.addImage(ih); //<= add the image to the applet
...
</script>
...
Convenience method for setting various Javascript callback functions.
| Parameter | Type | Description |
|---|---|---|
| specifiers | Object | Callback specifiers |
Upload ease uses "callbacks" to provide a convenient way to get input or provide feeback to the user. Currently supported callbacks are as follows:
...
<script type="text/javascript">
var storedFileParams = [];//<= store per file variables
function fileParamsCallback( action, key ) {
if (action == 'get') {
return storedFileParams[key];//<= return URL parameter formatted string
} else if (action == 'set') {
... //<= Initiate user input (e.g. display a form)
}
}
function onAbort( bundleGroupID ) {
alert('Upload aborted!');//<= Notify user of upload abort
}
function onFileUploaded( filename ) {
return 'Processing '+filename+'...';
}
function onUploadDone( bundleGroupID ) {
alert('Upload done!');//<= Notify user of upload completion
}
function getUploadParams() {
return $('#form').serialize();//<= return form variables (e.g. serialized with jQuery)
}
...
var ue = new ueAppletHelper( { options... } );
...
ue.setCallbacks({ //<= set one or more callbacks
fileParams: 'fileParamsCallback',
onAbort: 'onAbort',
onFileUploaded: 'onFileUploaded',
onUploadDone: 'onUploadDone',
uploadParams: 'getUploadParams'
});
...
</script>
...
Convenience method for setting the compression method and include/exclude filter when compressing.
| Parameter | Type | Description |
|---|---|---|
| method | String | Compression Method |
| include | String | Include Filename Filter |
| exclude | String | Exclude Filename Filter |
The setCompression method provides a convenient way to set the
upload compression method
and include/exclude filters (see the
include and
exclude helper options documentation for
details on specifying include/exclude filters). The example tells the uploader
to use Zip compression on files with "txt" or "doc"
extensions, but not if their names begin with "compact".
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.setCompression('zip', ['txt','doc'], '/^compact.*/'); //<= use ZIP compression
...
</script>
...
Convenience method for setting cookies to be passed to the server upload script.
| Parameter | Type | Description |
|---|---|---|
| specifiers | Object | Cookie specifiers |
Upload ease can send "cookies" with the upload to the server-side processing script. Such cookies are often used in security/authorisation mechanisms to identify the user and enforce upload limits and so on. setCookies() may be called multiple times and with multiple cookies specified each time (with the last specified overriding any earlier specifications).
Usage:
...
<script type="text/javascript">
var ue = new ueAppletHelper( { options... } );
...
ue.setCookies({ //<= set one or more cookies
name1: 'value1',
name2: 'value2',
...,
nameN: 'valueN'
});
...
</script>
...
Convenience method for setting the include/exclude filters.
| Parameter | Type | Description |
|---|---|---|
| include | String | Include Filename Filter |
| exclude | String | Exclude Filename Filter |
This method is a convenience method for setting the filename include/exclude filters that control what files are shown and selectable in the file view pane (see the include and exclude helper options documentation for details on specifying include/exclude filters). The example tells the uploader show files with the image extensions "jpg" or "jpeg" extensions, but not if their names begin with "private".
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.setFileFilter(['jpg','jpeg'], '/^private.*/'); //<= set filename filter
...
</script>
...
Convenience method for setting the hashing algorithm, "hashParameterName" configuration parameter and include/exclude filter when hashing.
| Parameter | Type | Description |
|---|---|---|
| algorithm | String | Hashing Algorithm |
| hashParameterName | String | Upload Variable Parameter Name |
| include | String | Include Filename Filter |
| exclude | String | Exclude Filename Filter |
The setHashing method provides a convenient way to set the
upload hashing algorithm, hashParameterName, and include/exclude
filters (see the include and
exclude helper options documentation for
details on specifying include/exclude filters). The example tells the uploader
to use the SHA hashing algorithm on all files.
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:
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.setHashing('SHA'); //<= use SHA hashing algorithm
...
</script>
...
Convenience method for setting the "LastFolderVisitedCookie" parameters.
| Parameter | Type | Description |
|---|---|---|
| expiry | String | Date | Number | Expiration time |
| path | String | Cookie Path |
| domain | String | Cookie domain |
| name | String | Cookie name |
The setLastFolderVisitedCookie method provides a convenient way to set the
"LastFolderVisitedCookie", which remembers the folder from which files were
last uploaded.
As users typically store the files and images they upload in the same folder or folder hierarchy, returning them there next time they wish to upload files can save them a lot of time by not having to navigate from the system root folder.
The cookie's expiry date may be set in several ways, either by a number of seconds
relative to the current time, or an absolute date specified by either a date-time string
(in a format recognized by the Javascript Date.parse method) or a Javascript Date object.
The cookie path may be set to make it apply across the site ("/") or to specific parts
of the site, depending on the application. If your site accepts uploads for different
types of files/images that are likely to come from different sources you may want to
make use of this parameter. By default the LastFolderVisitedCookie will
only apply to the URL of the page that it was embedded in.
In a similar way the domain parameter may be used to set the cookie's
domain.
If you wish to use a different name for the LastFolderVisitedCookie you
can change it via the name parameter.
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
var expiry = 3600; //<= expire in 1 hour
expiry = 'Jan 1, 2010'; //<= expire on New Year's Day 2010
expiry = new Date(2010, 0, 1, 14, 30, 0, 0); //<= expire on New Year's Day 2010 at 2:30pm
var path = "/"; //<= apply cookie across the whole site
var domain = window.location.host; //<= apply cookie to current domain
var name = "lfvc"; //<= use a short name
ue.setLastFolderVisitedCookie(expiry, path, domain, name); //<= set "LastFolderVisitedCookie"
...
</script>
...
Sets an AppletHelper option.
| Parameter | Type | Description |
|---|---|---|
| name | String | Parameter Name |
| value | See Parameter Detail | Parameter Value |
The setParam method allows you to specify AppletHelper options
individually.
Usage example:
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.setParam('maxFileCount', 10); //<= sets 'maxFileCount' option to 10
...
</script>
...
Convenience method for setting GUI properties and text translations.
| Parameter | Type | Description |
|---|---|---|
| specifiers | Object | Property specifiers |
Upload ease uses "properties" to provide a convenient way to customise the GUI. We have separated the properties into two groups below, the first is for controlling visual and behavioural aspects of the GUI, and the second is for language translations.
Properties that control visual (e.g. colour) and behavioural (e.g. display of preview images)
follow. Colours may be specified by name or hex code as
described here. Font names are specified as
FontFamilyName-Style-Size (e.g. Courier-plain-10) where style is
one of plain, bold, bolditalic, italic. Logical values may be given
as true or false, "on" or "off",
"yes" or "no", 0 or non-zero. The expected
type (Colour, Font, Logical, or URL) is given in parentheses after the property name.
Properties that specify text can be used to implement language translations, which should be given by UTF-8 encoded strings. For reference, the default (english) text follows each property name in parentheses. Numbers in braces (e.g. {0}, {1}, {2}) are placeholders for variable values (e.g. file names) that are substituted at run-time.
Note that property names are formed in a special way that allows related properties
to inherit their values (unless overridden). Take the font property for
example - if it were set then all properties with font as the right-most component
of their name would inherit its value. To then change the font used for a file item's label
the label.fileItem.view.font property could be specified to override the parent
value. This mechanism makes it easy to customise the general look and feel of the
GUI without having to specify each and every property.
setProperties() may be called multiple times and with multiple properties specified each time (with the last specified overriding any earlier specifications).
See the code below for usage examples:
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.setProperties({ //<= set one or more UI customisation properties
font: 'Tahoma-plain-10', //<= set font to Tahoma 10pt
backgroundColor: '#000', //<= set background colour to black
foregroundColor: 'white', //<= set foreground colour to white
logoIconURL: 'http://MySite.com/images/logo.png', //<= set logo (64x32 pixels)
images.noPreview: true //<= turn image preview generation off
});
...
ue.setProperties({ //<= set one or more translation properties
'view.selectAll.button.text': '选择所有项目', //<= set "Select All" button text for simplified Chinese
'view.unselectAll.button.text': '取消所有项目' //<= set "Unselect All" button text for simplified Chinese
});
...
</script>
...
Convenience method for setting name and ID when uploading.
| Parameter | Type | Description |
|---|---|---|
| name | String | Session Name |
| id | String | Session ID |
The setSession method provides a convenient way to set the
sessionName and sessionID options of the uploader
(see the sessionName and
sessionID helper options documentation for
details on specifying session cookies). The example shows how to set these
values in pages generated by PHP scripts.
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.setSession('<?=session_name()?>', '<?=session_id()?>'); //<= set session info in PHP
...
</script>
...
Convenience method for setting upload variables and their names.
| Parameter | Type | Description |
|---|---|---|
| specifiers | Object | Variable specifiers |
Upload ease uses "variables" to provide a convenient way to customise the
variables sent to the upload processing script. Each variable may be set to
true, false, or a string value. If true
the variable is uploaded with the same name, if false it is not
uploaded, and if set to a string value it is uploaded using that value as the
name of the variable. Where applicable the fileIndexPlaceholder
parameter is used to substitute file indices into the variable name.
Currently supported variables are as follows:
fileIndexBase parameter).
This variable is not affected by the restartFileIndices parameter.
bundleSize variable).Upload ease creates the file* upload variable names dynamically for each file where necessary (all except fileCount). Use the fileIndexPlaceholder (defaults to #) in the variable name to have the file index substituted into the variable name.
Note that for per file form variables, the form variable names are appended to the fileParams variable name.
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.setVariables({ //<= set one or more upload variables
fileCount: true, //<= turn "fileCount" variable on
fileParams: 'params_#', //<= per file parameters will be params_1, params_2, ...
fileParts: 'part_#' //<= file parts will be named file_1, file_2, ...
});
...
</script>
...
Writes an HTML applet element into the page with current option settings.
Once you have configured the ueAppletHelper the way you want it, it is ready
to embed in your web page. Calling the write method writes the
appropriate HTML applet element into your web page's HTML at the point where it's
called.
...
<script type="text/javascript">
...
var ue = new ueAppletHelper( { options... } );
...
ue.write(); //<= writes an HTML applet element into your web page
...
</script>
...
