Krajee
Thankful to Krajee! BUY A COFFEEor to get more out of us.

The plugin supports the following methods. To view a demonstration of various plugin methods, click here.

Many of the methods below support method chaining because they return the file input element as a jQuery object.

Tip

Not seeing the updated content on this page! Hard refresh your browser to clean cache for this page (e.g. SHIFT-F5 on Windows Chrome)

paste

This method can be triggered on the paste event on any HTML element on the page. It allows you to paste the files copied in the client's clipboard onto the fileinput. By default, this method is internally invoked by the plugin on the input element displaying the file caption name. You must supply the jQuery event object as a property. This method returns the file input element as a jQuery object and can thus be chained with other methods. An example of usage of this method is shown below:

$('#any-custom-text-input').on('paste', function(eventObj) {
    $('#input-id').fileinput('paste', eventObj); // copies files or images data in clipboard
});

enable

Enable the file input. This method returns the file input element as a jQuery object and can thus be chained with other methods.

$('#input-id').fileinput('enable');

// method chaining with disable
$('#input-id').fileinput('enable').fileinput('disable');

reset

Softer reset of the file input than the clear method. It cleans up the preview thumbnails (except successful uploads and initialPreview) and cleans up the ajax upload file stack. But this method does not directly clear the native file input of the files selected. This cleanup typically happens automatically when the enveloping form is reset. It thus differs a bit from the clear method which is a more deep hard reset and involves clearing the file input as well as clearing of the files in the preview. This method returns the file input element as a jQuery object and can thus be chained with other methods. However, note that when resetting the form enveloping the native file input - the clear method is automatically called and not this method.

$('#input-id').fileinput('reset');

// method chaining
$('#input-id').fileinput('reset').trigger('custom-event');

destroy

Destroys the file input plugin and reverts to a normal native file input. This method returns the file input element as a jQuery object and can thus be chained with other methods.

$('#input-id').fileinput('destroy');

// method chaining (and reinitializing plugin after destroy with new options)
$('#input-id').fileinput('destroy').fileinput({showPreview: false});

refresh

Refreshes the file input plugin based on options provided. You can supply an array of plugin options as a parameter. The difference between refresh method and reinitializing the plugin (after destroy) - is that, the refresh method will retain original plugin options and override the new options supplied. However, one cannot update the initialPreview via the refresh method. The refresh method returns the file input element as a jQuery object and can thus be chained with other methods.

Note

The refresh method cannot be used to update the initialPreview or initialPreviewConfig since v4.4.x. In case you need to replace initialPreview, then use the plugin's destroy method instead and then reinitialize the plugin with the new options. Note that when reinitializing after a destroy, you must provide all the options for the plugin to reinitialize (unlike the refresh).

// example 1 (disable at runtime)
$('#input-id').attr('disabled', 'disabled');
$('#input-id').fileinput('refresh');

// example 2 (modify plugin options at runtime)
$('#input-id').fileinput('refresh', {browseLabel: 'Select...', removeLabel: 'Delete'});

// method chaining
$('#input-id').fileinput('refresh', {showCaption: false}).fileinput('disable');

clear

Clear the file input. This method clears the preview of all non-uploaded files, clears the ajax filestack, and also clears the native file input. This method thus provides a more deeper cleaning of the fileinput as compared to the reset method. This method is automatically called when the main Remove button beside the file Browse button is clicked OR the enveloping native form RESET action is triggered (e.g. via a form RESET button). This method returns the file input element as a jQuery object and can thus be chained with other methods.

$('#input-id').fileinput('clear');

// method chaining
$('#input-id').fileinput('clear').fileinput('disable');

upload

Trigger ajax upload of the files that are selected. Applicable only if uploadUrl is set. This method returns the file input element as a jQuery object and can thus be chained with other methods.

$('#input-id').fileinput('upload');

// method chaining
$('#input-id').fileinput('upload').fileinput('disable');

cancel

Cancel an ongoing ajax upload of the files. This method returns the file input element as a jQuery object and can thus be chained with other methods.

