FileInput Widget FileInput.php

Thankful to Krajee!
to get more out of us.

NOTE: This extension depends on the yiisoft/yii2-bootstrap extension. Check the composer.json for this extension's requirements and dependencies that may be updated by composer.

The FileInput widget is a wrapper for the Bootstrap File Input JQuery Plugin designed by Krajee. This plugin enhances the HTML 5 file input for Bootstrap 3.x with file preview for images and text, multiple selection, and more. The widget enhances the default HTML file input with various features including the following:

Important

This widget can be also installed in isolation outside this bundle if needed. In addition to using via \kartik\widgets namespace, this widget can be also installed from the yii2-widget-fileinput repository and can also be accessed via \kartik\file\FileInput namespace.
  • Specially styled for Bootstrap 3.0 with customizable buttons, caption, and preview
  • Ability to select and preview multiple files
  • Includes file browse and optional remove and upload buttons.
  • Ability to format your file picker button styles
  • Ability to preview files before upload - images and/or text (uses HTML5 FileReader API)
  • Ability to preview multiple files of different types (both images and text)
  • Set your upload action/route (defaults to form submit). Customize the Upload and Remove buttons.
  • Internationalization enabled for easy translation to various languages

The widget runs on all modern browsers supporting HTML5 File Inputs and File Processing API. For browsers not supporting Javascript/Jquery this widget will gracefully degrade to normal HTML file input.

The widget is a wrapper for the Bootstrap FileInput JQuery plugin by Krajee. Refer plugin documentation and demos for details. The widget supports all parameters that one would pass for any Yii Input Widget. The additional parameter settings specially available for the FileInput widget configuration are:
  • showMessage: boolean, whether to display a warning message for browsers running IE9 and below. Defaults to true.

  • messageOptions: array, HTML attributes for the container for the warning message for browsers running IE9 and below. Defaults to ['class' => 'alert alert-warning'].

  • options: array, the HTML attributes for the file input.

  • pluginLoading: boolean, whether to show a loading progress indicator in place of the input before plugin is completely loaded. Defaults to true.

  • pluginOptions: array the plugin settings/options for the Bootstrap Star Rating Plugin. There are a quite a few options you can set in this plugin. Refer the plugin documentation and demos for details.

  • pluginEvents: array the StarRating JQuery events. You must define events in event-name => event-function format. All events will be stacked in the sequence. Refer the plugin documentation and demos for details. For example:

    pluginEvents = [
        "fileclear" => "function() { log("fileclear"); }",
        "filereset" => "function() { log("filereset"); }",
    ];
    

Note:

When using the widget to upload multiple files you must name the HTML input in array format by appending [] to the input/attribute name. Check the examples for usage.

Usage with ActiveForm and model
With model & without ActiveForm. Note: for multiple file upload, the attribute name must be appended with [] for PHP to be able to read an array of files.
Usage without a model
A disabled file input
use kartik\widgets\FileInput

// Usage with ActiveForm and model
echo $form->field($model, 'avatar')->widget(FileInput::classname(), [
    'options' => ['accept' => 'image/*'],
]);

// With model & without ActiveForm
// Note for multiple file upload, the attribute name must be appended with 
// `[]` for PHP to be able to read an array of files
echo '<label class="control-label">Add Attachments</label>';
echo FileInput::widget([
    'model' => $model,
    'attribute' => 'attachment_1[]',
    'options' => ['multiple' => true]
]);

// Usage without a model
echo '<label class="control-label">Upload Document</label>';
echo FileInput::widget([
    'name' => 'attachment_3',
]);

// A disabled fileinput input
echo '<label class="control-label">Select Attachment</label>';
echo FileInput::widget([
    'name' => 'attachment_4',
    'options' => [
        'disabled' => 'disabled'
    ],
]);

