File Input Features

1. The plugin will convert a simple HTML file input to an advanced file picker control. Will help fallback to a normal HTML file input for browsers not supporting JQuery or Javascript.

2. The file input consists of the following three sections with options and templates to control the display:

   • file caption section: to display a brief information of the file(s) selected

   • file action buttons section: to browse, remove, and upload files.

   • file preview section: to display the selected files on client for preview (supports preview of image, text, flash, and video file types). Other file types will be displayed as normal thumbnails.

3. The plugin automatically converts an input with type = file to an advanced file picker input if you set its class = file. All options to the input can be passed as HTML5 data attributes.

4. Ability to select and preview multiple files. Uses HTML 5 File reader API to read and preview files. Displays the progress of files being being loaded onto the preview zone, in case many files are chosen.

5. Offers predefined templates and CSS classes which can be changed to style your file-input display as per your needs.

6. With v1.5.0, you can now configure the plugin to show an initial preview of images/files with initial caption (more useful for record update scenarios). Refer the initialPreview and initialCaption properties in the plugin options section for configuring this.

7. Option to show/hide any or all of the following:

   • caption section

   • preview section

   • upload button

   • remove button

8. Customise the location of the target container elements to display the entire plugin, the caption container, the caption text, the preview container, preview image, and preview status.

9. For text file previews, autowrap the text to the thumbnail width, and show a wrap indicator link to display complete text on hover. You can customize the wrap indicator (which defaults to …).

10. Customise the messages for preview, progress, and files selected.

11. Upload action defaults to form submit. Supports an upload route/server action parameter for custom ajax based upload.

12. Triggers JQuery events for advanced development. Events currently available are filereset, fileclear, filecleared, fileloaded, and fileerror.

13. Disabled and readonly file input support.

14. Dynamically auto size the file captions for long file names exceeding container width.

15. Raise new fileimageuploaded event that fires after image is completely loaded on the preview container.

16. Autosize preview images when they exceed the size of the preview container.

17. Completely templatized and extensible to allow configuration of the file-input the way the developer wants.

18. Preview intelligence based on various file preview types. The inbuilt file support types are categorized as image, text, html, video, audio, flash, object, and other.

19. allowedPreviewTypes: You can now configure which all file types are allowed to be shown as a preview. This defaults to ['image', 'html', 'text', 'video', 'audio', 'flash', 'object']. Thus all file types are treated as an object to preview by default. For exampleTo preview only image and video, you can set this to ['image', 'video']. To disable content preview for all file-types and show the previewIcon instead as a thumbnail, set this to null, empty, or false.

20. allowedPreviewMimeTypes: In addition to allowedPreviewTypes, you can also control which all mime types can be displayed for preview. This defaults to null, meaning all mime types are supported. >NOTE: With release 2.5.0 you can now control which file types or extensions are allowed for upload by setting allowedFileTypes and allowedFileExtensions.

21. layoutTemplates: Allows you to configure all layout template settings within one property. The layout objects that can be configured are: main1, main2, preview, caption, and modal.

22. previewTemplates: All preview templates for each preview type have been combined into one property, instead of separate templates for image, text etc. The keys are the formats as set in allowedPreviewTypes and values are the templates used for previewing. There are default prebuilt templates for each preview file type (generic, image, text, html, video, audio, flash, object, and other). The generic template is used only for displaying initialPreview content using direct markup.

23. previewSettings: Allows you to configure width and height for each preview image type. The plugin has default widths and heights predefined for each type i.e image, text, html, video, audio, flash, and object.

24. fileTypeSettings: Allows you to configure and identify each preview file type using a callback. The plugin has default callbacks predefined to identify each type i.e image, text, html, video, audio, flash, and object.

25. Replacing tags within templates has been enhanced. With this release it will automatically check for multiple occurrences of each tag to replace within a template string.

26. Manipulate events and add your own custom validation messages easily by returning output to abort uploads in any of the other events.

27. Support for translations and locales.

File Upload Features

With release 4.0.0, the plugin now also includes inbuilt support for AJAX Uploads and selectively adding or deleting files. AJAX upload functionality are built upon HTML5 FormData and XMLHttpRequest Level 2 standards. Most modern browsers do support this standard, but the plugin will automatically degrade to normal form based submission for unsupported browsers.

1. Add functionality for AJAX based UPLOAD using HTML5 FormData (most modern browsers support it). Will degrade to normal Form Based File submission if this is not supported.

2. To use AJAX Upload, one must set the uploadUrl property.

3. Enhance plugin to now allow files to be added, appended, removed (based on FEEDBACK from many). Thus one can append files to preview.

4. New DRAG & DROP zone available in preview to drag and drop files and append.

5. Delete or upload files one by one OR in batch.

6. If showPreview is set to false, or uploadUrl is not supported plugin will degrade to normal form based upload.

7. Configurable indicators for file awaiting upload, file successfully uploaded, files errored in upload.

8. Ability to add extra form data with ajax based uploads.

9. Upload progress bar and individual thumbnail upload indicators.

10. Ability to cancel and abort ongoing AJAX uploads.

11. Build up initial preview content (e.g. gallery of saved images). You can set initial preview actions (prebuilt support for initial preview delete). Other custom action buttons can be set for initial preview thumbnails as well.

12. Ensure plugin is still lean in size and optimized for performance inspite of the above features by optimally utilizing HTML5 & jquery features only.

13. Automatically refresh preview with content from server as soon as an ajax upload finishes.

The plugin can be installed automatically or manually using one of these options:

Bower Package Manager

$ bower install bootstrap-fileinput

Composer Package Manager

$ php composer.phar require kartik-v/bootstrap-fileinput "dev-master"

or add:

"kartik-v/bootstrap-fileinput": "dev-master"

to your composer.json file

Manual Install

You can also manually install the plugin easily to your project. Just download the source ZIP or TAR ball and extract the plugin assets (css and js folders) into your project.

1. Bootstrap 3.x. However, the plugin can be customized for any CSS framework using templates.

2. Latest JQuery

3. Most modern browsers supporting HTML5 file inputs and FileReader API including CSS3 & JQuery.

4. For file previews to work, the browser must support the HTML5 FileReaderAPI - else the plugin will auto-degrade to a normal file input. For Internet Explorer, one must use IE versions 10 and above. IE9 and below will work as a normal file input, and will not support multiple file selection or the HTML 5 FileReader API.

5. With release 4.0, AJAX uploads are supported. AJAX uploads require that the browser support HTML5 FormData and XHR2 (XMLHttpRequest 2). Most modern browsers support FormData and XHR2. The plugin will automatically degrade to normal form based submission for browsers not supporting AJAX uploads.

The plugin uses HTML 5 features to achieve various functionalities. Most modern browsers support these features. However, to know if your browser supports these functions you must run through these checks once below.

Largely speaking, the plugin can be configured in one of the following two different modes for upload. IMPORTANT: Do not try to combine the modes below to receive file data as you will receive inconsistent and/or erroneous output.

1. Form Submission: In this mode, you do not set the uploadUrl property. The plugin will use the native file input to store files and it can be read after a normal FORM submission (you must envelop the input within a FORM). This is useful for single file uploads OR simpler scenarios of multiple file uploads. Configuration is straightforward as you can read all data POSTED from a native form submission. However, note that the native file input is read only and cannot be modified or updated by external code. Especially for multiple file input selections, ONE cannot append files to an already selected file list. If one tries to select files on an already selected file input, it will overwrite and clear the previous selection. Similarly, one cannot selectively remove/delete files that have been added before upload in this mode.

