Revver Developer Center: Widget : Flash : Upload

Widgets:Flash Upload Widget

Introduction

Revver’s flash upload tool is a simple flash tool which gives the user some feedback on how a http post upload is progressing without the need for complicate AJAX based call backs. It works in conjunction with the Revver API to provide a seamless upload process for Revver’s partner sites.

The Process

The upload process involves two steps which need to be completed for a successful upload to occur.

Uploading of the file
Submitting of the files metadata

Uploading File

1. Request an upload token from the Revver API

Specified here : http://developer.revver.com/api/methods/video#getuploadtokens

The API call should specify a count of 1 and the child user to whose account the file should be uploaded to if appropriate.

video.getUploadTokens(1, {'owner':'user12345'})

The returned value contains an upload url and an upload token. The upload url can be ignored since we are using the Flash upload tool.

2. Pass the upload token to the revver upload tool

As can be seen above the upload token is passed into the uploader.swf as the sessionToken parameter:

uploader.swf?sessionToken=0000fe61c8d80d33d7cca6c54dd76b86

3. User then selects a file for upload using the upload tools UI

The user then clicks the browse button and selects a file to upload. If the file is not too small or too large, the user can then click the upload button which will begin the upload process

4. File is uploaded

The file is now uploaded to the upload server.

Submitting Metadata

The files metadata must be submitted via the Revver API before the file will be passed on for transcoding. This is achieved using the API’s video.create function. This function is passed the same uploadToken as was used for the file upload along with metadata for that file.

video.create(‘0000fe61c8d80d33d7cca6c54dd76b86’, ‘Test Video’, ‘test’,1)

Specified here : http://developer.revver.com/api/methods/video#create

Gathering metadata

It is recommended that the upload and metadata gathering process be done in a 2 step manner so that the user is forced to add metadata either before the upload, after the upload or during the upload. To help with this the upload tool can be passed urls or javascript functions to call at certain stages of the upload process.

The callbacks provided are:

onStart	Called when the user clicks on the Upload button after selecting their file. This call should be used to call a javascript function in the upload page which can show a UI for gathering metadata.
onSuccess	Called when the upload is completed. This can be used to open a new page where the user can add metadata for the file once the upload is completed.
onFail	Called when the upload fails. Can be used to open an upload failed page.
onCancel	Called when the user cancels the upload. Can be used to open an upload canceled page.

All callbacks can be passed either a URL or a javascript function to call. In the case of URL, it should just be passed to the uploader.swf as follows :

onSuccess=http://foo.bar.com/success.html

In the case of a javascript function call, it should be passed as follows :

onStart=javascript:onUploadStart()

Example

<embed
src="uploader.swf?&sessionToken=0000fe61c8d80d33d7cca6c54dd76b86&onStart=javascript:uploadStart()&onSuccess=http://foo.bar.com/success.html&onFail=javascript:uploadFail()&onCancel=javascript:uploadCancel()"
quality="high"
width="500"
height="172"
type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" name="uploader">
</embed>

Note that all the callback parameters are optional.

Skinning

The Revver upload tool provides a simple xml based skinning mechanism which can be use to customize the upload tool to a limited extent.

The full path to the skin xml should be passed to the uploader.swf in the same was as other parameters :

<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000"
  codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=8,0,0,0"
  width="500"
  height="172"
  id="uploader"
  align="middle">
   <param name="allowScriptAccess" value="sameDomain" />
   <param name="movie" value="uploader.swf?sessionToken=0000ffc9776da3ce57b785f2fc451f2a&onStart=javascript:uploadStart('step2')&onSuccess=javascript:uploadSuccess('step3')&onFail=javascript:uploadFail('step4')&onCancel=javascript:uploadCancel('step5')&staging=revver&skinXML=FULLPATHTOSKIN" />
   <param name="quality" value="high" />
   <param name="bgcolor" value="#ffffff" />
   <embed src="uploader.swf?sessionToken=0000ffc9776da3ce57b785f2fc451f2a&onStart=javascript:uploadStart('step2')&onSuccess=javascript:uploadSuccess('step3')&onFail=javascript:uploadFail('step4')&onCancel=javascript:uploadCancel('step5')&staging=revver&skinXML=FULLPATHTOSKIN"
      quality="high"
      bgcolor="#ffffff"
      width="500"
      height="172"
      name="uploader"
      align="middle"
      allowScriptAccess="sameDomain"
      allowFullScreen="false"
      type="application/x-shockwave-flash"
      pluginspage="http://www.macromedia.com/go/getflashplayer" />
</object>

The Skin XML

The XML format is very simple and contains a single tag with multiple parameters.

Parameter	Description
background	A 500x172 png file which is displayed as the background of the upload tool
browse_btn	A 98x27 png which is displayed when the upload tool first loads up
upload_btn	A 98x27 png which is displayed after the use has browsed and selected their file
cancel_btn	A 30x27 png which is displayed with the upload button and during upload
font_color	A hex RGB value which dictates the font color
font_alert_color	A hex RGB value which dictates the alert font color
progress_txt	Text displayed at the bottom of the upload tool when the upload is in progress
confirm_txt	Text displayed at the bottom of the upload tool when the upload completes
confirm_inside_txt	Text displayed in the center of the upload tool when the upload completes

i.e.

<?xml version="1.0" encoding="UTF-8"?>
<uploader_config
background="http://foo.bar.com/skins/uploader_skin.png"
upload_btn="http://foo.bar.com/skins/upload_btn.png"
browse_btn="http://foo.bar.com/skins/browse_btn.png"
cancel_btn="http://foo.bar.com/skins/cancel_btn.png"
font_color="FFFFFF"
font_alert_color="00FFFF"
progress_txt=”Displayed at the bottom of the upload tool during upload”
confirm_txt=" Displayed at the bottom of the upload tool when upload completes"
confirm_inside_txt="Displayed in the center of the upload tool when upload completes"
/>

As with the url to the XML file, all urls in the xml must be absolute.

Upload Modes

The upload can be run in two modes :
To switch between these modes simply use the staging parameter when embedding the upload tool.

Mode	Embed String	Description
Production	No staging var	Runs agains production
Staging	staging=revver	Runs agains Revver’s staging servers