Documentation
This documentation covers the following.
- Basic Usage
- Options
- Functions
- Callbacks
Basic Usage
As a jQuery chained function
$(element).upload( /** options */ );
As a stand-alone jQuery function
$.ocupload($(element), /** options */ );
Options
Both of the functions accept an optional options object, which can contain any or all of the following (default value):
- name: ("file") The name of the file input form element.
- enctype: ("multipart/form-data") The enctype attribute of the form, it is usually a good idea to leave this as default.
- action: (null) The form action attribute, the page that will do the processing on the server side.
- autoSubmit: (true) If true the form will be submitted after the user selects a file (after the file browser closes).
- params: ({}) Additional paramaters to be sent with the file, creates a hidden form element using the key as the name of the form and the value as the value.
- onSubmit: (null) The callback function called before submitting the form.
- onComplete: (null) The callback function called after the action page loads.
- onSelect: (null) The callback function called after the user has selected a file.
Example
var myUpload = $(element).upload({
name: 'file',
action: '',
enctype: 'multipart/form-data',
params: {},
autoSubmit: true,
onSubmit: function() {},
onComplete: function() {},
onSelect: function() {}
});Functions
filename
Description
This function returns the name of the currently selected file.
Example
var myUpload = $(element).upload();
alert(myUpload.filename());
name
Description
| string name ( void ) |
| void name ( string ) |
This function is used to get and set the name of the file input.
Example
//Setting name at creation
var myUpload = $(element).upload({
name: 'myFile'
});
//Changes the file input name to "myNewFile"
myUpload.name('myNewFile');
//Alerts "myNewFile"
alert(myUpload.name());action
Description
| string action ( void ) |
| void action ( string ) |
This function is used to get and set the action of the form.
Example
//Setting action at creation
var myUpload = $(element).upload({
action: 'upload.php'
});
//Changes the form action to "path/to/dir/newUpload.php"
myUpload.action('path/to/dir/newUpload.php');
//Alerts "path/to/dir/newUpload.php"
alert(myUpload.action());enctype
Description
| string enctype ( void ) |
| void enctype ( string ) |
This function is used to get and set the enctype of the form.
Example
//Setting enctype at creation
var myUpload = $(element).upload({
enctype: 'multipart/form-data'
});
//Changes the form enctype to "application/x-www-form-urlencoded"
myUpload.enctype('application/x-www-form-urlencoded');
//Alerts "text/plain"
alert(myUpload.enctype());params
Description
| object params ( void ) |
| void params ( object ) |
This function is used to alter additional parameters.
Example
//Setting paramters at creation
var myUpload = $(element).upload({
params: {name: 'My file', description: 'My file description'}
});
/**
* Settings paramaters during runtime
* name: "My file" is replaced with "My new file
* description: remains the same
* size: is added
*/
myUpload.params({
name: 'My new file', size: '1000kb'
});set
Description
This function is used to alter options after creation of the object.
Example
//Setting options at creation
var myUpload = $(element).upload( /** options */ );
//Setting options after creation
myUpload.set({
name: 'file',
action: '',
enctype: 'multipart/form-data',
params: {},
autoSubmit: true,
onSubmit: function() {},
onComplete: function() {},
onSelect: function() {}
});submit
Description
This function is used to submit the form if autoSubmit is turned off.
Example
Javascript
var myUpload = $(element).upload( /** options */ );
HTML
<input type="button" value="submit" onclick="myUpload.submit()" />
Callbacks
onSubmit
Description
This is called before the form is submitted, this is where you should make last minute changes to the parameters etc...
onComplete
| void onComplete ( response ) |
Description
This is called after the action page has loaded, the first parameter contains the html response from the action so you can use it like an AJAX response. onComplete does not mean the file was uploaded successfully, you should use the action script to supply a suitable response.
onSelect
Description
This is called after the file browse window is closed or the value of the file input is changed.
how can get filename when onSelect is working ?
try...
var myUpload = $(element).upload(); myUpload.onSelect = function() { alert(myUpload.filename()); }Write plagin which simply hides input file. And farther already I would could to write, that is why however much a just the same variant does not suit me.
forgive me for my English.
How to know then downloadin complete sucsesfuly, If on complete - does not mean the file was uploaded successfully
Where downloading my file? Or it`s should made php script? Then... What params it must to get me?
super cool plugin!
But: - How to programatically SET/GET the file to upload, not through FILE BROWSE WINDOWS?
- How to integrate validate callback or send a 'TEST' request to VALIDATE, when not valid then STOP the upload?
Thanks in Advanced!
Hello! Quite well, but...
1. upload will probably failed when you try to send file to other domain (example: from www.website.com to images.website.com). If i remember well, browser will not allow to get iframe content. It should be done in other way...
2. not every browser allow to create multipart form in js
Mail me, if you need some additional informations... Bye!
how to add optional data to this post action ?
for 1nc...
You can add more data to that submit using the "params" key like:
... params : {id: 32, otherVar : 'a value'}, ...
Господа, подсобите кто чем сможет. Как получить имя файла, который загружается на сервер? функция filename нефига не возвращает!?
for igor.korotkov basename($FILES['file']['name']);
IE7 outline hide plz change down code and version up plz var input = $(
how I can prevent a file sending if I got "myUpload.filename()=='' "?
I have found a solution of this problem, it's very simple... just:
onSelect: function(){ if (myUpload.filename()==''){
}it's work fine. :)
hi
it is possible to use this plug-in more than one time in the same page. I am trying to write a page, where I will give an upload option everywhere where the class name of html tag is "upload".
My code is: var myUpload = $('.upload').upload({....
but one I have 2 or more html tags with classes "upload" then the plug-in stop working How can I resolve my issue?
Thank you for your help Tsvetelin
Hi,
An excellent plugin! Thank you. Just one small note from my side: when file size exceeds the max allowed request length, I don't reach onComplete code. I tested plugin inside ASP.NET page under IIS, uploading 7 MB file. Default setting for maxRequestLength is 4MB. If I extend this value to > 7MB, plugin works.
Very cool job!!! But i have 1 question: Do not work autoSubmit: false; exactly autoSubmit: false; = autoSubmit: true; File submiting after browse close.
error in Methods —
autoSubmit: false,<---autoSubmit: options.autoSubmit
{{{{ var uploader = $("#upload").upload({ ... }); uploader.onSelect = function() {
}; }}}}Where is FULL example?
how can I cancel an upload in progress?
thanks!
First off thanks Michael for this plugin
apparently i am the only one having the following issue: It doesn't seem to work on the mac (OS X 10.4 +firefox 3.0.7), but with safari it does work.
Any tips??
Hi can i change file dialog box title and ext. ?
Plugin is very good, thanks, but I have one question. Where I can get an tmp_name? and where it stores. i can POST filename() to php script but what should i pick in move_uploaded_file(), i can't find tmp. without it its nothing to download. Thanks for answer
it's ok, everything found, cool plugin the same is for fotogalery very good thing
but i've just found the question, how can i return any variable from my php script after onComplete() i should know is the same file exist. Because there isn't function in javascript that check file for existance
sorry but i understand how it to recieve callback //javascript onComplete: function(data) {
}, //phpscript if (file_exists($pathtofile)) { echo 'false'; } else { echo 'true'; }Hi guys, To fix the issue with ie7 not being able to click accurately(you have to do a double click to upload a file, this is due to the browse button being positioned incorrectly in ie7), do the following changes:
line 91:
left: e.pageX-container.offset().left-175+'px'
Finally, replace -175px to 0 of the input's css property on line 63:
marginLeft: 0+'px',
Hi
is anyone else having issues whereby the image used as buton that activates the upload, sometime it doesn't appear unless the browser is refreshed?
I have a small problem with this great plugin. When using autoSubmit: true, not only the file form is submitted, but also the main form where the file is part of.
Is there a way to prevent this?
It will be very interesting to know the size of loaded file. How can I know the size of the file to upload?
Because It's exceed the maximum size then I can not start the process.
I need to pass a variable that I have hidden in my <a href="#"> tag as a 'method' attribute.
How can I reference this? I keep trying to throw a onSubmit: function() { var variable = $(this).attr("attrName"); alert(variable); },
but it never gets passed. Hand anyone?
A couple enhancements: 1. autoSubmit doesn't seem to work. Believe it is caused by:
2. Creation of the hidden inputs shouldn't set the value. That should be done by a subsequent $("#" + key).val(value) callHow do I add an upload progress bar to this plugin?
how it works?
how is the html structure?
how is invoked?
it needs too much documentation
I can't find a working demo anywhere. Could you please add one?
Don't work for me. With firebug i can see de iframe hidden and <head></head><body></body> empty.
What i'm doing wrong ?
chris.pe...@gmail.com, Yes, You'e right about 1, but i haven't found troubles with 2.
Hy guys. If you want to fix <IE8 problems, do the following changes:
line 59: position: 'absolute', display: 'block', marginLeft: 0+'px', opacity: 0
line:88 top: e.pageY-container.offset().top+25+'px', left: e.pageX-container.offset().left-175+'px'
works for me in FF2+,IE6+,Chrome.
Unfortunately this plugin breaks absolute positioning because it wraps the element in a div but fails to set up the div to take over positioning duties.
There is a very small yet critical bug that doesn't let user select files, on line 84
input.css('marginTop', -container.height()-10+'px');
which should be
input.css('marginTop', -(container.height()-10)+'px');
Plus adding modify following line to have a cursor pointer.
Great! Flexible!!! Very cool! Thank you!
Nice plugin! I'd like 1 more feature - to be able not to add form tag around the input. Maby I want to add it to my html.
1. Yes, I think the cursor should be changed but it should not be hardcoded but inherit it from the object ocupload was assigned to:
var element_cursor = element.css('cursor');
/ File Input / var input = $( ).css({ });
2. Like I see from comments above and that the script didn't work for me either, file input position has been hardcoded. One should get height and width of the file input and position mouse in the center. Also, file input should be position absolute, not relative;
Here are my fixes https://github.com/hkirsman/jquery-ocupload . I did sent Pull Request, but don't know if it's accepted by the author.