All the options to the bootstrap file input plugin can be passed typically via the javascript object at plugin initialization. Depending on your need, these options can also be configured as HTML5 data attributes on the native file input (on which the plugin is initialized). Most of the plugin options can be retrieved at runtime by the following method.
var plugin = $('#file-input).data('fileinput');
console.log(plugin.initialPreview); // get initialPreview
The plugin supports the following options.
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)
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.
float, conversion factor for bytes to kilobytes, which is used in file size calculations and checks.
Defaults to the Base 2 factor of 1024.
array, list of file size units starting from byte to kilobyte and higher (each step being converted via bytesToKB). Defaults to:
['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'].
array, list of bitrate units starting from byte per second to kilobyte per second and higher (each step being converted via bytesToKB). Defaults to:
['B/s', 'KB/s', 'MB/s', 'GB/s', 'TB/s', 'PB/s', 'EB/s', 'ZB/s', 'YB/s']
string, theme to use for the plugin (will default to the inbuilt theme if not set). With release v4.3.2, the fileinput plugin supports advanced theming and ability to have separate themes for multiple widgets on the same page. To do this, follow these simple steps:
Load respective theme JS file(s) that you need (e.g. themes/fa/fa.js for Font
Awesome theme). The theme file(s) must be loaded after the fileinput.js.
Set the theme property in the plugin to the theme you need and which you have setup
in your theme configuration JS file above (e.g. 'fa').
The plugin will automatically read the theme configuration for the theme name from $fileinputThemes['<theme-name>']
from the JS file (e.g. via $fileinputThemes['<theme-name>']).
The plugin will automatically also prepend the CSS selector theme-<theme-name> to
the file input container, so that you can override your styles. The CSS for such themes can be
submitted by community in themes/THEME_NAME folder of the repo.
You can additionally load any theme specific CSS files if needed.
Font Awesome, Glyphicons, Krajee
Explorer,
and Krajee Explorer Font Awesome themes. More advanced themes may be added in future or can
be contributed here by the community.
boolean, whether file selection is mandatory before upload (for ajax) or submit of the form (for
non-ajax). When set to true, and if files are not selected before upload,
this will show the error message as set in msgFilerequired. Defaults
to false.
Check the required validation demos for understanding details on how to use this property.
boolean, whether to orient the widget in Right-To-Left (RTL) mode. To view RTL orientation you
must set this to true and also must load the
css/fileinput-rtl.css file after the css/fileinput.css on your page for RTL
styling. Defaults to false.
Check the RTL usage demo for understanding details on how to use this property.
boolean, whether to hide the preview content (image, pdf content, text content, etc.) within the
thumbnail. Defaults to false. When set to true, only the file
name and file size as defined in the thumbnail footer layout template will be displayed.
Check the Glyphicon Theme Alternate Demo for understanding details on how to use this property.
boolean, whether to encode all the URLs before triggering the ajax calls. Defaults to
true. The following URLs are currently set and used within the plugin:
url within initialPreviewConfig
downloadUrl within initialPreviewConfig
testUrl within resumableUploadOptions
boolean, whether to focus the file caption after browsing and selecting a file. Defaults to
true.
boolean, whether to focus the file caption after clearing / removing the files (using the remove
button for example). Defaults to true.
boolean, whether to display the file upload button. Defaults to true. This will
default to a
form submit button for a non-ajax scenario when the uploadUrl is not
specified. For an ajax upload scenario, this will use the uploadUrl as
a link.
boolean, whether to display the file upload statistics (upload bitrate / speed and upload
pending time). Defaults to true. This will display the upload statistics
typically below the file upload progress bar. This stats will be shown for both each file
thumbnail progress as well as below the main progress bar for all async and resumable
uploads. For synchronous uploads this will only be displayed below the main progress bar.
Check the stats template setting within layoutTemplates to control the HTML markup for display of this information.
boolean, whether to display the file upload cancel button to abort the ongoing upload(s). This
button will be enabled and displayed only when AJAX upload requests are in progress. If
not set, this will default to true for ajax uploads and false
for other uploads. For resumable uploads the pause button is shown instead of cancel by
default as read via showPause setting. One can set cancel button to be
displayed for resumable uploads as well by explicitly setting showCancel to
true. The cancel button is never displayed for non ajax / form based
uploads. Refer the resumable uploads section for overview on setting up resumable / chunk uploads.
boolean, whether to display the file upload pause button to pause the ongoing upload(s). This
button will be enabled and displayed only for resumable/chunk uploads
(i.e. enableResumableUpload property to true) and when AJAX upload requests are in progress. If not set,
this will default to true for resumable uploads and false for
other uploads. For cancelling ongoing uploads set the showCancel property. Refer the resumable uploads section for overview on setting up resumable / chunk uploads.
boolean, whether to display the close icon in the preview. Defaults to true. This
will be only parsed when showPreview is true or when you are using the
{close} tag in your preview templates.
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.
boolean, whether to enable file browse/select on clicking of the preview zone. Defaults to
false.
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.
boolean, whether to show a close icon next to the description bubble in the zoomed content. Defaults
to true.
boolean | function, whether to automatically orient the image for display based on EXIF
orientation tag (i.e. rotate or mirror flip horizontally/vertically). This
property will affect only the image preview and is applicable only for JPEG
images selected from client before upload. It does not alter the file sent to
server. Thus, it will not be applicable for images shown in initialPreview.
This can be a boolean flag or a javascript function callback. Defaults to
following callback (which allows all images except on Mobile IOS Safari to be
auto oriented).
Note that for auto image orientation, browsers which support the image-orientation CSS
will be auto detected by the plugin and this browser capability will be turned on or off. For browsers
which do not support the image-orientation CSS property, you must load the Piexifjs plugin by hMatoba before
the fileinput.js script.
function() {
var ua = window.navigator.userAgent, webkit = !!ua.match(/WebKit/i),
iOS = !!ua.match(/iP(od|ad|hone)/i), iOSSafari = iOS && webkit && !ua.match(/CriOS/i);
return !iOSSafari;
}
Note that only jpeg files will be detected for auto orientation.
You can see how this works in the auto image orientation demo.
boolean | function, similar to the autoOrientImage setting but detects
whether to automatically orient JPEG images pre-loaded within
the initialPreview (and not the client selected images).
Defaults to true. Unlike, autoOrientImage setting, the auto-orientation for initial preview images will be done using
the exif configuration set
within initialPreviewConfig (which you must pass from the
server). The exif object must contain the Orientation property
set. This does not need or use the piexif.js library for
orientation.
Note that for auto image orientation, browsers which support the image-orientation CSS
will be auto detected by the plugin and this browser capability will be turned on or off. For browsers
which do not support the image-orientation CSS property, you must load the Piexifjs plugin by hMatoba before
the fileinput.js script.
An example of a server code (PHP) of how you can pass the exif object orientation within initialPreview as a JSON is described below:
$img1 = '/uploads/images/image-01.jpg';
$img2 = '/uploads/images/image-02.jpg';
return json_encode([
'initialPreview' => [$img1, $img2],
'initialPreviewConfig' => [
// pass exif object below for `autoOrientImageInitial` detection
// it must contain the `Orientation` property
['caption' => 'Image 01.jpg', 'size' => 139823, 'key' => 1, 'exif' => exif_read_data($img1)],
['caption' => 'Image 02.jpg', 'size' => 339649, 'key' => 2, 'exif' => exif_read_data($img2)],
]
]);
You can see how this works in the ajax demo scenario # 6 by uploading files that have different orientations and checking the responses back from the server. For auto orientation of images selected from the client, set the autoOrientImage property and refer the auto image orientation demo.
function, a callback to generate the unique file identifier for each file selected from the
client. This will accept the file blob as a parameter. This defaults to the
following callback function to generate unique file identifier. You can override this if
necessary:
function (file) {
if (!file) {
return null;
}
var relativePath = String(file.relativePath || file.webkitRelativePath || $h.getFileName(file) || null);
if (!relativePath) {
return null;
}
return (file.size + '_' + encodeURIComponent(relativePath).replace(/%/g, '_'));
}
string, any additional CSS class to append to the plugin's main caption container that will envelop the input group containing caption and the browse, remove, and upload buttons. Defaults to an empty string.
string, any additional CSS class to append to the plugin's input group container (with bootstrap css class input-group) that is rendered
inside the main container above. Defaults to an empty string. You can set it to input-group-lg or input-group-sm to get a large or small
bootstrap styled input group. Check this basic example # 6 demo to understand usage.
string, the CSS class to be additionally applied to each file thumbnail frame. Defaults to
krajee-default.
boolean, the callback to generate the human friendly filesize based on the bytes
parameter. If not set this will default to the following callback:
function (bytes) {
var i = Math.floor(Math.log(bytes) / Math.log(1024)),
sizes = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
return (bytes / Math.pow(1024, i)).toFixed(2) * 1 + ' ' + sizes[i];
}
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:
file-preview-image
file-preview-text
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'>" +
"<h3><i class='bi-file-earmark-fill'></i></h3>" +
"Filename.xlsx" + "</div>"
integer, 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.
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 *$$*.
boolean, whether the initial preview content set is to be parsed as data instead of raw markup.
Defaults to false for backward compatibility (prior to v4.3.2).
string, one of the file template types as configured within the keys
in previewSettings. This is useful to identify the template to be used
to display the particular file's content. Defaults to image.
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 and attributes. Note that you can also set additional
custom attributes here which you could refer and use via the showXXX
properties within fileActionSettings or generally via javascript for you
runtime use.
key: string | object, the key that will be passed as data to the
url via AJAX POST. See deleteUrl to understand the format for
ajax request that will process the deletion based on this key.
fileId: string, string | object, an identifier for storing the
data-fileid attribute for each file thumbnail. If not set this will be
autogenerated.
caption: string, the caption or filename to display for each initial
preview item
content.
description: string,the description of the file content (will be displayed in a separate description bubble if set).
If this is not set, no description will be displayed. If you are setting a HTML markup here - please ensure right safe coding to sanitize the text without XSS.
type: string, one of the file template types as configured within the keys
in previewSettings. This will override
the initialPreviewFileType setting. This is useful to
identify the template to be used to display the particular file's content.
filetype: string, file mime type to identify the content. Useful for
certain file templates like audio or video (e.g. video/mp4).
size: float, the size of the file in BYTES which will be displayed using
the size layout template. If not set or if it cannot be parsed as a
float number, then a blank string will be displayed.
exif: object, exif properties for the image (applicable for JPEG image
files only) that will be used for auto orientation of images as configured
within autoOrientImageInitial.
previewAsData: boolean, whether to parse this preview content as a data
input instead of a raw markup source. This will override
the initialPreviewAsData setting.
width: string, the CSS width of the image/content displayed.
url: string | function, the URL for deleting the image/content in the
initial preview via AJAX
post response. This will default to deleteUrl if not set. You
can also set this as a function callback to return an URL dynamically.
See deleteUrl to understand the format for ajax request that
will process the deletion.
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: [
{
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()};
},
}
]
Note that initialPreview and initialPreviewConfig can also be setup in an
easier way without rendering the entire markup but just passing the data. For this
the initialPreviewAsData property must be set to true, and the preview
will be rendered using the templates for the initial preview types. Within the
initialPreviewConfig, the type key will identify the preview file type for the
data passed.
For example, initial preview can be setup as a data in the following way:
initialPreview: [
// IMAGE DATA
'http://lorempixel.com/800/460/business/1',
// IMAGE RAW MARKUP
'<img src="http://lorempixel.com/800/460/business/2" class="kv-preview-data file-preview-image" style="height:160px">',
// TEXT DATA
"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec ut mauris ut libero fermentum feugiat eu et dui. Mauris condimentum rhoncus enim, sed semper neque vestibulum id. Nulla semper, turpis ut consequat imperdiet, enim turpis aliquet orci, eget venenatis elit sapien non ante. Aliquam neque ipsum, rhoncus id ipsum et, volutpat tincidunt augue. Maecenas dolor libero, gravida nec est at, commodo tempor massa. Sed id feugiat massa. Pellentesque at est eu ante aliquam viverra ac sed est.",
// PDF DATA
'https://kartik-v.github.io/bootstrap-fileinput-samples/samples/pdf-sample.pdf',
// VIDEO DATA
"https://kartik-v.github.io/bootstrap-fileinput-samples/samples/small.mp4",
],
initialPreviewAsData: true, // defaults markup
initialPreviewConfig: [
{caption: "Business 1.jpg", size: 762980, url: "$urlD", key: 11},
{previewAsData: false, size: 823782, caption: "Business 2.jpg", url: "$urlD", key: 13},
{caption: "Lorem Ipsum.txt", type: "text", size: 1430, url: "$urlD", key: 12},
{type: "pdf", size: 8000, caption: "PDF Sample.pdf", url: "$urlD", key: 14},
{type: "video", size: 375000, filetype: "video/mp4", caption: "Krajee Sample.mp4", url: "$urlD", key: 15},
],
The ajax delete action will send the following data to server via POST:
key: the key setting as setup in initialPreviewConfig['key']
extra: the extra data passed either via
initialPreviewConfig['extra'] OR deleteExtraData
if former is not set.
boolean, whether the delete button will be displayed for each thumbnail that has been created
with initialPreview.
boolean, the URL to download the files in the initialPreview. This will be globally applied to show a download button for all files displayed in the initial preview. The following properties set within initialPreviewConfig for each file will be passed as GET parameters to the URL:
key
fileId (will be passed only if this is set
within initialPreviewConfig)
boolean, whether the file thumbnail should be removed from preview on error. Defaults to false.
string, the pattern that will be prepended to the id attribute of the generated thumbnail frame for each file in the preview. Defaults to:
thumb-{INPUT_ID}-
where, the {INPUT_ID} token will be replaced by the ID attribute of the source native file
input element.
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 = '<div class="file-thumbnail-footer">\n' +
' <div class="file-caption-name">{caption}{size}</div>\n' +
' {CUSTOM_TAG_NEW}\n' +
' {CUSTOM_TAG_INIT}\n' +
' {actions}\n' +
'</div>';
// set preview template tags
previewThumbTags = {
'{CUSTOM_TAG_NEW}': '<span class="custom-css">CUSTOM MARKUP</span>',
'{CUSTOM_TAG_INIT}': ' '
};
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 = '<div class="file-thumbnail-footer">\n' +
' <div class="file-caption-name">{caption}{size}</div>\n' +
' {CUSTOM_TAG_NEW}\n' +
' {CUSTOM_TAG_INIT}\n' +
' {actions}\n' +
'</div>';
// 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'>",
],
// set initial preview template tags
initialPreviewThumbTags = {
'{CUSTOM_TAG_NEW}': ' ',
'{CUSTOM_TAG_INIT}': '<span class="custom-css">CUSTOM MARKUP</span>'
};
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 url for each file within
initialPreviewConfig 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;
}
The ajax delete action will send the following data to server via POST:
key: the key setting as setup in initialPreviewConfig['key']
any other extra data passed as key: value pairs either via
initialPreviewConfig['extra'] OR deleteExtraData if former is not
set.
string | function, the URL for deleting the image/content in the initial preview via AJAX post
response. This will be
overridden by the url property for each file
within initialPreviewConfig. You can also
set deleteUrl as a function callback which will return a
string. In that case, the function will get executed every time at runtime.
This will enable you to set a dynamically changing url based on runtime
conditions.
The deleteUrl server action will receive data via AJAX POST request as a JSON format {key:
KEY_VALUE},
where:
the key represents the key property identifying each file record set
within initialPreviewConfig
The deleteUrl server action must send data via AJAX request as a JSON response {error:
BOOLEAN_VALUE},
where:
the error represents whether the deletion resulted in an error and has a boolean
value (true or false). If this property is not detected, the plugin
assumes that the deletion was successful. For a deletion error - explicitly set this to true.
Else you must send at least an empty JSON object to ensure a successful delete.
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.
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.
function, callback function that will sanitize the zoom cache content and return the sanitized html. Defaults to:
function(content) {
var $container = $(document.createElement('div')).append(content);
$container.find('input,select,.file-thumbnail-footer').remove();
return $container.html();
}
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.
fileIcon: the icon to render before the caption text.
size: the template to display the file size in the thumbnails. The tag {sizeText}
should be used to render the size data.
caption: the template for rendering the caption.
modal: the template for rendering the modal (for file content preview zooming).
zoomCache: the template for rendering the zoom cache content (recommended to not
change this). Defaults to:
<div class="kv-zoom-cache">{zoomContent}</div>
where zoomContent will be replaced by the zoom preview content for the file. Note
that you must set the CSS class kv-zoom-cache for the plugin to recognize the zoom
preview's cache container.
progress: the template for the progress bar when upload is in progress (for
batch/mass uploads and within each preview thumbnail for async/single
uploads). The upload progress bar when displayed within each thumbnail will
be wrapped inside a container having a CSS class of `file-thumb-progress`.
The following tags will be parsed and replaced automatically:
{percent}: will be replaced with the upload progress percentage.
{stats}: will be replaced with the stats layout template.
stats: the template for the upload statistics that displays the upload bitrate and
time remaining. This is typically displayed below the upload progress bar for
both the thumbnail and overall upload progress (check the
progress layout template). The following tags will be parsed and replaced
automatically:
{pendingTime}: will be replaced with the upload time remaining
{uploadSpeed}: will be replaced with the upload speed.
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.
{download}: will be replaced with the output of the
actionDownload template.
{rotate}: will be replaced with the output of the actionRotate
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 HTML5 data element data-url and its URL value
for
deleting the file thumbnail for initialPreview
content only. The URL value will be parsed from
the url set within initialPreviewConfig.
So if the URL is set to http://your-delete-api,
then this tag will be replaced to data-url="http://your-delete-api".
{dataKey}: the HTML5 data element data-key and the value of
the key (additional data)
that will be passed to the URL above via POST to the AJAX call.
The key value will be parsed from
the key set within initialPreviewConfig.
So if the key is set to 100,
then this tag will be replaced to data-key=100.
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.
actionRotate: the template for the rotation action button within the thumbnail
footer. This button when clicked will rotate preview content by 90 degrees clockwise.
{rotateClass}: the CSS class for the rotate button. Will be replaced with
the rotateClass
set within fileActionSettings.
{rotateIcon}: the icon for the rotate button. Will be replaced with the
rotateIcon
set within fileActionSettings.
{rotateTitle}: the title to display on hover for the rotate button. Will be
replaced
with the rotateTitle set within fileActionSettings.
actionDownload: the template for the file download action button within the
thumbnail
footer.
{downloadClass}: the css class for the download button. Will be replaced
with the downloadClass
set within fileActionSettings.
{downloadIcon}: the icon for the download button. Will be replaced with the
downloadIcon
set within fileActionSettings.
{downloadTitle}: the title to display on hover for the download button.
Will be replaced
with the downloadTitle set within fileActionSettings.
{downloadUrl}: the url to be used to trigger the download of the selected
thumbnail. This will be
derived from the downloadUrl property for the
thumbnail frame within initialPreviewConfig or if this is not set,
will be auto derived from
the initialPreviewDownloadUrl setting. If
neither are set, or the
url is set to false, then the download action
button will not be displayed.
{caption}: the name of the file that will be downloaded. Will be derived
from the filename property for the thumbnail frame
within initialPreviewConfig or if that is not available, will use the caption
property for the thumbnail frame
within initialPreviewConfig.
NOTE The caption name to download the file will be displayed using the HTML5 download attribute for the download link tag. The feature is supported only on specific browsers. Also the link to download the files must be on the same domain to prevent cross origin resource sharing (CORS) issue.
The main1 and main2 templates would automatically parse the following tags for
replacement:
{class}: the CSS class as set in the mainClass property.
{close}: will be replaced with the close (cross) icon (by default on top right of
the preview window). The layout template to control this markup is layoutTemplates.close.
{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.
{size}: the content parsed by the layoutTemplates.size.
{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.
{pause}: the file upload pause button that will be displayed when AJAX upload is in
process
to pause the AJAX upload. This is applicable only for resumable uploads
when enableResumableUpload property to true.
{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 the following. Note that there is check for
bootstrap 5.x version and the templates will be rendered a bit different for Bootstrap 5.x. This is
denoted by $h.isBs5() method in the code below which returns true if you have Bootstrap 5.x
JS library loaded on the page.
{
main1: '{preview}\n' +
'<div class="kv-upload-progress kv-hidden"></div><div class="clearfix"></div>\n' +
'<div class="file-caption {class}">\n' +
' <span class="file-caption-icon"></span>\n' +
' <div class="input-group">\n' + '{caption}\n' +
($h.isBs(5) ? '' : '<div class="input-group-btn input-group-append">\n') +
' {remove}\n' +
' {cancel}\n' +
' {pause}\n' +
' {upload}\n' +
' {browse}\n' +
($h.isBs(5) ? '' : ' </div>\n') +
' </div>'
'</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' +
' {close}\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>',
fileIcon: '<span class="bi-file-earmark-fill kv-caption-icon"></span>',
caption: '<input readonly class="file-caption-name form-control {class}">\n',
btnDefault: '<button type="{type}" title="{title}" class="{css}"{status} {tabIndexConfig}>{icon}{label}</button>',
btnLink: '<a href="{href}" title="{title}" class="{css}"{status} {tabIndexConfig}>{icon}{label}</a>',
btnBrowse: '<div class="{css}"{status} {tabIndexConfig}>{icon}{label}</div>',
modalMain: '<div id="kvFileinputModal" class="file-zoom-dialog modal fade" aria-labelledby="kvFileinputModalLabel" {tabIndexConfig}></div>',
modal: '<div class="modal-dialog modal-lg{rtl}" role="document">\n' +
' <div class="modal-content">\n' +
' <div class="modal-header kv-zoom-header">\n' +
' <h6 class="modal-title kv-zoom-title" id="' + tModalLabel + '"><span class="kv-zoom-caption"></span> <span class="kv-zoom-size"></span></h6>\n' +
' <div class="kv-zoom-actions">{rotate}{toggleheader}{fullscreen}{borderless}{close}</div>\n' +
' </div>\n' +
' <div class="floating-buttons"></div>\n' +
' <div class="kv-zoom-body file-zoom-content {zoomFrameClass}"></div>\n' + '{prev} {next}\n' +
' <div class="kv-zoom-description"></div>\n' +
' </div>\n' +
'</div>\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' +
' {status}\n' +
' </div>\n' +
'</div>\n' +
'{stats}',
stats: '<div class="text-info file-upload-stats">' +
'<span class="pending-time">{pendingTime}</span> ' +
'<span class="upload-speed">{uploadSpeed}</span>' +
'</div>'
footer: '<div class="file-thumbnail-footer">\n' +
' <div class="file-caption-name" style="width:{width}">{caption}</div>\n' +
' {progress} {actions}\n' +
'</div>',
actions: '<div class="file-actions">\n' +
' <div class="file-footer-buttons">\n' +
' {upload} {download} {delete} {zoom} {other}' +
' </div>\n' +
' {drag}\n' +
' <div class="file-upload-indicator" 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',
actionDownload: '<button type="button" class="{downloadClass}" title="{downloadTitle}" data-url="{downloadUrl}" data-caption="{caption}">{downloadIcon}</button>\n',
actionRotate: '<button type="button" class="kv-file-rotate {rotateClass}" title="{rotateTitle}">{rotateIcon}</button>\n',
actionZoom: '<button type="button" class="kv-file-zoom {zoomClass}" title="{zoomTitle}">{zoomIcon}</button>',
actionDrag: '<span class="file-drag-handle {dragClass}" title="{dragTitle}">{dragIcon}</span>'
}
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).
{tabIndexConfig}: the tabindex attribute for the caption or button if available
via tabIndexConfig (else will be blank).
{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.
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:
{rtl}: will be set to kv-rtl css class when rtl is
set to true, else will be a empty string.
{fileindex}: will be replaced with the sequential index of the file within the
selected file stack
{previewId}: will be replaced with the generated HTML identifier for the file
preview thumbnail frame
{template}: the template key name
{frameClass}: will be replaced by the frameClass setting
{caption}: will be replaced by the file caption / file name
{style}: will be replaced by the CSS style markup based on the settings in
previewSettings or previewSettingsSmall
{data}: will be replaced by the raw file data when files are selected on client,
or data source set via initialPreview for initial preview
content
{footer}: will be replaced with the thumbnail footer that displays the actions .
{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.
{zoomCache}: will be replaced by the template markup for zoomCache as
set in
layoutTemplates
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.
NOTE: when setting your own preview templates, the following CSS classes are mandatory to identify elements within each file preview template:
file-preview-frame: CSS class to identify each preview thumbnail frame container
kv-file-content: CSS class to identify the display container for the file content
kv-preview-data: CSS class to identify the element containing the data source (and
the {data} tag) for each file type
The other CSS classes that control styling of each preview thumbnail is based on each file type and
identified by helper CSS classes like file-preview-image, file-preview-text,
file-preview-html etc.
{
generic: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
' {content}\n' +
' {footer}\n' +
'</div>\n',
image: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
' <div class="kv-file-content">' +
' <img src="{data}" class="kv-preview-data file-preview-image" title="{caption}" alt="{caption}" {style}>\n' +
' </div>\n' +
' {footer}\n' +
'</div>\n',
office: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
' <div class="kv-file-content">' +
' <iframe class="kv-preview-data file-preview-office" src="https://docs.google.com/gview?url={data}" {style}></iframe>\n' +
' <img src="{data}" class="kv-preview-data file-preview-image" title="{caption}" alt="{caption}" {style}>\n' +
' </div>\n' +
' {footer}\n' +
'</div>\n',
gdocs: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
' <div class="kv-file-content">' +
' <iframe class="kv-preview-data file-preview-gdocs" src="https://docs.google.com/gview?url={data}&embedded=true" {style}></iframe>\n' +
' <img src="{data}" class="kv-preview-data file-preview-image" title="{caption}" alt="{caption}" {style}>\n' +
' </div>\n' +
' {footer}\n' +
'</div>\n',
html: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
' <div class="kv-file-content">' +
' <object class="kv-preview-data file-preview-html" title="{caption}" data="{data}" type="text/html" {style}>\n' +
' DEFAULT_PREVIEW + </object>\n' +
' </div>\n' +
' {footer}\n' +
'</div>',
text: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
' <div class="kv-file-content">' +
' <object class="kv-preview-data file-preview-text" title="{caption}" data="{data}" type="text/plain;charset=UTF-8" {style}>\n' +
' DEFAULT_PREVIEW + </object>\n' +
' </div>\n' +
' {footer}\n' +
'</div>',
pdf: '<div class="file-preview-frame{frameClass}" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
' <div class="kv-file-content">' +
' <object class="kv-preview-data file-preview-pdf" title="{caption}" data="{data}" type="application/pdf" {style}>\n' +
' DEFAULT_PREVIEW + </object>\n' +
' </div>\n' +
' {footer}\n' +
'</div>',
video: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}" title="{caption}">\n' +
' <div class="kv-file-content">' +
' <video class="kv-preview-data file-preview-video" controls {style}>\n' +
' <source src="{data}" type="{type}">\n' + DEFAULT_PREVIEW + '\n' +
' </video>\n' +
' </div>\n' +
' {footer}\n' +
'</div>\n',
audio: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}" title="{caption}" '
+ STYLE_SETTING + '>\n' +
' <div class="kv-file-content">' +
' <audio class="kv-preview-data file-preview-audio" controls {style}>\n' +
' <source src="{data}" type="{type}">\n' + DEFAULT_PREVIEW + '\n' +
' </audio>\n' +
' </div>\n' +
' {footer}\n' +
'</div>\n',
flash: '<div class="file-preview-frame{frameClass}" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
' <div class="kv-file-content">' +
' <embed class="kv-preview-data file-preview-flash" src="{data}" type="application/flash" {style}>\n',
' </div>\n' +
' {footer}\n' +
'</div>',
object: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}" title="{caption}" {style}>\n' +
' <div class="kv-file-content">' +
' <object class="kv-preview-data file-preview-object file-object" data="{data}" type="{type}" {style}>\n' +
' <param name="movie" value="{caption}" />\n' + OBJECT_PARAMS + '\n' + DEFAULT_PREVIEW + '\n' +
' </object>\n' +
' </div>\n' +
' {footer}\n' +
'</div>',
other: '<div class="file-preview-frame{frameClass}" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}"' +
' title="{caption}">\n' +
' <div class="kv-file-content">' +
' <div class="kv-preview-data file-preview-other-frame" {style}>\n' + DEFAULT_PREVIEW + '\n' +
' </div>\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:
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.
object, the CSS style settings for rendering each preview file type set above. This is by default setup as following:
{
image: {width: "auto", height: "auto", 'max-width': "100%", 'max-height': "100%"},
html: {width: "213px", height: "160px"},
text: {width: "213px", height: "160px"},
office: {width: "213px", height: "160px"},
gdocs: {width: "213px", height: "160px"},
video: {width: "213px", height: "160px"},
audio: {width: "100%", height: "30px"},
flash: {width: "213px", height: "160px"},
object: {width: "213px", height: "160px"},
pdf: {width: "213px", height: "160px"},
other: {width: "213px", height: "160px"}
}
object, similar to previewSettings, but the CSS styles are applied only for small devices with screen width less than 400px. This is by default setup as following:
{
image: {width: "auto", height: "auto", 'max-width': "100%", 'max-height': "100%"},
html: {width: "100%", height: "160px"},
text: {width: "100%", height: "160px"},
office: {width: "100%", height: "160px"},
gdocs: {width: "100%", height: "160px"},
video: {width: "100%", height: "auto"},
audio: {width: "100%", height: "30px"},
flash: {width: "100%", height: "auto"},
object: {width: "100%", height: "auto"},
pdf: {width: "100%", height: "160px"},
other: {width: "100%", height: "160px"}
}
object, the configuration of HTML attributes for the content displayed in the zoomed modal
preview. The configuration is similar to previewSettings, however you can in
this property set other HTML attributes beyond width and height.
This property will override the configuration in previewSettings. You can set
all CSS styling attributes as supported by HTML style attribute. Defaults to
the following configuration for each file type:
{
image: {width: "auto", height: "auto", 'max-width': "100%",'max-height': "100%"},
html: {width: "100%", height: "100%", 'min-height': "480px"},
text: {width: "100%", height: "100%", 'min-height': "480px"},
office: {width: "100%", height: "100%", 'max-width': "100%", 'min-height': "480px"},
gdocs: {width: "100%", height: "100%", 'max-width': "100%", 'min-height': "480px"},
video: {width: "auto", height: "100%", 'max-width': "100%"},
audio: {width: "100%", height: "30px"},
flash: {width: "auto", height: "480px"},
object: {width: "auto", height: "480px"},
pdf: {width: "100%", height: "100%", 'min-height': "480px"},
other: {width: "auto", height: "100%", 'min-height': "480px"}
}
object, the icons to be displayed for the various zoom control buttons in the detailed preview. The following buttons can be set:
prev: button to navigate to the PREVIOUS file content in the modal preview
next: button to navigate to the NEXT file content in the modal preview
rotate: button to rotate preview content by 90 degrees clockwise
toggleheader: button to toggle display and slide out/in the modal header
fullscreen: button to toggle zoomed preview to full screen display
borderless: button to toggle preview to a border less maximized state (only
difference from fullscreen button is that it does not set the browser to a
native full screen mode)
close: button to close the modal zoom preview dialog
The previewZoomButtonIcons defaults to the following configuration:
{
prev: '<i class="bi-caret-left-fill"></i>',
next: '<i class="bi-caret-right-fill"></i>',
rotate: '<i class="bi-arrow-clockwise"></i>',
toggleheader: '<i class="bi-arrows-expand"></i>',
fullscreen: '<i class="bi-arrows-fullscreen"></i>',
borderless: '<i class="bi-arrows-angle-expand"></i>',
close: '<i class="bi-x-lg"></i>'
}
object, the CSS classes to be set for the zoom control buttons in the detailed preview. The following buttons can be set:
prev: button to navigate to the PREVIOUS file content in the modal preview
next: button to navigate to the NEXT file content in the modal preview
rotate: button to rotate preview content by 90 degrees clockwise
toggleheader: button to toggle display and slide out/in the modal header
fullscreen: button to toggle zoomed preview to full screen display
borderless: button to toggle preview to a border less maximized state (only
difference from fullscreen button is that it does not set the browser to a
native full screen mode)
close: button to close the modal zoom preview dialog
The previewZoomButtonClasses defaults to the following configuration:
{
prev: 'btn btn-navigate btn-default btn-outline-secondary',
next: 'btn btn-navigate btn-default btn-outline-secondary',
rotate: 'btn btn-navigate btn-default btn-outline-secondary',
toggleheader: 'btn btn-kv btn-default btn-outline-secondary',
fullscreen: 'btn btn-kv btn-default btn-outline-secondary',
borderless: 'btn btn-kv btn-default btn-outline-secondary',
close: 'btn btn-kv btn-default btn-outline-secondary'
}
boolean, whether to force iconic preview of file thumbnails in the preview zone, by using the
configuration for previewFileIconSettings and previewFileExtSettings. Defaults to false. If set to
true, it will try to force an iconic file thumbnail preview if possible.
boolean, whether to force iconic preview of file thumbnails in the detailed zoom preview zone,
by using the configuration for previewFileIconSettings and previewFileExtSettings. Defaults to false. If set to
true, it will try to force an iconic preview for detailed zoom content if possible.
object, the titles to be set for the zoom control buttons in the detailed preview. The following buttons can be set:
prev: button to navigate to the PREVIOUS file content in the modal preview
next: button to navigate to the NEXT file content in the modal preview
rotate: button to rotate preview content by 90 degrees clockwise
toggleheader: button to toggle display and slide out/in the modal header
fullscreen: button to toggle zoomed preview to full screen display
borderless: button to toggle preview to a border less maximized state (only
difference from fullscreen button is that it does not set the browser to a
native full screen mode)
close: button to close the modal zoom preview dialog
The previewZoomButtonClasses defaults to the following configuration:
{
prev: 'View previous file',
next: 'View next file',
rotate: 'Rotate 90 deg. clockwise',
toggleheader: 'Toggle header',
fullscreen: 'Toggle full screen',
borderless: 'Toggle borderless mode',
close: 'Close detailed preview'
}
array, the list of allowed file extensions whose previews will always be enabled irrespective of preferIconicPreview or previewFileIconSettings configurations. This is typically useful for cases, when you have iconic preview enabled for file types but want to show full content preview for selective file types/extensions like images. For example, for always showing full preview for images, you can set this property to ['jpg', 'gif', 'png']. This by default set to an empty array.
[]
array, the list of allowed file extensions whose previews can be rotated for both thumbnail and zoom preview. This is typically useful for image files. For each extension set here, the rotate button will be shown in file actions and zoom modal window toolbar. This by default is set to the following extensions (common image types):
['jpg', 'jpeg', 'png', 'gif']
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']
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']
You need to be careful in case you are setting both allowedFileTypes and
allowedFileExtensions. In this case, the allowedFileTypes property is
validated first
and generally precedes the allowedFileExtensions setting (and the latter validation
maybe skipped).
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']
array, the opposite of allowedPreviewTypes where you disable / disallow
specific file types that you do not want to be allowed in preview. Disabling will just not
read / render the preview content (resulting in faster file selection). This will
effectively quick render the default preview template and icon without any file content.
Defaults to null.
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.
array, the opposite of allowedPreviewMimeTypes where you disable / disallow
specific file mime types that you do not want to be shown in preview. Disabling will just
not read / render the preview content (resulting in faster file selection). This will
effectively quick render the default preview template and icon without any file content.
Defaults to null.
array, the list of allowed preview file extensions for your widget. This by default supports all
file extensions. Defaults to null.
array, the opposite of allowedPreviewExtensions where you disable / disallow
specific file extensions that you do not want to be allowed in preview. Disabling will just
not read / render the preview content (resulting in faster file selection). This will
effectively quick render the default preview template and icon without any file content.
Defaults to ['msi', 'exe', 'com', 'zip', 'rar', 'app', 'vb', 'scr'] (disabling
preview rendering for these selected extensions).
object, the configuration of aliases for mime types that will be replaced within the markup of
the preview thumbnails embed content. This is useful for video files like Apple Quicktime
movie (.mov) files that do not display within a HTML5 video tag on non Apple
browsers like Chrome, IE, Firefox. Defaults to:
{
'video/quicktime': 'video/mp4'
}
The default setting above thus overrides video/quicktime files to be displayed as video/mp4
files that is recognized as HTML5 video by most modern browsers.
string, the default content / markup to show by default in the preview window whenever the files
are cleared or the input is cleared. This can be useful for use cases like showing the
default user profile picture or profile image before upload to overwrite. This is a bit
different from initialPreview in the sense, that the
initialPreview content will always be displayed unless it is deleted or overwritten based
on overwriteInitial. The defaultPreviewContent on the other hand
will only be shown ONLY on initialization OR whenever you clear the preview. At other
times when files have been selected this will be overwritten temporarily until file(s)
selected is/are cleared.
This property can be useful to display for example a default user profile picture (or saved picture) in the preview window unless the user selects a picture. Check the avatar upload demo example for details
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="badge bg-default">Tag A</span>',
'{tagB}': 'Tag B',
}
// example 2 - tags with value set as callback
customLayoutTags: {
'{tagC}': function() {
return $("#element-id").val();
}
}
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="badge bg-default">Tag A</span>',
'{tagB}': 'Tag B',
}
// example 2 - tags with value set as callback
customPreviewTags: {
'{tagC}': function() {
return $("#element-id").val();
}
}
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.*') && !vType.match(/(tiff?|wmf)$/i) : vName.match(/\.(gif|png|jpe?g)$/i);
},
html: function(vType, vName) {
return (typeof vType !== "undefined") ? vType == 'text/html' : vName.match(/\.(htm|html)$/i);
},
office: function (vType, vName) {
return vType.match(/(word|excel|powerpoint|office)$/i) ||
vName.match(/\.(docx?|xlsx?|pptx?|pps|potx?)$/i);
},
gdocs: function (vType, vName) {
return vType.match(/(word|excel|powerpoint|office|iwork-pages|tiff?)$/i) ||
vName.match(/\.(rtf|docx?|xlsx?|pptx?|pps|potx?|ods|odt|pages|ai|dxf|ttf|tiff?|wmf|e?ps)$/i);
},
text: function(vType, vName) {
return typeof vType !== "undefined" && vType.match('text.*') || vName.match(/\.(txt|md|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;
},
}
string, the icon to be shown in each preview file thumbnail when an unreadable file type for
preview is
detected. Defaults to <i class="bi-file-earmark-fill"></i>
.
string, the CSS class to be applied to the preview file icon container. Defaults to file-other-icon.
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': '<i class="fa fa-file-word-o text-primary"></i>',
'xls': '<i class="fa fa-file-excel-o text-success"></i>',
'ppt': '<i class="fa fa-file-powerpoint-o text-danger"></i>',
'jpg': '<i class="fa fa-file-photo-o text-warning"></i>',
'pdf': '<i class="fa fa-file-pdf-o text-danger"></i>',
'zip': '<i class="fa fa-file-archive-o text-muted"></i>',
}
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);
}
}
string, the CSS class for the each of the button labels for browse, remove, upload, and cancel.
Defaults to hidden-xs, which automatically hides the button labels for small
screen devices and renders as smaller iconic buttons to fit to the screen.
string, the icon to display before the label for the file picker/browse button. Defaults to
<i
class="bi-folder2-open"></i> .
string, the icon to display before the label for the file remove button. Defaults to <i
class="glyphicon
glyphicon-trash"></i>
.
string, the CSS class for the file remove button. Defaults to btn btn-default
btn-secondary.
string, the title to display on hover for the file remove button. Defaults to Clear
selected
files.
string, the icon to display before the label for the file upload cancel button. Defaults to
<i
class="bi-slash-circle"></i> .
string, the CSS class for the file upload cancel button. Defaults to btn btn-default
btn-secondary.
string, the title to display on hover for the file upload cancel button. Defaults to Abort
ongoing
upload.
string, the label to display for the file upload pause button (for resumable uploads only).
Defaults to Pause. Refer the resumable uploads section for overview on setting up resumable / chunk uploads.
string, the icon to display before the label for the file upload pause button. Defaults to
<i
class="bi-pause-fill"></i> .
string, the CSS class for the file upload pause button (for resumable uploads only). Defaults to
btn btn-default btn-secondary. Refer the resumable uploads section for overview on setting up resumable / chunk uploads.
string, the title to display on hover for the file upload pause button (for resumable uploads
only). Defaults to Pause ongoing upload. Refer the resumable uploads section for overview on setting up resumable / chunk uploads.
string, the icon to display before the label for the file upload button. Defaults to <i
class="glyphicon
glyphicon-upload"></i>
.
string, the CSS class for the file upload button. Defaults to btn btn-default
btn-secondary.
string, the title to display on hover for the file remove button. Defaults to Upload
selected
files.
string | function, 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.
You can also set uploadUrl as a function callback which will return a string. In that case,
the function will get executed at runtime just before every ajax call. This will enable you to set a
dynamic upload url based on runtime / dynamic conditions.
string | function, the URL for the ajax upload processing action applicable when each individual
file thumbnail is separately uploaded. Defaults to null.
If this is not set, this will default to the uploadUrl setting. This property is useful for synchronous uploads
when uploadAsync is set to false, and you want
to set a different server action for batch upload
via uploadUrl, but a different server action for single file
thumbnail upload via uploadUrlThumb.
You can also set uploadThumbUrl as a function callback which will return a string. In that
case, the function will get executed at runtime just before every ajax call. This will enable you to set
a dynamic upload thumbnail url based on runtime / dynamic conditions
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: string, the identifier for the preview file container (only
available when uploading each thumbnail file)
index: string, 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;
}
object, the tabindex attribute (refer HTML tabindex
specs) for
HTML markup of the modal preview dialog and the buttons beside the caption like browse, upload, remove, cancel,
pause. This will be set as a object (associative array of keys and values) with the key as
the section name and the value will be the tabindex attribute value. Check
the default setting below to understand the supported key names. If a null or an undefined
value is detected, then in that case the tabindex attribute will not be set. Note that if
no tab index property is set for caption and browse, the keyboard navigation to those
sections will be disabled.
tabIndexConfig: {
browse: 500,
remove: 500,
upload: 500,
cancel: null,
pause: null,
modal: -1
}
integer, the timeout delay in milliseconds used for animated fading in or out of error
containers. Defaults to 800.
integer, the timeout delay in milliseconds used across the various plugin internal workflow
processes. If not set or null, no delay is assumed. Defaults to 100.
integer, the timeout delay in milliseconds used for queuing ajax calls and processes. If not set
or null, no delay is assumed. This must be a small number usually less than 100 and MUST
BE lesser than the processDelay for correct performance. Defaults to
10.
integer, the timeout delay in milliseconds used for throttling and delaying the AJAX XHR upload
progress updates. This will control how frequently the upload statistics will be updated
in the progress bar. If not set or null, no delay is assumed. This must be a small number
usually less than 100 and MUST BE lesser than the processDelay for
correct performance. Defaults to 0.
boolean, whether the batch upload of multiple files will be asynchronous/in parallel. Defaults
to
true.
integer, the maximum number of simultaneous / parallel ajax calls that will be executed across
the file input (including upload, delete and resumable uploads/tests). This will control
throttling / delaying the ajax call in queue to be uploaded. Defaults to 5.
This setting must be greater than or equal to the maxThreads configuration
within resumableUploadOptions setting.
boolean, whether to enable resumable / chunk uploads. Defaults to false. When set
to true, this will override the uploadAsync setting and
enable a different upload mode for files to be sent as sliced chunks via AJAX (allowing
one to also pause and resume uploads). This setting is useful for large file sizes to be
sent in parts that can be meaningfully accepted by the server.
The uploadUrl action will be used to parse the file chunks and process
the upload to the server. Note that the browser must support HTML5 Blob slice
functionality along with HTML5 FileReader and XHR2 / Formdata support for this to be
functional and enabled. Refer the resumable uploads section for overview on setting up resumable / chunk uploads.
object, configuration of options for the resumable upload. The following properties can be set:
fallback: function, a callback for the plugin to fallback to in case the
browser or client does not support resumable uploads. Defaults to the
following callback:
function () {
console.log('The browser does not support resumable or chunk uploads.');
}
testUrl: string | function, the server code/api action that will test the
status of the file being uploaded and enable to resume the upload. This
defaults to null. If not set or false, no test will be performed
for the file selected for upload. You can also set this as a function
callback which will return a string. In that case, the function will get
executed every time at runtime. This will enable you to set a dynamically
changing url based on runtime conditions.
The following params are sent to the server for testing the file uploaded. These parameter names can be controlled and set via uploadParamNames.
fileId: string, string, unique file identifier for the
file being uploaded generated via generateFileId
fileName: string, name of the file being uploaded
fileSize: double, size of the file being uploaded in bytes
fileRelativePath: string, client relative path of the file being
uploaded
chunkSize: double, size of each file chunk in KB being uploaded
chunkCount: integer, total number of file chunks being uploaded
The following params are received back from the server for testing the file uploaded. These parameter names can be controlled and set via uploadParamNames.
chunksUploaded: array, list of chunk index numbers that are already
uploaded on the server. Based on this the plugin will skip
these file chunks and process from the chunks that are
missing.
chunkSize: integer, the size of each file chunk in KB which will be used to
slice the file and send for upload. Defaults to 2048 KB (i.e.
2 MB)
maxThreads: integer, the maximum number of simultaneous / parallel chunks
that can be uploaded. This will control throttling / delaying the chunks
in queue to be uploaded. Defaults to 4. This setting must be
less than or equal to the maxThreads plugin level
setting. Else, the maxThreads plugin level setting will
override this property.
maxRetries: integer, the maximum number of retries to be attempted for
uploading/resuming the file chunk uploads in case of any connection issues
or server errors. Defaults to 3.
showErrorLog: boolean, whether to log errors during the file chunk
operation and display it in the browser console. Defaults to
true.
skipErrorsAndProceed: boolean, whether to skip errors in upload (after max
retries) and proceed with the next file (for multiple file
uploads). Defaults to false. When set to
true, files with errors will be skipped and upload will proceed with other files.
retainErrorHistory: boolean, whether to retain history of all previous
validation errors in the error display. Defaults to
true. When set to false, only the latest/last validation error will be
shown for the file.
object, the configuration of the various parameter names that will be sent or received as data for ajax calls during resumable uploads. Refer the resumable uploads section for overview on setting up resumable / chunk uploads. Defaults to the following setting:
{
chunkCount: 'chunkCount',
chunkIndex: 'chunkIndex',
chunkSize: 'chunkSize',
chunkSizeStart: 'chunkSizeStart',
chunksUploaded: 'chunksUploaded',
fileBlob: 'fileBlob',
fileId: 'fileId',
fileName: 'fileName',
fileRelativePath: 'fileRelativePath',
fileSize: 'fileSize',
retryCount: 'retryCount'
}
integer, the default height in px for the modal window displaying the zoomed
preview content. Defaults to 480.
integer, the minimum allowed image height in px if you are uploading image files.
Defaults to null which means no limit on image height.
integer, the maximum allowed image height in px if you are uploading image files.
Defaults to null which means no limit on image height. Note that if you set
resizeImage property to true, then the entire image will be resized within
this height (depending on resizePreference).
integer, the minimum allowed image width in px if you are uploading image files.
Defaults to null which means no limit on image width.
integer, the maximum allowed image width in px if you are uploading image files.
Defaults to null which means no limit on image width. Note that if you set
resizeImage property to true, then the entire image will be resized within
this width (depending on resizePreference).
boolean, whether to add ability to resize uploaded images. Defaults to false. Note
that resizing images requires HTML5 canvas support which is supported on most modern
browsers. In addition, you must include Piexifjs plugin by hMatoba
by including plugins/piexif.min.js in your application. It is required to be
loaded before fileinput.min.js for restoring the exif data to the image
files when using the image resize feature of the bootstrap-fileinput plugin.
string, preference to resize the image based on width or height.
Defaults to width. This property is parsed only when resizeImage
is true. If set to width, the maxImageWidth
property is first tested and if image size is greater than this, then the image is resized
to maxImageWidth. The image height is resized and adjusted in
the same ratio as width. In case, the image width is already less than maxImageWidth
then the maxImageHeight property is used to resize and width is adjusted in
same ratio.
This will behave conversely, when resizePreference is set to height - the
maxImageHeight will be first tested against image height and then the rest of steps will be
similarly parsed with preference given to height instead of width as before.
For example:
// Example for resizePreference = 'width'
// - will resize image width to 200 px if image width is > 200 px
// - will resize image height to 200 px if image width is < 200 px and
// image height is > 200 px
// if none of the above image will be returned as is
$('#file-input').fileinput({
resizeImage: true,
maxImageWidth: 200,
maxImageHeight: 200,
resizePreference: 'width'
});
float, the quality of the resized image. This must be a decimal number between 0.00
to 1.00. Defaults to 0.92.
string, the default image mime type of the converted image after resize. Defaults to image/jpeg.
float, the file size in KB beyond which the resize will be performed. Defaults to 0.
Only files beyond a size set here will be resized.
float, the minimum file size for upload in KB. The file size must exceed the value set here,
else a validation error is thrown using the msgSizeTooSmall setting.
Defaults to 0.
If this is set to null, then the validation is skipped and no minimum value
check will be performed.
float, the maximum size (for each single file) for upload in KB. If greater than this, a validation error is
thrown using the msgSizeTooLarge setting. If set to 0, it
means size allowed is unlimited. Defaults to 0.
float, the maximum multiple file size (summed for all files) for upload in KB. If greater than this, a validation error is
thrown using the msgMultipleSizeTooLarge setting. If set to 0, it
means size allowed is unlimited. Defaults to 0.
float, the maximum preview file size for upload in KB. Files beyond this size will have a
default thumbnail without the preview content. If set to 0 or
null, it means the preview size allowed is unlimited. This is to be set carefully for
optimal browser memory performance when previewing large files. Defaults to
25600 (i.e. 25 MB).
integer, the minimum number of files allowed for each multiple upload. If set to 0,
it means number
of files are optional. Defaults to 0.
integer, 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. Depending
on validateInitialCount property, this value will be validated whether
to include initial files in preview. Note that if maxTotalFileCount is
set, the validateInitialCount property will not be used for
validating maxFileCount.
integer, the maximum total number of files allowed for each multiple upload (including files in
initial preview and files selected for upload). If set to 0, it means number
of files allowed is unlimited. Defaults to 0. Note that if this is set,
the validateInitialCount property will not be used for
validating maxFileCount.
boolean, whether to include initial preview file count (server uploaded files) in
validating minFileCount and maxFileCount. Defaults
to false. Note that if maxTotalFileCount is set,
the validateInitialCount property will not be used for
validating maxFileCount.
string, the message that will be displayed when no files are selected after a file validation operation. Defaults to
No files selected.
string, the message that will be displayed within the progress bar when file upload is paused via the pause button for resumable uploads. Defaults to:
Cancelled
string, the message that will be displayed within the progress bar when file upload is aborted or cancelled. Defaults to:
Paused
string, the placeholder text that will be displayed within the main file caption when no files are selected. Defaults to:
Select {files}...
where, the {files} token will be displayed with:
filePlural if the multiple attribute of the file input has been
set to true, OR
fileSingle if the multiple attribute of the file input is not
set.
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
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
string, the message to be displayed before upload (for ajax) or form submit (for non-ajax) when
no files have been selected and the required property has been set to
true. Defaults to:
You must select a file to upload.
Check the required validation demos for more details on usage of rtl validation.
string, the message to be displayed when the file size is less than or equal to the minimum size set in minFileSize. Defaults to:
File "{name}" (<b>{size} KB</b>) is too small and must be larger than <b>{minSize} KB</b>.
where:
{name}: will be replaced by the file name being uploaded
{size}: will be replaced by the uploaded file size
{minSize}: will be replaced by the minFileSize parameter.
string, the message to be displayed when the file size exceeds maximum size set in maxFileSize. Defaults to:
File "{name}" (<b>{size} KB</b>) exceeds maximum allowed upload size of <b>{maxSize} KB</b>. 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.
string, the message to be displayed when the file size exceeds maximum size set in maxMultipleFileSize. Defaults to:
Files "{name}" ({size}) exceeds maximum allowed upload size of {maxSize}.
where:
{name}: will be replaced by the file names being uploaded
{size}: will be replaced by the combined uploaded file size
{maxSize}: will be replaced by the maxMultipleFileSize parameter.
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 <b>{n}</b> {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.
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 <b>({n})</b> exceeds maximum allowed limit of <b>{m}</b>. 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
string, the message to be displayed when the file count exceeds maximum count as set in maxTotalFileCount. Defaults to:
You can upload a maximum of <b>{m}</b> files (<b>{n}</b> files detected).
where:
{n}: will be replaced by total number of files selected for upload as well as in
initial preview
{m}: will be replaced by the allowed maximum files as set
in maxTotalFileCount
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
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 <code>"{name}"</code>.
where:
{name}: will be replaced by the file name being uploaded
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
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
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
string, the message to be displayed when the slugified file name returns an empty string. Defaults to:
Invalid or unsupported characters in file name "{name}".
where:
{name}: will be replaced by the file name being uploaded
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.
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.
string, the message to be displayed when an ongoing ajax file upload is aborted by pressing the Cancel button. Defaults to:
The file upload was aborted
If this is set to null or empty, the internal ajax error message will be displayed. Defaults to:
File Upload Error
string, the message to be displayed within the progress bar when the progress exceeds the progressUploadThreshold setting. Defaults to:
Processing...
string, the message to be displayed within the progress bar when the progress is 0%
and upload is about to begin. Defaults to:
Initializing...
string, the message to be displayed within the progress bar when the progress is
100% and upload is completed. Defaults to:
Done
string, the message to be displayed within the progress bar when the upload is resumed after pausing for a resumable upload. Defaults to:
Resuming upload...
string, the error message displayed when no files or extra data were found to upload or submit. Defaults to:
No valid data available for upload
string, the message title displayed after an ajax upload error in the error alert box along with the file name. Defaults to:
Upload Error
string, the message title displayed after an ajax delete error in the error alert box along with the file name. Defaults to:
Delete Error
string, the message displayed within the upload progress bar when an ajax validation error is received from the server for the ajax upload. The message is applicable for both the main upload progress bar as well as each individual file thumbnail progress bar. Defaults to:
Error
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
string, the css class for the validation error message displayed in the caption container.
Defaults to text-danger.
string, the icon to be displayed before the validation error in the caption container. Defaults
to <i
class="fa fa-exclamation-circle"></i>
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.
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.
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.
string, the progress message displayed in caption window when multiple (more than one) files are selected. Defaults to:
{n} files selected
where:
{n}: will be replaced with the number of files selected.
string, the message displayed in the file caption name input section while files are being loaded and processed for rendering on preview. Defaults to:
Processing ...
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.
where:
{n}: will be replaced with the number of folders dropped.
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 (detected {dimension} px).
where:
{name}: will be replaced by the file name being uploaded.
{size}: will be replaced by the minImageWidth setting.
{dimension}: will be replaced by the actual detected image width.
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 (detected {dimension} px).
where:
{name}: will be replaced by the file name being uploaded.
{size}: will be replaced by the minImageHeight setting.
{dimension}: will be replaced by the actual detected image height.
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 (detected {dimension} px).
where:
{name}: will be replaced by the file name being uploaded.
{size}: will be replaced by the maxImageWidth setting.
{dimension}: will be replaced by the actual detected image width.
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 (detected {dimension} px).
where:
{name}: will be replaced by the file name being uploaded.
{size}: will be replaced by the maxImageHeight setting.
{dimension}: will be replaced by the actual detected image height.
string, the message to be displayed when an error is received during image resize operation. Defaults to:
Could not get the image dimensions to resize.
string, the message to be displayed when an exception is thrown during image resize operation. Defaults to:
Error while resizing the image.<pre>{errors}</pre>.
where:
{errors}: will be replaced by the javascript exception message.
string, the message to be displayed for a duplicate selection when the a file from the client is selected again with the same file size and file name. This is applicable only for the current session and not when the page is refreshed. Defaults to:
File "{name}" of same size "{size} KB" has already been selected earlier. Skipping duplicate selection.
where:
{name}: will be replaced by the file name
{size}: will be replaced by the file size in KB
string, the message to be displayed when number of retries for file chunk upload (post an error
or bad connection) exceeds maxRetries set
within resumableUploadOptions. This is applicable only for resumable
uploads. Defaults to:
Upload aborted beyond <b>{max}</b> retries for file <b>{file}</b>! Error Details: <pre>{error}</pre>.
where:
{file}: will be replaced by the file name
{max}: will be replaced by the maxRetries set
within resumableUploadOptions
string, the message to be displayed as pending time within the upload statistics (below the progress bar). Defaults to:
{time} remaining
where:
{time}: will be replaced by the calculated remaining time for upload
string, the message to be displayed in the duration while the upload stats pending time is being calculated. Defaults to:
calculating time remaining
string, the message to be displayed when an unknown error or exception is received during any of the ajax operations (e.g. upload or delete). Defaults to:
Something went wrong with the {operation} operation. Please try again later!
where:
{operation}: will be replaced by the file operation
(see ajaxOperations for list of ajax operations
supported by the plugin)
string, the message to be displayed in the progress bar when an unknown error or exception is received during any of the ajax operations (e.g. upload or delete). Defaults to:
{operation} failed
where:
{operation}: will be replaced by the file operation
(see ajaxOperations for list of ajax operations
supported by the plugin)
object, the user friendly messages displayed for each of the ajax operations (and used
in msgAjaxError to display an error specific to an ajax operation. The
keys must be one of deleteThumb, uploadThumb,
uploadBatch, or , uploadExtra. Defaults to:
{
deleteThumb: 'file delete',
uploadThumb: 'file upload',
uploadBatch: 'batch file upload',
uploadExtra: 'form data upload'
}
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.
stringthe upload progress bar CSS class to be applied when AJAX upload is complete. Defaults to
progress-bar
progress-bar-success.
stringthe upload progress bar CSS class to be applied when AJAX upload is cancelled or aborted.
Defaults to progress-bar
progress-bar-danger.
integer, the percentage progress threshold until which the file upload progress indicator will
display the percentage. Defaults to 99, beyond which the progress bar will
display the msgUploadThreshold.
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.
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>
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 CSS class as set
in msgErrorClass will be automatically appended
to this container element when displaying the error markup.
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 within in the
plugin main container.
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.
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.
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.
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.
function, a callback to convert the filename as a slug string eliminating special characters. The plugin uses this slug routine to convert the source file names containing non-standard 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. This defaults to the following callback:
slugCallback: function (text) {
return isEmpty(text) ? '' : String(text).replace(/[\[\]\/\{}:;#%=\(\)\*\+\?\\\^\$\|<>&"']/g, '_');
}
One can override this to what they want for their use case. For example:
slugCallback: function(filename) {
return filename.replace('(', '_');
}
boolean, whether to enable and display a drag and drop zone for dragging and dropping files to.
This is available
for both form based and ajax based uploads. To disable or not show a drop zone - set this
to false.
Defaults to true.
string, title to be displayed in the drag and drop zone. Defaults to:
Drag & drop files here …
string, CSS class for the drag & drop zone title. Defaults to file-drop-zone-title.
string, title to be appended to the dropZoneTitle in the drag and drop zone
when browseOnZoneClick is true. TDefaults to <br>(or
click
to
select
{files}).
object, configuration for setting up file actions for newly selected file thumbnails in the preview window. The following properties that can be set are listed below:
initialPreview, set these same properties within initialPreviewConfig for each file item.
showUpload: boolean | function, whether to show the upload button in the
thumbnail. NOTE: The upload button will be
displayed only for client selected files not yet uploaded to server. The
upload button will not be displayed for resumable uploads
when enableResumableUpload property to true. This property can also be setup as a callback
function of the following signature.
function(config) {
// config will give you the configuration row within initialPreviewConfig
// for the selected file thumbnail
if (config.type === 'XXX') {
return true;
}
return false;
}
showDownload: boolean | function, whether to show the download button in
the thumbnail. This can also be setup as a callback function as
described in the showUpload button above. NOTE: The download button will be displayed only for
uploaded files on server and when you have set a
valid initialPreview and a
valid initialPreviewDownloadUrl or set a valid downloadUrl
for each file configuration
within initialPreviewConfig.
showRemove: boolean | function, whether to show the remove button in the
thumbnail. This can also be setup as a callback function as described in
the showUpload button above. NOTE: Even if this property is set to true,
the remove button in thumbnails will never be shown in the following
cases:
Client Selected Files (Non-Ajax): The remove button will be hidden always for file thumbnails that are selected from client for non-ajax / form based submissions (when uploadUrl is not set).
Server Uploaded Files (Without delete URL): The remove button will not be
effective for server uploaded file
thumbnails set
via initialPreview,
unless you set a
valid initialPreview and a
valid deleteUrl or
a valid url for each file
configuration
within initialPreviewConfig .
showZoom: boolean | function, whether to show the zoom button in the
thumbnail. This can also be setup as a callback function as described in the
showUpload button above.
showDrag: boolean | function, whether to show the drag button in the
thumbnail (applicable only for initial preview content). This can also be
setup as a callback function as described in the showUpload
button above. NOTE: The drag indicator
button will be displayed only for uploaded files on server and when you have
set a valid initialPreview.
showRotate: boolean | function, whether to show the rotate button in the
thumbnail (which on click will rotate the preview content 90 degrees clockwise).
This property if set to false will override the rotatableFileExtensions property which controls the specific file extensions where rotation will be enabled .
uploadIcon: string, icon for upload button to be displayed in each file
thumbnail.
uploadClass: string, CSS class for the upload button in each file
thumbnail.
uploadTitle: string, title for upload button in each file thumbnail.
uploadRetryIcon: string, icon to be displayed for upload button after an
upload error is encountered from the server to allow retry of the
upload. This will be rendered in such a case for the errored file
thumbnail when retryErrorUploads is set to true.
uploadRetryIcon: string, title to be displayed for upload button after an
upload error is encountered from the server to allow retry of the
upload. This will be rendered in such a case for the errored file
thumbnail when retryErrorUploads is set to true.
downloadIcon: string, icon for download button to be displayed in each
file thumbnail.
downloadClass: string, CSS class for the download button in each file
thumbnail.
downloadTitle: string, title for download button in each file thumbnail.
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.
rotateIcon: string, icon for rotate button to be displayed in each
file thumbnail.
rotateClass: string, CSS class for the rotate button in each file
thumbnail.
rotateTitle: string, title for rotate button in each file thumbnail.
zoomIcon: string, icon for zoom button to be displayed in each file
thumbnail (to zoom thumbnail content to a detailed modal preview).
zoomClass: string, CSS class for the zoom button in each file thumbnail
(to zoom thumbnail content to a detailed modal preview).
zoomTitle: string, title for zoom button in each file thumbnail (to zoom
thumbnail content to a detailed modal preview).
dragIcon: string, icon for drag button to be displayed in each file
thumbnail (to sort / rearrange items in initial preview).
dragClass: string, CSS class for the drag button in each file thumbnail
(to sort / rearrange items in initial preview).
dragTitle: string, title for drag button in each file thumbnail (to sort /
rearrange items in initial preview).
dragSettings: object, the configuration for the Sortable plugin that will
allow you to control the drag settings.
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.
indicatorPaused: string, an indicator (HTML markup) for paused upload
displayed in
each file thumbnail (applicable for resumable uploads
when enableResumableUpload property to true).
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.
indicatorPausedTitle: string, title to display on hover of indicator for
paused
upload in each file thumbnail (applicable for resumable uploads
when enableResumableUpload property to true).
Defaults to the following setting:
{
showRemove: true,
showUpload: true, // will be always false for resumable uploads
showDownload: true,
showZoom: true,
showDrag: true,
removeIcon: '<i class="bi-trash"></i>',
removeClass: 'btn btn-kv btn-default btn-outline-secondary',
removeErrorClass: 'btn btn-kv btn-danger',
removeTitle: 'Remove file',
uploadIcon: '<i class="bi-upload"></i>',
uploadClass: 'btn btn-kv btn-default btn-outline-secondary',
uploadTitle: 'Upload file',
uploadRetryIcon: '<i class="bi-arrow-clockwise"></i>',
uploadRetryTitle: 'Retry upload',
downloadIcon: '<i class="bi-download"></i>',
downloadClass: 'btn btn-kv btn-default btn-outline-secondary',
downloadTitle: 'Download file',
zoomIcon: '<i class="bi-zoom-in"></i>',
zoomClass: 'btn btn-kv btn-default btn-outline-secondary',
zoomTitle: 'View Details',
dragIcon: '<i class="bi-arrows-move"></i>',
dragClass: 'text-info',
dragTitle: 'Move / Rearrange',
dragSettings: {},
indicatorNew: '<i class="bi-plus-lg text-warning"></i>',
indicatorSuccess: '<i class="bi-check-lg text-success"></i>',
indicatorError: '<i class="bi-exclamation-lg text-danger"></i>',
indicatorLoading: '<i class="bi-hourglass-bottom text-muted"></i>',
indicatorPaused: '<i class="bi-pause-fill text-info"></i>',
indicatorNewTitle: 'Not uploaded yet',
indicatorSuccessTitle: 'Uploaded',
indicatorErrorTitle: 'Upload Error',
indicatorLoadingTitle: 'Uploading ...',
indicatorPausedTitle: 'Upload Paused'
}
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:
{key}: Will be replaced with the key property set for each preview
thumbnail setting within initialPreviewConfig.
{dataKey}: Will be replaced with data-key="{keyval}", where {keyval}
is the
key property set for each preview thumbnail setting
within initialPreviewConfig.
{dataUrl}: Will be replaced with data-url="{urlval}", where {urlval}
is the delete
url property set for each preview thumbnail setting
within initialPreviewConfig.
{downloadUrl}: the url to be used to trigger the download of the selected
thumbnail. This will be
derived from the downloadUrl property for the thumbnail
frame within initialPreviewConfig or if this is not
set,
will be auto derived from
the initialPreviewDownloadUrl setting. If neither
are set, or the
url is set to false, then the download action button will
not be displayed.
{caption}: the name of the file that will be downloaded. Will be derived
from the filename property for the thumbnail frame
within initialPreviewConfig or if that is not available, will use the caption property
for the thumbnail frame
within initialPreviewConfig.
NOTE The caption name to download the file will be displayed using the HTML5 download attribute for the download link tag. The feature is supported only on specific browsers. Also the link to download the files must be on the same domain to prevent cross origin resource sharing (CORS) issue.
For example, you can set a custom button (or chain/append multiple button markups) like below:
var btns = '<button type="button" class="kv-cust-btn btn btn-kv btn-secondary" title="Edit"{dataKey}>' +
'<i class="bi-pencil-square"></i>' +
'</button>';
// note the tag/token {dataKey}
$('#input-id').fileinput({
otherActionButtons: btns,
// configure other plugin settings
});
You can write a custom action on the button by parsing the CSS class and/or the data key. For example:
$('.kv-cust-btn').on('click', function() {
var $btn = $(this), key = $btn.data('key');
// do some actions based on the key
});
string, the encoding to be used while reading a text file. Applicable only for previewing text
files.
Defaults to UTF-8.
function, callback to pre process upload which will return a converted or encrypted file
content. This can be useful for encrypting file content on client before sending it to
server e.g. when implementing E2EE (end-to-end encryption). This defaults to null. This
callback will only be parsed when using the ajax upload modes, but it will not be
enabled for resumable uploads. If this property is empty or not set to a valid callback,
the plugin will ignore this setting and send the RAW file data directly via ajax. The
callback function signature is where the parameter fileId is the unique
file identifier of each file and file is the selected file object.
function(fileId, file) {
return your_file_conversion_method(file); // some method to read/convert the file and return converted content
}
Note: When preProcessUpload is set to a valid callback, the file content will be sent
to the server as NORMAL POST data and not RAW FILES data. The POST key name will match file
input name attribute. For a multiple upload you must set the name
attribute to array square brackets format.
An alternative scenario to achieve more use cases like encrypting files, could be to combine this callback along with other plugin events like fileloaded or filebatchselected:
var encryptedFileStack = {}; // a global object to store your encrypted files
$('#input').on('fileloaded', function(e, file, previewId, fileId, index, reader) {
// reading via file reader - reader will return the filereader object instance if using with PREVIEW
// if no preview is enabled - then reader will be undefined
// your_encrypt_method is a method you will implement to read file content and return encrypted data
encryptedFileStack[fileId] = your_encrypt_method(file, reader);
});
$('#input').fileinput({
preProcessUpload: function(fileId, file) {
return encryptedFileStack[fileId];
},
// your other plugin settings
});
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.
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.
boolean, whether to show details of the error stack from the server log when an error is
encountered via
ajax response. Defaults to true.
boolean|string, whether to merge the ajax callback functions set
in ajaxSettings with the default plugin callbacks for beforeSend,
success, error,
complete. Defaults to false.
In addition to boolean false, the following string values can be set:
'before': when set to 'before', the ajax callbacks set in
ajaxSettings will be merged before the default plugin callback.
'after': when set to 'after', the ajax callbacks set in
ajaxSettings will be merged after the default plugin callback.
boolean|string, whether to merge the ajax callback functions set
in ajaxDeleteSettings with the default plugin callbacks for beforeSend,
success, error,
complete. Defaults to false.
In addition to boolean false, the following string values can be set:
'before': when set to 'before', the ajax callbacks set in
ajaxDeleteSettings will be merged before the default plugin callback.
'after': when set to 'after', the ajax callbacks set in
ajaxDeleteSettings will be merged after the default plugin callback.
boolean, whether to allow retry of file upload for file thumbnails that have errored out due to
a
server generated validation error via the ajax response. Defaults to true.
boolean, whether to reverse the order of files displayed in the preview. Defaults to
false. If this property is set to true, the last/latest file will be displayed
on the top/first and the oldest file will be displayed at the bottom/end.
This property will be applied to both the files in the initialPreview, as well as new files
selected for upload via file browse dialog or drag and drop.
Refer a demo example on usage of this property.
boolean|callback, whether to use a PDF Rendering library like PDF JS to render the PDF
files. This can be set directly as a boolean flag true or false,
or set as a javscript callback to conditionally use the PDF rendering library.
This property will be applied to both the files in the initialPreview, as well as new files
selected for upload via file browse dialog or drag and drop.
If this is false, then the plugin will use a default HTML5 OBJECT tag to embed the PDF
content/documents (rendered via pdf template setting in previewTemplates ).
This defaults to the following JS callback, whereby the PDF rendering library is enabled only for rendering PDF on iOS & Android devices and IE11 browser platforms.
function() {
var isIE11 = !!window.MSInputMethodContext && !!document.documentMode;
return !!navigator.userAgent.match(/(iPod|iPhone|iPad|Android)/i) || isIE11;
}
Setting this option is useful on rendering PDF in iOS devices like the iPad which do not allow scrolling in embed or object tags. Refer related resolved issue 1254.
string, the PDF rendering library URL that will be used to parse and render the PDF file
when usePdfRenderer is determined as true.
In order to configure the PDF Renderer using the PDF JS library, you would first need to install the PDF JS viewer on your same web server that processes the file input. Point it to the URL of the PDF JS Viewer. A prebuilt version of the library and the viewer is also been uploaded as a compressed file on the Bootstrap File Input Samples Repo. You can download and extract it on your web server.
If you have for example installed it in a web accessible folder called pdfjs on your web
root, then you can set pdfRendererUrl to:
http://localhost/pdfjs/web/viewer.html
where, localhost should be replaced by your web server domain name. If this property is not
set or empty, then the plugin will proceed to use a default HTML5 OBJECT tag to embed the PDF
content/documents (rendered via pdf template setting in previewTemplates ).
string, the PDF content template to render the content of PDF files
when usePdfRenderer is determined as true and
pdfRendererUrl is also set. Note that this is a bit different from previewTemplates['pdf']
setting in the sense that it will just be a replacement for the embed markup
in previewTemplates.pdf (refer previewTemplates).
This defaults to the following setting:
<iframe class="kv-preview-data file-preview-pdf" src="{renderer}?file={data}" {style}></iframe>'
where,
{renderer} will be replaced by the pdfRendererUrl. The parent
div thumbnail container to this rendered PDF iframe will have an additional CSS
class kv-pdf-rendered appended to it (for overriding your
styles for PDF Container). The default width for
kv-pdf-rendered is set to 400px.
{style} will be replaced by the CSS style markup based on the settings in
previewSettings or previewSettingsSmall
Comments & Discussion
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.