2. Ajax Submission: In this mode, you MUST SET the uploadUrl property to a VALID ajax processing server action/URL. If the uploadUrl is set, then the plugin automatically assumes an ajax upload for the scenario. The plugin offers advanced features for ajax submission that is not available in form submission. Features like drag and drop of files, appending/removing files in preview zone, getting a progress bar for your uploads are all possible ONLY IN THIS mode. Your browser must support HTML5 FormData/XHR2 for this to work and your server code that processes the ajax call must return a valid JSON response.

   Note

   As an advanced scenario, the plugin allows you to process the ajax upload even if there are no files selected but a valid uploadExtraData is sent with the ajax response. The events filebatchpreupload, filebatchuploadsuccess, filebatchuploadcomplete, or filebatchuploaderror will be triggered in this case. It will not have any data for the files selected, but will allow the extra data to be sent.

Step 1: Load the following assets in your header.

<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css" rel="stylesheet">
<link href="path/to/css/fileinput.min.css" media="all" rel="stylesheet" type="text/css" />
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.0/jquery.min.js"></script>
<script src="path/to/js/fileinput.min.js" type="text/javascript"></script>
<!-- bootstrap.js below is only needed if you wish to use the feature of viewing details 
     of text file preview via modal dialog -->
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js" type="text/javascript"></script>
<!-- optionally if you need translation for your language then include 
    locale file as mentioned below -->
<script src="path/to/js/fileinput_locale_<lang>.js"></script>

If you noticed, you need to load the jquery.min.js and bootstrap.min.css in addition to the fileinput.min.css and fileinput.min.js. The locale file fileinput_locale_<lang>.js can be optionally included for translating for your language if needed.

Step 2a: Initialize the plugin on your page. For example,

// initialize with defaults
$("#input-id").fileinput();
 
// with plugin options
$("#input-id").fileinput({'showUpload':false, 'previewFileType':'any'});

The #input-id is the identifier for the input (e.g. type=file) on your page, which is hidden automatically by the plugin.

Step 2b: Alternatively, you can directly set the plugin options to any input, through HTML 5 data attributes to your input field.

<input id="input-id" type="file" class="file" data-preview-file-type="text">

You need to setup the server methods to parse and return the right response via AJAX. You can setup uploads in asynchronous OR synchronous modes as described below.

The plugin supports these following options:

language

string language configuration for the plugin to enable the plugin to display messages for your locale (you must set the ISO code for the language). You can have multiple language widgets on the same page. The locale JS file for the language code must be defined as mentioned in the translations section. The file must be loaded after fileinput.js.

showCaption

boolean whether to display the file caption. Defaults to true.

showPreview

boolean whether to display the file preview. Defaults to true.

showRemove

boolean whether to display the file remove/clear button. Defaults to true.

showUpload

boolean whether to display the file upload button. Defaults to true. This will default to a form submit button, unless the uploadUrl is specified.

showCancel

boolean whether to display the file upload cancel button. Defaults to true. This will be only enabled and displayed when an AJAX upload is in process.

showUploadedThumbs

boolean whether to persist display of the uploaded file thumbnails in the preview window (for ajax uploads) until the remove/clear button is pressed. Defaults to true. When set to false, a next batch of files selected for upload will clear these thumbnails from preview.

autoReplace

boolean whether to automatically replace the files in the preview after the maxFileCount limit is reached and a new set of file(s) is/are selected. This will only work if a valid maxFileCount is set. Defaults to false.

captionClass

string any additional CSS class to append to the caption container.

previewClass

string any additional CSS class to append to the preview container.

mainClass

string any additional CSS class to append to the main plugin container.

initialPreview

string | array the initial preview content to be displayed. You can pass the minimal HTML markup for displaying your image, text, or file. If set as a string, this will display a single file in the initial preview if there is no delimiter. You can set a delimiter (as defined in initialDelimiter) to show multiple files in initial preview. If set as an array, it will display all files in the array as an initial preview (useful for multiple file upload scenarios).

The following CSS classes will need to be added for displaying each file type as per the plugin style theme:

• image files: Include CSS class file-preview-image
• text files: Include CSS class file-preview-text
• other files: Include CSS class file-preview-other

Examples of how you can setup various files for initial preview:

// for image files
initialPreview: [
    "<img src='/images/desert.jpg' class='file-preview-image' alt='Desert' title='Desert'>",
    "<img src='/images/jellyfish.jpg' class='file-preview-image' alt='Jelly Fish' title='Jelly Fish'>",
],

// for text files
initialPreview: "<div class='file-preview-text' title='NOTES.txt'>" +
    "This is the sample text file content upto wrapTextLength of 250 characters" +
    "<span class='wrap-indicator' onclick='$(\"#show-detailed-text\").modal(\"show\")' title='NOTES.txt'>[…]</span>" +
    "</div>"

// for other files
initialPreview: "<div class='file-preview-text'>" +
    "<h2><i class='glyphicon glyphicon-file'></i></h2>" +
    "Filename.xlsx" + "</div>"

initialPreviewCount

int, the count of initial preview items that will be added to the count of files selected in preview. This is applicable when displaying the right caption, when overwriteInitial is set to false.

initialPreviewDelimiter

string, the delimiter to be used for splitting the initial preview content as individual file thumbnails (applicable only if initialPreview is passed as a string instead of array). Defaults to *$$*.

initialPreviewConfig

array, the configuration for setting up important properties for each initialPreview item (that is setup as part of initialPreview). Each element in the array should be an object/associative array consisting of the following keys:

• caption: string, the caption or filename to display for each initial preview item content.

• width: string, the CSS width of the image/content displayed.

• url: string, the URL for deleting the image/content in the initial preview via AJAX post response. This will default to deleteUrl if not set.

• key: string | object, the key that will be passed as data to the url via AJAX POST.

• frameClass: string, the additional frame css class to set for the file's thumbnail frame.

• frameAttr: object, the HTML attribute settings (set as key:value pairs) for the thumbnail frame.

• extra: object | function, the extra data that will be passed as data to the initial preview delete url/AJAX server call via POST. This will default to deleteExtraData if not set.

An example configuration of initialPreviewConfig (for the previously set initialPreviewContent) can be:

// setup initial preview with data keys
initialPreview: [
    "<img src='/images/desert.jpg' class='file-preview-image' alt='Desert' title='Desert'>",
    "<img src='/images/jellyfish.jpg' class='file-preview-image' alt='Jelly Fish' title='Jelly Fish'>",
],
// initial preview configuration
initialPreviewConfig: initialPreviewConfig: [
    {
        caption: 'desert.jpg',
        width: '120px',
        url: '/localhost/avatar/delete',
        key: 100,
        extra: {id: 100}
    },
    {
        caption: 'jellyfish.jpg', 
        width: '120px', 
        url: '/localhost/avatar/delete', 
        key: 101, 
        frameClass: 'my-custom-frame-css',
        frameAttr: {
            style: 'height:80px',
            title: 'My Custom Title',
        },
        extra: function() { 
            return {id: $("#id").val()};
        },
    }
]

initialPreviewShowDelete

