Welcome to AJAX File Upload v. 0.1!

Thank you for using AJAX File Upload to quickly process your uploads on the go!

A small preview

WpChats 3.0 profile edit

This plugin will help you add file upload feature to your site, set maximum upload size, allowed file extensions, and much more through a simple shortcode or a custom function.

Totally AJAX, your uploads will be processed faster and an elegant way. All you need to do is to add the shortcode to your content, or call the plugin's custom function whithin your code and that's it.

Go to settings or carry on with the useful documentation

The Shortcode

You can use [ajax-file-upload] to output the AJAX file uploader, set its settings, markup, and much more through the shortcode attributes.

Shortcode attributes

1. unique_identifier — required

This is a required attribute. Insert anything random that makes the uploader unique, used to store the uploader settings in the database and get them while processing a file for the shortcode in use.
Example use: unique_identifier="my_contact_form"

2. max_size — optional

Allows you to set the maximum file size to upload in KB. 1 MB is equal to 1000 KB.
Example use: max_size=3000 for 3 MB upload

3. allowed_extensions — optional

With this attribute you can set the allowed file extensions to upload. Please separate the extensions with commas.
Example use: allowed_extensions="pdf,txt"

4. permissions — optional

Set the required permission for a user to upload a file. You can set all for all users (even logged-out ones), or logged_in for logged-in users only, or a custom user role e.g author. If you choose to set a role, the current user is required to have that role in order to process an upload.

5. on_success_alert — optional

Alert the user that their upload is done. You can set custom messages to output within the dialog. It is optional, and no default alert is there if you don't set this attribute.
Example use: on_success_alert="Your file was successfully uploaded"

6. on_fail_alert — optional

When a file is not processed successfully, you can use this attribute to alert the user with a custom message.
Example use: on_fail_alert="We couldn't have your file uploaded. Try again?"

7. on_fail_alert_error_message — optional

An error message is always included in the AJAX response while a file was not processed with success. To alert this message to the user, you just need to add this attribute with some value that makes it true.
Example use: on_fail_alert_error_message="true"

8. on_success_set_input_value — optional

You might have a hidden or visible input within your form where you want to put the uploaded media URL. If so, then use this attribute and put that field selector as the attribute value. If this field was not found in the DOM, an error will be added to the console.
Example use: on_success_set_input_value="#my_hidden_input"

9. set_background_image — optional

When uploading an image, you probably want to use this attribute to set an element's background-image property with the returned image upload URL. The value has to be a valid element selector.
Example use: set_background_image=".cover-photo-container"

10. set_image_source — optional

Same here, when uploading an image you would probably want to set an image source attribute with the returned image upload URL. If so then provide this image selector in the DOM.
Example use: set_image_source="img.profile-pic"

11. disallow_remove_button — optional

This attribute allows you to not provide a file delete button with the shortcode output. It can be handy when you don't want a user to multiple files everytime as they hit this button. Set its value and the button won't be there.
Example use: disallow_remove_button="1"

12. disallow_reupload — optional

This can be handy to prevent users to upload multiple files. Set its value to something that makes it true, as you do, when a user uploads a file, the upload and remove button will both disappear, and the select one will become disabled.
Example use: disallow_reupload=""

13 upload_button_value — optional

The default value is "upload" and translatable through the admin settings. Lets you edit the upload button text.
Example use: upload_button_value="upload file"

14. select_file_button_value — optional

The default value is "choose file" and translatable through the admin settings. Lets you edit the select button text..
Example use: select_file_button_value="choisir un fichier"

15. remove_file_button_value — optional

The default value is "remove" and translatable through the admin settings. Lets you edit the remove button text..
Example use: remove_file_button_value="click to remove this file"

16. show_preloader — optional

If you have a hidden preloader which you want to show while the upload is being processed, provide its selector in the attribute value.
Example use: show_preloader=".loading"

17. default_loading_text — optional

