jscripts/infusion/components/uploader/ReadMe.txt

   1 Infusion Uploader Read Me
   2
   3 1) Progressive Enhancement
   4 2) Upgrading
   5 3) Known Issues
   6 4) Troubleshooting
   7 5) Running the Uploader with out a Server
   8
   9 --------------------------------------
  10
  11 PROGRESSIVE ENHANCEMENT:
  12
  13 As of Infusion 1.3, the Uploader automatically delivers the best version of the component
  14 possible, based on the features supported by a user's browser. There are three flavours of the
  15 Uploader:
  16
  17     1. Single file: delivered to browsers that don't support JavaScript, Flash or HTML 5
  18     2. Flash with SWFUpload: delivered to older browsers with JavaScript enabled (especially IE)
  19     3. HTML 5: the best and most widely-supported version of Uploader, suitable for modern browsers
  20
  21 If you don't want to offer a particular version of Uploader to your users, you can simply omit the
  22 appropriate Support.js file from your page. So, for example, if you don't want to deliver Flash to
  23 your users, simply don't include FlashUploaderSupport.js and Flash9UploaderSupport.js in your page.
  24 To do this, you will have to include all the required files individually, instead of using a single
  25 concatenated file.
  26
  27 --------------------------------------
  28
  29 UPGRADING from previous versions:
  30
  31 Before upgrading from Infusion 1.2 or earlier, please refer to the Uploader API documentation and the
  32 latest example code. The Fluid Uploader was extensively refactored in the 1.3 release with the
  33 introduction of HTML 5 support. The API is expected to fully stabilize to a production level after
  34 Infusion 1.4.
  35
  36 Uploader includes automatic backwards compatibility for Infusion 1.2-era options, which can be enabled
  37 simply by including the following files in your page:
  38     ModelTransformations.js
  39     UploaderCompatibility-Infusion1.2.js
  40
  41 --------------------------------------
  42
  43 KNOWN ISSUES:
  44
  45 Uploader and HTML 5:
  46
  47 * Uploading more than one file at a time without Flash requires a reasonably up-to-date browser with
  48   support for the following open web technologies, referred to under the umbrella of "HTML 5":
  49     - Multiple file form elements
  50     - XmlHTTPRequest Level 2
  51     - FormData
  52     - File API
  53
  54 * The following browsers will support the HTML 5 version of the Uploader:
  55     - Firefox 3.6 or higher
  56     - Safari 4 or higher
  57     - Google Chrome
  58
  59   All others will automatically receive the Flash or single file versions of the Uploader depending
  60   on browser capabilities.
  61
  62 * Firefox 3.6 has only partial support for HTML 5 uploads, and will load the entire file into browser
  63   memory. This causes a risk of crashing with very large files on computers with less memory. As a
  64   result, we've included an additional option called "legacyBrowserFileLimit," allowing file sizes to
  65   be specially capped in Firefox 3.6. The default value for this option is 100 MB.
  66
  67 * The Uploader's HTML 5 implementation doesn't currently support filtering based on file types.
  68
  69 * The HTML 5 implementation is inconsistent with the Flash version when handling the
  70   queueSettings.fileSize limit option, causing it to be interpreted as MB instead of KB.
  71
  72 Uploader and Flash:
  73
  74 * As of Infusion 1.3, the Flash version of the Uploader is only delivered to users with older
  75   browsers that lack HTML 5 support, such as Firefox 3.5 and below and Internet Explorer. Due to
  76   ongoing accessibility and stability issues with Flash and SWFUpload, we encourage you and your
  77   users to upgrade to an HTML 5-compatible browser such as Firefox 3.6+, Safari 4+, or Chrome.
  78
  79 * The Flash 10-based implementation of the Uploader has a number of systemic bugs an accessibility
  80 issues, and is deprecated for all browsers except Internet Explorer on Windows. Some issues include:
  81
  82       - In Firefox and IE, the Flash-based "Browse" button does not size correctly when the text/page
  83       is resized or zoomed.
  84
  85       - In most browsers, the Flash-based "Browse" button is not  keyboard navigable and may trap
  86       keyboard navigation, refusing to give up focus without a mouse click.
  87
  88       - When the user presses the Stop button, the Uploader waits until the current file is complete
  89       before stopping the upload process.
  90
  91 --------------------------------------
  92
  93 TROUBLESHOOTING UPLOADER AND FLASH:
  94
  95 * When running the Flash version of the Uploader on a local system without a server, you may need to
  96   modify some of your Flash settings to allow the local SWFUpload object to access your file system.
  97   To do so, follow these directions:
  98
  99   1. Open your browser
 100   2. Browse to:
 101      http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04.html
 102   3. In the Flash Settings panel, click "Edit locations..."
 103   4. Select "Add location..."
 104   5. Click "Browse for folder..."
 105   6. Select the local /src/webapp/lib/swfupload/flash/ directory that contains the swfupload.swf file
 106   7. Restart your browser
 107
 108   You should be good to go!
 109
 110   However, if you move your installation, you'll need to do this all over again. There are settings
 111   that will allow the file to be run from any location on your local machine but these instructions
 112   are the minimum settings and therefore pose the least security risk.
 113
 114   These settings are global and do not need to repeated for every browser on a given system.
 115
 116 * If you see this error in your console:
 117      [Exception... "'Invalid function name' when calling method: [nsIDOMEventListener::handleEvent]"
 118      nsresult: "0x8057001e (NS_ERROR_XPC_JS_THREW_STRING)" location: "<unknown>" data: no]
 119
 120   the flashUrl option is probably wrong. Check that first.
 121
 122
 123 --------------------------------------
 124
 125 RUNNING THE UPLOADER ON A LOCAL SYSTEM WITHOUT A SERVER
 126
 127 Running the Uploader locally without a server is intended for basic testing purposes only. The
 128 DemoRemote object provides a simulated conversation with the server, but it doesn't represent an
 129 accurate picture of the component's behaviour when used in a real deployment environment.
 130
 131 To see the Uploader in action with a real server, have a look at Fluid's Image Gallery demo:
 132
 133 http://build.fluidproject.org:8080/sakai-imagegallery2-web/site/AddImages/
 134
 135
 136