yassinehamouten / ux-dropzone-multiple
File input dropzones multiple for Symfony Forms
Installs: 2 353
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 15
Type:symfony-bundle
Requires
- php: >=7.2.5
- symfony/config: ^4.4.17|^5.0
- symfony/dependency-injection: ^4.4.17|^5.0
- symfony/form: ^4.4.17|^5.0
- symfony/http-kernel: ^4.4.17|^5.0
Requires (Dev)
- symfony/framework-bundle: ^4.4.17|^5.0
- symfony/phpunit-bridge: ^5.2
- symfony/twig-bundle: ^4.4.17|^5.0
- symfony/var-dumper: ^4.4.17|^5.0
This package is auto-updated.
Last update: 2024-04-11 23:44:00 UTC
README
Symfony UX Dropzone is a Symfony bundle providing light dropzones for file inputs in Symfony Forms. It is part of the Symfony UX initiative.
It allows visitors to drag and drop files into a container instead of having to browse their computer for a file.
Installation
Symfony UX Dropzone requires PHP 7.2+ and Symfony 4.4+.
Install this bundle using Composer and Symfony Flex:
composer require symfony/ux-dropzone
# Don't forget to install the JavaScript dependencies as well and compile
yarn install --force
yarn encore dev
Also make sure you have at least version 2.0 of @symfony/stimulus-bridge
in your package.json
file.
Usage
The most common usage of Symfony UX Dropzone is to use it as a drop-in replacement of the native FileType class:
// ... use yassinehamouten\UX\DropzoneMultiple\Form\DropzoneMultipleType; class CommentFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder // ... ->add('photo', DropzoneMultipleType::class) // ... ; } // ... }
Customizing the design
Symfony UX Dropzone provides a default stylesheet in order to ease usage. You can disable it to add your own design if you wish.
In assets/controllers.json
, disable the default stylesheet by switching
the @yassinehamouten/ux-dropzone-multiple/src/style.css
autoimport to false
:
{ "controllers": { "@yassinehamouten/ux-dropzone-multiple": { "dropzone-multiple": { "enabled": true, "webpackMode": "eager", "autoimport": { "@yassinehamouten/ux-dropzone-multiple/src/style.css": false } } } }, "entrypoints": [] }
Note: you should put the value to
false
and not remove the line so that Symfony Flex won't try to add the line again in the future.
Once done, the default stylesheet won't be used anymore and you can implement your own CSS on top of the Dropzone.
Extend the default behavior
Symfony UX Dropzone allows you to extend its default behavior using a custom Stimulus controller:
// mydropzone_controller.js import { Controller } from 'stimulus'; export default class extends Controller { connect() { this.element.addEventListener('dropzone-multiple:connect', this._onConnect); this.element.addEventListener('dropzone-multiple:change', this._onChange); this.element.addEventListener('dropzone-multiple:clear', this._onClear); } disconnect() { // You should always remove listeners when the controller is disconnected to avoid side-effects this.element.removeEventListener('dropzone-multiple:connect', this._onConnect); this.element.removeEventListener('dropzone-multiple:change', this._onChange); this.element.removeEventListener('dropzone-multiple:clear', this._onClear); } _onConnect(event) { // The dropzone was just created } _onChange(event) { // The dropzone just changed } _onClear(event) { // The dropzone has just been cleared } }
Then in your form, add your controller as an HTML attribute:
// ... use yassinehamouten\UX\DropzoneMultiple\Form\DropzoneMultipleType; class CommentFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder // ... ->add('photo', DropzoneMultipleType::class, [ 'attr' => ['data-controller' => 'mydropzone'], ]) // ... ; } // ... }
Backward Compatibility promise
This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
However it is currently considered experimental, meaning it is not bound to Symfony's BC policy for the moment.
Run tests
PHP tests
php vendor/bin/phpunit
JavaScript tests
cd Resources/assets yarn test