The EAFlashUpload provides a number of JavaScript methods for component management.
List of methods
Method name | Description |
---|---|
getProperty | Gets the value of required property. |
setProperty | Sets the value of required property. |
getCustomProperty | Gets the value of required custom property of the file. |
setCustomProperty | Sets the value of required custom property of the file. |
getFormattedString | Accepts a string with fromatting constants and returns a formatted value. |
getFormattedDate | Accepts a Date object and returns formatted date string. |
getFormattedSize | Accepts an integer value and returns formatted size string. |
getFormattedTime | Accepts an integer value of seconds and returns formatted time string. |
sendAsyncRequest | Sends asynchronous request (POST or GET) to the server without page reload. |
urlVarsToObject | Returns an object representation of specified QueryString. |
getFiles | Gets file or list of files from the upload queue. |
removeFiles | Removes file or list of files from the upload queue. |
sortFilesList | Sorts files in the upload queue by specified field and order. |
setFileStatus | Sets status for the specific file. |
uploadFiles | Initiates an upload to the defined URL. |
continueUpload | Resume an upload from the current or next file in the upload queue. |
cancelUpload | Cancels the current upload. |
getProperty(name:String)
Parameters:
- name:String - a string reference to a appropriate property
Returned value type: Object
Description:
Gets the value of required property. The EAFlashUpload uses a string reference to get an access to property, you can find more information here Object structure overview.
Examples:
The following example shows how to retrieve a property value:
EAFlashUpload.getProperty("uploader.uploadUrl");
setProperty(name:String, value:Object)
Parameters:
- name:String - a string reference to a appropriate property
- value:String - a new value of the property
Returned value type: void
Description:
Sets the value of specified property. The EAFlashUpload uses a string reference to get an access to property, you can find more information here Object structure overview.
Examples:
The following example shows how to define a new property value:
EAFlashUpload.setProperty("view.filesList.columnStyle.headerBackgroundUpColor", ["#000000", "#ffffff"]); // You can also define an array as a string: "#000000|#ffffff"
getCustomProperty(propertyObject:Object)
Parameters:
-
propertyObject:Object - a dynamic JavaScript object with the following properties:
- name:string - a name of custom property
- isPublic:Boolean - true if property is public; otherwise false. Default value is false
- fileId:string - an unique identifier of file. Default value is null
Returned value type: Object
Description:
Gets the specified custom property object. The EAFlashUpload provides a possibility to define some additional text properties for each file or for all files in the upload queue. These propeties are sent as separate fields in a multipart/form-data post. The retrieving values on the server side is the same as for HTML Form fields. The method returns specified as the parameter object with additional property value. If no one custom property have found the value contains null.
Examples:
The following example demonstrates how to retrieve the custom property of the first file in the upload queue:
function getProp() { var propertyObject = new Object(); propertyObject.name = "Description"; propertyObject.isPublic = false; propertyObject.fileId = EAFlashUpload.getFiles(0).id; propertyObject = EAFlashUpload.getCustomProperty(propertyObject); alert(propertyObject.value); }
setCustomProperty(propertyObject:Object)
Parameters:
-
propertyObject:Object - a dynamic JavaScript object with the following properties:
- name:string - a name of custom property
- value:string - a value of custom property
- isPublic:Boolean - true if property is public; otherwise false. Default value is false
- fileId:string - an unique identifier of file. Default value is null
Returned value type: Boolean
Description:
Sets the value of specified custom property. The EAFlashUpload provides a possibility to define some additional text properties for each file or for all files in the upload queue. These propeties are sent as separate fields in a multipart/form-data post. The retrieving values on the server side is the same as for HTML Form fields. If you want to set up the same custom properties for all files in the upload queue omite fileId property. isPublic property indicates whether installable custom property will be available to editing via EAFlashUpload user interface. If property with specified name doesn't exist the new custom property is created. The method returns true if property have been successfully set; otherwise false.
Examples:
The following example demonstartes how to set the custom property and retrieve it on the server:
function setProp() { var propertyObject = new Object(); propertyObject.name = "Description"; propertyObject.value = "Personal information"; propertyObject.isPublic = false; // Here we omitted fileId property and custom property will apply to all files. // propertyObject.fileId EAFlashUpload.setCustomProperty(propertyObject); }// possible C# code on the server side String descriptionOfFile = ""; descriptionOfFile = Request.Form("Description");// possible PHP code on the server side $descriptionOfFile = $_REQUEST['Description'];
getFormattedString(formString:String, fileId:Object = null)
Parameters:
- formString:String - the string containing formatting constants to converting
- fileId:Object - an unique identifier of the file. Default value is null
Returned value type: string
Description:
Converts the string containing formatting constants to the formatted text. You can find more information related to string formatting here String formatting. If you specify a string containing constants related to file then fileId parameter should be defined.
Examples:
The following example demonstrates the string formatting:
var fileObj = EAFlashUpload.getFiles(0); var pattern = "The file size is #FILE_SIZE#"; EAFlashUpload.getFormattedString(pattern, fileObj.id); // the output may be as follows: // The file size is 15 MB
getFormattedDate(formDate:Date)
Parameters:
- formDate:Date - a Date object to converting
Returned value type: string
Description:
Converts a Date object to the formatted string. The formatting is based on dateFormatString property. This method may be usefull if you want to create JavaScript interface and display user friendly information.
Examples:
The following example demonstrates Date object formatting:
var date = new Date("October 12, 2008 13:14:00"); alert(EAFlashUpload.getFormattedDate(date)); // if dateFormatString is "d/M/Y H:i" then output will be as follows: // 12/Oct/2008 13:14
getFormattedSize(formSize:Integer)
Parameters:
- formSize:Integer - a size in bytes to converting.
Returned value type: string
Description:
Converts a size in bytes to the formatted string. The formatting is based on sizeAbbrev property. This method may be usefull if you want to create JavaScript interface and display user friendly propgress information.
Examples:
The following example demonstrates formatting of a different size value:
EAFlashUpload.getFormattedSize(1610612736); // output is 1.5 GB EAFlashUpload.getFormattedSize(536870912); // output is 512 MB EAFlashUpload.getFormattedSize(262144); // output is 256 KB EAFlashUpload.getFormattedSize(536); // output is 536 B
getFormattedTime(formTime:Integer)
Parameters:
- formTime:Integer - a time in secondes to converting.
Returned value type: string
Description:
Converts an integer value of seconds to the formatted string. The formatting is based on timeAbbrev property. This method may be usefull if you want to create JavaScript interface and display user friendly propgress information.
Examples:
The following example demonstrates formatting of a different time value:
EAFlashUpload.getFormattedTime(8580); // output is 2 h 23 m EAFlashUpload.getFormattedTime(332); // output is 5 m 32 s
sendAsyncRequest(requestObject:Object)
Parameters:
-
requestObject:Object - a dynamic JavaScript object with the following properties:
- url:string - an URL of the server script configured to receive a request. The value should be non empty string, otherwise an error will occur.
- method:stirng - a http method name (POST or GET) that will be used for request sending. The value sholud be non empty string, otherwise an error will occur.
- data:object - a set of data that should be sent to the server.
Returned value type: void
Description:
Sends asynchronous request (POST or GET) to the server without page reload. If method is GET then all data will be sent in the query string of specified url. If POST method is used then Content-Type request header is "application/x-www-form-urlencoded".
Examples:
The following example describes how to send async request to the server and receive a response:
function sendData() { var requestObject = new Object(); requestObject.url = "http://www.myhost.com/receiver.php"; requestObject.mwthod = "POST"; requestObject.data = EAFlashUpload.urlVarsToObject("name=Jhon Smit&position=CEO"); EAFlashUpload.sendAsyncRequest(requestObject); } function EAFlashUpload_onAsyncRequestEnd(response) { alert(response); } function EAFlashUpload_onAsyncRequestError(message) { alert(message); }
urlVarsToObject(varsString:String)
Parameters:
- varsString:String - a string for converting.
Returned value type: object
Description:
The method accepts url variables string(key=value pairs delimited with a semicolon) and returns an object.
Examples:
In the following examples url variables string is converted to the object:
function convertQueryString() { var varObject = EAFlashUpload.urlVarsToObject("name=Jhon Smit&position=CEO"); var output = ""; output += "name: " + varObject.name; output += "; " output += "position: " + varObject.position; } // the output will contain name: Jhon Smit; position: CEO
getFiles()
getFiles(fileIndex:int)
getFiles(fileId:String)
getFiles(filesIndexes:Array)
getFiles(filesIds:Array)
Parameters:
- fileIndex:int - an index of a file in the upload queue.
- fileId:String - an unique identifier of a file in the upload queue.
- filesIndexes:Array - an array of indexes of files in the upload queue.
- filesIds:Array - an array of unique identifiers of files in the upload queue.
Returned value type: File or an Array of File objects.
Description:
Returns files from the upload queue by specified identifiers. If the method is called without parameters then all file of the upload queue is returned. The files are reperesented as the File object instances.
Examples:
The following example demonstrates various calls of getFiles method:
// Get all files contained in the upload queue. EAFlashUpload.getFiles(); // Get the first file in the upload queue EAFlashUpload.getFiles(0); // Get the file with the specific identifier. EAFlashUpload.getFiles("6959483923458790"); // Get the first five files in the upload queue. EAFlashUpload.getFiles([0, 1, 2, 3, 4]);
removeFiles()
removeFiles(fileIndex:int)
removeFiles(fileId:String)
removeFiles(filesIndexes:Array)
removeFiles(filesIds:Array)
Parameters:
- fileIndex:int - an index of a file in the upload queue.
- fileId:String - an unique identifier of a file in the upload queue.
- filesIndexes:Array - an array of indexes of files in the upload queue.
- filesIds:Array - an array of unique identifiers of files in the upload queue.
Returned value type: void
Description:
The method removes files from the upload queue by the specified identifiers. If files identifiers is not specified all files will be removed. If fileIndex or filesIndexes contains the value that is out of the queue range an error will occur.
Examples:
The following example demonstrates various calls of removeFiles method:
// Remove all files contained in the upload queue. EAFlashUpload.removeFiles(); // Remove the first file in the upload queue EAFlashUpload.removeFiles(0); // Remove the file with the specific identifier. EAFlashUpload.removeFiles("6959483923458790"); // Remove the first five files in the upload queue. EAFlashUpload.removeFiles([0, 1, 2, 3, 4]);
sortFilesList(fieldName:String, isSortDescending:Boolean = false)
Parameters:
- fieldName:String - the name of the File object property.
- isSortDescending:Boolean - determines an order of sorting. Default value is false
Returned value type: void
Description:
The method sorts the files in the upload queue by the specified field and in the specified order.
Examples:
In the following example files are sorted by size:
function sortBySize() { EAFlashUpload.sortFilesList("size", true); }
setFileStatus(id:String, status:int)
Parameters:
- id:String - the unique identifier of the specific file.
- status:int - status of the file. The value is within a range 0 - 5:
- 0 - READY
- 1 - UPLOADING
- 2 - UPLOADED
- 3 - ERROR
- 4 - CANCELED
- 5 - CUSTOM
Returned value type: void
Description:
The method sets status for the specific file.
Examples:
The following example sets custom status for each file that exists on the server. Here we assume that server script returns the following code:
function EAFlashUpload_onUploadError(errorObject) { if(errorObject.type == "SERVER_CUSTOM_ERROR" && errorObject.message == "The file already exists") { // sets a custom status for the file EAFlashUpload.setFileStatus(errorObject.file.id, 5); EAFlashUpload.continueUpload(false); } }
uploadFiles(null, uploadUrl:String = "")
uploadFiles(fileIndex:int, uploadUrl:String = "")
uploadFiles(fileId:String, uploadUrl:String = "")
uploadFiles(filesIndexes:Array, uploadUrl:String = "")
uploadFiles(filesIds:Array, uploadUrl:String = "")
Parameters:
- fileIndex:int - an index of a file in the upload queue.
- fileId:String - an unique identifier of a file in the upload queue.
- filesIndexes:Array - an array of indexes of files in the upload queue.
- filesIds:Array - an array of unique identifiers of files in the upload queue.
- uploadUrl:String - an alternative URL of the server script configured to handle upload through HTTP POST calls. Default value is empty string.
Returned value type: void
Description:
The method initiates an upload of files which identifiers are specified as a parameter. The uploadUrl is optional and allows to define an alternative url for upload. Use this parameter if you wish to upload files to the location different from uploader.uploadUrl property value. If fileIndex or filesIndexes contains the value that is out of the queue range an error will occur.
Examples:
The following example demonstrates various calls of uploadFiles method:
// Upload all files that are being contained in the upload queue. EAFlashUpload.uploadFiles(); // Upload the first file in the upload queue EAFlashUpload.uploadFiles(0); // Upload a file with the specific identifier. EAFlashUpload.uploadFiles("6959483923458790"); // Upload the first five files in the upload queue. EAFlashUpload.uploadFiles([0, 1, 2, 3, 4]);
continueUpload(retryCurrent:Boolean = false)
Parameters:
- retryCurrent:Boolean - determines whether an upload should be renewed from the file where it was stopped. Default value is false
Returned value type: void
Description:
The method renew an upload that was stopped by calling cancelUpload method or due to some error. The EAFlashUpload doesn't supports uploading of part of the file.
Examples:
In the following example an upload is canceled and after timeout renewed again:
function cancelUpload() { EAFlashUpload.cancelUpload(); setTimeout('renewUpload', 1000); } function renewUpload() { // Renew the upload from the file where it was stopped. EAFlashUpload.continueUpload(true); }
cancelUpload(immediately:Boolean = true)
Parameters:
- immediately:Boolean - determines whether an upload should be canceled immediately or after current file will be uploaded. Default value is true.
Returned value type: void
Description:
The method cancels an upload. Cancellation is achieved immediately or with a timeout. The canceled uploads may be renewed by using continueUpload method.
Examples:
In the following example an upload is canceled and after timeout renewed again:
function cancelUpload() { EAFlashUpload.cancelUpload(); setTimeout('renewUpload', 1000); } function renewUpload() { // Renew the upload from the file where it was stopped. EAFlashUpload.continueUpload(true); }