Display an initial preview of files with caption (useful in UPDATE scenarios). Set overwriteInitial preview to false to append uploaded images to the initial preview.
Control display of elements
Adjust caption and button size
Style widget buttons
A block file picker button with custom icon and label
Multiple file selection with image only preview. Note: for multiple file upload, the attribute name must be appended with [] for PHP to be able to read an array of files.
Multiple file selection with both text and image preview. Note: for multiple file upload, the attribute name must be appended with [] for PHP to be able to read an array of files.
No file selected
Customizing the plugin elements (e.g. using a different container to display the caption)
FileInput inside a modal dialog.
use kartik\widgets\FileInput

// Display an initial preview of files with caption 
// (useful in UPDATE scenarios). Set overwrite `initialPreview`
// to `false` to append uploaded images to the initial preview.
echo FileInput::widget([
    'name' => 'attachment_49[]',
    'options'=>[
        'multiple'=>true
    ],
    'pluginOptions' => [
        'initialPreview'=>[
            Html::img("/images/moon.jpg", ['class'=>'file-preview-image', 'alt'=>'The Moon', 'title'=>'The Moon']),
            Html::img("/images/earth.jpg",  ['class'=>'file-preview-image', 'alt'=>'The Earth', 'title'=>'The Earth']),
        ],
        'initialCaption'=>"The Moon and the Earth",
        'overwriteInitial'=>false
    ]
]);

// Control display of widget elements
echo FileInput::widget([
    'name' => 'attachment_50',
    'pluginOptions' => [
        'showPreview' => false,
        'showCaption' => true,
        'showRemove' => true,
        'showUpload' => false
    ]
]);

// Adjust caption and button size
 echo FileInput::widget([
    'name' => 'attachment_51',
    'pluginOptions' => [
        'showUpload' => false,
        'browseLabel' => '',
        'removeLabel' => '',
        'mainClass' => 'input-group-lg'
    ]
]);

// Style widget buttons
echo FileInput::widget([
    'name' => 'attachment_52',
    'pluginOptions' => [
        'browseClass' => 'btn btn-success',
        'uploadClass' => 'btn btn-info',
        'removeClass' => 'btn btn-danger',
        'removeIcon' => '<i class="glyphicon glyphicon-trash"></i> '
    ]
]);

// A block file picker button with custom icon and label
echo FileInput::widget([
    'name' => 'attachment_53',
    'pluginOptions' => [
        'showCaption' => false,
        'showRemove' => false,
        'showUpload' => false,
        'browseClass' => 'btn btn-primary btn-block',
        'browseIcon' => '<i class="glyphicon glyphicon-camera"></i> ',
        'browseLabel' =>  'Select Photo'
    ],
    'options' => ['accept' => 'image/*']
]);
        
// Multiple file/image selection with image only preview
// Note for multiple file upload, the attribute name must be appended with 
// `[]` for PHP to be able to read an array of files
echo $form->field($model, 'avatar[]')->widget(FileInput::classname(), [
    'options' => ['multiple' => true, 'accept' => 'image/*'],
    'pluginOptions' => ['previewFileType' => 'image']
]);
        
// Multiple file selection with both text and image preview
// Note for multiple file upload, the attribute name must be appended with 
// `[]` for PHP to be able to read an array of files
echo $form->field($model, 'upload_files[]')->widget(FileInput::classname(), [
    'options' => ['multiple' => true],
    'pluginOptions' => ['previewFileType' => 'any']
]);

// Customizing the plugin elements (e.g. using a different container to display the caption)
echo '<div class="well well-small">';
echo FileInput::widget([
    'name' => 'attachment_30',
    'pluginOptions' => [
        'showPreview' => false,
        'showCaption' => false,
        'elCaptionText' => '#customCaption'
    ]
]);
echo '<span id="customCaption" class="text-success">No file selected</span>';
echo '</div>';

// FileInput inside a modal dialog
use yii\bootstrap\Modal;
use kartik\widgets\ActiveForm;
use kartik\widgets\FileInput;
Modal::begin([
    'header'=>'File Input inside Modal',
    'toggleButton' => [
        'label'=>'Show Modal', 'class'=>'btn btn-default'
    ],
]);
$form1 = ActiveForm::begin([
    'options'=>['enctype'=>'multipart/form-data'] // important
]);
echo FileInput::widget(['name'=>'kartiks_file']);
ActiveForm::end();
Modal::end();