Thursday 17 November 2011

NeatUpload jQuery plugin – Examples – Part 1

Sorry for the delay but it’s been a busy month, well, in my previous post I promised some examples in different scenarios on how to use the plugin. So, let’s start with the simplest scenario:

Scenario 1 – Using default functionality and default visual appearance.
The basic structure is:
$(function() {
    $("#file1").neatupload({
        postDataUrl: "path/to/the/server/",
        fnShowStatus: function (plugin, index, data) {
            // handle the data progress values in order to make some visual feedback.
        }
    });
});

Here, we have the two essential parameters:
·         postDataUrl, the path for the elements in server side who is going to handle the POST.
·         fnShowStatus, in fact, this is not a required parameter but this function is ideal to keep visual feedback of uploading process, and here we have three parameters in the function:
o   The plugin object, available for call any function.
o   The file index, usually used for keep track on which file is, it is increased each time an upload in queued.
o   The data, JSON object with useful data for show on screen, such as: status, percent, speed, etc. Here is an example.
{
"Status":"Completed",
"BytesRead":806688,
"BytesTotal":806688,
"PercentComplete":100,
"BytesPerSec":12927672,
"Message":"",
"SecsRemaining":0,
"SecsElapsed":0,
"CurrentFileName":" picture01.jpg",
"ProcessingState":null,
"Files":
[
{
"ControlUniqueID":"fileField",
"FileName":"picture01.jpg",
"ContentType":"image/jpeg",
"ContentLength":806466
}
]
}

In the previous examples I’ve done something like this: 
$(function() {
        $("#file1").neatupload({
        postDataUrl: $("input[type=hidden][id=upload-action]").val(),
        fnShowStatus: function (plugin, index, data) {
            $('span#progress-file').text(data.PercentComplete + "%");
        }
    });
});

In this case, the only thing we are doing is get the percent complete each time the internal timer-scheduled poll returns a value and display it in a prepared span. That may look good, but What if I don’t like the add link or the upload link? Or what if I want change these texts?

Scenario 2 – Modifying the links ‘add’ and ‘upload’.
The last thing I want users to be is tied to defaults, let’s start by changing the texts for the actions add and upload. I’ll introduce you three new plugin parameters:
·         textAdd: Text for the link Add
·         textUpload: Text for the link Upload
·         textCancel: Text for the link Cancel
Sometimes we have to produce applications that are going to be viewed by people from different cultures and languages, so the static texts are not an option for these cases, and that’s why I let open the text for these links. In the example I use a simple way to change the texts, but I want you to realize the power of this choice.

@{
    // get the text from wherever i.e. some i18n service in the application
    var textAdd = "Add a file to upload list";
    var textUpload = "Start Upload";
    var textCancel = "Abort Operation";
}
(...)
<script type="text/javascript" defer="defer">
    $(function() {
        $("#file1").neatupload({
            postDataUrl: $("input[type=hidden][id=upload-action]").val(),
            fnShowStatus: function (plugin, index, data) {
                $('span#progress-file').text(data.PercentComplete + "%");
            },
            textAdd: "@textAdd",
            textUpload: "@textUpload",
            textCancel: "@textCancel"
        });
    });
</script>

Another way for changing these links and not just the texts is through other two parameters, this time they replace the entire ‘a’ element by whatever you specify to. They are:
·         selectorButtonAdd: jQuery selector indicating how to get the DOM element that will click for the add action.
·         selectorButtonUpload: jQuery selector indicating how to get the DOM element that will click for the upload action.

This time the parameters regarding the text for add and upload will be ignored, if you change the element, you are responsible for give them their own text using any strategy. So the example is as follows:
@{
    // get the text from wherever i.e. some i18n service in the application
    var textAdd = "Add a file to upload list";
    var textUpload = "Start Upload";
    var textCancel = "Abort Operation";
}
(...)
<script type="text/javascript" defer="defer">
    $(function() {
        $("#file1").neatupload({
            postDataUrl: $("input[type=hidden][id=upload-action]").val(),
            fnShowStatus: function (plugin, index, data) {
                $('span#progress-file').text(data.PercentComplete + "%");
            },
            textCancel: "@textCancel",
            selectorButtonAdd: "input[name=addfile]",
            selectorButtonUpload: "input[name=uploadfile]"
        });
    });
</script>
(...)
<input type="button" name="addfile" value="@textAdd" />
<input type="button" name="uploadfile" value="@textUpload" />

The source code is available here.

No comments:

Post a Comment