bool, whether the delete button will be displayed for each thumbnail that has been created with initialPreview.

previewThumbTags

array, this will be a list of tags used in thumbnail templates that will be replaced dynamically within the thumbnail markup, when the thumbnail is rendered. For example:

// change thumbnail footer template
layoutTemplates.footer = 'lt;div class="file-thumbnail-footer">\n' +
'    lt;div class="file-caption-name">{caption}lt;/div>\n' +
'    {CUSTOM_TAG_NEW}\n' +
'    {CUSTOM_TAG_INIT}\n' +
'    {actions}\n' +
'lt;/div>';

// set preview template tags
previewThumbTags = {
    '{CUSTOM_TAG_NEW}': 'lt;span class="custom-css">CUSTOM MARKUPlt;/span>',
    '{CUSTOM_TAG_INIT}': ' '
};

initialPreviewThumbTags

array, this is an extension of previewThumbTags specifically for initial preview content - but will be configured as an array of objects corresponding to each initial preview thumbnail. The initial preview thumbnails set via initialPreview will read this configuration for replacing tags. Extending example above:

// change thumbnail footer template
layoutTemplates.footer = 'lt;div class="file-thumbnail-footer">\n' +
'    lt;div class="file-caption-name">{caption}lt;/div>\n' +
'    {CUSTOM_TAG_NEW}\n' +
'    {CUSTOM_TAG_INIT}\n' +
'    {actions}\n' +
'lt;/div>';

// setup initial preview with data keys
initialPreview: [
    "lt;img src='/images/desert.jpg' class='file-preview-image' alt='Desert' title='Desert'>",
    "lt;img src='/images/jellyfish.jpg' class='file-preview-image' alt='Jelly Fish' title='Jelly Fish'>",
],

// set initial preview template tags
initialPreviewThumbTags = {
    '{CUSTOM_TAG_NEW}': ' ',
    '{CUSTOM_TAG_INIT}': 'lt;span class="custom-css">CUSTOM MARKUPlt;/span>'
};

deleteExtraData

object | function the extra data that will be passed as data to the initial preview delete url/AJAX server call via POST. This will be overridden by the initialPreviewConfig['extra'] property. This property is only applicable for ajax deletions in initial preview and when you have set a value for initialPreviewConfig['url'] or deleteUrl.

This can be setup either as an object (associative array of keys and values) or as a function callback. As an object, it can be set for example as:

  {id: 100, value: '100 Details'}

As a function callback, it can be setup for example as:

function() {
    var obj = {};
    $('.your-form-class').find('input').each(function() {
        var id = $(this).attr('id'), val = $(this).val();
        obj[id] = val;
    });
    return obj;
}

deleteUrl

string, the URL for deleting the image/content in the initial preview via AJAX post response. This will be overridden by the initialPreviewConfig['url'] property.

initialCaption

string the initial preview caption text to be displayed. If you do not set a value here and initialPreview is set to true this will default to "{preview-file-count} files selected", where {preview-file-count} is the count of the files passed in initialPreview.

overwriteInitial

boolean whether you wish to overwrite the initial preview content and caption setup. This defaults to true, whereby, any initialPreview content set will be overwritten, when new file is uploaded or when files are cleared. Setting it to false will help displaying a saved image or file from database always - useful especially when using the multiple file upload feature.

layoutTemplates

object the templates configuration for rendering each part of the layout. You can set the following templates to control the widget layout:

• main1: the template for rendering the widget with caption.

• main2: the template for rendering the widget without caption.

• preview: the template for rendering the preview.

• icon: the icon to render before the caption text.

• caption: the template for rendering the caption.

• modal: the template for rendering the modal (for text file preview zooming).

• progress: the template for the progress bar when upload is in progress (for batch/mass uploads). The following tags will be parsed and replaced automatically:

  • {percent}: will be replaced with the upload progress percentage.

• footer: the template for the footer section of each file preview thumbnail. The following tags will be parsed and replaced automatically:

  • {actions}: will be replaced with the output of the actions template.

• actions: the template for the file action buttons to be displayed within the thumbnail footer. The following tags will be parsed and replaced automatically:

  • {upload}: will be replaced with the output of the actionUpload template.

  • {delete}: will be replaced with the output of the actionDelete template.

• actionDelete: the template for the file delete action button within the thumbnail footer. The following tags will be parsed and replaced automatically:

  • {removeClass}: the css class for the remove button. Will be replaced with the removeClass set within fileActionSettings.

  • {removeIcon}: the icon for the remove button. Will be replaced with the removeIcon set within fileActionSettings.

  • {removeTitle}: the title to display on hover for the remove button. Will be replaced with the removeTitle set within fileActionSettings.

  • {dataUrl}: the URL for deleting the file thumbnail for initialPreview content only. Will be replaced with the url set within initialPreviewConfig.

  • {dataKey}: the key (additional data) that will be passed to the URL above via POST to the AJAX call. Will be replaced with the key set within initialPreviewConfig.
    

• actionUpload: the template for the file upload action button within the thumbnail footer.

  • {uploadClass}: the css class for the upload button. Will be replaced with the uploadClass set within fileActionSettings.

  • {uploadIcon}: the icon for the upload button. Will be replaced with the uploadIcon set within fileActionSettings.

  • {uploadTitle}: the title to display on hover for the upload button. Will be replaced with the uploadTitle set within fileActionSettings.

The main1 and main2 templates would automatically parse the following tags for replacement:

• {class}: the CSS class as set in the mainClass property.

• {preview}: the content parsed by the previewTemplate and will be displayed only if showPreview is true.

• {caption}: the content parsed by the captionTemplate and will be displayed only if showCaption is true.

• {remove}: the file remove/clear button and will be displayed only if showRemove is true.

• {upload}: the file upload button and will be displayed only if showUpload is true.

• {cancel}: the file upload cancel button that will be displayed when AJAX upload is in process to abort the AJAX upload.

• {browse}: the main file browse button to select your files for input.

The progress template would automatically parse the following tags for replacement:

• {class}: the CSS class as set in the progressClass or progressCompleteClass property (depending on the progress percentage).

The preview and caption templates can understand the following special tags which will be replaced:

• {class}: the CSS class as set in the mainClass, captionClass or previewClass properties.

The layoutTemplates if not set will default to:

