From 5cd922a756c7862127d25af8236ac9ffc0a761d6 Mon Sep 17 00:00:00 2001 From: Pedro X Date: Thu, 4 May 2023 18:30:28 +0100 Subject: [PATCH 1/8] add dropzone docs --- 6.x/crud-fields.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/6.x/crud-fields.md b/6.x/crud-fields.md index 19dbd34a..b01badde 100644 --- a/6.x/crud-fields.md +++ b/6.x/crud-fields.md @@ -1401,6 +1401,43 @@ Input preview:
+ +### dropzone PRO + +Show a [Dropzone JS Input](https://docs.dropzone.dev/). + +```php +[ + 'name' => 'photos', + 'label' => 'Photos', + 'type' => 'dropzone', + + // optional configuration. + // check available options in https://docs.dropzone.dev/configuration/basics/configuration-options + 'configuration' => [ + 'parallelUploads' => 2, + ] +], +``` + +**IMPORTANT NOTE:** Altough you can do some "validation" in Javascript, we highly advise you to don't disregard server validation. Check the following [dropzone validation docs](#dropzone-validation) + + +#### Validation +The proper validation of dropzone should be done in two steps: +1 - Files should be validated on the file upload endpoint +2 - Field in general should be validated on form submission. + +To make things easy on your side we created `ValidDropzone` validation rule. It's a [Custom Validation Rule](/docs/{{version}}/custom-validation-rules) that allow you to define those set of rules: +- `::field()` - the field rules (independent of the file content); +- `->file()` - rules that apply to the sent files; + +Input preview: + +![CRUD Field - dropzone](https://user-images.githubusercontent.com/7188159/236273902-ca7fb5a5-e7ce-4a03-91a7-2af81598331c.png) + +
+ ### easymde PRO From b4d4f3ba850730e17f6de94f4aa1b8bd66a05ece Mon Sep 17 00:00:00 2001 From: Pedro X Date: Thu, 4 May 2023 18:38:37 +0100 Subject: [PATCH 2/8] add dropzone validation rule docs --- 6.x/custom-validation-rules.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/6.x/custom-validation-rules.md b/6.x/custom-validation-rules.md index 99c3688c..86cfd6b9 100644 --- a/6.x/custom-validation-rules.md +++ b/6.x/custom-validation-rules.md @@ -28,7 +28,7 @@ The `::field()` constructor accepts the rules for the field, while `->file()` ac ## `ValidUploadMultiple` for `upload_multiple` field type -You can use this validation rule to handle validation for you `upload_multiple` field - both for the Create and the Update operation in one go: +You can use this validation rule to handle validation for your `upload_multiple` field - both for the Create and the Update operation in one go: - use the `::field()` constructor to define the rules for the field; - use the `->file()` method for rules specific to the files sent in field; @@ -42,4 +42,23 @@ use Backpack\CRUD\app\Library\Validation\Rules\ValidUploadMultiple; 'attachments' => ValidUploadMultiple::field(['min:2', 'max:5'])->file('mimes:pdf|max:10000'), +``` + + +## `ValidDropzone` for `dropzone` field type + +You can use this validation rule to handle validation for your `dropzone` field - both for the Create and the Update operation in one go: +- use the `::field()` constructor to define the rules for the field; +- use the `->file()` method for rules specific to the files sent in field; + +```php +// for the field +CRUD::field('photos')->type('dropzone'); + +// you can write the validation rule as + +use Backpack\Pro\Uploads\Validation\ValidDropzone; + +'attachments' => ValidDropzone::field('min:2|max:5')->file('file|mimes:jpg,png,gif|max:10000'), + ``` \ No newline at end of file From fe10efdf8498cf3120d911126a4feaed344e8913 Mon Sep 17 00:00:00 2001 From: Pedro X Date: Wed, 10 May 2023 11:35:11 +0100 Subject: [PATCH 3/8] update --- 6.x/crud-fields.md | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/6.x/crud-fields.md b/6.x/crud-fields.md index b01badde..77a2f4b1 100644 --- a/6.x/crud-fields.md +++ b/6.x/crud-fields.md @@ -1406,8 +1406,21 @@ Input preview: Show a [Dropzone JS Input](https://docs.dropzone.dev/). +**Step 1:** Add the `DropzoneOperation` to your `CrudController` + ```php -[ +class UserCrudController extends CrudController +{ + use \Backpack\CRUD\app\Http\Controllers\Operations\CreateOperation; + // ... other operations + use Backpack\Pro\Http\Controllers\Operations\DropzoneOperation; +} +``` + +**Step 2:** Add the field in CrudController + +```php +$this->crud->addField([ 'name' => 'photos', 'label' => 'Photos', 'type' => 'dropzone', @@ -1417,13 +1430,35 @@ Show a [Dropzone JS Input](https://docs.dropzone.dev/). 'configuration' => [ 'parallelUploads' => 2, ] +]); +``` + +**Step 3:** Configure the file upload process. + +At this point you have the dropzone field showing up, and the ajax routes setup to upload/delete files, but the process is not complete. +Your files are now only uploaded to the temporary folder, they need to be moved to the permanent location and their paths stored in the database. + +You can manually implement the saving process yourself using model events, mutators or any other flavor that suits you, or use the `AjaxUploader` that we developed to help you with this task. + +To enable the `AjaxUploader` just add `withFiles => true` to your field definition: + +```php +[ + 'name' => 'photos', + 'label' => 'Photos', + 'type' => 'dropzone', + 'withFiles' => true ], ``` -**IMPORTANT NOTE:** Altough you can do some "validation" in Javascript, we highly advise you to don't disregard server validation. Check the following [dropzone validation docs](#dropzone-validation) +To know more about the `withFiles`, how it works and how to configure it, [ click here to read the documentation ](https://backpackforlaravel.com/docs/6.x/crud-uploaders). + #### Validation + +**IMPORTANT NOTE:** Altough you can do some "validation" in Javascript, we highly advise you to don't disregard server validation. + The proper validation of dropzone should be done in two steps: 1 - Files should be validated on the file upload endpoint 2 - Field in general should be validated on form submission. From 7e5a16bca1328d962f00133f15e43f5358e1d849 Mon Sep 17 00:00:00 2001 From: Pedro X Date: Wed, 10 May 2023 11:43:17 +0100 Subject: [PATCH 4/8] add note about column type --- 6.x/crud-fields.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/6.x/crud-fields.md b/6.x/crud-fields.md index 77a2f4b1..d8d31032 100644 --- a/6.x/crud-fields.md +++ b/6.x/crud-fields.md @@ -1406,6 +1406,8 @@ Input preview: Show a [Dropzone JS Input](https://docs.dropzone.dev/). +**Step 0.** Make sure the db column can hold the amount of text this field will have. For example, for MySQL, `VARCHAR(255)` might not be enough all the time (for 3+ files), so it's better to go with `TEXT`. Make sure you're using a big column type in your migration or db. + **Step 1:** Add the `DropzoneOperation` to your `CrudController` ```php From a330a2a641bf908b68ad8e00231016bceba84535 Mon Sep 17 00:00:00 2001 From: Pedro X Date: Wed, 10 May 2023 13:09:22 +0100 Subject: [PATCH 5/8] add validation example --- 6.x/crud-fields.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/6.x/crud-fields.md b/6.x/crud-fields.md index d8d31032..05b19f41 100644 --- a/6.x/crud-fields.md +++ b/6.x/crud-fields.md @@ -1469,6 +1469,13 @@ To make things easy on your side we created `ValidDropzone` validation rule. It' - `::field()` - the field rules (independent of the file content); - `->file()` - rules that apply to the sent files; +```php +use Backpack\Pro\Uploads\Validation\ValidDropzone; + +'photos' => ValidDropzone::field('required|min:2|max:5') + ->file('file|mimes:jpeg,png,jpg,gif,svg|max:2048'), +``` + Input preview: ![CRUD Field - dropzone](https://user-images.githubusercontent.com/7188159/236273902-ca7fb5a5-e7ce-4a03-91a7-2af81598331c.png) From e27763687bf889203caaac11133c1c8b034920a9 Mon Sep 17 00:00:00 2001 From: Pedro X Date: Fri, 12 May 2023 15:18:23 +0100 Subject: [PATCH 6/8] note about storage link --- 6.x/crud-fields.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/6.x/crud-fields.md b/6.x/crud-fields.md index 05b19f41..5365ce00 100644 --- a/6.x/crud-fields.md +++ b/6.x/crud-fields.md @@ -1408,6 +1408,9 @@ Show a [Dropzone JS Input](https://docs.dropzone.dev/). **Step 0.** Make sure the db column can hold the amount of text this field will have. For example, for MySQL, `VARCHAR(255)` might not be enough all the time (for 3+ files), so it's better to go with `TEXT`. Make sure you're using a big column type in your migration or db. +**Step 0.1** If you haven't created the storage/public symlinks now it's a good time to do it: `php artisan storage:link` + + **Step 1:** Add the `DropzoneOperation` to your `CrudController` ```php From 47fa368f04912b7b91c6defdc9c7a45086721ffe Mon Sep 17 00:00:00 2001 From: Pedro X Date: Tue, 16 May 2023 16:28:26 +0100 Subject: [PATCH 7/8] fix docs --- 6.x/crud-fields.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/6.x/crud-fields.md b/6.x/crud-fields.md index 5365ce00..8bd350ee 100644 --- a/6.x/crud-fields.md +++ b/6.x/crud-fields.md @@ -1418,7 +1418,7 @@ class UserCrudController extends CrudController { use \Backpack\CRUD\app\Http\Controllers\Operations\CreateOperation; // ... other operations - use Backpack\Pro\Http\Controllers\Operations\DropzoneOperation; + use \Backpack\Pro\Http\Controllers\Operations\DropzoneOperation; } ``` From e130f1469477dc237bdd43e4a468911b2b0706b2 Mon Sep 17 00:00:00 2001 From: Pedro X Date: Tue, 16 May 2023 18:12:03 +0100 Subject: [PATCH 8/8] tmp folder to dropzone --- 6.x/crud-fields.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/6.x/crud-fields.md b/6.x/crud-fields.md index 8bd350ee..3b2c59b1 100644 --- a/6.x/crud-fields.md +++ b/6.x/crud-fields.md @@ -1479,6 +1479,52 @@ use Backpack\Pro\Uploads\Validation\ValidDropzone; ->file('file|mimes:jpeg,png,jpg,gif,svg|max:2048'), ``` + +#### Temporary folder configuration + +The temporary folder is configured in `config/backpack/operations/dropzone.php`. + +You can publish this configuration file using `php artisan vendor:publish --provider="Backpack\Pro\AddonServiceProvider" --tag="dropzone-config"` + +```php + 'temporary_disk' => 'local', + 'temporary_folder' => 'backpack/temp', + 'purge_temporary_files_older_than' => 72 // hours +``` +It can also be configured on a "per crud" basis with: +```php +CRUD::setOperationSetting('temporary_disk', 'public'); +CRUD::setOperationSetting('temporary_folder', 'backpack/temp'); +CRUD::setOperationSetting('purge_temporary_files_older_than', 72); +``` + +The first two options are self-explanatory. The third one is the number of hours after which temporary files are deleted and requires further atention and configuration. + +The process of file **deletion** does **not happen** automatically. +In case of Dropzone we manually call the `PurgeTemporaryFolder` job whenever new files are uploaded so that we keep the dropzone temporary upload folder clean. + +To make the cleanup process more general, we created a command that you can run periodically, `backpack:purge-temporary-files`. +It accepts the following optional parameter: +`--older-than=24`: the number of hours after which temporary files are deleted. +`--disk=public`: the disk used by the temporary files. +`--path="backpack/temp"`: the folder inside the disk where files will be stored. + +```bash +php artisan backpack:purge-temporary-files --older-than=24 --disk=public --path="backpack/temp" +``` + +You can use any strategy to run this command periodically, like a cron job, a scheduled task or hooking into application termination hooks. + +Laravel provides a very easy way to setup your scheduled tasks, if you are on board with that idea. You can read more about it [here](https://laravel.com/docs/10.x/scheduling). + +As an example, you can run the command every hour by adding the following line to your `app/Console/Kernel.php` file in the `schedule()` method: +```php +// app/Console/Kernel.php +$schedule->command('backpack:purge-temporary-files')->hourly(); +``` + +After adding this, you need to setup a cron job that will process the Laravel scheduler. You can manually run it in development with `php artisan schedule:run`, for production, you can setup a cron job take care of it for you. You can read more about it [here](https://laravel.com/docs/10.x/scheduling#running-the-scheduler). + Input preview: ![CRUD Field - dropzone](https://user-images.githubusercontent.com/7188159/236273902-ca7fb5a5-e7ce-4a03-91a7-2af81598331c.png)