Componette

Componette

nepada

nepada / file-upload-control v1.8.1

File upload control for Nette forms: multi-file AJAX upload via blueimp-file-upload, Bootstrap 4 and 5 template.

download-cloud-line composer require nepada/file-upload-control

File Upload form control

Build Status Coverage Status Downloads this Month Latest stable

Installation

Via Composer:

$ composer require nepada/file-upload-control

Register and configure container extension

The only required configuration option is uploadDirectory, which determines where are the uploaded files temporarily stored.

extensions:
    fileUploadControl: Nepada\Bridges\FileUploadControlDI\FileUploadControlExtension
fileUploadControl:
    uploadDirectory: %appDir%/../files/uploads

Add factory method to your forms

Option A: install form container extension method via DI extension

fileUploadControl:
    registerExtensionMethod: true # defaults to false

This will register extension method addFileUpload($name, $label = null): FileUploadControl to Nette\Forms\Container.

Option B: use trait in your base form/container class

You can also use FileUploadControlMixin trait in your base form/container class to add method addFileUpload($name, $label = null): FileUploadControl. You need to inject FileUploadControlFactory into every form/container you create, e.g. by combination of a common form factory service and decorator configuration for enabling injects.

Example:

services:
    - FormFactory
decorator:
    Form:
        inject: true
trait FormControls
{

    use \Nepada\Bridges\FileUploadControlForms\FileUploadControlMixin;

    public function addContainer($name)
    {
        $control = new Container;
        $control->injectFileUploadFactory($this->fileUploadControlFactory);
        $control->setCurrentGroup($this->getCurrentGroup());
        if ($this->currentGroup !== null) {
            $this->currentGroup->add($control);
        }
        return $this[$name] = $control;
    }

}

class Container extends \Nette\Forms\Container
{

    use FormControls;

}

class Form extends \Nette\Application\UI\Form
{

    use FormControls;

}

interface FormFactory
{

    public function create(): Form;

}

Usage

FileUploadControl provides a way to upload files similarly to the standard Nette\Forms\Controls\UploadControl. The main difference is that the files are uploaded in chunks via AJAX requests into the temporary storage. This means you can upload multiple large files without the risk of running into server-side file/POST size limits. After submitting the form, the form control's value is set to a list of FileUpload instances of previously uploaded files in temporary storage.

Configuration

The DI extension supports to following configuration options:

fileUpload:
    uploadDirectory: path/to/temp/storage # required, no default value
    registerExtensionMethod: true # defaults to false
    templateFile: path/to/alternative/control-template.latte # defaults to the bundled Bootstrap 4 template
    thumbnails: # image thumbnail settings
        enable: true
        width: 200
        height: 150

The package includes templates and styles build for Bootstrap version 4 and version 5. By default, version 4 is used, but to improve forward compatibility you should always explicitly specify which version you'd like to be used:

fileUpload:
    templateFile: ::constant(Nepada\FileUploadControl\FileUploadControl::TEMPLATE_FILE_BOOTSTRAP4)
    # or for Bootstrap 5
    # templateFile: ::constant(Nepada\FileUploadControl\FileUploadControl::TEMPLATE_FILE_BOOTSTRAP5)

Validation

All standard Nette file upload related validations work as expected. Furthermore, you can limit the number of allowed uploads by "length" rules.

Client side

This package comes with client side built on top of blueimp-file-upload. It is published as npm package @nepada/file-upload-control.

Bootstrap 4 theme

Using precompiled bundle

Using precompiled bundles is the quick'n'dirty way of getting client side to work.

<link rel="stylesheet" href="https://unpkg.com/@nepada/file-upload-control@%5E1.7/dist/css/file-upload-control-bootstrap4.min.css">
<!-- or for Bootstrap 5
<link rel="stylesheet" href="https://unpkg.com/@nepada/file-upload-control@%5E1.7/dist/css/file-upload-control-bootstrap5.min.css">
-->
<script src="https://unpkg.com/jquery@%5E3.5.0/dist/jquery.min.js"></script>
<script src="https://unpkg.com/blueimp-file-upload@%5E10.10.0/js/vendor/jquery.ui.widget.js"></script>
<script src="https://unpkg.com/blueimp-file-upload@%5E10.10.0/js/jquery.fileupload.js"></script>
<script src="https://unpkg.com/nette-forms@%5E3.0.3/src/assets/netteForms.min.js"></script>
<script src="https://unpkg.com/@nepada/file-upload-control@%5E1.7/dist/js/file-upload-control.min.js"></script>

Building your own bundle

It is highly recommended to install the client side package via nmp and compile your own bundle.

Here is an example script for initialization of file upload control and Nette forms.

import Nette from 'nette-forms';
import initializeFileUploadControl from '@nepada/file-upload-control';

initializeFileUploadControl(Nette);

Nette.initOnLoad();

If you use Bootstrap 4 or 5, you can easily customize the default look by importing the source SCSS files into your Sass styles:

  • v1.8.1 1.8.1

    • Fix compatibility with nette/application 3.2
  • v1.8.0 1.8.0

    • Added validation to prevent form submit with partially uploaded files
      • Client side form validation rule checking no upload is in progress
      • Backend form validation rule checking all uploads have successfully finished
    • Partially uploaded files are rendered as failed uploads after form submit to notify user and make it possible to delete them
      • Previously they were not shown in UI at all
      • Custom control templates need to be updated - there are new $partiallyUploadedFiles and $allFiles variables available alongside the old $completedFiles
    • Prefer standard Nette error message for failed uploads
    • Change internal representation of failed uploads (possible BC break)
      • FileUploadChunk now represents successful upload only
      • New FailedUpload value object represents failed uploads
  • v1.7.1 1.7.1

    • Chunked upload validation #143 bugfix (mime type validation rule causing failure on upload of 2nd chunk)
  • v1.7.0 1.7.0

    • DI extension: allow to configure the template file by a constant reference
    • Forward compatibility with Nette Forms 3.2
      • Loosen paramater typehints for validation methods (Html -> Stringable)
      • Loosen caption typehints where possible (Html -> Stringable)
    • Added Bootstrap 5 support - new template & styles
    • Bootstrap 4 template & styles made available under new more specific names
      • To improve forward compatibility always explicitly specify which version of template and styles you'd like to be used
  • v1.6.0 1.6.0

    • Drop support for PHP <8.1
    • Drop Latt 2.x support
    • Use PHP8 native typehints
    • Use readonly properties in simple DTOs
    • Drop useless annotations
    • PHP 8.3 compatibility
  • v1.5.0 1.5.0

    • Nette utils 4.x support
  • v1.4.0 1.4.0

    • Cleanup Nette deprecations
    • PHP 8.2 compatibility
    • Bump FE dependencies
  • v1.3.0 1.3.0

    • Explicitly restrict maximum supported PHP version in composer.json
    • Latte 3.x compatibility
  • v1.2.0 1.2.0

    • PHP 8.1 compatibility.
  • v1.1.0 1.1.0

    • PHP 8.0 compatibility.
  • v1.0.1 1.0.1

    • Fixed client side initialization. In some edge cases the UI did not get properly initialized.
  • v1.0.0 1.0.0

    • Initial release.
bar-chart-fill

Statistics

download-cloud-fill
2692
star-fill
7
bug-fill
1
flashlight-fill
5d
price-tag-2-line

Badges

guide-fill

Dependencies

php (>=7.4.0)
ext-json (*)
latte/latte (^2.7.0)
nette/application (^3.0.2@dev)
nette/forms (^3.0@dev)
nette/http (^3.0@dev)
nette/utils (^3.1.1@dev)
Componette Componette felix@nette.org