{
    main1: '{preview}\n' +
        '<div class="kv-upload-progress hide"></div>\n' +
        '<div class="input-group {class}">\n' +
        '   {caption}\n' +
        '   <div class="input-group-btn">\n' +
        '       {remove}\n' +
        '       {cancel}\n' +
        '       {upload}\n' +
        '       {browse}\n' +
        '   </div>\n' +
        '</div>',
    main2: '{preview}\n<div class="kv-upload-progress hide"></div>\n{remove}\n{cancel}\n{upload}\n{browse}\n',
    preview: '<div class="file-preview {class}">\n' +
        '    <div class="close fileinput-remove">×</div>\n' +
        '    <div class="{dropClass}">\n' +
        '    <div class="file-preview-thumbnails">\n' +
        '    </div>\n' +
        '    <div class="clearfix"></div>' +
        '    <div class="file-preview-status text-center text-success"></div>\n' +
        '    <div class="kv-fileinput-error"></div>\n' +
        '    </div>\n' +
        '</div>',
    icon: '<span class="glyphicon glyphicon-file kv-caption-icon"></span>',
    caption: '<div tabindex="-1" class="form-control file-caption {class}">\n' +
        '   <div class="file-caption-name"></div>\n' +
        '</div>',
    btnDefault: '<button type="{type}" tabindex="500" title="{title}" class="{css}"{status}>{icon}{label}</button>',
    btnLink: '<a href="{href}" tabindex="500" title="{title}" class="{css}"{status}>{icon}{label}</a>',
    btnBrowse: '<div tabindex="500" class="{css}"{status}>{icon}{label}</div>',
    modal: '<div id="{id}" class="modal fade">\n' +
        '  <div class="modal-dialog modal-lg">\n' +
        '    <div class="modal-content">\n' +
        '      <div class="modal-header">\n' +
        '        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button>\n' +
        '        <h3 class="modal-title">Detailed Preview <small>{title}</small></h3>\n' +
        '      </div>\n' +
        '      <div class="modal-body">\n' +
        '        <textarea class="form-control" style="font-family:Monaco,Consolas,monospace; height: {height}px;" readonly>{body}</textarea>\n' +
        '      </div>\n' +
        '    </div>\n' +
        '  </div>\n' +
        '</div>',
    zoom: '<button type="button" class="btn btn-default btn-sm btn-block" title="{zoomTitle}: {caption}" onclick="{dialog}">\n' +
        '   {zoomInd}\n' +
        '</button>\n',
    progress: '<div class="progress">\n' +
        '    <div class="progress-bar progress-bar-success progress-bar-striped text-center" role="progressbar" aria-valuenow="{percent}" aria-valuemin="0" aria-valuemax="100" style="width:{percent}%;">\n' +
        '        {percent}%\n' +
        '     </div>\n' +
        '</div>',
    footer: '<div class="file-thumbnail-footer">\n' +
        '    <div class="file-caption-name" style="width:{width}">{caption}</div>\n' +
        '    {actions}\n' +
        '</div>',
    actions: '<div class="file-actions">\n' +
        '    <div class="file-footer-buttons">\n' +
        '        {upload}{delete}' +
        '    </div>\n' +
        '    <div class="file-upload-indicator" tabindex="-1" title="{indicatorTitle}">{indicator}</div>\n' +
        '    <div class="clearfix"></div>\n' +
        '</div>',
    actionDelete: '<button type="button" class="kv-file-remove {removeClass}" title="{removeTitle}"{dataUrl}{dataKey}>{removeIcon}</button>\n',
    actionUpload: '<button type="button" class="kv-file-upload {uploadClass}" title="{uploadTitle}">{uploadIcon}</button>\n'

}

The following templates will be used in rendering the main buttons for upload, remove, cancel, and browse.

• btnDefault: The template for upload, remove, and cancel buttons.

• btnLink: The template for upload button when used with ajax (i.e. when uploadUrl is set).

• btnBrowse: The template for the browse button.

The following tags will be parsed and auto replaced in the above button templates:

• {type}: the HTML button type, defaults to button for most buttons and submit for form based uploads.

• {title}: the title to display on button hover.

• {css}: the CSS class for the button. This is derived from settings for uploadClass or removeClass or cancelClass or browseClass.

• {status}: the disabled status for the button if available (else will be blank).

• {icon}: the button icon as identified by uploadIcon or removeIcon or cancelIcon or browseIcon.

• {label}: the button label as identified by uploadLabel or removeLabel or cancelLabel or browseLabel.

• {href}: applicable only for Upload button for ajax uploads and will be replaced with the uploadUrl property.

previewTemplates

object the templates configuration for rendering each preview file type. The following file types are recognized:

• image: the preview template for image files.

• text: the preview template for text files.

• html: the preview template for html files.

• video: the preview template for video files (supported by HTML 5 video tag).

• audio: the preview template for audio files (supported by HTML 5 audio tag).

• flash: the preview template for flash files (supported currently on webkit browsers).

• object: the preview template for all other files - by default treated as object. To disable this behavior, configure the allowedPreviewTypes property.

• generic: this template is used ONLY for rendering the initialPreview markup content passed directly as a raw format.

The following tags will be parsed and replaced in each of the templates:

• {previewId}: will be replaced with the generated identifier for the preview frame container.

• {data}: will be replaced with the data source for each preview type.

• {width}: will be replaced with the width for the file type as set in previewSettings.

• {height}: will be replaced with the height for the file type as set in previewSettings.

• {caption}: will be replaced with the file name.

• {type}: will be replaced with the file type.

• {content}: this is applicable only for the generic template. It will be replaced with the raw HTML markup as set in initialPreview. None of the above tags will be parsed for the generic template.

• {dialog}: currently applicable only for text file previews. Will be replaced with the JS code to launch the modal dialog.

• {zoomTitle}: currently applicable only for text file previews. This will be replaced with the msgZoomTitle property. This is the title that is displayed on hover of the zoom button (which on clicking will display the text file).

• {zoomInd}: currently applicable only for text file previews. This will be replaced with the zoomIndicator property. This is the title that is displayed on hover of the zoom button (which on clicking will display the text file).

• {heading}: currently applicable only for text file previews. This represents the modal dialog heading title. This will be replaced with the msgZoomModalHeading property.

As noted, if you are coming from an earlier release (before v2.4.0), all preview templates have now been combined into one property, instead of separate templates for image, text etc.

{
    generic: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}">\n' +
        '   {content}\n' +
        '   {footer}\n' +
        '</div>\n',
    html: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}">\n' +
        '    <object data="{data}" type="{type}" width="{width}" height="{height}">\n' +
        '       ' + DEFAULT_PREVIEW + '\n' +
        '    </object>\n' +
        '   {footer}\n' +
        '</div>',
    image: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}">\n' +
        '   <img src="{data}" class="file-preview-image" title="{caption}" alt="{caption}" ' + STYLE_SETTING + '>\n' +
        '   {footer}\n' +
        '</div>\n',
    text: '<div class="file-preview-frame{frameClass}" id="{previewId}" data-fileindex="{fileindex}">\n' +
        '   <pre class="file-preview-text" title="{caption}" ' + STYLE_SETTING + '>{data}</pre>\n' +
        '   <button type="button" class="btn btn-default btn-sm btn-block" title="{zoomText}: {caption}" onclick="{dialog}">\n' +
        '       {zoomInd}\n' +
        '   </button>\n' +
        '   {footer}\n' +
        '</div>',
    video: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" title="{caption}" ' + STYLE_SETTING + '>\n' +
        '   <video width="{width}" height="{height}" controls>\n' +
        '       <source src="{data}" type="{type}">\n' +
        '       ' + DEFAULT_PREVIEW + '\n' +
        '   </video>\n' +
        '   {footer}\n' +
        '</div>\n',
    audio: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" title="{caption}" ' + STYLE_SETTING + '>\n' +
        '   <audio controls>\n' +
        '       <source src="{data}" type="{type}">\n' +
        '       ' + DEFAULT_PREVIEW + '\n' +
        '   </audio>\n' +
        '   {footer}\n' +
        '</div>\n',
    flash: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" title="{caption}" ' + STYLE_SETTING + '>\n' +
        '   <object type="application/x-shockwave-flash" width="{width}" height="{height}" data="{data}">\n' +
        OBJECT_PARAMS + '       ' + DEFAULT_PREVIEW + '\n' +
        '   </object>\n' +
        '   {footer}\n' +
        '</div>\n',
    object: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" title="{caption}" ' + STYLE_SETTING + '>\n' +
        '    <object data="{data}" type="{type}" width="{width}" height="{height}">\n' +
        '      <param name="movie" value="{caption}" />\n' +
        OBJECT_PARAMS + '           ' + DEFAULT_PREVIEW + '\n' +
        '   </object>\n' + 
        '   {footer}\n' +
        '</div>',
    other: '<div class="file-preview-frame{frameClass}" id="{previewId}" data-fileindex="{fileindex}"' +
        ' title="{caption}" ' + STYLE_SETTING + '>\n' +
        '   <div class="file-preview-other-frame">\n'+
        '   ' + DEFAULT_PREVIEW + '\n' +
        '   </div>\n' +
        '   <div class="file-preview-other-footer">{footer}</div>\n' +
        '</div>'
}

