Completed documentation

LICENSE

@@ -1,27 +0,0 @@
-Copyright (c) 2014, Kartik Visweswaran
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice, this
-  list of conditions and the following disclaimer in the documentation and/or
-  other materials provided with the distribution.
-
-* Neither the name of the {organization} nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
-ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
-ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,4 +1,297 @@
 bootstrap-fileinput
 ====================
 
-An enhanced HTML 5 file input for Bootstrap 3.x with file preview, multiple selection, and more features.
+An enhanced HTML 5 file input for Bootstrap 3.x with file preview for images and text, multiple selection, and more. This plugin is inspired by the [blog article](http://www.abeautifulsite.net/blog/2013/08/whipping-file-inputs-into-shape-with-bootstrap-3/) and [Jasny's File Input plugin](http://jasny.github.io/bootstrap/javascript/#fileinput). The plugin enhances these concepts and simplifies the widget initialization by simple HTML markup on a file input. It also offers support for multiple file preview and previewing both images and text types.
+
+## Features  
+
+1. The plugin will convert a simple HTML file input to an advanced file picker control. Will help fallback to a file input for browsers not supporting JQuery or Javascript.
+2. The file input consists of the following three sections with options and templates to control the display:
+   - file caption section: to display a brief information of the file(s) selected
+   - file action buttons section: to browse, remove, and upload files.
+   - file preview section: to display the selected files on client for preview (supports images and text file types). Other file types will be displayed as normal thumbnails.
+3. The plugin automatically converts an input with `type = file` to an advanced file picker input if you set its `class = file`. All options to the input can be passed as HTML5 `data` attributes.
+4. Ability to select and preview multiple files. Uses HTML 5 File reader API to read and preview files. Displays the progress of files being being loaded onto the preview zone, in case many files are chosen.
+5. Offers predefined templates and CSS classes which can be changed to style your file-input display as per your needs.
+6. Option to show/hide any or all of the following:
+   - caption section
+   - preview section
+   - upload button
+   - remove button
+7. Customise the location of the target container elements to display the entire plugin, the caption container, the caption text, the preview container, preview image, and preview status.
+8. For text file previews, autowrap the text to the thumbnail width, and show a wrap indicator link to display complete text on hover. You can customize the wrap indicator (which defaults to …).
+9. Customise the messages for preview, progress, and files selected.
+10. Upload action defaults to form submit. Supports an upload route/server action parameter for custom ajax based upload.
+11. Triggers JQuery events for advanced development. Events currently available are `filereset` and `fileclear`.
+12. Disabled and readonly file input support.
+13. Size of the entire plugin is less than 11KB (about 9KB for the minified JS and 2KB for the minified CSS).
+
+## Demo
+
+View the [plugin documentation](http://plugins.krajee.com/fileinput) and [plugin demos](http://plugins.krajee.com/fileinput/demo) at Krajee JQuery plugins. 
+
+## Pre-requisites  
+
+1. [Bootstrap 3.x](http://getbootstrap.com/)
+2. Latest [JQuery](http://jquery.com/)
+3. Most modern browsers supporting HTML5 file inputs and FileReader API including CSS3 & JQuery. For Internet Explorer, one must use IE versions 10 and above.
+
+## Restrictions
+The plugin supports only provides a file input/capture support. It does not actually process the upload of the files to the server.
+
+## Installation
+
+### Using Bower
+You can use the `bower` package manager to install. Run:
+
+    bower install bootstrap-fileinput
+
+### Using Composer
+You can use the `composer` package manager to install. Either run:
+
+    $ php composer.phar require kartik-v/bootstrap-fileinput "dev-master"
+
+or add:
+
+    "kartik-v/bootstrap-fileinput": "dev-master"
+
+to your composer.json file
+
+### Manual Install
+
+You can also manually install the plugin easily to your project. Just download the source [ZIP](https://github.com/kartik-v/bootstrap-fileinput/zipball/master) or [TAR ball](https://github.com/kartik-v/bootstrap-fileinput/tarball/master) and extract the plugin assets (css and js folders) into your project.
+
+## Usage
+
+Step 1: Load the following assets in your header. 
+
+```html
+<link href="http://netdna.bootstrapcdn.com/bootstrap/3.1.0/css/bootstrap.min.css" rel="stylesheet">
+<link href="path/to/css/fileinput.min.css" media="all" rel="stylesheet" type="text/css" />
+<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
+<script src="path/to/js/fileinput.min.js" type="text/javascript"></script>
+```
+
+If you noticed, you need to load the `jquery.min.js` and `bootstrap.min.css` in addition to the `fileinput.min.css` and `fileinput.min.js`.
+
+Step 2: Initialize the plugin on your page. For example,
+
+```js
+// initialize with defaults
+$("#input-id").fileinput();
+
+// with plugin options
+$("#input-id").fileinput({'showUpload':false, 'previewFileType':'any'});
+```
+
+The `#input-id` is the identifier for the input (e.g. `type = file`) on your page, which is hidden automatically by the plugin. 
+
+Alternatively, you can directly call the plugin options by setting data attributes to your input field.
+
+```html
+<input id="input-id" type="file" class="file" data-preview-file-type="text" >
+```
+
+## Documentation
+
+### Plugin Options
+The plugin supports these following options:
+
+#### showCaption
+_boolean_ whether to display the file caption. Defaults to `true`.
+
+#### showPreview
+_boolean_ whether to display the file preview. Defaults to `true`.
+
+#### showRemove
+_boolean_ whether to display the file remove/clear button. Defaults to `true`.
+
+#### showUpload
+_boolean_ whether to display the file upload button. Defaults to `true`. This will default to a form submit button, unless the uploadUrl is specified.
+
+#### captionClass
+_string_ any additional CSS class to append to the caption container.
+
+#### previewClass
+_string_ any additional CSS class to append to the preview container.
+
+#### mainClass
+_string_ any additional CSS class to append to the main plugin container.
+
+#### mainTemplate
+_string_ the template used to render the widget. The following template variables will be parsed:
+
+- `{class}`: any additional CSS class to append to the main widget container.
+- `{preview}`: the content parsed by the `previewTemplate` and will be displayed only if `showPreview` is `true`.
+- `{caption}`: the content parsed by the `captionTemplate` and will be displayed only if `showCaption` is `true`.
+- `{remove}`: the file remove/clear button and will be displayed only if `showRemove` is `true`.
+- `{upload}`: the file upload button and will be displayed only if `showUpload` is `true`.
+- `{browse}`: the main file browse button to select your files for input.
+
+The `mainTemplate` if not passed, will be automatically set based on `showCaption` settings.
+
+- If `showCaption` is set to `true`, the `mainTemplate` will default to:
+    
+    {preview}\n
+    <div class="input-group {class}">\n
+       {caption}\n
+       <div class="input-group-btn">\n
+           {remove}\n
+           {upload}\n
+           {browse}\n
+       </div>\n
+    </div>\n
+
+- If `showCaption` is set to `false`, the `mainTemplate` will default to:
+
+    {preview}\n{remove}\n{upload}\n{browse}\n
+
+#### captionTemplate
+_string_ the template used to render the caption. The following template variables will be parsed:
+
+- `{class}`: any additional CSS class to append to the caption container.
+
+The `captionTemplate` if not set will default to:
+
+    <div class="form-control file-caption {class}">\n
+       <span class="glyphicon glyphicon-file"></span> <span class="file-caption-name"></span>\n
+    </div>
+
+#### previewTemplate
+_string_ the template used to render the preview. The following template variables will be parsed:
+
+- `{class}`: any additional CSS class to append to the preview container.
+
+The `previewTemplate` if not set will default to:
+
+    <div class="file-preview {class}">\n
+       <div class="file-preview-status text-center text-success"></div>\n
+       <div class="close fileinput-remove text-right">&times;</div>\n
+       <div class="file-preview-thumbnails"></div>\n
+       <div class="clearfix"></div> +
+    </div>
+
+#### browseLabel
+_string_ the label to display for the file picker/browse button. Defaults to `Browse &hellip;`.
+
+#### browseIcon
+_string_ the icon to display before the label for the file picker/browse button. Defaults to `<i class="glyphicon glyphicon-folder-open"></i> &nbsp;`.
+
+#### browseClass
+_string_ the CSS class for the file picker/browse button. Defaults to `btn btn-primary`.
+
+#### removeLabel
+_string_ the label to display for the file remove button. Defaults to `Remove`.
+
+#### removeIcon
+_string_ the icon to display before the label for the file picker/remove button. Defaults to `<i class="glyphicon glyphicon-ban-circle"></i> &nbsp;`.
+
+#### removeClass
+_string_ the CSS class for the file remove button. Defaults to `btn btn-default`.
+
+#### uploadLabel
+_string_ the label to display for the file upload button. Defaults to `Remove`.
+
+#### uploadIcon
+_string_ the icon to display before the label for the file upload button. Defaults to `<i class="glyphicon glyphicon-upload"></i> &nbsp;`.
+
+#### uploadClass
+_string_ the CSS class for the file upload button. Defaults to `btn btn-default`.
+
+#### uploadUrl
+_string_ the URL for the upload processing action (typically for ajax based processing). Defaults to `null`. If this is not set or `null`, then the upload button action will default to form submission.
+
+#### msgLoading
+_string_ the message displayed when the files are getting read and loaded for preview. Defaults to `Loading &hellip;`.
+
+#### msgProgress
+_string_ the progress message displayed as each file is loaded for preview. Defaults to `Loaded {percent}% of {file}`. The following variables will be replaced:
+
+`{percent}`: the percentage of file read and loaded.
+`{file}`: the name of the file being loaded.
+
+#### msgSelected
+_string_ the progress message displayed in caption window when multiple (more than one) files are selected. Defaults to `{n} files selected`. The following variables will be replaced:
+
+`{n}`: the number of files selected.
+
+#### previewFileType
+_string_ the type of files that are to be displayed in the preview window. Defaults to `image`. Can be one of the following:
+
+- `image`: Only `image` type files will be shown in preview.
+- `text`:  Only `text` type files will be shown in preview.
+- `any`: Both `image` and `text` files content will be shown in preview.
+
+Files other than `image` or `text` will be displayed as a thumbnail with the filename in the preview window.
+
+#### wrapTextLength
+_integer_ the number of characters after which the content will be stripped/wrapped for text preview. Defaults to `250`.
+
+#### wrapIndicator
+_string_ the type of files that are to be displayed in the preview window. Defaults to ` <span class="wrap-indicator" title="{title}">[&hellip;]</span>`.  The following variables will be replaced:
+
+`{title}`: the content of the entire text file that will be displayed as a span title element.
+
+#### elCaptionContainer
+_DOM Element_ the container element containing the caption. If not set, will default to the container with CSS class `file-caption` inside the main plugin container.
+
+#### elCaptionText
+_DOM Element_ the container element containing the caption text. If not set, will default to the container with CSS class `file-caption-name` inside the main plugin container.
+
+#### elPreviewContainer
+_DOM Element_ the container element containing the preview. If not set, will default to the container with CSS class `file-preview` inside the main plugin container.
+
+#### elPreviewImage
+_DOM Element_ the container element containing the preview image thumbnails. If not set, will default to the container with CSS class `file-preview-thumbnails` inside the main plugin container.
+
+#### elPreviewStatus
+_DOM Element_ the container element containing the preview progress status. If not set, will default to the container with CSS class `file-preview-status` inside the main plugin container.
+
+### Plugin Events
+The plugin supports these events:
+
+#### fileclear
+This event is triggered when the file input is cleared with the remove button.
+
+**Example:**
+```js
+$('#input-id').on('fileclear', function(event) {
+    console.log("fileclear");
+});
+```
+
+#### filereset
+This event is triggered when the file input is reset to initial value.
+
+**Example:**
+```js
+$('#input-id').on('filereset', function(event) {
+    console.log("filereset");
+});
+```
+
+### Plugin Methods
+The plugin supports these methods:
+
+#### refresh
+Refreshes the file input after changing its value via javascript.
+```js
+$('#input-id').val(3);
+$('#input-id').fileinput('refresh');
+```
+
+#### reset
+Reset the file input.
+```js
+$('#input-id').fileinput('reset');
+```
+
+#### clear
+Clear the file input.
+```js
+$('#input-id').fileinput('clear');
+```
+
+## License
+
+**bootstrap-fileinput** is released under the BSD 3-Clause License. See the bundled `LICENSE.md` for details.

examples/index.html

@@ -17,6 +17,9 @@
                 </div>
                 <div class="form-group">
                     <input id="file-2" type="file" class="file" readonly=true>
+                </div> 
+                <div class="form-group">
+                    <input id="file-1" type="file" class="file" multiple=true data-show-caption="false" data-browse-class="btn btn-primary btn-lg" data-preview-file-type="any">
                 </div>
                 <div class="form-group">
                     <button class="btn btn-primary">Submit</button>

js/fileinput.js

@@ -8,7 +8,7 @@
  * and Jasny's File Input plugin http://jasny.github.io/bootstrap/javascript/#fileinput
  * 
  * The plugin drastically enhances the file input to preview multiple files on the client before
- * upload. In addition it provides the ability to preview content of images and text/htm files. 
+ * upload. In addition it provides the ability to preview content of images and text files. 
  * 
  * Author: Kartik Visweswaran
  * Copyright: 2013, Kartik Visweswaran, Krajee.com
@@ -16,7 +16,7 @@
  * For more Yii related demos visit http://demos.krajee.com
  */
 (function($) {
-    var MAIN_TEMPLATE =
+    var MAIN_TEMPLATE_1 =
         '{preview}\n' +
         '<div class="input-group {class}">\n' +
         '   {caption}\n' +
@@ -27,6 +27,8 @@
         '   </div>\n' +
         '</div>';
 
+    var MAIN_TEMPLATE_2 = '{preview}\n{remove}\n{upload}\n{browse}\n';
+
     var PREVIEW_TEMPLATE =
         '<div class="file-preview {class}">\n' +
         '   <div class="file-preview-status text-center text-success"></div>\n' +
@@ -65,11 +67,15 @@
         this.showPreview = options.showPreview;
         this.showRemove = options.showRemove;
         this.showUpload = options.showUpload;
-        this.showMessage = options.showMessage;
         this.captionClass = options.captionClass;
         this.previewClass = options.previewClass;
         this.mainClass = options.mainClass;
-        this.mainTemplate = options.mainTemplate;
+        if (isEmpty(options.mainTemplate)) {
+            this.mainTemplate = this.showCaption ? MAIN_TEMPLATE_1 : MAIN_TEMPLATE_2;
+        }
+        else {
+            this.mainTemplate = options.mainTemplate;
+        }
         this.previewTemplate = options.previewTemplate;
         this.captionTemplate = options.captionTemplate;
         this.browseLabel = options.browseLabel;
@@ -81,7 +87,7 @@
         this.uploadLabel = options.uploadLabel;
         this.uploadIcon = options.uploadIcon;
         this.uploadClass = options.uploadClass;
-        this.uploadRoute = options.uploadRoute;
+        this.uploadUrl = options.uploadUrl;
         this.msgLoading = options.msgLoading;
         this.msgProgress = options.msgProgress;
         this.msgSelected = options.msgSelected;
@@ -268,11 +274,11 @@
             if (self.isDisabled) {
                 status = ' disabled ';
             }
-            if (isEmpty(self.uploadRoute)) {
+            if (isEmpty(self.uploadUrl)) {
                 content = '<button type="submit" class="' + self.uploadClass + '"' + status + '>' + self.uploadIcon + self.uploadLabel + '</button>';
             }
             else {
-                content = '<a href="' + self.uploadRoute + '" class="' + self.uploadClass + '"' + status + '>' + self.uploadIcon + self.uploadLabel + '</a>';
+                content = '<a href="' + self.uploadUrl + '" class="' + self.uploadClass + '"' + status + '>' + self.uploadIcon + self.uploadLabel + '</a>';
             }
             return content;
         },
@@ -310,20 +316,14 @@
     };
 
     $.fn.fileinput.defaults = {
-        elCaptionContainer: null,
-        elCaptionText: null,
-        elPreviewContainer: null,
-        elPreviewImage: null,
-        elPreviewStatus: null,
         showCaption: true,
         showPreview: true,
         showRemove: true,
         showUpload: true,
-        showMessage: true,
         captionClass: '',
         previewClass: '',
         mainClass: '',
-        mainTemplate: MAIN_TEMPLATE,
+        mainTemplate: null,
         previewTemplate: PREVIEW_TEMPLATE,
         captionTemplate: CAPTION_TEMPLATE,
         browseLabel: 'Browse &hellip;',
@@ -331,17 +331,22 @@
         browseClass: 'btn btn-primary',
         removeLabel: 'Remove',
         removeIcon: '<i class="glyphicon glyphicon-ban-circle"></i> ',
-        removeClass: 'btn btn-danger',
+        removeClass: 'btn btn-default',
         uploadLabel: 'Upload',
         uploadIcon: '<i class="glyphicon glyphicon-upload"></i> ',
         uploadClass: 'btn btn-default',
-        uploadRoute: null,
+        uploadUrl: null,
         msgLoading: 'Loading &hellip;',
         msgProgress: 'Loaded {percent}% of {file}',
         msgSelected: '{n} files selected',
         previewFileType: 'image',
         wrapTextLength: 250,
-        wrapIndicator: ' <span class="wrap-indicator" title="{title}">[&hellip;]</span>'
+        wrapIndicator: ' <span class="wrap-indicator" title="{title}">[&hellip;]</span>',
+        elCaptionContainer: null,
+        elCaptionText: null,
+        elPreviewContainer: null,
+        elPreviewImage: null,
+        elPreviewStatus: null
     };
 
     /**