From 92b42d0a975f8b63c029b05dc6d063cce9c85c5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Kr=C3=A4mer?= Date: Tue, 13 Oct 2015 10:09:50 +0200 Subject: [PATCH] Documentation updates. --- docs/Documentation/How-To-Use.md | 81 ++++++++++++++++++-------------- 1 file changed, 45 insertions(+), 36 deletions(-) diff --git a/docs/Documentation/How-To-Use.md b/docs/Documentation/How-To-Use.md index 45d9f429..d78abbeb 100644 --- a/docs/Documentation/How-To-Use.md +++ b/docs/Documentation/How-To-Use.md @@ -14,7 +14,7 @@ Preparing the File Upload This section is going to show how to store a file using the Storage Manager directly. -For example you have a Report model and want to save a pdf to it, you would then create an association like: +For example you have a Report table and want to save a pdf to it, you would then create an association like: ```php public function initialize(array $config) @@ -29,48 +29,21 @@ public function initialize(array $config) } ``` -In your `add.ctp` or `edit.ctp` views you would add something like: +In your `add.ctp` or `edit.ctp` views you would add something like this. ```php +echo $this->Form->create($report, ['type' => 'file']); echo $this->Form->input('title'); -echo $this->Form->input('pdf_files.file'); +echo $this->Form->file('pdf_files.file'); // Pay attention here! echo $this->Form->input('description'); +echo $this->Form->submit(__('Submit')); +echo $this->Form->end(); ``` -Handling the File Upload ------------------------- +[Make sure your form is using the right HTTP method](http://book.cakephp.org/3.0/en/views/helpers/form.html#changing-the-http-method-for-a-form)! -**Now comes the crucial point of the whole implementation** - -Because of to many different requirements and personal preferences out there the plugin is *not* automatically storing the file. You'll have to customize it a little but its just a matter for a few lines. - -Lets go by this scenario inside the report model, assuming there is an add() method: - -```php -$entity = $this->newEntity($postData); -$saved = $this->save($entity); -if ($saved) { - $key = 'your-file-name'; - if (StorageManager::adapter('Local')->write($key, file_get_contents($this->data['pdf_files']['file']['tmp_name']))) { - $postData['pdf_files']['foreign_key'] = $saved->id; - $postData['pdf_files']['model'] = 'Reports'; - $postData['pdf_files']['path'] = $key; - $postData['pdf_files']['adapter'] = 'Local'; - $this->PdfDocuments->save($this->PdfDocuments->newEntity($postData)); - } -} -``` - -Later, when you want to delete the file, for example in the beforeDelete() or afterDelete() callback of your Report model, you'll know the adapter you have used to store the attached PdfFile and can get an instance of this adapter configuration using the StorageManager. By having the path or key available you can then simply call: - -```php -StorageManager::adapter($data['PdfFile']['adapter'])->delete($data['PdfFile']['path']); -``` - -Insted of doing all of this in the model that has the files associated to it you can also simply extend the FileStorage model from the plugin and add your storage logic there and use that model for your association. - -How to store an uploaded file II - using Events ------------------------------------------------ +Store an uploaded file using Events +----------------------------------- The **FileStorage** plugin comes with a class that acts just as a listener to some of the events in this plugin. Take a look at [LocalImageProcessingLister.php](../../Event/LocalImageProcessingLister.php). @@ -105,6 +78,42 @@ Event Listeners See [this page](Included-Event-Listeners.md) for the event listeners that are included in the plugin. + +Handling the File Upload Manually +--------------------------------- + +You'll have to customize it a little but its just a matter for a few lines. + +Note the Listener expects a request data key `file` present in the form, so use `echo $this->Form->input('file');` to allow the Marshaller pick the right data from the uploaded file. + +Lets go by this scenario inside the report table, assuming there is an add() method: + +```php +public function add() { + $entity = $this->newEntity($postData); + $saved = $this->save($entity); + if ($saved) { + $key = 'your-file-name'; + if (StorageManager::adapter('Local')->write($key, file_get_contents($this->data['pdf_files']['file']['tmp_name']))) { + $postData['pdf_files']['foreign_key'] = $saved->id; + $postData['pdf_files']['model'] = 'Reports'; + $postData['pdf_files']['path'] = $key; + $postData['pdf_files']['adapter'] = 'Local'; + $this->PdfDocuments->save($this->PdfDocuments->newEntity($postData)); + } + } + return $entity; +} +``` + +Later, when you want to delete the file, for example in the beforeDelete() or afterDelete() callback of your Report model, you'll know the adapter you have used to store the attached PdfFile and can get an instance of this adapter configuration using the StorageManager. By having the path or key available you can then simply call: + +```php +StorageManager::adapter($data['PdfFile']['adapter'])->delete($data['PdfFile']['path']); +``` + +Insted of doing all of this in the table object that has the files associated to it you can also simply extend the FileStorage table from the plugin and add your storage logic there and use that table for your association. + Why is it done like this? -------------------------