updated doc

Resources/doc/index.md

@@ -4,9 +4,10 @@ VichUploaderBundle
 The VichUploaderBundle is a simple Symfony2 bundle that attempts to ease file 
 uploads that are attached to an entity. The bundle will automatically name and 
 save the uploaded file according to the configuration specified on a per property
-basis. The bundle also provides templating helpers for generating URLs to the 
-file as well. The file can also be configured to be removed from the file system 
-upon removal of the entity.
+basis. It will also load the file back into the entity upon retrieval from the
+datastore if configured to do so. The bundle also provides templating helpers
+for generating URLs to the file. The file can also be configured to be
+removed from the file system upon removal of the entity.
 
 ## Installation
 
@@ -90,7 +91,10 @@ All options are listed below:
 - `upload_dir`: The directory to upload the file to
 - `namer`: The id of the namer service for this entity (See Namers section below)
 - `delete_on_remove`: Set to true if the file should be deleted from the 
-filesystem when the entity is removed.
+filesystem when the entity is removed
+- `inject_on_load`: Set to true if the file should be injected into the uploadable
+field property when it is loaded from the data store. The object will be an instance
+of `Symfony\Component\HttpFoundation\File\File`
 
 **Note:**
 
@@ -99,18 +103,18 @@ filesystem when the entity is removed.
 
 ## Annotate Entities
 
-In order for your entity to work with the bundle, you need to add some annotations
-to it. First you must annotate your class with the `Uploadable` annotation. This
-lets the bundle know that it should look for files to upload in your class when
-it is saved or check to see if it needs to remove files when it is removed. Next,
-you should annotate the fields which hold the instance of
-`Symfony\Component\HttpFoundation\File\UploadedFile` when the form is submitted
-with the `UploadableField` annotation. The `UploadableField` annotation has a few
-required options. They are as follows:
+In order for your entity or document to work with the bundle, you need to add a
+few annotations to it. First, annotate your class with the `Uploadable` annotation.
+This lets the bundle know that it should look for files to upload in your class when
+it is saved, inject the files when it is loaded and check to see if it needs to
+remove files when it is removed. Next, you should annotate the fields which hold
+the instance of `Symfony\Component\HttpFoundation\File\UploadedFile` when the form
+is submitted with the `UploadableField` annotation. The `UploadableField` annotation
+has a few required options. They are as follows:
 
 - `mapping`: The mapping specified in the bundle configuration to use
 - `fileNameProperty`: The property of the class that will be filled with the file name
-generated by the bundle.
+generated by the bundle
 
 Lets look at an example using a fictional `Product` ORM entity:
 
@@ -136,7 +140,7 @@ class Product
      */
     protected $id;
 
-    // .....
+    // ..... other fields
 
     /**
      * @Assert\File(
@@ -145,7 +149,7 @@ class Product
      * )
      * @Vich\UploadableField(mapping="property_image", fileNameProperty="imageName")
      *
-     * @var UploadedFile $image
+     * @var File $image
      */
     protected $image;
 
@@ -161,30 +165,42 @@ class Product
 ## Namers
 
 The bundle uses namers to name the files it saves to the filesystem. A namer
-implements the `Vich\UploaderBundle\Naming\NamerInterface` interface. By default,
-the bundle will simply use the name of the file that was uploaded. if you would like
-to change this then you must implement a custom namer.
+implements the `Vich\UploaderBundle\Naming\NamerInterface` interface. If no namer is
+configured for a mapping, the bundle will simply use the name of the file that
+was uploaded. if you would like to change this then you must implement a custom namer.
 
-To create a custom namer, simply implement the `NamerInterface` and return a string 
-in the `name` method. Since your entity is passed to the `name` method you are free 
-to get any information from it to create the name, or inject any other services 
-that you require.
+To create a custom namer, simply implement the `Vich\UploaderBundle\Naming\NamerInterface`
+and in the `name` method of your class return the desired file name. Since your entity
+is passed to the `name` method, as well as the field name, you are free to get any information
+from it to create the name, or inject any other services that you require.
 
 > **Note**: The name returned should include the file extension as well. This can easily
-> be retrieved from the `UploadedFile`.
+> be retrieved from the `UploadedFile` instance using the `getExtension` or `guessExtension`
+> depending on what version of PHP you are running.
 
 After you have created your namer and configured it as a service, you simply specify 
-the service id for the `namer` configuration option of your mapping.
+the service id for the `namer` configuration option of your mapping. An example:
+
+``` yaml
+vich_uploader:
+    # ...
+    mappings:
+        product_image:
+            upload_dir: %kernel.root_dir%/../web/images/products
+            namer: my.namer.product
+```
+
+Here `my.namer.product` is the configured id of the service.
 
 ## Generating URLs
 
-To get a url for the file you can use the `vich_uploader.uploader` service as 
-follows:
+To get a url for the file you can use the `vich_uploader.templating.helper`
+service as follows:
 
 ``` php
 $entity = // get the entity..
-$uploader = $this->container->get('vich_uploader.uploader');
-$path = $uploader->getPublicPath($entity, 'image');
+$helper = $this->container->get('vich_uploader.templating.helper');
+$path = $helper->asset($entity, 'image');
 ```
 or in a Twig template you can use the `vich_uploader_asset` function:
 
@@ -194,17 +210,17 @@ or in a Twig template you can use the `vich_uploader_asset` function:
 
 You must specify the annotated property you wish to get the file path for.
 
+> **Note:** The path returned is relative to the web directory which is specified
+> using the `web_dir_name` configuration parameter.
+
 ## Limitations
 
 - Currently the bundle only supports generating a relative url for the file.
 - Currently the bundle only supports saving/deleting files to the local filesystem.
 
-I will probably only change this when I need to do it for a project I work on.
-So far, this bundle has satisfied all of my needs, but feel free to fork and send a PR.
-
 ## Configuration Reference
 
-Below is the default coniguration for the bundle:
+Below is the full default coniguration for the bundle:
 
 ``` yaml
 # app/config/config.yml
@@ -218,5 +234,5 @@ vich_uploader:
             namer: ~ # specify a namer service id for this entity, null default
             delete_on_remove: true # determines whether to delete file upon removal of entity
             inject_on_load: true # determines whether to inject a File instance upon load
-        # ...
+        # ... more mappings
 ```