The values of the constants used in the above templates are as follows:

STYLE_SETTING = 'style="width:{width};height:{height};"',
OBJECT_PARAMS = '      <param name="controller" value="true" />\n' +
    '      <param name="allowFullScreen" value="true" />\n' +
    '      <param name="allowScriptAccess" value="always" />\n' +
    '      <param name="autoPlay" value="false" />\n' +
    '      <param name="autoStart" value="false" />\n'+
    '      <param name="quality" value="high" />\n',
DEFAULT_PREVIEW = '<div class="file-preview-other">\n' +
    '   <span class="{previewFileIconClass}">{previewFileIcon}</span>\n' +
    '</div>'

where:

• {previewFileIcon}: corresponds to the previewFileIcon property.

• {previewFileIconClass}: corresponds to the previewFileIconClass property.

allowedFileTypes

array the list of allowed file types for upload. This by default is set to null which means the plugin supports all file types for upload. If an invalid file type is found, then a validation error message as set in msgInvalidFileType will be raised. The following types as set in fileTypeSettings are available for setup.

['image', 'html', 'text', 'video', 'audio', 'flash', 'object']

allowedFileExtensions

array the list of allowed file extensions for upload. This by default is set to null which means the plugin supports all file extensions for upload. If an invalid file extension is found, then a validation error message as set in msgInvalidFileExtension will be raised. An example of setting this could be:

['jpg', 'gif', 'png', 'txt']

allowedPreviewTypes

array the list of allowed preview types for your widget. This by default supports all file types for preview. The plugin by default treats each file as an object if it does not match any of the previous types. To disable this behavior, you can remove object from the list of allowedPreviewTypes OR fine tune it through allowedPreviewMimeTypes.To disable content preview for all file-types and show the previewIcon instead as a thumbnail, set this to null, empty, or false.

This is by default setup as following:

['image', 'html', 'text', 'video', 'audio', 'flash', 'object']

allowedPreviewMimeTypes

array the list of allowed mime types for preview. This is set to null by default which means all possible mime types are allowed. This setting works in combination with allowedPreviewTypes to filter only the needed file types allowed for preview. You can check this list of allowed mime types to add to this list if needed.

customLayoutTags

object the list of additional custom tags that will be replaced in the layout templates. This should be an associative array object of key: value pairs, where:

• key: string, is the tag to be replaced and as a standard is recommended to be enclosed between braces.

• value: string|function, is the value that will replace the tag key above. This can be setup either as a string or callback function.

// example 1 - tags with value set as string
customLayoutTags: {
    '{tagA}': '<span class="label label-default">Tag A</span>',
    '{tagB}': 'Tag B',
}

// example 2 - tags with value set as callback
customLayoutTags: {
    '{tagC}': function() {
        return $("#element-id").val();
    }
}

customPreviewTags

object the list of additional custom tags that will be replaced in the preview templates. This should be an associative array object of key: value pairs, where:

• key: string, is the tag to be replaced and as a standard is recommended to be enclosed between braces.

• value: string|function, is the value that will replace the tag key above. This can be setup either as a string or callback function.

// example 1 - tags with value set as string
customPreviewTags: {
    '{tagA}': '<span class="label label-default">Tag A</span>',
    '{tagB}': 'Tag B',
}

// example 2 - tags with value set as callback
customPreviewTags: {
    '{tagC}': function() {
        return $("#element-id").val();
    }
}

previewSettings

object the format settings (width and height) for rendering each preview file type. This is by default setup as following:

{
    image: {width: "auto", height: "160px"},
    html: {width: "213px", height: "160px"},
    text: {width: "160px", height: "136px"},
    video: {width: "213px", height: "160px"},
    audio: {width: "213px", height: "80px"},
    flash: {width: "213px", height: "160px"},
    object: {width: "213px", height: "160px"},
    other: {width: "160px", height: "160px"}
}

fileTypeSettings

object the settings to validate and identify each file type when a file is selected for upload. This is a list of callbacks, which accepts the file mime type and file name as a parameter. This is by default setup as following:

// vType: is the file mime type
// vName: is the file name
{
    image: function(vType, vName) {
        return (typeof vType !== "undefined") ? vType.match('image.*') : vName.match(/\.(gif|png|jpe?g)$/i);
    },
    html: function(vType, vName) {
        return (typeof vType !== "undefined") ? vType == 'text/html' : vName.match(/\.(htm|html)$/i);
    },
    text: function(vType, vName) {
        return typeof vType !== "undefined" && vType.match('text.*') || vName.match(/\.(txt|md|csv|nfo|php|ini)$/i);
    },
    video: function (vType, vName) {
        return typeof vType !== "undefined" && vType.match(/\.video\/(ogg|mp4|webm)$/i) || vName.match(/\.(og?|mp4|webm)$/i);
    },
    audio: function (vType, vName) {
        return typeof vType !== "undefined" && vType.match(/\.audio\/(ogg|mp3|wav)$/i) || vName.match(/\.(ogg|mp3|wav)$/i);
    },
    flash: function (vType, vName) {
        return typeof vType !== "undefined" && vType == 'application/x-shockwave-flash' || vName.match(/\.(swf)$/i);
    },
    object: function (vType, vName) {
        return true;
    },
    other: function (vType, vName) {
        return true;
    },
}

previewFileIcon

string the icon to be shown in each preview file thumbnail when an unreadable file type for preview is detected. Defaults to <i class="glyphicon glyphicon-file"></i> &nbsp;.

previewFileIconClass

string the CSS class to be applied to the preview file icon container. Defaults to file-icon-4x.

previewFileIconSettings

object the preview icon markup settings for each file extension (type). You need to set this as key: value pairs, where the key corresponds to a file extension (e.g. doc, docx, xls etc.), and the value corresponds to the markup of the icon to be rendered. If this is not set OR a file extension is not set here, the preview will default to previewFileIcon. Note that displaying the icons instead of file content is controlled via allowedPreviewTypes and allowedPreviewMimeTypes

You can setup previewFileIconSettings as shown below:

previewFileIconSettings: {
    'doc': '',
    'xls': '',
    'ppt': '',
    'jpg': '',
    'pdf': '',
    'zip': '',
}

previewFileExtSettings

object the extensions to be auto derived for each file extension (type). This is useful if you want to set the same icon for multiple file extension types. You need to set this as `key: value` pairs, where the key corresponds to a file extension as set in previewFileIconSettings (e.g. doc, docx, xls etc.). The value will be a function callback that accepts the following parameter:

