Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 511 lines (336 sloc) 26.608 kb
a02f986 @mwilcox no message
mwilcox authored
1 #format dojo_rst
2
b84cebe no message
MarcusReimann authored
3 dojox.form.FileUploader
4 =======================
a02f986 @mwilcox no message
mwilcox authored
5
27178d6 @mwilcox no message
mwilcox authored
6 :Project owner: Mike Wilcox
ec019a2 @mwilcox no message
mwilcox authored
7 :Author: Mike Wilcox
27178d6 @mwilcox no message
mwilcox authored
8 :Available: since 1.1
a02f986 @mwilcox no message
mwilcox authored
9
de60370 @mwilcox no message
mwilcox authored
10 .. contents::
11 :depth: 3
7af4738 @mwilcox no message
mwilcox authored
12
8658762 @mwilcox no message
mwilcox authored
13 Handles multiple file uploading to a server.
70fd526 @mwilcox no message
mwilcox authored
14
b84cebe no message
MarcusReimann authored
15 =====
16 Usage
17 =====
18
f291e5a @mwilcox no message
mwilcox authored
19 CDN Note
20 --------
21
22 FileUploader does work with the Google and AOL CDNs, but because of cross domain issues, you need to run the SWF locally, and point to its location with djConfig.uploaderPath.
23
8658762 @mwilcox no message
mwilcox authored
24 Dojo Version 1.2.x
25 ------------------
70fd526 @mwilcox no message
mwilcox authored
26
8658762 @mwilcox no message
mwilcox authored
27 The FileUploader version 1.1 and 1.2 is no longer supported. FileUploader 1.2 programmatically called the Flash browse() method which Adobe soon after removed for security reasons.
28
29 Dojo Version 1.3
30 ----------------
31
32 This version is supported but has limitations. It floats the SWF over the styled button, so the CSS is tricky and not always 100% accurate. And this will not work in many cases where the button is in scrolling content, specifically Windows and Linux Firefox.
33
34 Dojo Version 1.3.2
35 ------------------
36
37 This version is a major upgrade from 1.3, makes CSS placement easier and fixes the scrolling bug. However there is an IE8 bug that was not caught at the time of release. This bug can be patched using the instructions found in the Trac ticket:
38
39 http://bugs.dojotoolkit.org/ticket/9615
40
59ce9f6 @mwilcox no message
mwilcox authored
41 Another bug found is uploading multiple files more than once causes onComplete to fire on every file. It should only fire after all files have uploaded. The fix for this is to use the SWF from the trunk (1.4) in the 1.3.2 release.
8658762 @mwilcox no message
mwilcox authored
42
43 http://bugs.dojotoolkit.org/ticket/9646
44
a665e7d @mwilcox no message
mwilcox authored
45 Dojo Version 1.4.0
46 ------------------
47
48 This version has some serious upgrades, including a more robust upload system that has been tested to upload 500 files and 500 megs. This version also fixes several bugs including the ability to display the uploader in a Dialog.
49
50 Dojo Version 1.5.0
51 ------------------
52
5a895a8 @mwilcox no message
mwilcox authored
53 This version adds the ability to use the uploader in a TabContainer. However, see the next section.
54
55 ===============
56 IMPORTANT NOTES
57 ===============
a665e7d @mwilcox no message
mwilcox authored
58
59 There is a serious limitation in the Flash version for Firefox and Safari in TabContainers. When a node in those browsers is hidden (or essentially repainted which can mean other style applications) the SWF is reloaded. This means that if you browse for a file but don't upload upload it, change the tab and return, the files will no longer be in the FileUploader. This problem can be seen when tabbing between Tab 1 and Tab 2 and observing the console logs and you will see the SWF reinitializes. This problem does not exist in Internet Explorer. The HTML version of the Uploader should also work fine.
60
61 See form/tests/test_FileUploaderTabs.html for the workaround. It floats a div above the tab container and moves it on and off screen as the tab is toggled.
62
6b72b3f @mwilcox no message
mwilcox authored
63 While the FileUploader instantiates like a widget, it has limitations due to the fact that it has to manage a Flash plugin. Before it is built, it inspects the DOM and checks style information. Due to this process there needs to be a node to inspect, so dojo 1.4 functionality like:
64
65 *var f = new dojox.form.FileUploader(props).placeAt(anything);*
66
67 ...will not work. There may also be problems with placing it in other widgets unless it displays right away, although as of 1.5 these problems have mostly been worked out.
68
5a895a8 @mwilcox no message
mwilcox authored
69 Another limitation with using Flash is passing data back and forth. There is a problem with passing variable names with illegal characters, like:
70
71 *{form["my-var"]: "foo")*
72
73 Currently the only workaround is to *don't do that*.
74
b3fadda @mwilcox no message
mwilcox authored
75 =====================
8658762 @mwilcox no message
mwilcox authored
76 Updating Your Release
b3fadda @mwilcox no message
mwilcox authored
77 =====================
8658762 @mwilcox no message
mwilcox authored
78
79 I often suggest to people who are not able to use the 1.3.2 or trunk version of Dojo to copy over the latest uploader files. The involved files would be:
80
81 - dojox/form/FileUploader.js
e3de84c fixed paths for copying from 1.4 - synced css class names in programa…
trutwijd authored
82 - dojox/form/resources/uploader.swf
83 - dojox/form/resources/FileUploader.css
8658762 @mwilcox no message
mwilcox authored
84 - dojox/embed/flashVars.js
85 - dojox/embed/Flash.js
86
87 and optionally:
88
89 - dojox/form/resources/UploadFile.php
e3de84c fixed paths for copying from 1.4 - synced css class names in programa…
trutwijd authored
90 - dojox/form/resources/cLOG.php
8658762 @mwilcox no message
mwilcox authored
91
8a08354 @mwilcox no message
mwilcox authored
92 Note that if you are moving these files into Dojo 1.2 or less, you will have to change some of the code in the FileUploader to not use the 1.3 html method dojo.destroy() and replace it with the previous version of dojo._destroyElement()
93
de60370 @mwilcox no message
mwilcox authored
94 ======================================
6b72b3f @mwilcox no message
mwilcox authored
95 FileUploader Functionality 1.3.2 - 1.5
de60370 @mwilcox no message
mwilcox authored
96 ======================================
8658762 @mwilcox no message
mwilcox authored
97
6b72b3f @mwilcox no message
mwilcox authored
98 FileUploader is now a widget and **DOES** create a button. You do not have to pass a button in. Passing a button is still supported until version 1.5 to maintain backwards compatibility, but it is not recommended. In a majority of cases, you can create your uploader like any other widget.
ee51e2b @mwilcox no message
mwilcox authored
99
f03dcfb @mwilcox no message
mwilcox authored
100 Setup
101 -----
ffe0ea3 @mwilcox no message
mwilcox authored
102
f03dcfb @mwilcox no message
mwilcox authored
103 The button styles are now recreated in Flash, so there is no longer an invisible Flash movie with *wmode=transparent*. This way the Flash button is actually placed inline with the DOM, not floating above it and constantly resetting its position. The "Windows Firefox clickable bug" should be fixed (and hopefully some Linux problems).
7ed97a0 @mwilcox no message
mwilcox authored
104
105 The HTML button is created in a new way and it is now inline as is the Flash button. Styling is much easier and more versatile.
106
70fd526 @mwilcox no message
mwilcox authored
107 The process is to create a typical HTML button, with either a button, input, div, or span tag. Button tags work the best. Style the button how you would like it to look in CSS. Then create another class that will append to the class chain to style the button in its hover state. Follow the same procedure for active state (press) and disabled state. Assign the normal class to your button and make the widget either programmtically or with markup.
108
109 A basic example follows:
110
111 .. code-block :: css
7ed97a0 @mwilcox no message
mwilcox authored
112 :linenos:
70fd526 @mwilcox no message
mwilcox authored
113
114 .uploadBtn{
115 border:1px solid #333333;
116 background:url(buttonEnabled.png) #d0d0d0 repeat-x scroll 0px top;
117 font-size:14px;
118 width:201px;
119 height:30px;
120 vertical-align:middle; /* emulates a <button> if node is not */
121 text-align:center;
122 }
123 .uploadHover{
124 background-image:url(buttonHover.png);
125 cursor:pointer;
126 font-weight:bold;
127 }
128
129 .uploadPress{
130 background-image:url(buttonActive.png);
131 }
132 .uploadDisabled{
133 background-image:none;
134 background-color:#666;
135 color:#999;
136 border:1px solid #999;
137 }
138
139
140 .. code-block :: html
7ed97a0 @mwilcox no message
mwilcox authored
141 :linenos:
70fd526 @mwilcox no message
mwilcox authored
142
259b65f no message
trutwijd authored
143 <div id="btn" class="uploadBtn">Select Files</div>
70fd526 @mwilcox no message
mwilcox authored
144
145 .. code-block :: javascript
146 :linenos:
147
ba668f0 @viisual Small change: construction of the 'uploader' in the document's basic …
viisual authored
148 var uploader = new dojox.form.FileUploader({
e3de84c fixed paths for copying from 1.4 - synced css class names in programa…
trutwijd authored
149 hoverClass:"uploadHover",
150 activeClass:"uploadBtn",
151 pressClass:"uploadPress",
152 disabledClass:"uploadDisable",
70fd526 @mwilcox no message
mwilcox authored
153 uploadUrl:pathToUploadServerScript
29ee824 @viisual Small change: construction of the 'uploader' in the document's basic …
viisual authored
154 }, "btn");
70fd526 @mwilcox no message
mwilcox authored
155
7ed97a0 @mwilcox no message
mwilcox authored
156 Or, using the same CSS, create it as markup:
157
158
159 .. code-block :: html
160 :linenos:
161
e3de84c fixed paths for copying from 1.4 - synced css class names in programa…
trutwijd authored
162 <div class="uploadBtn" dojoType="dojox.form.FileUploader" hoverClass="uploadHover" pressClas="uploadPress"
259b65f no message
trutwijd authored
163 activeClass="uploadBtn" disabledClass="uploadDisable" uploadUrl="../serverpage.php">Select Files</div>
7ed97a0 @mwilcox no message
mwilcox authored
164
165
166 Dependencies
167 ------------
168
169 FileUploader no longer uses FileInput.css. It now uses FileUploader.css. See requires for JavaScript dependencies.
170
171 New Features
172 ------------
173
174 * Disabled: Can be toggled with widget.attr("disable", true|false)
175 * Submit: A convenience method has been added for if the uploader is in a form. Instead of submitting the form, call uploader.submit(theForm), and the Uploader will handle all of the form values and post the data.
176 * Selected List: If passing the ID of a container, the Uploaders will populate it with the selected files.
177 * Deleting Files: You can now delete pending files.
178 * Progress Built in: showProgress:true will change the button to a progress bar on upload.
179 * Progress Attach: Passing progressWidgetId will tell the Uploader of a progress widget. If the Progress widget is initially hidden, it will change to visible and then restored after upload.
180 * A11Y: The Flash button can be accessed with the TAB key. (The HTML cannot due to browser limtations)
181 * Deferred Uploading: (Flash only) throttles the upload to one file at a time
182
2c29c70 @mwilcox no message
mwilcox authored
183 Changed in 1.4: deferredUploading is now mandatory to prevent errors in Firefox and Safari. It accepts a number and the idea is you can upload more than one file in parallel, though my tests have shown it always does one at a time anyway. This change makes the upload a little slower, but now it is much more robust and can handle uploads of 500 files or more without crashing the browser.
184
7ed97a0 @mwilcox no message
mwilcox authored
185 There are two new tests added to DojoX: *test_FileUpladerCSS.html* and *test_FileUpladerForm.html*. The form test will show how to implement most of the new features. The CSS test will show different methods of styling the Uploader.
186
187 http://mwilcox.dojotoolkit.org/dtk/dojox/form/tests/test_FileUploaderForm.html
188
189 http://mwilcox.dojotoolkit.org/dtk/dojox/form/tests/test_FileUploaderCSS.html
190
191 Continue with the 1.3 instructions for other information that still applies to implementing the FileUploader.
70fd526 @mwilcox no message
mwilcox authored
192
193 Version 1.3
194 -----------
195
196 Version 1.3 does **NOT** create a button - it transforms an existing button into an uploader. This can be used for toolbar buttons for example. Because of this, it only works programmatically, it does not work in markup. Use the other other DojoX FileInput files for markup solutions.
a02f986 @mwilcox no message
mwilcox authored
197
2fff780 @mwilcox no message
mwilcox authored
198 FileUploader will detect if the correct version of Flash Player is available, and if so, a transparent SWF is laid over the top of the original (referred to as the 'fake') button. If not available, a traditional fileInput button with opacity set to zero is laid over the fake button.
199
200 A basic example follows:
201
202 .. code-block :: javascript
203 :linenos:
204
fe5b07d @mwilcox no message
mwilcox authored
205 var uploader = new dojox.form.FileUploader({
206 button:dijit.byId("myFakeButton"),
207 uploadUrl:uploadUrl,
208 });
2fff780 @mwilcox no message
mwilcox authored
209
210 The example has doesn't show *selectMultipleFiles*, but it defaults to true. Setting it to false restricts the user to one file selection. Multiple files are also supported in the HTML version, although only one file can be selected at a time. But after the files are selected, they will all be uploaded at once.
211
212 The *uploadUrl* property is the location of the server side script. Note that this URL needs to be relative to the SWF, not to the HTML page, nor to dojo.js. It's recommended that an absolute URL is used if possible. FlashUpload will try to "normalize" relative URLs and point them to the SWF.
213
214 Use *dojo.connect* to connect to the *onChange*, *onProgress* and *onComplete* methods:
215
216 .. code-block :: javascript
217 :linenos:
218
fe5b07d @mwilcox no message
mwilcox authored
219 dojo.connect(uploader, "onChange", function(dataArray){
220 dojo.forEach(dataArray, function(data){
221 dojo.byId("myTextarea").value += data.name+" "+Math.ceil(data.size*.001)+"kb \n";
222 });
223 });
224 dojo.connect(uploader, "onProgress", function(dataArray){
225 dojo.forEach(dataArray, function(data){
226 dojo.byId("myTextarea").value += "onProgress: ("+data.percent+"%) "+data.name+" \n";
227 });
228 });
229 dojo.connect(uploader, "onComplete", function(dataArray){
230 dojo.forEach(dataArray, function(d){
231 dojo.byId("myTextarea").value += "onComplete: "+d.file+" \n";
232 });
233 });
2fff780 @mwilcox no message
mwilcox authored
234
235 Use *upload* to initiate the upload after files have been selected. Or set *uploadOnChange* to true to initiate upload automatically after the selection.
7af4738 @mwilcox no message
mwilcox authored
236
008f4db some additional notes on dataArray
trutwijd authored
237 Note that the "dataArray" param above is always an array, even if selectMultipleFiles is set to false.
238
22361fc @mwilcox no message
mwilcox authored
239 Updated: Be careful not to construct the connect so that it sends a mouse event to the upload method (as this example used to do). The upload method expects no arguments or one argument to use as postData. The mouse event will be treated as postData and throw an error. This is fixed in the trunk but exists in 1.32.
1652c80 @mwilcox no message
mwilcox authored
240
2fff780 @mwilcox no message
mwilcox authored
241 .. code-block :: javascript
242 :linenos:
243
1652c80 @mwilcox no message
mwilcox authored
244 dojo.connect(dijit.byId("myUploadButton"), "onClick", function(){
245 uploader.upload();
246 });
2fff780 @mwilcox no message
mwilcox authored
247
248
249 Advanced Parameters
250 -------------------
7af4738 @mwilcox no message
mwilcox authored
251
2fff780 @mwilcox no message
mwilcox authored
252 The FileUploader has many advanced properties to handle most situations.
253
fcdb6ca @mwilcox no message
mwilcox authored
254 **fileMask**: An array, or an array of arrays. Restrict file selection to certain file types Empty array defaults to "All Files". NOTE: MacType is not supported, as it does not work very well. fileMask will work on a Mac, but differently than Windows.
2fff780 @mwilcox no message
mwilcox authored
255
256 .. code-block :: javascript
257 :linenos:
b66cdba @mwilcox no message
mwilcox authored
258
fe5b07d @mwilcox no message
mwilcox authored
259 var fileMask = ["Images", "*.jpg;*.jpeg;*.gif;*.png"]
260 // or
261 var fileMask = [
262 ["Jpeg File", "*.jpg;*.jpeg"],
263 ["GIF File", "*.gif"],
264 ["PNG File", "*.png"],
265 ["All Images", "*.jpg;*.jpeg;*.gif;*.png"],
266 ];
267 var uploader = new dojox.form.FileUploader({
268 button:dijit.byId("myFakeButton"),
269 uploadUrl:uploadUrl,
270 fileMask:fileMask
271 });
2fff780 @mwilcox no message
mwilcox authored
272
273
fcdb6ca @mwilcox no message
mwilcox authored
274 **force**: You can use either HTML (force="html") or Flash only, with this parameter. If force="flash" and the user does not have Flash installed, they will be prompted to install the plugin. "flash" forces Flash Uploader. Defaults to an empty string (force="") which checks for the availability of the proper Flash player (Flash 9 or higher).
2fff780 @mwilcox no message
mwilcox authored
275
fcdb6ca @mwilcox no message
mwilcox authored
276 **postData**: The data that will be sent via POST to the server along with the uploaded files. This data object can bet set on instantiation, and the data will be sent to the server with each file on every upload. You can also pass postData in the upload method as an object argument which can be different with each upload.
2fff780 @mwilcox no message
mwilcox authored
277
c2bede5 @mwilcox no message
mwilcox authored
278 Note: as of 1.4.0 there is a bug: http://bugs.dojotoolkit.org/ticket/10559 where postData is not being sent for flash based uploaders where uploadOnChange is also true. This is fixed in 1.5.
279
280 **Returned postData**: Post data is regurgitated to the uploader in the tests. Your case may be different. The SWF returns postdata in an *additionalParams* object, and it is in this object in which the postdata can be found in the onComplete object. The reason for this was originally to get around AS3 issues, but it turns out to be a good system, as it prevents post data variables from overwriting standard variables such as 'name' or 'file'.
6873e81 no message
trutwijd authored
281
fcdb6ca @mwilcox no message
mwilcox authored
282 **htmlFieldName**: The name of the field of the fileInput that the server is expecting. See "Server Side Code" below.
2fff780 @mwilcox no message
mwilcox authored
283
fcdb6ca @mwilcox no message
mwilcox authored
284 **flashFieldName**: The name of the field of the flash uploaded files that the server is expecting. See "Server Side Code" below.
2fff780 @mwilcox no message
mwilcox authored
285
22b8cf4 @mwilcox no message
mwilcox authored
286 Dependencies
287 ------------
288
289 dojox.html.styles to create dynamic CSS for an IE workaround.
290 dojo.io.iframe for the HTML POST upload.
291 dojox.embed.Flash for embedding the SWF in the page.
292 dojox/form/resources/FileInput.css for some fileInput styling.
293
2fff780 @mwilcox no message
mwilcox authored
294 Debugging
295 ---------
296
297 Because of the complex nature of the FileUploader code (or more accurately, the hack!). It's often necessary to do some debugging to test if something is working properly. The following parameters assist with this:
298
fcdb6ca @mwilcox no message
mwilcox authored
299 **isDebug**: Unlike most Dojo code, the logging has been left in the FileUploader, but is disabled by default. isDebug=true will turn on the log messages for inspection. This also passes to the SWF which will output messages of what's happening in there.
2fff780 @mwilcox no message
mwilcox authored
300
fcdb6ca @mwilcox no message
mwilcox authored
301 **devMode**: Changing this parameter to true will set the opacity of the HTML upload button to 100% and remove transparency from the Flash upload button. This helps to determine of the button is being positioned correctly.
2fff780 @mwilcox no message
mwilcox authored
302
de60370 @mwilcox no message
mwilcox authored
303 ===========
43c24e9 @mwilcox no message
mwilcox authored
304 Server Side
de60370 @mwilcox no message
mwilcox authored
305 ===========
306
307 The transfer of data happens through Flash and so the you will not be able to inspect the data in Firebug. It's recommended to use Charles or Fiddler if you wish to inspect the transfer.
43c24e9 @mwilcox no message
mwilcox authored
308
de60370 @mwilcox no message
mwilcox authored
309 http://www.charlesproxy.com/
310
311 http://www.fiddler2.com/fiddler2/
43c24e9 @mwilcox no message
mwilcox authored
312
313 The following transfer example is taken from:
314
315 http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/net/FileReference.html
316
de60370 @mwilcox no message
mwilcox authored
317 It includes examples two post parameters, api_sig and api_key. The name for the field where the file can be found is set to "photo" (Adobe default is "FileData" and FileUploader changes this default to "flashUploadFiles").
43c24e9 @mwilcox no message
mwilcox authored
318
319 .. code-block :: text
320 :linenos:
321
322 POST /handler.cfm HTTP/1.1
323 Accept: text/*
324 Content-Type: multipart/form-data;
325 boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
326 User-Agent: Shockwave Flash
327 Host: www.example.com
328 Content-Length: 421
329 Connection: Keep-Alive
330 Cache-Control: no-cache
331
332 ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
333 Content-Disposition: form-data; name="Filename"
334
335 MyFile.jpg
336 ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
337 Content-Disposition: form-data; name="api_sig"
338
339 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
340 ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
341 Content-Disposition: form-data; name="api_key"
342
343 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
344 ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
345 Content-Disposition: form-data; name="auth_token"
346
347 XXXXXXXXXXXXXXXXXXXXXX
348 ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
349 Content-Disposition: form-data; name="photo"; filename="MyFile.jpg"
350 Content-Type: application/octet-stream
351
352 FileDataHere
353 ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
354 Content-Disposition: form-data; name="Upload"
355
356 Submit Query
357 ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7--
358
de60370 @mwilcox no message
mwilcox authored
359 Whether HTML or Flash, the payload is done with a multipart transfer. The file data is uploaded to a temp folder on the server. After the upload is complete, the server script is called. It is the job of the server script to know where this temp folder is and access the file (to move it to the destination, and or perform tasks upon it).
360
361 During a Flash multi-file upload, the images are uploaded in parallel (unless FileUploader.deferredUploading=true), however, the server script only receives one file at a time. So if five files are uploaded, the server script will be called five times.
362
363 During an HTML multi-file upload, the files are all uploaded at once, and after all five are completely uploaded to the temp folder, the server script is called just once. Each file will be referenced as numerically sequenced fields: uploadedfile0, uploadedfile1, uploadedfile2, etc. Single file uploads will of course call the server script once.
364
365 With a multipart request the POST data is the contents for the first part and the uploaded files is an array (or an object) of each additional part. Refer to your particular server documentation for how to reference the files (PHP is used as an example in the next section).
43c24e9 @mwilcox no message
mwilcox authored
366
aeccedc @mwilcox no message
mwilcox authored
367 The return data needs to be formatted very specifically, ad there are different formats for Flash and HTML. See **Server Side Return Data** below.
43c24e9 @mwilcox no message
mwilcox authored
368
369 Server Side Code PHP
370 --------------------
2fff780 @mwilcox no message
mwilcox authored
371
372 FlashUploader comes with a working PHP file, *dojox/form/resources/UploadFile.php*, to use as a reference for how your server side code should work. UploadFile.php has two dependencies, *dojo/tests/resources/JSON.php*, which is used for converting the return data to a JSO string, and *dojox/form/resources/cLog.php* which is used to log message to a text file, placed relative to the PHP file.
373
374 UploadFile.php is expecting one of three things:
375
376 1) A file or files from Flash
377 2) A file from HTML
378 3) Multiple files from HTML
379
380 The PHP file is inspecting the header and looking for the parameters set in FileUploader: *htmlFieldName* or *flashFieldName*. Whatever you set these parameters to, they must match on the server. The current code uses "flashUploadFiles" as the default Flash field name. (The default field name in Flash is "Filedata", which is over written to show that you can do custom field names). Therefore the server must be made aware of this parameter, as it is set on line 69: *$fieldName = "flashUploadFiles";*
381
382 The field name for the HTML uploader works much the same way. The only difference is if you do multi-file upload with HTML, this essentially continues to add fileInputs to the form, and in doing so, appends numbers to the fileInput field names, starting with '0'. That's why one file fieldname will look like "myFieldName" but two files will look like [ "myFieldName0", "myFieldName1" ] to the server side code.
383
384 Server Side Return Data
385 -----------------------
386
387 How the data is returned from the server is not difficult, but it is very important. If not done correctly, it can be the cause of reported errors that the "onComplete" is not firing in FileUploader.
388
aeccedc @mwilcox no message
mwilcox authored
389 **NOTE** The Flash uploader and the HTML uploader need differently formatted return data. You will need to inspect the post data to determine which type to return.
390
391 If *flashFieldName* is found in the post data and Flash is being used on the client side, all that is needed for return data is a key-value string, and it can simply be returned, as at the end of a function. You may also want to insert *exit* or whatever necessary to cease execution of the remainder of the code. Example:
2fff780 @mwilcox no message
mwilcox authored
392
59ce9f6 @mwilcox no message
mwilcox authored
393 .. code-block :: html
394 :linenos:
395
396 $data .='file='.$file.',name='.$name.',width='.$width.',height='.$height.',type='.$type;
397 echo($data);
398 exit;
399
aeccedc @mwilcox no message
mwilcox authored
400 For non-PHP devs this translates to:
401
67580f6 @mwilcox no message
mwilcox authored
402 .. code-block :: text
403 :linenos:
404
405 $name = name of the file, such as "PIC01.jpg"
406 $file = name of the file and the path, such as "uploaded/PIC01.jpg"
407 $width, $height = the dimensions (if you are working with images)
408 $type = the extension of the file - JPG, GIF, PNG, etc.
409
aeccedc @mwilcox no message
mwilcox authored
410
411 The return to Flash should look like:
412
67580f6 @mwilcox no message
mwilcox authored
413 .. code-block :: text
414 :linenos:
aeccedc @mwilcox no message
mwilcox authored
415
67580f6 @mwilcox no message
mwilcox authored
416 "file=uploaded/PIC01.jpg,name=PIC01.jpg,width=320,height=240,type=jpg"
417
aeccedc @mwilcox no message
mwilcox authored
418
67580f6 @mwilcox no message
mwilcox authored
419 This string should be returned, or printed, or echoed.
59ce9f6 @mwilcox no message
mwilcox authored
420
1618100 @mwilcox no message
mwilcox authored
421 New in 1.4, you can add an error key if one file was in error; say if it was not of the correct type. This error code or message will be returned in the onComplete dataArray. It's important to note that as far as the FileUploader is concerned, everything was a success. It's up to your custom code to test for this error.
422
423 The return string with an error might look like:
424
425 .. code-block :: text
426 :linenos:
427
428 "file=uploaded/PIC01.jpg,name=PIC01.jpg,width=320,height=240,type=jpg,error=Not recognized file type"
429
485819e minor
trutwijd authored
430 You can also send back arbitrary parameters from your server-side script using this comma-delimitted format. For example, adding variables foo and abc:
008f4db some additional notes on dataArray
trutwijd authored
431
432 .. code-block :: text
433 :linenos:
434
435 "file=uploaded/PIC01.jpg,name=PIC01.jpg,width=320,height=240,type=jpg,foo=bar,abc=123"
436
437 Then you can access these variables in the client-side functions using dataArray[i].additionalParams.foo and dataArray[i].additionalParams.abc.
438
49dd8e6 no message
trutwijd authored
439 Note: there is an open ticket http://bugs.dojotoolkit.org/ticket/10576 - when the uploader is set/forced to HTML mode, additionalParams is not created on the client side. In the situation above dataArray[i].foo would exist though.
fdb6f66 note on http://bugs.dojotoolkit.org/ticket/10576
trutwijd authored
440
59ce9f6 @mwilcox no message
mwilcox authored
441 If *htmlFieldName* is used, the code on the client side gets pretty tricky, as an iframe is necessary for the file-post, and reading back from that iframe presents problems. In order to read the iframe return data accurately cross browser, the code needs to be wrapped in a *<textarea>*. You can see the code for this on the very last line of UploadFiles.php. Note that the textarea needs to be outside of the PHP. Example:
442
443 .. code-block :: html
444 :linenos:
445
446 <?php
447 ....code....
448 ?>
449 <textarea><?php print $json->encode($dataObject); ?></textarea>
450
aeccedc @mwilcox no message
mwilcox authored
451 For non-PHP devs, this translates into a JSON string, wrapped in a textarea, returned as HTML. I know it's screwy, but that's how it works.
2fff780 @mwilcox no message
mwilcox authored
452
453 If you are having problems getting onComplete to fire, look at this code first. Often the problem is the server side code is not catching the flash field name for whatever reason (perhaps the client and server names don't match) and the code is falling to the end of the page and returning a textarea to Flash. Recently Code has been added in the SWF that checks for this, so if that is the problem, you should be notified with a console message.
fe5b07d @mwilcox no message
mwilcox authored
454
6179fe2 @mwilcox no message
mwilcox authored
455 HTTPS Issues
456 ------------
fe5b07d @mwilcox no message
mwilcox authored
457
6179fe2 @mwilcox no message
mwilcox authored
458 Attempting to upload to an HTTPS server can be very difficult in Firefox and Safari due to the fact that they do not share the same session as the browser page. IE has much fewer issues. Potential workarounds (mostly unverified as I do not have an HTTPS server to test with):
fe5b07d @mwilcox no message
mwilcox authored
459
6179fe2 @mwilcox no message
mwilcox authored
460 - Here is the official Adobe bug report on the issue: https://bugs.adobe.com/jira/browse/FP-226
7ed97a0 @mwilcox no message
mwilcox authored
461
6179fe2 @mwilcox no message
mwilcox authored
462 - Firefox does not like self signed security certificates. It has been said that an official signed cert will work.
7ed97a0 @mwilcox no message
mwilcox authored
463
6179fe2 @mwilcox no message
mwilcox authored
464 - It was brought to my attention that an .htaccess files on the server will work with the following content:
465
466 .. code-block :: text
467 :linenos:
468
469 <IfModule mod_security.c>
470 SecFilterEngine Off
471 SecFilterScanPOST Off
472 </IfModule>
473
474
475 HOWEVER, this site says that opens you up to SQL injection attacks. He offers other solutions:
476 http://pumastudios.com/2009/05/file-uploads-and-mod_security-vs-wordpress-wp-adminadmin-ajaxphp
3f8e17d @mwilcox no message
mwilcox authored
477
478 The original poster responds:
479
480 This is not only a https issue. It's also on simple http connections. Ist a bug of adobe flash player in conjunction with the web application firewall (modsecurity). If i understand that correctly the flash player sends one "\\n\\r" instead but the http protocol requires "\\n\\r\\n\\r". For modsecutiry this is a rule break so it delivers 403 rejected.
481
482 And yes if you disable modsecurity sql injections can be done on all post vars that are later processed by the database an not escaped within the application. So another safer way - until adobe fixed this problem and all flash players are updated - is the following but may not work on all servers:
483
484 .. code-block :: text
485 :linenos:
486
487 <IfModule mod_security.c>
488 SetEnvIfNoCase Content-Type "^multipart/form-data;" "MODSEC_NOPOSTBUFFERING=Do not buffer file uploads"
489 </IfModule>
490
491 (Thanks to minobun for all the great info on this thorny issue)
6179fe2 @mwilcox no message
mwilcox authored
492
493 The other, less desirable solutions, are:
494 - Have an HTTP server to handle the uploads and use a crossdomain.xml file to handle the different protocol.
495 - You may need to resort to force the HTML uploader.
496
497 More references to this issue:
498 - http://bugs.dojotoolkit.org/ticket/8911
499 - http://bugs.dojotoolkit.org/ticket/10306
500 - http://wiki.modxcms.com/index.php/What_is_mod_security_and_how_does_it_affect_me
501 - http://www.modsecurity.org/documentation/modsecurity-apache/1.9.3/html-multipage/06-special_features.html
502
503 =====
504 Demos
505 =====
506
507 - http://mwilcox.dojotoolkit.org/dtk/dojox/form/tests/test_FileUploader.html
508 - http://mwilcox.dojotoolkit.org/dtk/demos/uploader/demo.html
509 - http://mwilcox.dojotoolkit.org/dtk/dojox/form/tests/test_FileUploaderForm.html
510 - http://mwilcox.dojotoolkit.org/dtk/dojox/form/tests/test_FileUploaderCSS.html
Something went wrong with that request. Please try again.