$('#input-id').fileinput('cancel');

// method chaining
$('#input-id').fileinput('cancel').fileinput('disable');

pause

Pause an ongoing resumable ajax upload of the files (applicable only when enableResumableUpload property to true). This method returns the file input element as a jQuery object and can thus be chained with other methods.

$('#input-id').fileinput('pause');

// method chaining
$('#input-id').fileinput('pause').fileinput('disable');

resume

Resume a paused resumable ajax upload of the files (applicable only when enableResumableUpload property to true). This method returns the file input element as a jQuery object and can thus be chained with other methods.

$('#input-id').fileinput('resume');

// method chaining
$('#input-id').fileinput('resume').fileinput('unlock');

lock

Locks the file input by disabling all actions/buttons except a cancel button to abort ongoing AJAX requests (for ajax uploads only). This method returns the file input element as a jQuery object and can thus be chained with other methods.

$('#input-id').fileinput('lock');

// method chaining
$('#input-id').fileinput('lock').fileinput('disable');

unlock

Unlocks and enables the file input back again by reversing the outcome of the lock action. This method returns the file input element as a jQuery object and can thus be chained with other methods.

$('#input-id').fileinput('unlock');

// method chaining
$('#input-id').fileinput('unlock').fileinput('disable');

addToStack

This method pushes (appends) a file object to the cached file stack array for upload (note that this only adds files to the internal stack and does not update the preview). This method accepts the following parameters:

  • file: blob, filelist / file blob object typically returned when selecting a file in a native HTML file input

  • id: string, unique identifier for the file (if not passed, the plugin will attempt to autogenerate this using the file object based on the generateFileId setting.

$('#input-id').fileinput('addToStack', fileObj, id);
// where `fileObj` is the file blob object instance
// and `id` is the optional file identifier

clearFileStack

This method clears the entire file upload array stack (note that this only clears files from the internal stack and does not update the preview).

$('#input-id').fileinput('clearFileStack');

getFileStack

This method returns an object (associative array) containing the file objects selected indexed by file identifer (see generateFileId option). This method is useful and applicable only for ajaxUploads when uploadUrl is set). This method will not return files that failed validation error or which have already been uploaded.

As mentioned, note that this method is useful to get file objects only for ajax uploads. For normal form based submission, you can get the files selected by directly reading the input value i.e. $('#input-id').val().

// example of reading filestack
var filestack = $('#input-id').fileinput('getFileStack'), fstack = [];
$.each(filestack, function(fileId, fileObj) {
    if (fileObj !== undefined) {
        fstack.push(fileObj);
    }
});
console.log('Files selected - ' + fstack.length);

getFileList

This method returns an array of file objects (in case you do not wish to read an object/ associative array as returned by getFileStack). This method is useful and applicable only for ajaxUploads when uploadUrl is set). This method will not return files that failed validation error or which have already been uploaded.

As mentioned, note that this method is useful to get file objects only for ajax uploads. For normal form based submission, you can get the files selected by directly reading the input value i.e. $('#input-id').val().

var files = $('#input-id').fileinput('getFileList'); // returns file list selected

getFilesCount

This method returns the count of all files pending upload and files already uploaded (based on initial preview). The count will include files selected from client (not uploaded) PLUS the files uploaded to server and displayed via initial preview. The validateInitialCount property will be used to check if initial preview count will be used. This method will return count of files for both normal form submissions as well as ajaxUploads when uploadUrl is set.

This method accepts the following parameters:

  • includeInitial: boolean, whether to include initial preview files in the count. Defaults to false. If set to true will return the total count of files pending upload PLUS files in initial preview.

var filesCount = $('#input-id').fileinput('getFilesCount'); // returns count of files (pending upload)\
var totalFilesCount = $('#input-id').fileinput('getFilesCount', true); // returns count of files (pending upload plus files already uploaded and set via initial preview)

readFiles

