PhoneGap - File Upload

Description

Upload one or more files to either the Alpha Anywhere server or to the Amazon S3 using the PhoneGap File Transfer feature. (Only applies to UX components running in a PhoneGap shell.)

Used with the UX component.

 PhoneGap File Upload Properties

Target
Specify if you want to upload files to the Alpha Anywhere server or to Amazon S3 Choices include AlphaAnywhere Server, S3.
Files to upload Javascript Function
Specify the name of a Javascript function to call. This function must return an array containing the names of the files that you want to upload. Each file in the array must be a fully qualified filename in the filesystem of device on which your PhoneGap wrapped UX component is running. For example: return ['file:///storage/emulated/12345345.jpg']

 Upload Properties

Display progress during file upload
Specify if progress should be shown while file(s) are being uploaded.
Progress bar color
Specify the progress bar color.
Progress bar width
Specify the progress bar width. Use CSS units.
Show progress for individual files
Show progress for individual files property.
Show progress for all files combined
Show progress for all files combined property.
Placeholder for progress indicator
Specify the name of a Placeholder control where the progress indicator should be shown. TIP: You can enter 'Element:name_of_element' to target a specific element on the page rather than a Placeholder. For example: Element:div1

 S3 Upload Properties

Storage connection string
Specify the named storage connection string. IMPORTANT: The storage connection string MUST NOT BE ENCRYPTED. TIP: To define a storage connection string, go to the Tools menu in the Web Projects Control Panel.
Display progress during file upload
Specify if progress should be shown while file(s) are being uploaded.
Progress bar color
Specify the progress bar color.
Progress bar width
Specify the progress bar width. Use CSS units.
Show progress for individual files
Show progress for individual files property.
Show progress for all files combined
Show progress for all files combined property.
Placeholder for progress indicator
Specify the name of a Placeholder control where the progress indicator should be shown. TIP: You can enter 'Element:name_of_element' to target a specific element on the page rather than a Placeholder. For example: Element:div1
Authenticated read
Specify if authentication is required to read the object once it has been uploaded to S3

 Xbasic Events Properties

onAfterFileUploaded
Specify the name of the Xbasic function to call after each file in the list of files to be uploaded has been uploaded.

 Javascript Properties

Target object name on Amazon S3
You can define a function that returns the name of the object in Amazon S3. By default, the filename of the file on the client will be used. Your code can reference e.name, e.size and e.type (the client-side name, size and mime-type of the selected file). Your function must return the name to use. The name can include a folder. For example: return 'myfolder1/' + e.name. This will use the same name as the client-side file but the object will be stored in a folder called 'myfolder1'. NOTE: The target name on Amazon will be available to other Javascript functions in the e.targetName property.
On Progress
Fires when another 'chunk' of the file being uploaded has been sent. This event allows you to write custom progress displays. Your code can reference these variables: array - an array with entries for each file being uploaded, arrayIndex - index into the array for the current progress event - will either be a number or 'total' if the event is for the total of all files combined, pctComplete -- percent complete for the specified file or if arrayIndex is 'total', percent complete for the entire job, bytesCompleted -- number of bytes sent for the specified file, or if arrayIndex is 'total', total number of bytes sent, bytesTotal -- number of bytes in the specified file, or if arrayIndex is 'total', total number of bytes to be sent. The array( array) is an object array. Each item has a .name, property and several other properties.
On Upload Complete (all files)
Fires after all of the files to be uploaded have been processed. Not all files were necessarily uploaded successfully. You need to check the array's 'succeeded' property, as described here. Your Javascript can reference 'array' - an array with an object for each file that was uploaded. The object for each item in the array will have these properties: filename (name of the file on the device), targetName (name of the file on the target), completed (always true) , failed (true or false depending on whether an error was reported) , succeeded (true or false depending on whether the file uploaded successfully) , aborted (true if the user aborted this file upload)
On Upload Complete (individual file)
Fires after each file in the array of files to be uploaded has been processed. Note that the file did not necessarily upload successfully. You need to check the array's 'succeeded' property, as described here. Your Javascript can reference 'array' - an array with an object for each file that was uploaded and 'itemNumber' - an index into the array for the file on which the event is fired. The object for each item in the array will have these properties: filename (name of the file on the device), targetName (name of the file on the target), completed (always true) , failed (true or false depending on whether an error was reported) , succeeded (true or false depending on whether the file uploaded successfully) , aborted (true if the user aborted this file upload)
On Error
Fires if there is any type of error while uploding a file. Your Javascript can reference 'array' -- the array of files being uplaoded and 'arrayIndex' - the index into this array. You can also reference 'error' - the error object.
On Ajax callback failed
Fires if the Ajax callback to sign S3 policy fails.
On device offline
Fires if the device is offline when the attempt to make an Ajax callback to sign S3 policy is made.
On before upload starts - validate
Fires before a file is uploaded. If your Javascript returns false then the file is not uploaded (and the item's 'aborted' property in the array is set to true, as is its 'completed' property). Your Javascript can reference 'array' - an array with an object for each file to be uploaded and 'itemNumber' - an index into the array for the file on which the event is fired. Each item in the array has information about the file, including the file size and filename.

See Also