Skip to content

Commit 1c481d4

Browse files
solveratsolverat
authored
Dynamic Multi File Adapter (#282)
* refactor dynamic multi file to allow different interfaces * add fieldname to attachment asset * remove adapter label if empty * introduce dropzonejs adapter * improve event dispatch and corresponding docs * disable autoDiscover for dropZone * improve docs * improve dropZone docs * improve fineUploader docs * add upgrade notes
1 parent d92187e commit 1c481d4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+2230
-943
lines changed

‎README.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
```json
2222
"require" : {
23-
"dachcom-digital/formbuilder" : "~3.3.0"
23+
"dachcom-digital/formbuilder" : "~3.4.0"
2424
}
2525
```
2626

@@ -83,6 +83,9 @@ Nothing to tell here, it's just [Symfony](https://symfony.com/doc/current/templa
8383
- [Form Presets](docs/60_Presets.md)
8484
- [Events](docs/70_Events.md)
8585
- [Mastering File Uploads](docs/80_FileUpload.md)
86+
- [DropZoneJs](docs/DynamicMultiFile/01_DropZoneJs.md)
87+
- [FineUploader](docs/DynamicMultiFile/02_FineUploader.md)
88+
- [Custom Adapter](docs/DynamicMultiFile/99_CustomAdapter.md)
8689
- [Conditional Logic](docs/81_ConditionalLogic.md)
8790
- [Form & Field Attributes](docs/83_Attributes.md)
8891
- [Frontend Tips](docs/90_FrontendTips.md)

‎UPGRADE.md

+4
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,16 @@ After every update you should check the pimcore extension manager.
77
Just click the "update" button or execute the migration command to finish the bundle update.
88

99
#### Update from Version 3.3.5 to Version 3.4.0
10+
- **[NEW FEATURE]**: Introduce Dynamic Multi File Adapter (DropZoneJs added) [#261](https://github.com/dachcom-digital/pimcore-formbuilder/issues/261)
11+
- **[DEPRECATION]**: FineUploader Adapter has been marked as deprecated and will be removed with version 4.0.
12+
1013
- **[NEW FEATURE]**: Choice Meta Data [#275](https://github.com/dachcom-digital/pimcore-formbuilder/issues/275)
1114
- **[NEW FEATURE]**: Pimcore 6.9.0 ready
1215
- **[IMPROVEMENT]**: D&D-Support/Sortable Container Fields [#231](https://github.com/dachcom-digital/pimcore-formbuilder/issues/231)
1316
- **[IMPROVEMENT]**: Adjust field attribute label "Preselected" [#270](https://github.com/dachcom-digital/pimcore-formbuilder/issues/270)
1417
- **[IMPROVEMENT]**: Field name preview added [#237](https://github.com/dachcom-digital/pimcore-formbuilder/issues/237)
1518
- **[BUGFIX]**: Remove `body` param from mail object after rendering [#268](https://github.com/dachcom-digital/pimcore-formbuilder/issues/268)
19+
- **[BUGFIX]**: Fix container toggle in conditional logic
1620

1721
#### Update from Version 3.3.5 to Version 3.3.6
1822
- **[IMPROVEMENT]**: Allow `label_translation_parameters` [#252](https://github.com/dachcom-digital/pimcore-formbuilder/issues/252) and restrict translated labels to 190 characters [#226 (comment)](https://github.com/dachcom-digital/pimcore-formbuilder/issues/226#issuecomment-769022296)

‎docs/80_FileUpload.md

+42-36
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,50 @@
1-
# File Upload Type
1+
# Dynamic Multi File
22

3-
<img width="566" src="https://user-images.githubusercontent.com/700119/30774631-1eaf7d22-a086-11e7-81d8-382e30a60eef.png">
3+
FormBuilder comes with a smart multi file upload type.
4+
It allows you to use different adapters/libraries like FineUploader or DropZoneJs.
45

5-
FormBuilder comes with a smart multi file upload type.
6-
For a superb user experience, it's using the [fineUploader](https://github.com/FineUploader/fine-uploader) library.
7-
8-
## Workflow:
6+
## Highlights
97
- File Upload per file type (yes, it's possible to place multiple upload fields per form)
10-
- Chunked upload for large files
11-
- Store uploaded file reference in session, since the upload works decoupled from form submission
12-
- After a form submission, the data will be compressed and get stored in pimcore (`/formdata` asset folder)
13-
- Append download link in mail
14-
- Clean Up: unsubmitted data / chunk data will be swiped via maintenance
15-
16-
## Configuration
17-
There are some options in the field configuration.
18-
19-
### Max File Size
20-
Max file size will be calculated in MB. Empty or Zero means no Limit
21-
22-
### Allowed Extensions
23-
Define allowed extensions, for example: `pdf, zip`.
24-
25-
### Item limit
26-
The maximum number of files that can be uploaded. Empty or Zero means no Limit
27-
28-
## Implementation
8+
- Large File Support: Process chunked files to allow large file uploads
9+
- Different adapters: Choose between different upload handler or create a custom one!
10+
- Stateless: no session is required to handle file uploads
11+
- Different storage principals: Store data as pimcore assets (`/formdata` asset folder) and add download-link to mail **or** add them as native mail attachments
12+
- Stay clean: unsubmitted data / chunk data will be swiped via maintenance
13+
- Prebuild Extensions: Use included jQuery extensions to set up your form in front end in no time!
14+
15+
## Field Configuration
16+
There are some options in the (backend) field configuration:
17+
18+
| Name | Description
19+
|------|------------|
20+
| `Max File Size` | Max file size will be calculated in MB. Empty or zero means no limit |
21+
| `Allowed Extensions` | Define allowed extensions, for example: `pdf, zip` (Format depends on active adapter) |
22+
| `Item limit` | The maximum number of files that can be uploaded. Empty or zero means no limit |
23+
| `Send Files as Attachment` | All Files will be stored in your pimcore asset structure (/formdata) by default. If you check this option, the files will be attached to the mail instead of adding a download link |
24+
25+
## Setup
26+
Per default, FineUploader will be used. If you want to change the dmf adapter, you need to define it:
27+
28+
```yaml
29+
form_builder:
30+
dynamic_multi_file_adapter: FormBuilderBundle\DynamicMultiFile\Adapter\DropZoneAdapter
31+
```
2932
30-
### Styling
33+
## Front-End Setup
34+
By default, you don't need to implement more than the standard initialization, described in [FormBuilder Javascript Core Extension](./91_Javascript.md#core-extension).
35+
The core extension will try to fetch the handler path, defined by `dynamicMultiFileDefaultHandlerPath`.
3136

32-
Add the CDN Link or implement your own styling.
37+
### Disable Default Initialization
38+
All handler will be initialized by lazy loading, so they will be requested only if upload files are available.
39+
However, if you **don't** want to initialize any handler because of your own frontend logic for example, you may want to disable the initialization:
3340

34-
```twig
35-
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/file-uploader/5.15.0/all.fine-uploader/fine-uploader-new.min.css" />
41+
```javascript
42+
$('form.formbuilder.ajax-form').formBuilderAjaxManager({
43+
setupFileUpload: false, // disable default dynamic multi file handler
44+
});
3645
```
3746

38-
To enable fineuploader, add the javascript library and formbuilder core script.
39-
40-
### Scripts
41-
```twig
42-
<script type="text/javascript" src="{{ asset('bundles/formbuilder/js/frontend/vendor/fineuploader/jquery.fine-uploader.min.js') }}"></script>
43-
<script type="text/javascript" src="{{ asset('bundles/formbuilder/js/frontend/plugins/jquery.fb.core.form-builder.js') }}"></script>
44-
```
47+
## Available Adapter
48+
- [DropZoneJs](./DynamicMultiFile/01_DropZoneJs.md)
49+
- [FineUploader](./DynamicMultiFile/02_FineUploader.md)
50+
- [Custom Adapter](./DynamicMultiFile/99_CustomAdapter.md)

‎docs/91_Javascript.md

+11-2
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@ Of course it's up to you to copy those files into your project and modify them a
1212
- [reCAPTCHA V3 Extension](#recaptcha-v3-extension)
1313

1414
## Core Extension
15-
This Plugin will enable the ajax functionality but also the multi file handling:
15+
This Plugin will enable the ajax functionality but also the multi file handling.
16+
17+
> Read more about the dynamic multi file setup [here](./80_FileUpload.md)
1618
1719
### Enable Extension
1820

@@ -25,6 +27,7 @@ $(function () {
2527
$('form.formbuilder.ajax-form').formBuilderAjaxManager();
2628
});
2729
```
30+
2831
### Extended Usage
2932
```javascript
3033
$('form.formbuilder.ajax-form').formBuilderAjaxManager({
@@ -37,7 +40,13 @@ $('form.formbuilder.ajax-form').formBuilderAjaxManager({
3740
removeFormValidations: function($form) {
3841
console.log($form);
3942
}
40-
}
43+
},
44+
dynamicMultiFileDefaultHandlerPath: '/bundles/formbuilder/js/frontend/plugins/dynamic-multi-file',
45+
dynamicMultiFileHandlerOptions: {
46+
// these options will be passed to the active dmf handler
47+
/* @deprecated libPath is a deprecated since 3.4 and will be removed in 4.0 */
48+
libPath: '/bundles/formbuilder/js/frontend/vendor/fineuploader/jquery.fine-uploader.min.js',
49+
},
4150
});
4251
```
4352

‎docs/Deprecated/SuccessMessage.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ If you're adding a text type, the form is just returning the text value you coul
1919
"Thank you for your message" for example.
2020

2121
*Snippet*
22-
A Snippet could be useful if you need more output structure. FormBuild will render the snippet and return its html data.
22+
A Snippet could be useful if you need more output structure. FormBuilder will render the snippet and return its html data.
2323

2424
*Document*
2525
Use a document to get its path to perform a redirect for example.

‎docs/DynamicMultiFile/01_DropZoneJs.md

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Dynamic MultiFile | DropZone
2+
3+
![image](https://user-images.githubusercontent.com/700119/119269406-daf90080-bbf7-11eb-9059-01485bf2edf7.png)
4+
5+
- Resource: https://www.dropzonejs.com
6+
- Handler: `jquery.fb.dmf.drop-zone.js`
7+
- Library: [dropzone.min.js](https://cdnjs.cloudflare.com/ajax/libs/dropzone/5.9.2/min/dropzone.min.js)
8+
9+
***
10+
11+
## Implementation
12+
13+
### Declarative Way
14+
The simplest way to implement this adapter is by using the precompiled library loading by CDN and the corresponding handler.
15+
16+
```twig
17+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/dropzone/5.9.2/dropzone.min.css" />
18+
<script type="text/javascript" src="{{ asset('bundles/formbuilder/js/frontend/plugins/jquery.fb.core.form-builder.js') }}"></script>
19+
```
20+
21+
```javascript
22+
$(function () {
23+
$('form.formbuilder.ajax-form').formBuilderAjaxManager({
24+
dynamicMultiFileHandlerOptions: {
25+
libPath: 'https://cdnjs.cloudflare.com/ajax/libs/dropzone/5.9.2/min/dropzone.min.js'
26+
}
27+
});
28+
});
29+
```
30+
31+
#### Events
32+
If you're using the default handler, you're able to hook into the most important initialization processes:
33+
34+
```javascript
35+
$forms.on('formbuilder.dynamic_multi_file.init', function(ev, $dmfField, configuration) {
36+
// overwrite configuraiton
37+
configuration.addRemoveLinks = false;
38+
39+
// NEVER! override configuration.init! this would break all the internal server side communication!
40+
// use event below to add your custom events!
41+
});
42+
43+
$forms.on('formbuilder.dynamic_multi_file.drop_zone.init', function(ev, dropZoneInstance) {
44+
// add eventlistener
45+
dropZoneInstance.on('sending', function (file, xhr, formData) {
46+
console.log(file);
47+
});
48+
});
49+
```
50+
51+
### Imperative Way
52+
This requires more work from your side since we only provide a simple jQuery Handler.
53+
Read more about the implementation [here](https://dropzone.gitbook.io/dropzone/getting-started/setup/imperative).
54+
You also need to build your own handler and requires to **[disable the default behaviour](../80_FileUpload.md#disable-default-initialization)**.

‎docs/DynamicMultiFile/02_FineUploader.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Dynamic Multi File | FineUploader
2+
3+
> Note! FineUploader has reached the [end of life](https://github.com/FineUploader/fine-uploader/issues/2073)
4+
> and therefore we cannot longer maintain this adapter. It has been marked as deprecated since 3.4 and will be removed with 4.0.
5+
6+
![image](https://user-images.githubusercontent.com/700119/119269468-23b0b980-bbf8-11eb-8778-a43ad9a56088.png)
7+
8+
> This is the default adapter. If you want do use this adapter, you only need to enable the [core extension (Section "Enable Extension")](../91_Javascript.md#core-extension) and include the styling resources.
9+
10+
Resource:
11+
12+
- Resource: https://fineuploader.com
13+
- Handler: `jquery.fb.dmf.fine-uploader.js`
14+
- Library: [fine-uploader.min.js](https://cdnjs.cloudflare.com/ajax/libs/file-uploader/5.16.2/fine-uploader.min.js)
15+
16+
***
17+
18+
## Implementation
19+
20+
#### Declarative Way
21+
The simplest way to implement this adapter is by using the precompiled library loading by CDN and the corresponding handler.
22+
23+
```twig
24+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/dropzone/5.9.2/dropzone.min.css" />
25+
<script type="text/javascript" src="{{ asset('bundles/formbuilder/js/frontend/plugins/jquery.fb.core.form-builder.js') }}"></script>
26+
```
27+
28+
```javascript
29+
$(function () {
30+
$('form.formbuilder.ajax-form').formBuilderAjaxManager({
31+
dynamicMultiFileHandlerOptions: {
32+
libPath: 'https://cdnjs.cloudflare.com/ajax/libs/file-uploader/5.16.2/fine-uploader.min.js'
33+
}
34+
});
35+
});
36+
```
37+
38+
#### Imperative Way
39+
This requires more work from your side since we only provide a simple jQuery Handler.
40+
Read more about the implementation [here](https://docs.fineuploader.com/features/modules.html).
41+
You also need to build your own handler and requires to **[disable the default behaviour](../80_FileUpload.md#disable-default-initialization)**.

0 commit comments

Comments
 (0)