This method reads a FileList object, appends/pushes it to the file object stack, and also updates the preview to display the files based on the plugin settings. Note that this method is meaningful to use only for ajaxUploads when uploadUrl is set. You must supply a FileList object as a parameter.

$('#input-id').fileinput('readFiles', files); // where `files` is a FileList object

zoom

Zooms the content in detailed preview for the passed thumbnail frame id parameter. This method takes in the following parameters:

  • frameId: string, the HTML identifier for the file preview thumbnail frame for which the exif data will be returned

$('#input-id').fileinput('zoom', 'preview-123882'); // pass the HTML identifier for the thumbnail frame

getPreview

Returns the initial preview content, the initial preview configuration, and initial preview thumb tags. This is returned as an object (associative array) of the following format:

{
    content: ['content1', 'content2'],
    config: [
        {
            // initial preview config for content1
        },
        {
            // initial preview config for content2
        },

    ],
    tags: [
        {
            // initial preview tags for content1
        },
        {
            // initial preview tags for content2
        },
    ]
}

Usage example:

console.log($('#input-id').fileinput('getPreview'));

getExif

Gets the exif data for the specified file thumbnail frame (applicable only for JPEG image file types). The exif data is returned as an object using the piexif.js library. If exif data is not found - this will be returned as NULL. The piexif.min.js plugin is required to be loaded before fileinput.min.js for restoring the exif data to the image files. This method takes in the following parameters:

  • frameId: string, the HTML identifier for the file preview thumbnail frame for which the exif data will be returned

Usage example:

console.log($('#input-id').fileinput('getPreview', 'yourThumbFrameId'));

getFrames

Returns the list of file preview thumbnail frames as jQuery objects. This method takes in the following parameters:

  • cssFilter: string, additional CSS filter to be applied to restrict and return the relevant thumbnail preview frames

Usage example:

// no css filter - returns all thumbnail frames
console.log($('#input1').fileinput('getFrames'));

// returns only initial preview thumbnail frames
console.log($('#input2').fileinput('getFrames', '.file-preview-initial'));

// returns all  thumbnail frames except the successfully uploaded thumbnails
console.log($('#input3').fileinput('getFrames', ':not(.file-preview-success)'));

showUserError

This method can be used to show a custom user error and can typically be called from other plugin events. The method takes in the following properties:

  • message: string, custom error message to show.

  • data: object, the data object where you can pass the fileId key (the file identifier) which can be used to show file specific error message. If this object is not passed or not readable or does not contain the fileId key, then the error message will be shown universally and not specific to each file. Typically, the data object is already available from events like fileuploaderror which can be passed as a parameter to this method.

  • retainErrorHistory: boolean, whether to retain history of previous errors. Defaults to false.

const userMessage = 'We could not process the upload because of a server error.';
var $input = $('#file-input-id');

// Scenario 1: show file specific error message on `fileuploaderror` event
// (this example retains error history)
$input.on('fileuploaderror', function(event, data) {
  var retainErrorHistory = true; // whether to retain error history
  $input.fileinput('showUserError', userMessage, data, retainErrorHistory);
});

// Scenario 2: show file specific error message on `fileuploaderror` event
// (this example does not retains error history)
$input.on('fileuploaderror', function(event, data) {
  var retainErrorHistory = false; // whether to retain error history
  $input.fileinput('showUserError', userMessage, data, retainErrorHistory);
});

// Scenario 3: show generic specific error message on `fileuploaderror` event
$input.on('fileuploaderror', function(event, data) {
  var retainErrorHistory = false; // whether to retain error history
  $input.fileinput('showUserError', userMessage, false, retainErrorHistory);
});

Note

You can now visit the Krajee Webtips Q & A forum for searching OR asking questions OR helping programmers with answers on these extensions and plugins. For asking a question click here. Select the appropriate question category (i.e. Krajee Plugins) and choose this current page plugin in the question related to field.

The comments and discussion section below are intended for generic discussions or feedback for this plugin. Developers may not be able to search or lookup here specific questions or tips on usage for this plugin.

 
visitors to Krajee Jquery Plugins since 22-May-2017