• ext, string, the file extension (without the . [dot]) of the file currently selected in the preview.

You can configure the callback to match the set of file extensions (via regex or similar) for each `key` and return a boolean output if the file extension matches.

For example, you can setup `previewFileExtSettings` as shown below:

previewFileExtSettings: {
    'doc': function(ext) {
        return ext.match(/(doc|docx)$/i);
    },
    'xls': function(ext) {
        return ext.match(/(xls|xlsx)$/i);
    },
    'ppt': function(ext) {
        return ext.match(/(ppt|pptx)$/i);
    }
}

browseLabel

string the label to display for the file picker/browse button. Defaults to Browse ….

browseIcon

string the icon to display before the label for the file picker/browse button. Defaults to <i class="glyphicon glyphicon-folder-open"></i> &nbsp;.

browseClass

string the CSS class for the file picker/browse button. Defaults to btn btn-primary.

removeLabel

string the label to display for the file remove button. Defaults to Remove.

removeIcon

string the icon to display before the label for the file picker/remove button. Defaults to <i class="glyphicon glyphicon-trash"></i> &nbsp;.

removeClass

string the CSS class for the file remove button. Defaults to btn btn-default.

removeTitle

string the title to display on hover for the file remove button. Defaults to Clear selected files.

uploadLabel

string the label to display for the file upload button. Defaults to Upload.

uploadIcon

string the icon to display before the label for the file upload button. Defaults to <i class="glyphicon glyphicon-upload"></i> &nbsp;.

uploadClass

string the CSS class for the file upload button. Defaults to btn btn-default.

uploadTitle

string the title to display on hover for the file remove button. Defaults to Upload selected files.

uploadUrl

string the URL for the upload processing action (typically for ajax based processing). Defaults to null. If this is not set or null, then the upload button action will default to form submission. NOTE: This is MANDATORY if you want to use advanced features like drag & drop, append/remove files, selectively upload files via ajax etc. The plugin automatically send $_FILES data to the server with the input `name` attribute as the key if provided. If input name is not set, the key defaults to file-data.

uploadAsync

bool whether the batch upload of multiple files will be asynchronous/in parallel. Defaults to true.

maxFileSize

float the maximum file size for upload in KB. If set to 0, it means size allowed is unlimited. Defaults to 0.

uploadExtraData

object | function, the extra data that will be passed as data to the url/AJAX server call via POST. This property is only applicable for ajax uploads and when you have set a value for uploadUrl.

This can be setup either as an object (associative array of keys and values) or as a function callback. As an object, it can be set for example as:

  {id: 100, value: '100 Details'}

As a function callback, the uploadExtraData can be setup as shown below. Note that for uploading individual file via thumbnail, the callback can also receive the thumbnail previewId and index as parameters. These are described below:

• previewId: the identifier for the preview file container (only available when uploading each thumbnail file)

• index: the zero-based sequential index of the loaded file in the preview list (only available when uploading each thumbnail file)

// previewId and index is only available for individual file upload via the thumbnail
function (previewId, index) {
    var obj = {};
    $('.your-form-class').find('input').each(function() {
        var id = $(this).attr('id'), val = $(this).val();
        obj[id] = val;
    });
    return obj;
}

maxImageWidth

int, the maximum allowed image width in px if you are uploading image files. Defaults to null which means no limit on image width.

maxImageHeight

int, the maximum allowed image height in px if you are uploading image files. Defaults to null which means no limit on image height.

minImageWidth

int, the minimum allowed image width in px if you are uploading image files. Defaults to null which means no limit on image width.

minImageHeight

int, the minimum allowed image height in px if you are uploading image files. Defaults to null which means no limit on image height.

minFileCount

int the minimum number of files allowed for each multiple upload. If set to 0, it means number of files are optional. Defaults to 0.

maxFileCount

int the maximum number of files allowed for each multiple upload. If set to 0, it means number of files allowed is unlimited. Defaults to 0.

validateInitialCount

boolean, whether to include initial preview file count (server uploaded files) in validating minFileCount and maxFileCount. Defaults to false.

msgZoomTitle

string the title displayed (before the file name) on hover of the zoom button for zooming the file content in a modal window. This is currently applicable only for text file previews. Defaults to View details.

msgZoomModalHeading

string the heading of the modal dialog that displays the zoomed file content. This is currently applicable only for text file previews. Defaults to Detailed Preview.

msgSizeTooLarge

string the message to be displayed when the file size exceeds maximum size. Defaults to:

File "{name}" ({size} KB) exceeds maximum allowed upload size of {maxSize} KB. Please retry your upload!

where:

• {name}: will be replaced by the file name being uploaded
• {size}: will be replaced by the uploaded file size
• {maxSize}: will be replaced by the maxFileSize parameter.

msgFilesTooLess

string message to be displayed when the file count is less than the minimum count as set in minFileCount. Defaults to:

You must select at least {n} {files} to upload. Please retry your upload!

where:

• {n}: will be replaced by the allowed minimum files as set in minFileCount.
• {files}: will be replaced with fileSingle or filePlural properties in locale file depending on the minFileCount.

msgFilesTooMany

string the message to be displayed when the file count exceeds maximum count as set in maxFileCount. Defaults to:

Number of files selected for upload ({n}) exceeds maximum allowed limit of {m}. Please retry your upload!

where:

• {n}: will be replaced by number of files selected for upload

• {m}: will be replaced by the allowed maximum files as set in maxFileCount

msgFileNotFound

string the exception message to be displayed when the file selected is not found by the FileReader. Defaults to:

File "{name}" not found!

where:

• {name}: will be replaced by the file name being uploaded

msgFileSecured

string the exception message to be displayed when the file selected is not allowed to be accessed due to a security exception. Defaults to:

Security restrictions prevent reading the file "{name}".

where:

• {name}: will be replaced by the file name being uploaded

msgFileNotReadable

string the exception message to be displayed when the file selected is not readable by the FileReader API. Defaults to:

File "{name}" is not readable.

where:

• {name}: will be replaced by the file name being uploaded

msgFilePreviewAborted

string the exception message to be displayed when the file preview upload is aborted. Defaults to:

File preview aborted for "{name}".

where:

• {name}: will be replaced by the file name being uploaded

msgFilePreviewError

string the exception message to be displayed for any other error when previewing the file. Defaults to:

An error occurred while reading the file "{name}".

where:

• {name}: will be replaced by the file name being uploaded

msgInvalidFileType

string the message to be displayed when the file type is not in one of the file types set in allowedFileTypes. Defaults to:

Invalid type for file "{name}". Only "{types}" files are supported.

where:

• {name}: will be replaced by the file name being uploaded
• {types}: will be replaced by the comma separated list of types defined in allowedFileTypes.

msgInvalidFileExtension

string the message to be displayed when the file type is not in one of the file extensions set in allowedFileExtensions. Defaults to:

Invalid extension for file "{name}". Only "{extensions}" files are supported.

where:

• {name}: will be replaced by the file name being uploaded
• {extensions}: will be replaced by the comma separated list of extensions defined in allowedFileExtensions.

msgValidationError

string the exception message to be displayed within the caption container (instead of msgFilesSelected), when a validation error is encountered. Defaults to File Upload Error.

msgValidationErrorClass

string the css class for the validation error message displayed in the caption container. Defaults to text-danger.

