FileCatalyst JavaScript API: In-Browser File Transfer

posted in: Acceleration, Applets

Introduction

The FileCatalyst JavaScript API offers the ability to implement an accelerated file transfer application from within a web browser. Using the API, you are able to customize the end-user’s file transfer experience, integrating the file transfer into your site (in terms of both functionality and UI) in a way not necessarily possible with the default configuration alone.

The Quick Version

If you just want to see how the API can be called, here’s an example using jQuery:

$('#uploadButton').click(function() {
  document.FileCatalyst.uploadLive();
});

It’s that easy. The API documentation gives a rundown of each of the methods available via JavaScript. Here, we have bound a click listener to some element with the ID “uploadButton”. When that element is clicked, the JavaScript triggers the upload function of the applet.

Requirements

End user: JavaScript enabled on their browsers, Java installed on their machines (for the desktop environment, this is the vast majority of users)

Developer: 2 files that come with FileCatalyst; plus 2 custom components:

  1. Included: The applet script (ex. fcupload.js)
  2. Included: The applet JAR file (referenced by the applet script) (ex. FileCatalystApplets.jar)
  3. Custom: A webpage that will load the applet and provide controls (applets ship with sample pages to use as a starting point)
  4. Custom: Additional script(s)

Our Longer Example: Uploader with buttons

In this simple example, we have decided that we want to reduce the full-blown UI down to three key buttons: “Add to Queue”, “Upload”, and “Cancel”. In the following code samples, three important tasks are accomplished: 1. the applet is added to the page; 2. the applet’s default UI is hidden; 3. our three buttons are hooked up using the FileCatalyst API and the jQuery JavaScript library.

The Webpage

Let’s have a look at the webpage. In this case we’re just using static HTML.


  
    
     
     
  
  
    

Upload Sample

In the <head> section, we have included jQuery (which we will use for event binding) and then our custom script (which will contain the event binding and any other JS functionality we may wish for). jQuery is possibly overkill if your page is literally as simple as this example; however, many people are already using jQuery on their site.

Buttons are simply <input> elements with type “button”. The buttons also have the class “fcbutton” for convenience in styling and scripting. They are disabled by default, and will be enabled upon applet load. This has the added benefit of keeping the buttons disabled for users without JavaScript enabled on their browsers.

Adding the applet to any webpage couldn’t be easier. Below the buttons we simply load the applet’s JavaScript file with a <script> or <embed> element (depending on browser). Once loaded, the applet appears in the DOM inside an <applet> node.

Hiding the applet

Next, we need to hide the applet’s default UI. You can do this with pure CSS using visibility: hidden, but NOT with display: none (which will not allow the applet to load). A safer bet is to use the height and width parameters inside fcupload.js, however. Setting these to zero will work in some but not all browsers. The safest bet is to make the applet tiny (1X1) and stick it somewhere on the page that’s out of the way.

Inside fcupload.js, find these lines and modify as shown:
// GUI Behaviours and Presentation
var width                       = "1";
var height                      = "1";
var background                  = "255,255,255"; //RGB value for white. You can make it the same color as the element it sits inside

// (later in file)
var callurlonload               = "javascript:appletLoaded()"; // this will trigger the JS "appletloaded" function

For additional insurance, you might have some CSS that hides the applet or takes it out of the document flow:

#fc_upload {
  position: absolute; /* remove from flow */
  visibility: hidden; /* optionally make it completely invisible */
}

Hooking Up the Buttons / Custom Scripts

This is the meat of the whole exercise. We are using jQuery for its simple syntax, but you can use whatever event-binding method you prefer (even inline onclick attributes). All we do in the script is bind a listener to each button. When the button is clicked, a JavaScript function from the FileCatalyst API (now available through the included applet) is fired.

Inside uploadApp.js (or whatever you have named your file):

function appletLoaded() {
  $('.fcbutton').removeAttr('disabled'); // the applet has loaded, so enable the buttons
}

/* bind the click events when the DOM is ready for scripting */

$(document).ready(function() {

  $('#browseButton').click(function() {
    document.FileCatalyst.browseLive(true);
  });

  $('#uploadButton').click(function() {
    document.FileCatalyst.uploadLive();
  });

  $('#cancelButton').click(function() {
    document.FileCatalyst.setCancelled();
  });
});

The appletLoaded function (referenced in fcupload.js modifications) removes the "disabled" attribute, enabling the buttons. The event handler listens for clicks on the buttons, and fires off a method call to the applet, using the available JavaScript functions.

Conclusion

Using a Java applet puts FileCatalyst right in the browser, with no installation required. Full acceleration and security options, without the end-user needing to configure anything is a big win for any organization that uses the web (and what organizations don’t?). Our own API sits under our powerful Workflow and Webmail applications, but if you do not need a fully realized web portal out of the box, or are integrating FileCatalyst within your existing portal, the JavaScript API offers virtually every option you might need.

Transfer hook functions such as getTimeRemaining(), and getFilesSoFar() (along with a whopping 42 other useful hooks) allow you to capture information from an ongoing session. For the upload applet, functions such as the ones used in this post’s example (along with another 20) allow you to invoke applet methods through JavaScript.

The potential is huge. Included in the FileCatalyst Upload Applet package is a sample of a web application that uses AJAX to fetch page content; the applet is never unloaded/destroyed (the way it would be when navigating to an entirely separate page), so you can have a transfer persisting while the user continues to explore the site. The sample uses a number of transfer hooks and upload applet methods, so look to it as a more sophisticated sample than the one provided in this exercise.