| [ Index ] |
PHP Cross Reference of Drupal 6 (yi-drupal) |
[Summary view] [Print] [Text view]
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml" > 3 <head> 4 <title>SWFUpload v2 Documentation</title> 5 </head> 6 7 <style type="text/css"> 8 h1 /* Title */ { 9 } 10 h2 /* Chapter Header */ { 11 background-color: #DCE7F2; 12 border: solid 1px #CCD7E0; 13 padding: 10px; 14 15 margin-top: 50px; 16 margin-left: 5px; 17 } 18 h3 /* Section Header */ { 19 background-color: #EDFFEB; 20 padding: 10px; 21 22 margin-left: 15px; 23 } 24 h4 { 25 background-color: #FFFFD1; 26 padding: 7px; 27 28 margin-left: 20px; 29 } 30 31 h5 { 32 background-color: #F0F0F0; 33 padding: 4px; 34 35 font-weight: normal; 36 37 margin-left: 25px; 38 } 39 40 p { 41 margin-left: 35px; 42 } 43 span.function { 44 font-weight: bold; 45 } 46 span.parameter { 47 font-style: italic; 48 font-weight: normal; 49 } 50 51 hr { 52 margin-right: 25px; 53 } 54 55 ul, ol { 56 list-style-position: outside; 57 margin: 0; 58 padding: 0; 59 margin-left: 50px; 60 } 61 li { 62 padding-left: 15px; 63 } 64 65 code { 66 display: block; 67 border: solid 1px #EFEFEF; 68 background-color: #FAFAFA; 69 padding: 15px; 70 margin-left: 25px; 71 72 white-space: pre; 73 74 overflow-x: scroll; 75 overflow-y: visible; 76 } 77 </style> 78 79 <body> 80 <h1>SWFUpload v2.2.0.1 Documentation</h1> 81 <h2>TOC</h2> 82 <ol> 83 <li><a href="#swfupload">SWFUpload</a></li> 84 <li><a href="#v2">SWFUpload Version 2</a></li> 85 <li><a href="#overview">Overview</a></li> 86 <li><a href="#gettingstarted">Getting Started</a></li> 87 <li><a href="#javascriptobject">SWFUpload JavaScript Object</a> 88 <ol> 89 <li><a href="#constructor">Constructor</a></li> 90 <li><a href="#globals">Globals and Constants</a> 91 <ol> 92 <li><a href="#instances">instances</a></li> 93 <li><a href="#movieCount">movieCount</a></li> 94 <li><a href="#queue_error">QUEUE_ERROR</a></li> 95 <li><a href="#upload_error">UPLOAD_ERROR</a></li> 96 <li><a href="#file_status">FILE_STATUS</a></li> 97 <li><a href="#button_action">BUTTON_ACTION</a></li> 98 <li><a href="#button_cursor">CURSOR</a></li> 99 <li><a href="#button_window_mode">BUTTON_WINDOW_MODE</a></li> 100 </ol> 101 </li> 102 <li><a href="#properties">Properties</a> 103 <ol> 104 <li><a href="#customSettings">customSettings</a></li> 105 <li><a href="#movieName">movieName</a></li> 106 </ol> 107 </li> 108 <li><a href="#methods">Methods</a> 109 <ol> 110 <li><a href="#addSetting">addSetting</a> (deprecated)</li> 111 <li><a href="#getSetting">getSetting</a> (deprecated)</li> 112 <li><a href="#retrieveSetting">retrieveSetting</a> (removed in v2.1.0)</li> 113 <li><a href="#destroy">destroy</a> (added in v2.1.0)</li> 114 <li><a href="#displayDebugInfo">displayDebugInfo</a></li> 115 <li><a href="#selectFile">selectFile</a></li> 116 <li><a href="#selectFiles">selectFiles</a></li> 117 <li><a href="#startUpload">startUpload</a></li> 118 <li><a href="#cancelUpload">cancelUpload</a></li> 119 <li><a href="#stopUpload">stopUpload</a></li> 120 <li><a href="#getStats">getStats</a></li> 121 <li><a href="#setStats">setStats</a></li> 122 <li><a href="#getFile">getFile</a></li> 123 <li><a href="#addPostParam">addPostParam</a></li> 124 <li><a href="#removePostParam">removePostParam</a></li> 125 <li><a href="#addFileParam">addFileParam</a></li> 126 <li><a href="#removeFileParam">removeFileParam</a></li> 127 <li><a href="#setUploadURL">setUploadURL</a></li> 128 <li><a href="#setPostParams">setPostParams</a></li> 129 <li><a href="#setFileTypes">setFileTypes</a></li> 130 <li><a href="#setFileSizeLimit">setFileSizeLimit</a></li> 131 <li><a href="#setFileUploadLimit">setFileUploadLimit</a></li> 132 <li><a href="#setFileQueueLimit">setFileQueueLimit</a></li> 133 <li><a href="#setFilePostName">setFilePostName</a></li> 134 <li><a href="#setUseQueryString">setUseQueryString</a></li> 135 <li><a href="#setDebugEnabled">setDebugEnabled</a></li> 136 <li><a href="#setButtonImageURL">setButtonImageURL (added in v2.2.0)</a></li> 137 <li><a href="#setButtonDimensions">setButtonDimensions (added in v2.2.0)</a></li> 138 <li><a href="#setButtonText">setButtonText (added in v2.2.0)</a></li> 139 <li><a href="#setButtonTextStyle">setButtonTextStyle (added in v2.2.0)</a></li> 140 <li><a href="#setButtonTextPadding">setButtonTextPadding (added in v2.2.0)</a></li> 141 <li><a href="#setButtonDisabled">setButtonDisabled (added in v2.2.0)</a></li> 142 <li><a href="#setButtonAction">setButtonAction (added in v2.2.0)</a></li> 143 <li><a href="#setButtonCursor">setButtonCursor (added in v2.2.0)</a></li> 144 </ol> 145 </li> 146 <li><a href="#events">Events</a> 147 <ol> 148 <li><a href="#flashReady">flashReady</a></li> 149 <li><a href="#swfUploadLoaded">swfUploadLoaded</a></li> 150 <li><a href="#fileDialogStart">fileDialogStart</a></li> 151 <li><a href="#fileQueued">fileQueued</a></li> 152 <li><a href="#fileQueueError">fileQueueError</a></li> 153 <li><a href="#fileDialogComplete">fileDialogComplete</a></li> 154 <li><a href="#uploadStart">uploadStart</a></li> 155 <li><a href="#uploadProgress">uploadProgress</a></li> 156 <li><a href="#uploadError">uploadError</a></li> 157 <li><a href="#uploadSuccess">uploadSuccess</a></li> 158 <li><a href="#uploadComplete">uploadComplete</a></li> 159 <li><a href="#debug">debug</a></li> 160 </ol> 161 </li> 162 <li><a href="#utility">SWFUpload Utility Objects</a> 163 <ol> 164 <li><a href="#settingsobject">Settings Object</a></li> 165 <li><a href="#settingsdescription">Settings Description</a></li> 166 <li><a href="#fileobject">File Object</a></li> 167 <li><a href="#statsobject">Stats Object</a></li> 168 </ol> 169 </li> 170 </ol> 171 </li> 172 <li><a href="#plugins">SWFUpload Plug-ins</a></li> 173 <li><a href="#knownissues">Known Issues</a></li> 174 </ol> 175 176 177 <h2><a name="swfupload"></a>SWFUpload</h2> 178 <p> 179 <a href="http://www.swfupload.org">SWFUpload</a> is a client-side file upload tool originally developed by <a href="http://www.vinterwebb.se/">Vinterwebb.se</a>. It uses a combination of Flash and JavaScript to 180 provide file upload functionality beyond what the basic browser provides with the <input type="file" /> tag. 181 </p> 182 <p>The main features that SWFUpload provides are:</p> 183 <p> 184 <ul> 185 <li>The ability to select multiple files in the file browser dialog.</li> 186 <li>AJAX-style uploading without a page refresh.</li> 187 <li>Upload progress events.</li> 188 <li>Namespaced classes compatible with other JavaScript libraries (i.e., jQuery, Prototype, etc.).</li> 189 <li>Flash 9 and Flash 10 support. (Flash 8 support dropped in version 2.2.0)</li> 190 </ul> 191 </p> 192 <p> 193 SWFUpload is different from other Flash based upload tools because of the philosophy 194 behind its design. SWFUpload gives developers control by leaving the UI in the browser (as much as possible). 195 Developers can use XHTML, CSS, and JavaScript to tailor the upload UI to the needs and 196 style of their site. Upload status updates are made through a set of simple JavaScript events. 197 The developer uses these events to update the webpage as the file upload progresses. 198 </p> 199 <p> 200 Unfortunately Flash Player 10 has forced us have one button in a flash movie in order to trigger the file browser dialog window. SWFUpload 201 still empowers the devloper by provding the ability the button and overlay text from JavaScript. 202 </p> 203 204 <h2><a name="v2"></a>SWFUpload v2</h2> 205 <p> 206 SWFUpload v2 includes new advanced features, improved stability, Flash Player 207 bug work-arounds and a helpful set of Plug-ins. New features include: 208 </p> 209 <p> 210 <ul> 211 <li>Flash Player 10 security compatibility.</li> 212 <li>The ability to send additional POST values with the uploads.</li> 213 <li>Sending per file POST values.</li> 214 <li>Complete set of events.</li> 215 <li>All settings dynamically updateable.</li> 216 <li>Retrieve result data from the server.</li> 217 <li>Stop an upload without cancelling.</li> 218 <li>Upload files in any order.</li> 219 <li>Multi- & Single-file selection dialogs.</li> 220 <li>Queue size, files uploaded and file size limits.</li> 221 <li>Properly handling of zero-byte files.</li> 222 <li>Pre-upload validation event.</li> 223 <li>Work-arounds for bugs in Flash and Browser.</li> 224 </ul> 225 </p> 226 227 <h2><a name="overview"></a>Overview</h2> 228 <h3>HTML Upload</h3> 229 <p> 230 The standard HTML upload input box provides a box and a button to the user for selecting a file. 231 The file is submitted with the form. The entire file must be uploaded before the next 232 page is displayed. No pre-upload validation can be made on the file (e.g., file size limits or valid extensions). 233 Very little feedback is given to the user while the file uploads. 234 </p> 235 <p> 236 The usage pattern for standard HTML uploads is simple, straight forward, and supported by nearly all browser. 237 </p> 238 <h3>SWFUpload</h3> 239 <p> 240 SWFUpload uses a Flash movie to handle file selection and upload. A customizable button is displayed by the 241 Flash movie that activates Flashes advanced file selection dialog window. 242 The file selection dialog is configured to allow the user select to a single file or multiple files. 243 The file types can be restricted so users only select the appropriate files (e.g., *.jpg;*.gif). 244 </p> 245 <p> 246 Once selected each file is validated and queued. As the file is uploaded by Flash 247 several JavaScript events are fired which the developer handles in order to update the page's UI allowing you to provide 248 upload status and error messages in real-time. 249 </p> 250 <p> 251 The uploaded file is submitted separately from the rest of the page and form. Each file is uploaded 252 individually keeping the server-side upload handling script simple. Since Flash is providing the upload 253 service the page does not have to be submitted or reloaded. The usage pattern for SWFUpload is more 254 like that of an AJAX application than that of a standard HTML form. The page's form will be processed 255 separately from the file upload. 256 </p> 257 <h2><a name="gettingstarted"></a>Getting Started</h2> 258 <p>SWFUpload is not a drag & drop upload control. It requires knowledge of JavaScript and the DOM. Several demos are available that 259 show some of the things SWFUpload is capable of and how to accomplish common tasks.</p> 260 261 <p>SWFUpload consists of 4 pieces:</p> 262 <ol> 263 <li>Initialization and Settings (JavaScript)</li> 264 <li>JavaScript library: SWFUpload.js</li> 265 <li>Flash Control: swfupload.swf</li> 266 <li>The Event Handlers (JavaScript)</li> 267 </ol> 268 269 <p>Most problems implementing SWFUpload are caused by incorrect settings, poorly built event handlers, Flash/Browser Bugs, or server configuration.</p> 270 271 <h3>Initialization and Settings</h3> 272 <p>SWFUpload must be initialized on the page. This is commonly done in the window.onload event. The SWFUpload constructor takes a settings object. 273 The settings object can be passed directly to the constructor as an object literal.</p> 274 <p>A reference to the initialized SWFUpload object should be kept as it is needed to start uploads and to control other aspects of SWFUpload.</p> 275 276 <p><strong>Example:</strong> Initializing SWFUpload with an object literal</p> 277 278 <code>var swfu; 279 280 window.onload = function () { 281 swfu = new SWFUpload({ 282 upload_url : "http://www.swfupload.org/upload.php", 283 flash_url : "http://www.swfupload.org/swfupload.swf", 284 file_size_limit : "20 MB" 285 }); 286 };</code> 287 288 <p><strong>Example:</strong> Initializing SWFUpload with a settings object stored in a variable</p> 289 290 <code>var swfu; 291 292 window.onload = function () { 293 var settings_object = { 294 upload_url : "http://www.swfupload.org/upload.php", 295 flash_url : "http://www.swfupload.org/swfupload.swf", 296 file_size_limit : "20 MB" 297 }; 298 299 swfu = new SWFUpload(settings_object); 300 };</code> 301 302 <h3>JavaScript library</h3> 303 <p>The JavaScript library file (swfupload.js) must be included on the page where the user will upload files.</p> 304 <p>Once a SWFUpload object has been created access to several functions become available which allow the developer to control SWFUpload.</p> 305 306 <p><strong>Example:</strong> Adding SWFUpload.js to a page</p> 307 308 <code> 309 <script type="text/javascript" src="http://www.swfupload.org/swfupload.js"></script> 310 </code> 311 312 <p><strong>Example:</strong> Initializing SWFUpload with the required settings.</p> 313 <code>var swfu = new SWFUpload({ 314 upload_url : "http://www.swfupload.org/upload.php", 315 flash_url : "http://www.swfupload.org/swfupload_f9.swf", 316 button_placeholder_id : "spanSWFUploadButton" 317 }); 318 </code> 319 320 <h3>Flash Control</h3> 321 <p>The SWFUpload JavaScript library dynamically loads the Flash Control (swfupload.swf).</p> 322 323 <p>The location of the Flash Control file must be provided in the SWFUpload settings object during setup.</p> 324 325 <p>The Flash Control is a small Flash Movie that handles file browsing, validation and upload. It appears on the page as 326 a button and communicates with JavaScript to notify the browser of upload status and other events.</p> 327 328 <h3>The Event Handlers</h3> 329 330 <p>Developers must create a set of JavaScript functions that handle SWFUpload events. These functions are called as different important events occur.</p> 331 332 <p>By handling the SWFUpload events developers can provide feedback regarding the upload progress, error messages, and upload completion. Developers should not 333 overwrite functions stored in SWFUpload.prototype. Instead create your own set of functions and pass references to them in the settings object.</p> 334 335 <p><strong>Example:</strong> SWFUpload event handlers and initialization.</p> 336 337 <code>// The uploadStart event handler. This function variable is assigned to upload_start_handler in the settings object 338 var myCustomUploadStartEventHandler = function (file) { 339 var continue_with_upload; 340 341 if (file.name === "the sky is blue") { 342 continue_with_upload = true; 343 } else { 344 continue_with_upload = false; 345 } 346 347 return continue_with_upload; 348 }; 349 350 // The uploadSuccess event handler. This function variable is assigned to upload_success_handler in the settings object 351 var myCustomUploadSuccessEventHandler = function (file, server_data, receivedResponse) { 352 alert("The file " + file.name + " has been delivered to the server. The server responded with " + server_data); 353 }; 354 355 // Create the SWFUpload Object 356 var swfu = new SWFUpload({ 357 upload_url : "http://www.swfupload.org/upload.php", 358 flash_url : "http://www.swfupload.org/swfupload.swf", 359 file_size_limit : "200 MB", 360 361 upload_start_handler : myCustomUploadStartEventHandler, 362 upload_success_handler : myCustomUploadSuccessEventHandler 363 });</code> 364 365 366 <h2><a name="javascriptobject"></a>SWFUpload JavaScript Object</h2> 367 368 <h3><a name="constructor"></a>Constructor</h3> 369 370 <p><span class="function">SWFUpload(<span class="parameter">settings object</span>)</span></p> 371 <p><b>Returns:</b> A SWFUpload instance</p> 372 <code>var swfupload_instance = new SWFUpload(settings_object);</code> 373 374 <h3><a name="globals"></a>Globals and Constants</h3> 375 <p> 376 Several globals and constants are associated with the SWFUpload object. These are useful for 377 advanced SWFUpload applications and for handling errors. These are considered read-only. 378 </p> 379 <h4><a name="instances"></a>SWFUpload.instances</h4> 380 <p>SWFUpload.instances is an object containing a reference to each SWFUpload instance loaded on a page. The Flash Player 381 relies on this object in order to call the correct event handlers. SWFUpload.instances indexes by the movieName property.</p> 382 383 <h4><a name="movieCount"></a>SWFUpload.movieCount</h4> 384 <p>SWFUpload.movieCount is a global that tracks the number on SWFUpload instances that have been created and helps to ensure each movie is 385 given a unique movieName.</p> 386 387 <h4><a name="queue_error"></a>SWFUpload.QUEUE_ERROR</h4> 388 <p>SWFUpload.QUEUE_ERROR is a simple object that contains Queue Error code constants. It is generally used to determine which error code was sent 389 in the fileQueueError event.</p> 390 391 <ul style="padding-left: 15px;"> 392 <li>QUEUE_LIMIT_EXCEEDED - indicates that the user has attempted to queue more files that is allowed by the settings. Once files have been updated and removed from the queue the user is again allowed to queue additional files.</li> 393 <li>FILE_EXCEEDS_SIZE_LIMIT - indicates the selected file is larger than is allwed by the file_size_limit.</li> 394 <li>ZERO_BYTE_FILE - indicates that the selected file is empty. The Flash Player cannot handle empty files and the file is rejected. Windows Shortcut files may also trigger this error.</li> 395 <li>INVALID_FILETYPE - The selected file's extension does not match a valid extension from the file_types setting. User's can circumvent the file_types restriction by manually entering a file name.</li> 396 </ul> 397 398 <h4><a name="upload_error"></a>SWFUpload.UPLOAD_ERROR</h4> 399 <p>SWFUpload.UPLOAD_ERROR is a simple object that contains Upload Error code constants. It is generally used to determine which error code was sent 400 in the uploadError event.</p> 401 402 <ul style="padding-left: 15px;"> 403 <li>HTTP_ERROR - The file upload was attempted but the server did not return a 200 status code.</li> 404 <li>MISSING_UPLOAD_URL - The upload_url setting was not set.</li> 405 <li>IO_ERROR - Some kind of error occurred while reading or transmitting the file. This most commonly occurs when the server unexpectedly terminates the connection.</li> 406 <li>SECURITY_ERROR - The upload violates a security restriction. This error is rare.</li> 407 <li>UPLOAD_LIMIT_EXCEEDED - The user has attempted to upload more files than is allowed by the file_upload_limit setting.</li> 408 <li>UPLOAD_FAILED - The attempt to initiate the upload caused an error. This error is rare.</li> 409 <li>SPECIFIED_FILE_ID_NOT_FOUND - A file ID was passed to startUpload but that file ID could not be found.</li> 410 <li>FILE_VALIDATION_FAILED - False was returned from the uploadStart event</li> 411 <li>FILE_CANCELLED - cancelUpload was called</li> 412 <li>UPLOAD_STOPPED - stopUpload was called.</li> 413 </ul> 414 415 <h4><a name="file_status"></a>SWFUpload.FILE_STATUS</h4> 416 <p>SWFUpload.FILE_STATUS is a simple object that contains File Status code constants. It can be used to check the file status property on the File object.</p> 417 418 <ul style="padding-left: 15px;"> 419 <li>QUEUED - indicates the this file is waiting in the queue.</li> 420 <li>IN_PROGRESS - indicates that this file is currently being uploaded.</li> 421 <li>ERROR - indicates that this file caused a queue or upload error.</li> 422 <li>COMPLETE - indicates that this file was successfully transmitted to the server.</li> 423 <li>CANCELLED - indicates that this file was cancelled by a call to cancelUpload.</li> 424 </ul> 425 426 427 <h4><a name="button_action"></a>SWFUpload.BUTTON_ACTION</h4> 428 <p>SWFUpload.BUTTON_ACTION is a simple object that contains button action code constants. It is used with the button_action setting to set the behavior of the Flash based file dialog button.</p> 429 430 <ul style="padding-left: 15px;"> 431 <li>SELECT_FILE - when the Flash button is clicked the file dialog will only allow a single file to be selected.</li> 432 <li>SELECT_FILES - when the Flash button is clicked the file dialog allows multiple files to be selected.</li> 433 <li>START_UPLOAD - while the Flash button is clicked the first queued file will be uploaded.</li> 434 </ul> 435 436 <h4><a name="button_cursor"></a>SWFUpload.CURSOR</h4> 437 <p>SWFUpload.CURSOR is a simple object that contains button cursor code constants. It is used with the button_cursor setting to set the mouse cursor when hovering over the Flash button.</p> 438 439 <ul style="padding-left: 15px;"> 440 <li>ARROW - the cursor will display as an arrow pointer</li> 441 <li>HAND - the cursor will display has a finger/hand pointer</li> 442 </ul> 443 444 <h4><a name="button_window_mode"></a>SWFUpload.WINDOW_MODE</h4> 445 <p>SWFUpload.WINDOW_MODE is a simple object that contains button movie wmode parameter constants. It is used to tell the browser how to display the Flash Movie.</p> 446 <p>The some WINDOW_MODE/WMODE settings can cause problems in some browsers. See the <a href="#knownissues">Known Issues</a>.</p> 447 448 <ul style="padding-left: 15px;"> 449 <li>WINDOW is the default mode. The movie is drawn over the top of all other elements on the page.</li> 450 <li>OPAQUE causes the movie to be rendered in the page allowing other elements to cover up the button.</li> 451 <li>TRANSPARENT the button background is rendered transparent allowing html elements under the button to show through.</li> 452 </ul> 453 454 <h3><a name="properties"></a>Properties</h3> 455 <p> 456 The following list of properties is intended for your use as described below. Using other properties or 457 writing to read-only properties can cause SWFUpload to malfunction. 458 </p> 459 <h4><a name="customSettings"></a>customSettings (read/write)</h4> 460 <p> 461 The customSettings property is an empty JavaScript object that can be used to store data associated with 462 an instance of SWFUpload. The customSettings object contents can be initialized using the custom_settings setting. 463 </p> 464 465 <p><strong>Example:</strong></p> 466 <code>// Initialize SWFUpload with some custom settings 467 var swfu = new SWFUpload({ 468 custom_settings : { 469 custom_setting_1 : "custom_setting_value_1", 470 custom_setting_2 : "custom_setting_value_2", 471 custom_setting_n : "custom_setting_value_n", 472 } 473 }); 474 475 swfu.customSettings.custom_setting_1 = "custom_setting_value_1"; // Change an existing custom setting 476 swfu.customSettings.myNewCustomSetting = "new custom setting value"; // Add a new custom setting 477 478 // Overwrite the customSettings with a completely new object 479 swfu.customSettings = { 480 custom_setting_A : "custom_setting_value_A", 481 custom_setting_B : "custom_setting_value_B" 482 }; 483 </code> 484 485 <p>The values stored in the customSettings object can then be easily accessed in the event handlers: </p> 486 487 <code> 488 function uploadSuccess(file, serverData, receivedResponse) { 489 if (this.customSettings.custom_setting_A === true) { 490 alert("Checked the custom setting!"); 491 } 492 } 493 </code> 494 495 <h4><a name="movieName"></a>movieName</h4> 496 <p>Contains the unique movie name of the SWFUpload instance. This value is passed to Flash and is used to facilitate Flash-to-JavaScript communication. 497 This value is used to index the instance in the SWFUpload.instances array. You should not change the movieName value.</p> 498 499 <h3><a name="methods"></a>Methods</h3> 500 <p>The following methods are used to operate SWFUpload. Some are bound to DOM element click event handlers and others are used inside 501 SWFUpload event handlers.</p> 502 503 <h4><a name="addSetting"></a>object addSetting(<span class="parameter">setting_name</span>, <span class="parameter">value</span>, <span class="parameter">default_value</span>)</h4> 504 <p><strong>Deprecated</strong> The addSetting function sets a setting value. If the value is undefined then the default_value is used. The function is used by SWFUpload 505 during initialization. Using addSetting to update a setting will not change the setting in the Flash Control.</p> 506 <p>addSetting returns the value that was stored in the setting.</p> 507 508 <h4><a name="getSetting"></a>object getSetting(<span class="parameter">setting_name</span>)</h4> 509 <p><strong>Deprecated</strong> The getSetting function retrieves the value of a setting. If the setting is not found an empty string is returned.</p> 510 511 <h4><a name="retrieveSetting"></a>object retrieveSetting(<span class="parameter">setting_value</span>, <span class="parameter">default_value</span>)</h4> 512 <p><strong>Removed in v2.1.0</strong> The retrieveSetting function is similar to the addSetting function except it does not modify the internal settings object. retrieveSetting 513 returns the setting_value unless it is undefined in which case it returns the default_value</p> 514 <p>This is a utility function.</p> 515 516 <h4><a name="destroy"></a>bool destroy()</h4> 517 <p><strong>Added in v2.1.0</strong></p> 518 <p>Removes the SWF DOM elements and then destroys SWFUpload internal references. Used for removing a SWFUpload instance from a page. It also attempts to prevent memory leaks in IE.</p> 519 <p>Returns true if the elements were removed successfully. Returns false if any error occurs leaving the SWFUpload instance in an inconsistent state.</p> 520 521 <h4><a name="displayDebugInfo"></a>void displayDebugInfo()</h4> 522 <p>The displayDebugInfo outputs SWFUpload settings using the debug event. This function is automatically called after initialization if the debug setting is 'true'</p> 523 524 <h4><a name="selectFile"></a>void selectFile()</h4> 525 <p><strong>Deprecated. Not compatible with Flash Player 10.</strong></p> 526 <p>selectFile causes the Flash Control to display a File Selection Dialog window. A single file may be selected from the Dialog window.</p> 527 <p>Calling selectFile begins the File Event Chain.</p> 528 529 <h4><a name="selectFiles"></a>void selectFiles()</h4> 530 <p><strong>Deprecated. Not compatible with Flash Player 10.</strong></p> 531 <p>selectFiles causes the Flash Control to display a File Selection Dialog window. A multiple files may be selected from the Dialog window.</p> 532 <p>Calling selectFiles begins the File Event Chain.</p> 533 534 <h4><a name="startUpload"></a>void startUpload(<span class="parameter">file_id</span>)</h4> 535 <p>startUpload causes the file specified by the file_id parameter to start the upload process. If the file_id parameter is omitted or undefined then the first file in the queue is uploaded.</p> 536 537 <p>Calling startUpload begins the Upload Event Chain.</p> 538 539 <h4><a name="cancelUpload"></a>void cancelUpload(<span class="parameter">file_id</span>, <span class="parameter">trigger_error_event</span>)</h4> 540 541 <p>cancelUpload cancels the file specified by the file_id parameter. The file is then removed from the queue.</p> 542 <p>If the file_id parameter is omitted or undefined then the first file in the queue is cancelled.</p> 543 <p>The trigger_error_event is optional. If set to false the uploadError event is suppressed.</p> 544 545 <h4><a name="stopUpload"></a>void stopUpload()</h4> 546 547 <p>stopUpload stops and re-queues the file currently being uploaded.</p> 548 <p>After the uploading file is stopped the uploadError event is fired. If no file is being uploaded then nothing happens and no event is fired.</p> 549 550 <h4><a name="getStats"></a>object getStats()</h4> 551 <p>Retrieves the stats object.</p> 552 553 <h4><a name="setStats"></a>void setStats(<span class="parameter">stats_object</span>)</h4> 554 <p>The Stats Object may be modified. This is useful if you wish to change the number of successful uploads or upload errors after an upload 555 has completed.</p> 556 557 <h4><a name="getFile"></a>object getFile(<span class="parameter">file_id</span>|<span class="parameter">index</span>)</h4> 558 <p>getFile is used to retrieve a File Object from the queue. The file retrieved by passing in a file id (the id property from a file object) or a file index (the index property from a file object).</p> 559 <p>When getting a file by file_id only files in the queue are available. If the file is not found null is returned.</p> 560 <p>When getting a file by index all queued (or files that generated a queue error) are available. If the index is out of range then null is returned</p> 561 562 <h4><a name="addPostParam"></a>void addPostParam(<span class="parameter">name</span>, <span class="parameter">value</span>)</h4> 563 <p>The addPostParam function adds a name/value pair that will be sent in the POST for all files uploaded.</p> 564 <p>The name/value pair will also appear in the post_params setting.</p> 565 566 <h4><a name="removePostParam"></a>void removePostParam(<span class="parameter">name</span>)</h4> 567 <p>The removePostParam function removes a name/value pair from the values sent with the POST for file uploads.</p> 568 <p>The name/value pair is also be removed from the post_params setting.</p> 569 570 <h4><a name="addFileParam"></a>bool addFileParam(<span class="parameter">file_id</span>, <span class="parameter">name</span>, <span class="parameter">value</span>)</h4> 571 <p>The addFileParam function adds a name/value pair that will be sent in the POST with the file specified by the file_id parameter.</p> 572 <p>The name/value pair will only be sent with the file it is added to. To send name/value pairs with all uploads use the post_param setting.</p> 573 574 <h4><a name="removeFileParam"></a>bool removeFileParam(<span class="parameter">file_id</span>, <span class="parameter">name</span>)</h4> 575 <p>The removeFileParam function removes a name/value pair from a file upload that was added using addFileParam.</p> 576 <p>If the name/value pair was not found then 'false' is returned.</p> 577 578 <h4><a name="setUploadURL"></a>void setUploadURL(<span class="parameter">url</span>)</h4> 579 <p>Dynamically modifies the upload_url setting.</p> 580 581 <h4><a name="setPostParams"></a>void setPostParams(<span class="parameter">param_object</span>)</h4> 582 <p>Dynamically modifies the post_params setting. Any previous values are over-written. The param_object should be a simple JavaScript object. All names and values must be strings.</p> 583 584 <h4><a name="setFileTypes"></a>void setFileTypes(<span class="parameter">types</span>, <span class="parameter">description</span>)</h4> 585 <p>Dynamically updates the file_types and file_types_description settings. Both parameters are required.</p> 586 587 <h4><a name="setFileSizeLimit"></a>void setFileSizeLimit(<span class="parameter">file_size_limit</span>)</h4> 588 <p>Dynamically modifies the file_size_limit setting. This applies to all future files that are queued. The file_size_limit parameter will accept a unit. Valid units are B, KB, MB, and GB. The default unit is KB.</p> 589 <p>Examples: 2147483648 B, 2097152, 2097152KB, 2048 MB, 2 GB</p> 590 591 <h4><a name="setFileUploadLimit"></a>void setFileUploadLimit(<span class="parameter">file_upload_limit</span>)</h4> 592 <p>Dynamically modifies the file_upload_limit setting. The special value zero (0) indicates "no limit".</p> 593 594 <h4><a name="setFileQueueLimit"></a>void setFileQueueLimit(<span class="parameter">file_queue_limit</span>)</h4> 595 <p>Dynamically modifies the file_queue_limit setting. The special value zero (0) indicates "no limit".</p> 596 597 <h4><a name="setFilePostName"></a>void setFilePostName(<span class="parameter">file_post_name</span>)</h4> 598 <p>Dynamically modifies the file_post_name setting. The Linux Flash Player ignores this setting.</p> 599 600 <h4><a name="setUseQueryString"></a>void setUseQueryString(<span class="parameter">use_query_string</span>)</h4> 601 <p>Dynamically modifies the use_query_string setting. When true this forces SWFUpload to send post parameters on the query string rather than in the post. The use_query_string parameter should be a boolean true or false.</p> 602 603 <h4><a name="setDebugEnabled"></a>void setDebugEnabled(<span class="parameter">debug_enabled</span>)</h4> 604 <p>Dynamically enables or disables debug output. The debug_enabled parameter should be a boolean true or false.</p> 605 606 <h4><a name="setButtonImageURL"></a>void setButtonImageURL(<span class="parameter">url</span>)</h4> 607 <p>Dynamically change the image used in the Flash Button. The image url must be relative to the swfupload.swf file, an absolute path (e.g., starting with a /), or 608 a fully qualified url (e.g., http://www.swfupload.org/buttonImage.png). Any image format supported by Flash can be loaded. The most notable formats are jpg, gif, and png.</p> 609 610 <p>The button image is expected to be a button sprite (or a single image file with several images stacked together). The image will be used to represent 611 all the button states by moving the image up or down to only display the needed portion. These states include: normal, hover, click, disabled. See the sample button images.</p> 612 613 <h4><a name="setButtonDimensions"></a>void setButtonDimensions(<span class="parameter">width</span>, <span class="parameter">height</span>)</h4> 614 <p>Dynamically change the Flash button's width and height. The values should be numeric and should not include any units. The height value should 615 be 1/4th of the total button image height so the button state sprite images can be displayed correctly</p> 616 617 <h4><a name="setButtonText"></a>void setButtonText(<span class="parameter">text</span>)</h4> 618 <p>Sets the text that should be displayed over the Flash button. Text that is too large and overflows the button size will be clipped.</p> 619 <p>The text can be styled using HTML supported by the Flash Player (<a target="_blank" href="http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/text/TextField.html#htmlText">Adobe Documentation</a>)</p> 620 621 <h4><a name="setButtonTextStyle"></a>void setButtonTextStyle(<span class="parameter">css_style_text</span>)</h4> 622 <p>Sets the CSS styles used to style the Flash Button Text. CSS should be formatted according to the Flash Player documentation (<a target="_blank" href="http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/text/StyleSheet.html">Adobe Documentation</a>)</p> 623 <p>Style classes defined here can then be referenced by HTML in the button_text setting.</p> 624 625 <h4><a name="setButtonTextPadding"></a>void setButtonTextPadding(<span class="parameter">left</span>, <span class="parameter">top</span>)</h4> 626 <p>Sets the top and left padding of the Flash button text. The values may be negative.</p> 627 628 <h4><a name="setButtonDisabled"></a>void setButtonDisabled(<span class="parameter">isDisabled</span>)</h4> 629 <p>When 'true' changes the Flash Button state to disabled and ignores any clicks.</p> 630 631 <h4><a name="setButtonAction"></a>void setButtonAction(<span class="parameter">buttonAction</span>)</h4> 632 <p>Sets the action taken when the Flash button is clicked. Valid action values are taken from the BUTTON_ACTION constants.</p> 633 634 <h4><a name="setButtonCursor"></a>void setButtonCursor(<span class="parameter">buttonCursor</span>)</h4> 635 <p>Sets the mouse cursor shown when hovering over the Flash button. Valid cursor values are taken from the CURSOR constants.</p> 636 637 638 639 <h3><a name="events"></a>Events</h3> 640 <p>SWFUpload fires various events during its operation. These events can be handled by the developer to update the UI, change behavior, or report errors.</p> 641 <p>All SWFUpload events are called in the context of a SWFUpload instance. This means that the 'this' object refers to the SWFUpload instance that 642 fired the event.</p> 643 644 <p>SWFUpload events should be set only by assigning the event handler function in the settings object during object initialization. You should not override the 645 internal functions belonging to the SWFUpload.prototype object.</p> 646 647 <p>During a file upload events are usually called in this order (the Upload Event Chain):</p> 648 <ul> 649 <li>uploadStart</li> 650 <li>uploadProgress (called over and over again as the file uploads)</li> 651 <li>uploadError (called if some kind of error occurs, the file is canceled or stopped)</li> 652 <li>uploadSuccess (the upload finished successfully, data returned from the server is available)</li> 653 <li>uploadComplete (the upload is complete and SWFUpload is ready to start the next file)</li> 654 </ul> 655 656 <h4><a name="flashReady"></a><span class="function">flashReady()</span></h4> 657 <p>flashReady is an internal event that should not be overwritten. It is called by the Flash Control to notify SWFUpload that the Flash 658 movie has loaded and is ready to accept commands.</p> 659 660 <h4><a name="swfUploadLoaded"></a><span class="function">swfUploadLoaded()</span></h4> 661 <p>The swfUploadLoaded event is fired by flashReady. It is settable. swfUploadLoaded is called to let you know that it is safe to call SWFUpload methods.</p> 662 663 <h4><a name="fileDialogStart"></a><span class="function">fileDialogStart(<span class="parameter"></span>)</span></h4> 664 <p>fileDialogStart is fired after selectFile for selectFiles is called. This event is fired immediately before the File Selection Dialog 665 window is displayed. However, the event may not execute until after the Dialog window is closed.</p> 666 667 <h4><a name="fileQueued"></a><span class="function">fileQueued(<span class="parameter">file object</span>)</span></h4> 668 <p>The fileQueued event is fired for each file that is queued after the File Selection Dialog window is closed.</p> 669 670 <h4><a name="fileQueueError"></a><span class="function">fileQueueError(<span class="parameter">file object</span>, <span class="parameter">error code</span>, <span class="parameter">message</span>)</span></h4> 671 <p>The fileQueueError event is fired for each file that was not queued after the File Selection Dialog window is closed. A file may not be queued 672 for several reasons such as, the file exceeds the file size, the file is empty or a file or queue limit has been exceeded.</p> 673 <p>The reason for the queue error is specified by the error code parameter. The error code corresponds to a SWFUpload.QUEUE_ERROR constant.</p> 674 675 <h4><a name="fileDialogComplete"></a><span class="function">fileDialogComplete(<span class="parameter">number of files selected</span>, <span class="parameter">number of files queued</span>, <span class="parameter">total number of files in the queued</span>)</span></h4> 676 <p>The fileDialogComplete event fires after the File Selection Dialog window has been closed and all the selected files have been processed. The 'number of files queued' argument indicates the number of files that were queued from the dialog selection (as opposed to the number of files in the queue).</p> 677 <p>If you want file uploading to begin automatically this is a good place to call 'this.startUpload()'</p> 678 679 <h4><a name="uploadStart"></a><span class="function">uploadStart(<span class="parameter">file object</span>)</span></h4> 680 <p>uploadStart is called immediately before the file is uploaded. This event provides an opportunity to perform any last minute validation, add post 681 params or do any other work before the file is uploaded.</p> 682 683 <p>The upload can be cancelled by returning 'false' from uploadStart. If you return 'true' or do not return any value then the upload proceeds. Returning 684 'false' will cause an uploadError event to fired.</p> 685 686 <h4><a name="uploadProgress"></a><span class="function">uploadProgress(<span class="parameter">file object</span>, <span class="parameter">bytes complete</span>, <span class="parameter">total bytes</span>)</span></h4> 687 <p>The uploadProgress event is fired periodically by the Flash Control. This event is useful for providing UI updates on the page.</p> 688 <p><strong>Note:</strong> The Linux Flash Player fires a single uploadProgress event after the entire file has been uploaded. This is a bug in 689 the Linux Flash Player that we cannot work around.</p> 690 691 <h4><a name="uploadError"></a><span class="function">uploadError(<span class="parameter">file object</span>, <span class="parameter">error code</span>, <span class="parameter">message</span>)</span></h4> 692 <p>The uploadError event is fired any time an upload is interrupted or does not complete successfully. The error code parameter indicates the type of error 693 that occurred. The error code parameter specifies a constant in SWFUpload.UPLOAD_ERROR.</p> 694 <p>Stopping, Cancelling or returning 'false' from uploadStart will cause uploadError to fire. Upload error will not fire for files that are cancelled 695 but still waiting in the queue.</p> 696 697 <h4><a name="uploadSuccess"></a><span class="function">uploadSuccess(<span class="parameter">file object</span>, <span class="parameter">server data</span>, <span class="parameter">received response</span>)</span></h4> 698 <p>uploadSuccess is fired when the entire upload has been transmitted and the server returns a HTTP 200 status code. Any data outputted by the server is available 699 in the server data parameter.</p> 700 701 <p> 702 Due to some bugs in the Flash Player the server response may not be acknowledged and no uploadSuccess event is fired by Flash. In this case the 703 assume_success_timeout setting is checked to see if enough time has passed to fire uploadSuccess anyway. In this case the received response parameter will be false. 704 </p> 705 706 <p> 707 The http_success setting allows uploadSuccess to be fired for HTTP status codes other than 200. In this case no server data is available from the Flash Player. 708 </p> 709 710 <p>At this point the upload is not yet complete. Another upload cannot be started from uploadSuccess.</p> 711 712 <h4><a name="uploadComplete"></a><span class="function">uploadComplete(<span class="parameter">file object</span>)</span></h4> 713 <p>uploadComplete is always fired at the end of an upload cycle (after uploadError or uploadSuccess). At this point the upload is complete and 714 another upload can be started.</p> 715 <p>If you want the next upload to start automatically this is a good place to call this.uploadStart(). Use caution when calling uploadStart inside 716 the uploadComplete event if you also have code that cancels all the uploads in a queue.</p> 717 718 <h4><a name="debug"></a><span class="function">debug(<span class="parameter">message</span>)</span></h4> 719 <p>The debug event is called by the SWFUpload library and the Flash Control when the debug setting is set to 'true'. If the debug 720 event is not overridden then SWFUpload writes debug messages to the SWFUpload console (a text box dynamically added to the end of the page body).</p> 721 722 <h3><a name="utility"></a>SWFUpload Utility Objects</h3> 723 <h4><a name="settingsobject"></a>Settings object</h4> 724 <p>The settings object is a JavaScript object that provides the settings for the SWFUpload instance. <strong>Each setting should only appear once.</strong> Many settings 725 are optional and provide suitable default values if omitted. See the setting details for required and optional settings.</p> 726 <p><strong>Example:</strong></p> 727 <code>{ 728 upload_url : "http://www.swfupload.org/upload.php", 729 flash_url : "http://www.swfupload.org/swfupload.swf", 730 731 file_post_name : "Filedata", 732 post_params : { 733 "post_param_name_1" : "post_param_value_1", 734 "post_param_name_2" : "post_param_value_2", 735 "post_param_name_n" : "post_param_value_n" 736 }, 737 use_query_string : false, 738 requeue_on_error : false, 739 http_success : [201, 202], 740 assume_success_timeout : 0, 741 file_types : "*.jpg;*.gif", 742 file_types_description: "Web Image Files", 743 file_size_limit : "1024", 744 file_upload_limit : 10, 745 file_queue_limit : 2, 746 747 debug : false, 748 749 prevent_swf_caching : false, 750 preserve_relative_urls : false, 751 752 button_placeholder_id : "element_id", 753 button_image_url : "http://www.swfupload.org/button_sprite.png", 754 button_width : 61, 755 button_height : 22, 756 button_text : "<b>Click</b> <span class="redText">here</span>", 757 button_text_style : ".redText { color: #FF0000; }", 758 button_text_left_padding : 3, 759 button_text_top_padding : 2, 760 button_action : SWFUpload.BUTTON_ACTION.SELECT_FILES, 761 button_disabled : false, 762 button_cursor : SWFUpload.CURSOR.HAND, 763 button_window_mode : SWFUpload.WINDOW_MODE.TRANSPARENT, 764 765 swfupload_loaded_handler : swfupload_loaded_function, 766 file_dialog_start_handler : file_dialog_start_function, 767 file_queued_handler : file_queued_function, 768 file_queue_error_handler : file_queue_error_function, 769 file_dialog_complete_handler : file_dialog_complete_function, 770 upload_start_handler : upload_start_function, 771 upload_progress_handler : upload_progress_function, 772 upload_error_handler : upload_error_function, 773 upload_success_handler : upload_success_function, 774 upload_complete_handler : upload_complete_function, 775 debug_handler : debug_function, 776 777 custom_settings : { 778 custom_setting_1 : "custom_setting_value_1", 779 custom_setting_2 : "custom_setting_value_2", 780 custom_setting_n : "custom_setting_value_n", 781 } 782 }</code> 783 <h4><a name="settingsdescription"></a>Settings Description</h4> 784 785 <h5>upload_url</h5> 786 <p>The upload_url setting accepts a full, absolute, or relative target URL for the uploaded file. Relative URLs should be relative to document. The upload_url should be in the same domain as the Flash Control for best compatibility.</p> 787 <p>If the preserve_relative_urls setting is false SWFUpload will convert the relative URL to an absolute URL to avoid the URL being interpreted differently by the Flash Player on different platforms. If you disable SWFUploads conversion of the URL relative URLs should be relative to the swfupload.swf file.</p> 788 789 <h5>file_post_name</h5> 790 <p>The file_post_name allows you to set the value name used to post the file. This is not related to the file name. 791 The default value is 'Filedata'. For maximum compatibility it is recommended that the default value is used.</p> 792 793 <h5>post_params</h5> 794 <p> 795 The post_params setting defines the name/value pairs that will be posted with each uploaded file. This setting accepts a simple JavaScript object. 796 Multiple post name/value pairs should be defined as demonstrated in the sample settings object. Values must be either strings or numbers (as interpreted by the JavaScript typeof function). 797 </p> 798 <p>Note: Flash Player 8 does not support sending additional post parameters. SWFUpload will automatically send the post_params as part of the query string.</p> 799 800 <h5>use_query_string</h5> 801 <p> 802 The use_query_string setting may be true or false. This value indicates whether SWFUpload should send the post_params and file params on the query string or the post. This setting was introduced in SWFUpload v2.1.0. 803 </p> 804 805 <h5>preserve_relative_urls</h5> 806 <p>A boolean value that indicates whether SWFUpload should attempt to convert relative URLs used by the Flash Player to absolute URLs. If set to true SWFUpload will not modify any URLs. The default value is false.</p> 807 808 <h5>requeue_on_error</h5> 809 <p> 810 The requeue_on_error setting may be true or false. When this setting is true any files that has an 811 uploadError (excluding fileQueue errors and the FILE_CANCELLED uploadError) is returned to the front of 812 the queue rather than being discarded. The file can be uploaded again if needed. To remove the file from the 813 queue the cancelUpload method must be called. 814 </p> 815 <p> 816 All the events associated with a failed upload are still called and so the requeuing the failed upload can conflict 817 with the Queue Plugin (or custom code that uploads the entire queue). Code that automatically uploads the next file 818 in the queue will upload the failed file over and over again if care is not taken to allow the failing upload to be 819 cancelled. 820 </p> 821 <p> 822 This setting was introduced in SWFUpload v2.1.0. 823 </p> 824 825 <h5>http_success</h5> 826 <p> 827 An array that defines the HTTP Status Codes that will trigger success. 200 is always a success. Also, only the 200 status code provides the serverData. 828 </p> 829 <p> 830 When returning and accepting an HTTP Status Code other than 200 it is not necessary for the server to return content. 831 </p> 832 833 <h5>assume_success_timeout</h5> 834 <p> 835 The number of seconds SWFUpload should wait for Flash to detect the server's response after the file has finished uploading. This setting allows you to 836 work around the Flash Player bugs where long running server side scripts causes Flash to ignore the server response or the Mac Flash Player bug that ignores 837 server responses with no content. 838 </p> 839 <p> 840 Testing has shown that Flash will ignore server responses that take longer than 30 seconds after the last uploadProgress event. 841 </p> 842 <p> 843 A timeout of zero (0) seconds disables this feature and is the default value. SWFUpload will wait indefinitely for the Flash Player to trigger the uploadSuccess event. 844 </p> 845 846 <h5>file_types</h5> 847 <p> 848 The file_types setting accepts a semi-colon separated list of file extensions that are allowed to be selected by the user. Use '*.*' to allow all file types. 849 </p> 850 851 <h5>file_types_description</h5> 852 <p> 853 A text description that is displayed to the user in the File Browser dialog. 854 </p> 855 856 <h5>file_size_limit</h5> 857 <p> 858 The file_size_limit setting defines the maximum allowed size of a file to be uploaded. This setting accepts a value and unit. 859 Valid units are B, KB, MB and GB. If the unit is omitted default is KB. A value of 0 (zero) is interpreted as unlimited. 860 </p> 861 <p> 862 Note: This setting only applies to the user's browser. It does not affect any settings or limits on the web server. 863 </p> 864 865 <h5>file_upload_limit</h5> 866 <p> 867 Defines the number of files allowed to be uploaded by SWFUpload. This setting also sets the upper bound of the file_queue_limit 868 setting. Once the user has uploaded or queued the maximum number of files she will no longer be able to queue additional files. The 869 value of 0 (zero) is interpreted as unlimited. Only successful uploads (uploads the trigger the uploadSuccess event) are counted 870 toward the upload limit. The setStats function can be used to modify the number of successful uploads. 871 </p> 872 <p>Note: This value is not tracked across pages and is reset when a page is refreshed. File quotas should be managed by the web server.</p> 873 874 <h5>file_queue_limit</h5> 875 <p> 876 Defines the number of unprocessed files allowed to be simultaneously queued. Once a file is uploaded, errored, or cancelled a new 877 files can be queued in its place until the queue limit has been reached. If the upload limit (or remaining uploads allowed) is less 878 than the queue limit then the lower number is used. 879 </p> 880 881 <h5>flash_url</h5> 882 <p> 883 The full, absolute, or relative URL to the Flash Control swf file. This setting cannot be changed once the SWFUpload has been 884 instantiated. Relative URLs are relative to the page URL. 885 </p> 886 887 <h5>flash_width</h5> 888 <p> 889 <strong>(Removed in v2.1.0)</strong> Defines the width of the HTML element that contains the flash. Some browsers do not function correctly if this setting is less than 1 px. 890 This setting is optional and has a default value of 1px. 891 </p> 892 893 <h5>flash_height</h5> 894 <p> 895 <strong>(Removed in v2.1.0)</strong> Defines the height of the HTML element that contains the flash. Some browsers do not function correctly if this setting is less than 1 px. 896 This setting is optional and has a default value of 1px. 897 </p> 898 899 <h5>flash_color</h5> 900 <p> 901 <strong>Removed in v2.2.0</strong> This setting sets the background color of the HTML element that contains the flash. The default value is '#FFFFFF'. 902 </p> 903 <p> 904 Note: This setting may not be effective in "skinning" 1px flash element in all browsers. 905 </p> 906 907 <h5>prevent_swf_caching</h5> 908 <p> 909 <strong>Added in v2.2.0</strong> This boolean setting indicates whether a random value should be added to the Flash URL in an attempt to 910 prevent the browser from caching the SWF movie. This works around a bug in some IE-engine based browsers. 911 </p> 912 <p>Note: The algorithm for adding the random number to the URL is dumb and cannot handle URLs that already have some parameters.</p> 913 914 <h5>debug</h5> 915 <p>A boolean value that defines whether the debug event handler should be fired.</p> 916 917 <h5>button_placeholder_id</h5> 918 <p><strong>(Added in v2.2.0)</strong> This required setting sets the ID of DOM element that will be <em>replaced</em> by the Flash Button. This setting overrides the button_placeholder setting. The Flash button can be styled using the CSS class 'swfupload'.</p> 919 920 <h5>button_placeholder</h5> 921 <p><strong>(Added in v2.2.0)</strong> This required setting sets the DOM element that will be <em>replaced</em> by the Flash Button. This setting is only applied if the button_placeholder_id is not set. The Flash button can be styled using the CSS class 'swfupload'.</p> 922 923 <h5>button_image_url</h5> 924 <p><strong>(Added in v2.2.0)</strong> Fully qualified, absolute or relative URL to the image file to be used as the Flash button. Any Flash supported image file format can be used (another SWF file or gif, jpg, or png).</p> 925 <p>This URL is affected by the preserve_relative_urls setting and should follow the same rules as the upload_url setting.</p> 926 927 <p>The button image is treated as a sprite. There are 4 button states that must be represented by the button image. Each button state image 928 should be stacked above the other in this order: normal, hover, down/click, disabled.</p> 929 930 <h5>button_width</h5> 931 <p><strong>(Added in v2.2.0)</strong> A number defining the width of the Flash button.</p> 932 933 <h5>button_height</h5> 934 <p><strong>(Added in v2.2.0)</strong> A number defining the height of the Flash button. This value should be 1/4th of the height or 935 the button image.</p> 936 937 <h5>button_text</h5> 938 <p><strong>(Added in v2.2.0)</strong> Plain or HTML text that is displayed over the Flash button. HTML text can be further styled using CSS 939 classes and the button_text_style setting. See <a target="_blank" href="http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/text/TextField.html#htmlText">Adobe's Flash documentation</a> for details.</p> 940 941 <h5>button_text_style</h5> 942 <p><strong>(Added in v2.2.0)</strong> CSS style string that defines how the button_text is displayed. 943 See <a target="_blank" href="http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/text/StyleSheet.html">Adobe's Flash documentation</a> for details.</p> 944 945 <h5>button_text_top_padding</h5> 946 <p><strong>(Added in v2.2.0)</strong> Used to vertically position the Flash button text. Negative values may be used.</p> 947 948 <h5>button_text_left_padding</h5> 949 <p><strong>(Added in v2.2.0)</strong> Used to horizontally position the Flash button text. Negative values may be used.</p> 950 951 <h5>button_action</h5> 952 <p><strong>(Added in v2.2.0)</strong> Defines the action taken when the Flash button is clicked. Valid action values can be found in the swfupload.js file under the BUTTON_ACTION object.</p> 953 954 <h5>button_disabled</h5> 955 <p><strong>(Added in v2.2.0)</strong> A boolean value that sets whether the Flash button is in the disabled state. When in the disabled state the button will not execute any actions.</p> 956 957 <h5>button_cursor</h5> 958 <p><strong>(Added in v2.2.0)</strong> Used to define what type of mouse cursor is displayed when hovering over the Flash button.</p> 959 960 <h5>button_window_mode</h5> 961 <p><strong>(Added in v2.2.0)</strong> Sets the WMODE property of the Flash Movie. Valid values are available in the SWFUpload.WINDOW_MODE constants.</p> 962 963 <h5>custom_settings</h5> 964 <p> 965 The custom_settings setting allows developers to safely attach additional information to a SWFUpload instance without 966 worrying about affecting internal SWFUpload values or changes in new SWFUpload versions. This setting accepts a JavaScript 967 object. 968 </p> 969 <p> 970 Once instantiated the custom settings are accessed in the 'customSettings' property of the SWFUpload instance. 971 </p> 972 <code>var swfu = new SWFUpload({ 973 custom_settings : { 974 "My Setting" : "This is my setting", 975 myothersetting : "This is my other setting", 976 integer_setting : 100, 977 a_dom_setting : document.getElementById("some_element_id") 978 } 979 }); 980 981 var my_setting = swfu.customSettings["My Setting"]); 982 swfu.customSettings["My Setting"] = "This is my new setting"; 983 swfu.customSetting.myothersetting = "another new value"; 984 swfu.customSetting.integer_setting += 25; 985 swfu.customSetting["a_dom_setting"].style.visibility = "hidden";</code> 986 987 <h5>Event Handlers</h5> 988 <p> 989 The remaining settings define the event handlers called by SWFUpload during its operation. JavaScript functions should 990 be defined to handle these events as needed. 991 </p> 992 993 994 995 <h4><a name="fileobject"></a>File Object</h4> 996 <p>The file object is passed to several event handlers. It contains information about the file. Some operating systems do not fill in all the values (this 997 is especially true for the createdate and modificationdate values).</p> 998 <code>{ 999 id : string, // SWFUpload file id, used for starting or cancelling and upload 1000 index : number, // The index of this file for use in getFile(i) 1001 name : string, // The file name. The path is not included. 1002 size : number, // The file size in bytes 1003 type : string, // The file type as reported by the client operating system 1004 creationdate : Date, // The date the file was created 1005 modificationdate : Date, // The date the file was last modified 1006 filestatus : number, // The file's current status. Use SWFUpload.FILE_STATUS to interpret the value. 1007 1008 }</code> 1009 1010 <h4><a name="statsobject"></a>Stats Object</h4> 1011 <p>The Stats object provides information about the upload queue.</p> 1012 <p>That stats object contains the following properties:</p> 1013 <code>{ 1014 in_progress : number // 1 or 0 indicating if a file upload is currently in progress 1015 files_queued : number // The number of files currently in the queue 1016 successful_uploads : number // The number of files that have uploaded successfully (caused uploadSuccess to be fired) 1017 upload_errors : number // The number of files that have had errors (excluding cancelled files) 1018 upload_cancelled : number // The number of files that have been cancelled 1019 queue_errors : number // The number of files that caused fileQueueError to be fired 1020 }</code> 1021 <p>All these values can be updated using setStats() except the <em>in_progress</em> and <em>files_queued</em> values.</p> 1022 1023 <h2><a name="plugins"></a>SWFUpload Plug-ins</h2> 1024 1025 <p>With SWFUpload v2.0 several plugins have been introduced. They are provided to help with common tasks associated with implementing SWFUpload.</p> 1026 <p>Currently most of the documentation for using the plugins is contained in the plugin JavaScript file.</p> 1027 1028 <h3>SWFObject</h3> 1029 <p> 1030 The SWFObject plugin uses the <a href="http://code.google.com/p/swfobject/">SWFObject library</a> to handle the embedding 1031 of the SWFUpload Flash Component into the page. 1032 </p> 1033 <p> 1034 This plugin also provides support for Document Ready loading and Flash Version Detection. Usage details are documented 1035 in the plugin file itself. You should not use the SWFObject's Document Ready loading mixed with another libraries DOMReady. Use 1036 one or the other but not both. 1037 </p> 1038 1039 <p><strong>Flash Player 10: </strong> Because Flash Player 10 requires the SWFUpload swf to act is a button the movie must be visible in order 1040 for it to load. If the button_placeholder_id is set to an element that is hidden (visibility set to hidden or display set to none) SWFUpload will 1041 fail to load.</p> 1042 1043 <h3>Cookies</h3> 1044 <p>In response to the Flash Cookie Bug the Cookies Plugin automatically retrieves your browser's cookies and sends them 1045 with the upload. The are sent as POST or GET variables to the upload url.</p> 1046 1047 <p>Note that this plugin sends the cookies name/values in the POST or GET. On the server side they will not be accessible as cookies. Some frameworks that 1048 automatically check cookies for session or authentication values still will not be able to find the values.</p> 1049 1050 <h3>Queue Handling</h3> 1051 <p>This plugin provides Queue Handling features such as entire queue uploading, entire queue cancelling and automatic starting of uploads after being queued.</p> 1052 1053 1054 <h3>Speed</h3> 1055 <p>This Plugin extends the 'file' object with several properties that describe the current upload. This includes current speed, average speed, elapsed time, remaining time and more.</p> 1056 1057 1058 <h2><a name="knownissues"></a>Known Issues</h2> 1059 <p>The Flash Player and many Browsers have bugs that have a direct impact on the performance of SWFUpload. While we have worked 1060 hard to get around many issues but there are some things that we cannot fix.</p> 1061 1062 <h3>Cancelling in Linux</h3> 1063 <p>Older Flash 9 Players for Linux cause the browser to crash if an upload is cancelled. Newer Flash 9 Players behave better.</p> 1064 1065 <h3>Upload Progress in Linux</h3> 1066 <p>The Flash Player in Linux sends a single uploadProgress event after the file has finished uploading.</p> 1067 <p>In some distributions the entire browser locks up while the upload is in progress.</p> 1068 1069 <h3>Upload Progress in OS X</h3> 1070 <p>There have been some reports that uploadProgress events are not fired in MAC Flash Players. The specifics haven't been pinned down but be aware of the possible issue.</p> 1071 1072 <h3>MIME Type</h3> 1073 <p>The Flash Player uploads all files with a mime type of <em>application/octet-stream</em> regardless of the file's actual mime type.</p> 1074 1075 <h3>Maximum number of selected files</h3> 1076 <p>The Flash Player does not impose a maximum number of selected files. However, it builds a selected files string which does have a maximum length. 1077 The string is built using the file's name and the separator [quote][space][quote]. The total number of files selected is determined by the sum 1078 of the lengths of the file names and a prefixed and postfixed [quote] character (2 characters) and the number of files selected minus one times 3 (for the separator string)</p> 1079 1080 <p>This limitation may vary from system to system. If a use selects too many files they will be receive a Flash Player generated warning message and will 1081 be left at the File Selection Dialog.</p> 1082 1083 <h3>Proxies</h3> 1084 <p>The Flash Player may not properly use proxies. It does not handle authenticating proxies well (if at all) and will some-times crash.</p> 1085 <p>Some anti-virus software uses a proxy to scan uploads and cause SWFUpload to believe the entire file has been uploaded. SWFUpload will fire uploadProgress events very quickly 1086 until it reaches 100% and will then seem to pause until the proxy completes uploading the file to the server.</p> 1087 1088 <h3>Apache mod_security</h3> 1089 <p>Apache's mod_security validates POST to the server. Flash Player has implemented an edge case (there is argument as to whether it is invalid or note) 1090 POST for file uploads and so servers implementing 1091 mod_security will reject the upload. mod_security can be disabled using your .htaccess file</p> 1092 1093 <h3>SSL</h3> 1094 <p>There have been some reports that the Flash Player cannot upload through SSL. 1095 The issue has not been pinned down but uploading over SSL may be unreliable. There especially seems to be an issue with 1096 using self-signed certificates.</p> 1097 <p>Also, SSL tickets from untrusted Certificate Authorities (CA) do not work as Flash does not provide a method for accepting the certificate. It has been noted that, like the cookie bug, 1098 that Flash Player on Windows obtains its trusted CA list from Internet Explorer regardless of the browser in use.</p> 1099 1100 <h3>Authentication</h3> 1101 <p>HTTP Authentication is not well supported by the Flash Player. Later versions of Flash Player behave better. Old version of Flash Player would crash the browser.</p> 1102 1103 <h3>Prematurely terminated connections</h3> 1104 <p>Prematurely ending the response (such as a Response.end() in ASP.Net) can sometimes cause successful uploads to be reported as failed.</p> 1105 1106 <h3>Filedata in Linux</h3> 1107 <p>Changing the Filedata value (file_post_name setting) is ignored in Linux Flash Players.</p> 1108 1109 <h3>Cookie issue</h3> 1110 <p>On Windows the Non-IE Flash Player plugin (FireFox, Opera, Safari, etc) will send the IE cookies regardless of the browser used. This breaks authentication and sessions for many server-side scripting technologies.</p> 1111 <p>Developers should manually pass Session and Authentication cookie information and manually restore Sessions on the Server Side if they wish to use Sessions</p> 1112 <p>The SWFUpload package contains work-around sample code for PHP and ASP.Net</p> 1113 1114 <h3>ExternalInterface bugs</h3> 1115 <p>Flash Player does not properly escape data when communication with the browser/JavaScript. SWFUpload goes to great lengths to work-around this issue. If this 1116 bug is fixed in future Flash Players/Browsers then SWFUpload will send extra escaped data.</p> 1117 1118 <h3>Server Data length bugs</h3> 1119 <p>Very long server data is corrupted on Mac and Linux Flash Players. Server data will be truncated, garbled, and/or repeated. We recommend 1120 keeping data returned from the server short and concise.</p> 1121 1122 <h3>Avant Browser</h3> 1123 <p>For some users the Avant Browser does not work with SWFUpload after the Flash Control has been cached. This has been reproduced by the 1124 SWFUpload developers but the Avant Browser developers did not experience any problems.</p> 1125 <p>When the page is reloaded SWFUpload loads and fires the swfupload_loaded event. However, none of the ExternalInterface callback functions are defined 1126 on the movie element. SWFUpload v2.0.2 has added checks which prevent swfupload_loaded from firing if the callback functions are not detected.</p> 1127 1128 <p><strong>SWFUpload v2.2.0 added the prevent_swf_caching setting that attempts to work around this issue.</strong></p> 1129 1130 <h3>File Dialog & Page Changing</h3> 1131 <p>Leaving or reloading the current page while the File Browser Dialog window is open will cause the browser to crash (all browsers, all OSs). Most commonly this is caused by failing to 1132 cancel a click event on an <a> tag where the onclick event calls the selectFile or selectFiles function.</p> 1133 1134 <h3>Long Running Upload Scripts</h3> 1135 <p>After Flash has uploaded the file to the webserver the upload script is executed. This script handles the file whether that means saving it, creating a thumbnail, scanning for viruses, etc. 1136 If the upload script does not return any data within 30 seconds Flash will disconnect and return an IO Error. You can prevent this by returning characters or data while 1137 the script runs (if possible). For PHP, the script continues to run and complete successfully even though Flash has terminated the connection. Any data returned 1138 by the script after Flash has disconnected is lost.</p> 1139 1140 <h3>WMODE / BUTTON_WINDOW_MODE</h3> 1141 1142 <p>In some browsers the selected WMODE (which is set using the BUTTON_WINDOW_MODE) can prevent the Flash Control from loading 1143 if the control is not on screen. The control will finally load once the user scrolls the page so the control becomes visible.</p> 1144 1145 <p>This behavior can adversely affect the SWFObject plugin. No SWFUpload events will be fire and the button image will not be 1146 loaded until the control becomes visible.</p> 1147 1148 <h3>Memory Leaks</h3> 1149 <p>Some browsers (especially IE) cannot recover memory used by the Flash Player when JavaScript communication via the ExternalInterface classes is used (like in SWFUpload). 1150 Creating many SWFUpload instances and/or reloading the page several times will cause the browser to consume more and more memory until it crashes or otherwise harms the 1151 system.</p> 1152 1153 <p>In v2.2.0 SWFUpload we gave implemented some preventative measures. Some of these measures are pro-active but it is still recommended that you 1154 call the destroy method when the page unloads. If you are using hundreds of SWFUpload instances on a page you should use caution and test 1155 carefully for memory leaks.</p> 1156 1157 <h3>Other Mac Issues</h3> 1158 <ul> 1159 <li> 1160 Users have reported that uploading to subdomains does not work with the Mac Flash Player. 1161 </li> 1162 <li> 1163 Users have reported that pages that redirect (HTTP Status 302) are not handled by the Mac Flash Player. Windows 1164 clients seem to handle this issue. 1165 </li> 1166 <li> 1167 The flash documentation states that on OS early than OS X 10.3 the bytes loaded is always reported as -1. SWFUpload converts 1168 this to 0 but the total bytes will never be sent and 100% won't be reached. The UI should be updated to display 100% complete in 1169 uploadSuccess or uploadComplete events to maintain a consistent UI. 1170 </li> 1171 <li> 1172 Some users have reported issues if there is a space character in the upload_url for the Mac Flash Player. Avoid spaces or try replacing them with + or %20. 1173 </li> 1174 <li> 1175 Users have reported that the Flash Player for Mac adds the PORT to the HTTP_HOST server variable (e.g., http://www.example.com:80). If you are 1176 checking this variable in your server-side script be aware of the possible issue. 1177 </li> 1178 </ul> 1179 1180 </body> 1181 </html>
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Mon Jul 9 18:01:44 2012 | Cross-referenced by PHPXref 0.7 |