msgValidationErrorIcon

string the icon to be displayed before the validation error in the caption container. Defaults to <i class="glyphicon glyphicon-exclamation-sign"></i>

msgErrorClass

string the css class for the error message to be displayed in the preview window when the file size exceeds maxSize. Defaults to file-error-message.

msgLoading

string the message displayed when the files are getting read and loaded for preview. Defaults to

Loading file {index} of {files} …

The following special variables will be replaced:

• {index}: the sequence number of the current file being loaded.
• {files}: the total number of files selected for upload.

msgProgress

string the progress message displayed as each file is loaded for preview. Defaults to:

Loading file {index} of {files} - {name} - {percent}% completed.

The following variables will be replaced:

• {index}: the sequence number of the current file being loaded.
• {files}: the total number of files selected for upload.
• {percent}: the percentage of file read and loaded.
• {name}: the name of the current file being loaded.

msgSelected

string the progress message displayed in caption window when multiple (more than one) files are selected. Defaults to {n} files selected. The following variables will be replaced:

• {n}: the number of files selected.

msgFoldersNotAllowed

string the message displayed when a folder has been dragged to the drop zone. Defaults to Drag & drop files only! {n} folder(s) dropped were skipped.. The following variables will be replaced:

• {n}: the number of folders dropped.

msgImageWidthSmall

string, the exception message to be displayed when the file selected for preview is an image and its width is less than the minImageWidth setting. Defaults to:

Width of image file "{name}" must be at least {size} px.

where:

• {name}: will be replaced by the file name being uploaded.

• {size}: will be replaced by the minImageWidth setting.

msgImageHeightSmall

string, the exception message to be displayed when the file selected for preview is an image and its height is less than the minImageHeight setting. Defaults to:

Height of image file "{name}" must be at least {size} px.

where:

• {name}: will be replaced by the file name being uploaded.

• {size}: will be replaced by the minImageHeight setting.

msgImageWidthLarge

string, the exception message to be displayed when the file selected for preview is an image and its width exceeds the maxImageWidth setting. Defaults to:

Width of image file "{name}" cannot exceed {size} px.

where:

• {name}: will be replaced by the file name being uploaded.

• {size}: will be replaced by the maxImageWidth setting.

msgImageHeightLarge

string, the exception message to be displayed when the file selected for preview is an image and its height exceeds the maxImageHeight setting. Defaults to:

Height of image file "{name}" cannot exceed {size} px.

where:

• {name}: will be replaced by the file name being uploaded.

• {size}: will be replaced by the maxImageHeight setting.

progressClass

string the upload progress bar CSS class to be applied when AJAX upload is in process (applicable only for ajax uploads). Defaults to progress-bar progress-bar-success progress-bar-striped active.

progressCompleteClass

stringthe upload progress bar CSS class to be applied when AJAX upload is complete. Defaults to progress-bar progress-bar-success.

previewFileType

string the type of files that are to be displayed in the preview window. Defaults to image. Can be one of the following:

• image: Only image type files will be shown in preview.
• text: Only text type files will be shown in preview.
• any: Both image and text files content will be shown in preview.

Files other than image or text will be displayed as a thumbnail with the filename in the preview window.

zoomIndicator

string the icon for zooming the file content in a new modal dialog. This is currently applicable only for text file previews. Defaults to <i class="glyphicon glyphicon-zoom-in"></i>

elErrorContainer

string the identifier for the container element displaying the error (e.g. '#id'). If not set, will default to the container with CSS class kv-fileinput-error inside the preview container (identified by elPreviewContainer). The msgErrorClass will be automatically appended to this container before displaying the error.

elCaptionContainer

string the identifier for the container element containing the caption (e.g. '#id'). If not set, will default to the container with CSS class file-caption inside the main plugin container.

elCaptionText

string the identifier for the container element containing the caption text (e.g. '#id'). If not set, will default to the container with CSS class file-caption-name inside the main plugin container.

elPreviewContainer

string the identifier for the container element containing the preview (e.g. '#id'). If not set, will default to the container with CSS class file-preview inside the main plugin container.

elPreviewImage

string the identifier for the element containing the preview image thumbnails (e.g. '#id'). If not set, will default to the container with CSS class file-preview-thumbnails inside the main plugin container.

elPreviewStatus

string the identifier for the element containing the preview progress status (e.g. '#id'). If not set, will default to the container with CSS class file-preview-status inside the main plugin container.

slugCallback

function a callback to convert the filename as a slug string eliminating special characters. If not set, it will use the plugin's own internal slugDefault method. This callback function includes the filename as parameter and must return a converted filename string.

Example:

slugCallback: function(filename) {
    return filename.replace('(', '_');
}

dropZoneEnabled

bool whether to enable a drag and drop zone for dragging and dropping files to. This is available only for ajax based uploads. Defaults to true.

dropZoneTitle

string title to be displayed in the drag and drop zone. This is available only for ajax based uploads. Defaults to Drag & drop files here ….

dropZoneTitleClass

string CSS class for the drag & drop zone title. Defaults to file-drop-zone-title.

fileActionSettings

object configuration for setting up file actions for newly selected file thumbnails in the preview window. The following properties can be set: The following properties can be set:

• removeIcon: string, icon for remove button to be displayed in each file thumbnail.
• removeClass: string, CSS class for the remove button in each file thumbnail.
• removeTitle: string, title for remove button in each file thumbnail.
• uploadIcon: string, icon for upload button to be displayed in each file thumbnail.
• uploadClass: string, CSS class for the remove button in each file thumbnail.
• uploadTitle: string, title for remove button in each file thumbnail.
• indicatorNew: string, an indicator (HTML markup) for new pending upload displayed in each file thumbnail.
• indicatorSuccess: string, an indicator (HTML markup) for successful upload displayed in each file thumbnail.
• indicatorError: string, an indicator (HTML markup) for error in upload displayed in each file thumbnail.
• indicatorLoading: string, an indicator (HTML markup) for ongoing upload displayed in each file thumbnail.
• indicatorNewTitle: string, title to display on hover of indicator for new pending upload in each file thumbnail.
• indicatorSuccessTitle: string, title to display on hover of indicator for successful in each file thumbnail.
• indicatorErrorTitle: string, title to display on hover of indicator for error in upload in each file thumbnail.
• indicatorLoadingTitle: string, title to display on hover of indicator for ongoing upload in each file thumbnail.

Defaults to the following setting:

{
    removeIcon: '<i class="glyphicon glyphicon-trash text-danger"></i>',
    removeClass: 'btn btn-xs btn-default',
    removeTitle: 'Remove file',
    uploadIcon: '<i class="glyphicon glyphicon-upload text-info"></i>',
    uploadClass: 'btn btn-xs btn-default',
    uploadTitle: 'Upload file',
    indicatorNew: '<i class="glyphicon glyphicon-hand-down text-warning"></i>',
    indicatorSuccess: '<i class="glyphicon glyphicon-ok-sign file-icon-large text-success"></i>',
    indicatorError: '<i class="glyphicon glyphicon-exclamation-sign text-danger"></i>',
    indicatorLoading: '<i class="glyphicon glyphicon-hand-up text-muted"></i>',
    indicatorNewTitle: 'Not uploaded yet',
    indicatorSuccessTitle: 'Uploaded',
    indicatorErrorTitle: 'Upload Error',
    indicatorLoadingTitle: 'Uploading ...'
}