The default value is "uploading.." and it is translatable. When you don't have show_preloader set, the select file button's text will change to this attribute value while an upload is processing, and the icon will change to a spin icon (icons by fontello.com)
Example use: default_loading_text="Processing your file. please wait.."

18. on_success_dialog_prompt_value — optional

This will let your uses get the media URI of what they have uploaded. A dialog box will prompt with acustom message and an input where they can copy the file URL. in the attribute value, you can set the message to show above the input in the dialog box.
Example use: on_success_dialog_prompt_value="Upload done! make sure to copy your URL below and save it!"

19. hide_if_no_permissions — optional

If a user does not have permissions to upload (as per what you input in permissions attribute or its default), then this user will no longer be able to use the upload buttons if you set this attribute.
Example use: hide_if_no_permissions="true"

The function

In your PHP template, you could call the shortcode with do_shortcode('[ajax-file-upload ..]') WordPress's native shortcode parser function. Or, there's this function ajax_file_upload() you can use instead, carry on.

ajax_file_upload( $args ) accepts an array of arguments, these arguments are basically the shortcode attributes! So, keep consulting the above list if you need an element to add to your function..

Here's an example use:

$args = array(
    "unique_identifier" => "my_subscription_form_file_upload",
    "allowed_extensions" => "jpg, png, bmp, gif",
    "on_success_alert" => "Your file was uploaded. Please continue with your subscription operation."
);
echo ajax_file_upload( $args );

Further usage

Child theme

This plugin supports child theme. You can copy the entire plugin file to your active theme, and there you can modifications and changes to all the plugin files except the ajax-file-upload.php which is the core file. Neat huh? useful when you want to customize the shortcode template more or edit a little bit of jQuery and CSS..

JavaScript events

This plugin creates DOM events that you can hook into to perform your required actions. Here are the events created by far:

afu_got_response

afu? that's the plugin's prefix. This event is initiated when an upload is processed or not, mainly when the ajax request is completed successfully, and it has data attached to it which you can access through event.data method:

window.addEventListener( "afu_got_response", function(e){
    var data = e.data; // full data object
    if( data.response.success ) { // success
        console.log( data.response.media_uri ); // the uploaded media URL
    }
}, false);

Do a console.log(e.data) there's much more useful data included with the event's attached data.

afu_file_uploaded

Same as the previous one, but afu_file_uploaded is only called when the file was successfully uploaded. You can use it to get the media URI with e.data.response.media_uri as you set the event listener

window.addEventListener( "afu_file_uploaded", function(e){
    if( "undefined" !== typeof e.data.response.media_uri ) {
        console.log( e.data.response.media_uri ); // the uploaded media URL
    }
}, false);

afu_error_uploading

Runs when a file was not uploaded. Useful data are included about the file, the applied settings and the response.

window.addEventListener( "afu_error_uploading", function(e){
    console.log( e.data ); // debugging
}, false);

afu_file_removed

Runs when a file was not uploaded. Useful data are included about the file, the applied settings and the response.

window.addEventListener( "afu_file_removed", function(e){
    console.log( e.data.this ); // the clicked button
    console.log( e.data.container ); // the container div of this button if you want to apply changes to its children or so
}, false);

afu_upload_loading

Runs right before an upload in being initiated. It can be used to do stuff while a user is waiting in the front-end for a file to process. Use other events to stop this when needed.

window.addEventListener( "afu_upload_loading", function(e){
    console.log( e.data.task_data ); // the upload settings and properties
    console.log( e.data.selector ); // the container div of the buttons used to process the current upload
}, false);

Thank you!

Thanks for reading about this plugin. This plugin is totally free and open-source, that means you can contribute to it to add many more cool features and improve it better. Interested? hit me up at samelh.com/contact/. AFU is available on the free open source software repository Github.

If you like it by far, please take some time to leave us a ☆☆☆☆☆ rating on WordPress, a star ☆ on the Github repository, and thank you for your time!

Go to settings

Star on Github - Share on Twitter - Follow @Samuel_Elh on Twitter - Find support - samelh.com