otherActionButtons

string markup for additional action buttons to display within the initial preview thumbnails (for example displaying an image edit button). The following tags can be used in the markup and will be automatically replaced:

• {dataKey}: Will be replaced with the key set within initialPreviewConfig.

textEncoding

string the encoding to be used while reading a text file. Applicable only for previewing text files. Defaults to UTF-8.

ajaxSettings

object additional ajax settings to pass to the plugin before submitting the ajax request for upload. Applicable only for ajax uploads. This can be useful to pass additional tokens to headers or one can use it for setting other ajax options for advanced cases. Refer the jQuery ajax documentation for the various settings you can configure.

ajaxDeleteSettings

object additional ajax settings to pass to the plugin before submitting the delete ajax request in each initial preview thumbnail. Applicable only for ajax deletions. This can be useful to pass additional tokens to headers or one can use it for setting other ajax options for advanced cases. Refer the jQuery ajax documentation for the various settings you can configure.

showAjaxErrorDetails

boolean whether to show details of the error stack from the server log when an error is encountered via ajax response. Defaults to true.

The plugin supports various events and allows advanced features like returning event results for validating and manipulating your file upload dynamically. The section is categorized into file events, error events, and event manipulation.

$('#input-id').on('fileclear', function(event) {
    console.log("fileclear");
});

$('#input-id').on('filecleared', function(event) {
    console.log("filecleared");
});

$('#input-id').on('fileloaded', function(event, file, previewId, index, reader) {
    console.log("fileloaded");
});

$('#input-id').on('filereset', function(event) {
    console.log("filereset");
});

$('#input-id').on('fileimageloaded', function(event, previewId) {
    console.log("fileimageloaded");
});

$('#input-id').on('filebrowse', function(event) {
    console.log("File browse triggered.");
});

$('#input-id').on('filebatchselected', function(event, files) {
    console.log('File batch selected triggered');
});

$('#input-id').on('fileselectnone', function(event) {
    console.log("Huh! No files were selected.");
});

$('#input-id').on('filelock', function(event, filestack, extraData) {
    var fstack = filestack.filter(function(n){ return n != undefined });
    console.log('Files selected - ' + fstack.length);
});

$('#input-id').on('fileunlock', function(event, filestack, extraData) {
    var fstack = filestack.filter(function(n){ return n != undefined });
    console.log('Files selected - ' + fstack.length);
});

$('#input-id').on('filepredelete', function(event, key) {
    console.log('Key = ' + key);
});

$('#input-id').on('filedeleted', function(event, key) {
    console.log('Key = ' + key);
});

$('#input-id').on('filepreajax', function(event, previewId, index) {
    console.log('File pre ajax triggered');
});

$('#input-id').on('filepreupload', function(event, data, previewId, index) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File pre upload triggered');
});

$('#input-id').on('fileuploaded', function(event, data, previewId, index) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File uploaded triggered');
});

$('#input-id').on('filebatchpreupload', function(event, data, previewId, index) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File batch pre upload');
});

$('#input-id').on('filebatchuploadsuccess', function(event, data, previewId, index) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File batch upload success');
});

$('#input-id').on('filebatchuploadcomplete', function(event, files, extra) {
    console.log('File batch upload complete');
});

$('#input-id').on('filesuccessremove', function(event, id) {
    if (some_processing_function(id)) {
       console.log('Uploaded thumbnail successfully removed');
    } else {
        return false; // abort the thumbnail removal
    }
});

$('#input-id').on('filedisabled', function(event) {
    console.log('File disabled');
});

$('#input-id').on('fileenabled', function(event) {
    console.log('File enabled');
});

$('#input-id').on('fileerror', function(event, data) {
   console.log(data.id);
   console.log(data.index);
   console.log(data.file);
   console.log(data.reader);
   console.log(data.files);
});

$('#input-id').on('fileuploaderror', function(event, data, previewId, index) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File upload error');
});

$('#input-id').on('filebatchuploaderror', function(event, data) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File batch upload error');
});

$('#input-id').on('filedeleteerror', function(event, data) {
    console.log('File delete error');
});

$('#input-id').on('filefoldererror', function(event, folders) {
    console.log('File folder dropped error');
});

$("#input").on('filecustomerror', function(event, params) {
   console.log(params.id);
   console.log(params.index);
   console.log(params.data);
});

With release v4.1.8, you can return data for most of the events and use it for advanced processing. This functionality is supported for most events listed above, but is not applicable for the following events.

• fileclear

• filecleared

• filereset

• fileerror

• fileuploaderror

• filebatchuploaderror

• filedeleteerror

• filefoldererror

• filecustomerror

• fileuploaded

• filebatchuploadcomplete

• filebatchuploadsuccess

For all the events other than ones mentioned above, you can set a custom validation error which will be triggered just before upload is initiated.

This will enable you to add your additional custom validations to enhance the fileinput to be used for innumerous scenarios. It will allow an ability to return an associative object with any of the fileinput events (except the except the events above) e.g. change, fileselect, filepreupload, filebatchpreupload etc.

The object can return the following keys:

• message: string, the validation error message to be displayed before upload. If this is set the plugin will automatically abort the upload whenever called and display this as an error message. You can use this property for example to read a file and perform your own custom validation.

• data: object, an optional associative array of additional data at abort, that you can pass for usage later.

Example

• STEP 1: You can trigger for example an error to abort from filepreupload

  $('#input').on('filepreupload', function(event, data, previewId, index, jqXHR) {
      // do your validation and return an error like below
      if (customValidationFailed) {
         return {
             message: 'You are not allowed to do that',
             data: {key1: 'Key 1', detail1: 'Detail 1'}
         };
     }
  });
  

  The above abort will be triggered at time of upload for (ajax uploads) OR at form submission (for non-ajax uploads).

• STEP 2: Reading additional data at abort by trapping the filecustomerror event

  $('#input').on('filecustomerror', function(event, params) {
     // params.abortData will contain the additional abort data passed
     // params.abortMessage will contain the aborted error message passed
  });
  

As mentioned before, the above functionality of raising a filecustomerror is not supported in the following events:

• fileclear

• filecleared

• filereset

• fileerror

• fileuploaderror

• filebatchuploaderror

• filedeleteerror

• filecustomerror

• fileuploaded

• filebatchuploadcomplete

• filebatchuploadsuccess

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

disable

Disable the file input.

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

enable

Enable the file input.

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

reset

Reset the file input.

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

destroy

Destroys the file input plugin and reverts to a normal native file input.

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

refresh

Refreshes the file input plugin based on options provided. You can supply an array of plugin options as a parameter.

// 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'});

clear

Clear the file input.

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

upload

Trigger ajax upload of the files that are selected. Applicable only if uploadUrl is set.

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

cancel

Cancel an ongoing ajax upload of the files.

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

lock

Locks the file input by disabling all actions/buttons except a cancel button to abort ongoing AJAX requests (for ajax uploads only).

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

unlock

Unlocks and enables the file input back again by reversing the outcome of the lock action.

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

The plugin has been implemented as extensions in the following frameworks

Do you know any other framework extension using this plugin which is not listed here? Tell us so that we can consider its inclusion in this list.

bootstrap-fileinput is released under the BSD 3-Clause License. See the bundled LICENSE.md for details.