Document the export action

Resources/doc/reference/action_export.rst

@@ -1,17 +1,20 @@
 The Export action
 =================
 
-.. note::
-
-    This document is a stub representing a new work in progress. If you're reading
-    this you can help contribute, **no matter what your experience level with Sonata
-    is**. Check out the `issues on GitHub`_ for more information about how to get involved.
-
 This document will cover the Export action and related configuration options.
 
 Basic configuration
 -------------------
 
+If you have registered the ``SonataExporterBundle`` bundle in the kernel of your application,
+you can benefit from a lot of flexibility:
+
+* You can configure default exporters globally.
+* You can add custom exporters, also globally.
+* You can configure every default writer.
+
+See `the exporter bundle documentation`_ for more information.
+
 Translation
 ~~~~~~~~~~~
 
@@ -19,58 +22,59 @@ All field names are translated by default.
 An internal mechanism checks if a field matching the translator strategy label exists in the current translation file
 and will use the field name as a fallback.
 
-Customizing export
-~~~~~~~~~~~~~~~~~~
+Picking which fields to export
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To customize available export formats just overwrite AbstractAdmin::getExportFormats()
+By default, all fields are exported. More accurately, it depends on the
+persistence backend you are using, but for instance, the doctrine ORM backend
+exports all fields (associations are not exported). If you want to change this
+behavior for a specific admin, you can override the ``getExportFields()`` method:
 
 .. code-block:: php
 
     <?php
-    // src/AppBundle/Admin/PersonAdmin.php
 
-    class PersonAdmin extends AbstractAdmin
+    public function getExportFields()
     {
-        /**
-         * {@inheritdoc}
-         */
-        public function getExportFormats()
-        {
-            return array(
-                'json', 'xml', 'csv', 'xls',
-            );
-        }
+        return array('givenName', 'familyName', 'contact.phone');
     }
 
-If you want to customize the list of fields to export, overwrite AbstractAdmin::getExportFields() like
-this:
+.. note::
 
-.. code-block:: php
+    Note that you can use `contact.phone` to access the `phone` property of `Contact` entity
 
-    <?php
-    // src/AppBundle/Admin/PersonAdmin.php
+You can also tweak the list by creating an admin extension that implements the
+``configureExportFields()`` method.
 
-    class PersonAdmin extends AbstractAdmin
+.. code-block:: php
+
+    public function configureExportFields(AdminInterface $admin, array $fields)
     {
-        /**
-         * @return array
-         */
-        public function getExportFields() {
-            return array(
-                'Id' => 'id',
-                'First Name' => 'firstName',
-                'Last Name' => 'lastName',
-                'Contact' => 'contact.phone',
-            );
-        }
+        unset($fields['updatedAt']);
+
+        return $fields;
     }
 
-.. note::
 
-    Note that you can use `contact.phone` to access the `phone` property of `Contact` entity
+Overriding the export formats for a specific admin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Changing the export formats can be done by defining a ``getExportFormats()``
+method in your admin class.
+
+.. code-block:: php
+
+    <?php
+
+    public function getExportFormats()
+    {
+        return array('pdf', 'html');
+    }
 
-To add more customization to your export you can overwrite AbstractAdmin::getDataSourceIterator().
-Supposing you want to change date format in your export file. You can do it like this:
+Customizing the query used to fetch the results
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you want to customize the query used to fetch the results for a specific admin,
+you can override the ``getDataSourceIterator()`` method:
 
 .. code-block:: php
 
@@ -90,9 +94,7 @@ Supposing you want to change date format in your export file. You can do it like
 .. note::
 
     **TODO**:
-    * any global (yml) options that affect the export actions
-    * how to add new export formats
-    * customising the query used to fetch the results
+    * customising the templates used to render the output
+    * publish the exporter documentation on the project's website and update the link
 
-.. _`issues on Github`: https://github.com/sonata-project/SonataAdminBundle/issues/1519
-.. _`the exporter bundle documentation`: https://github.com/sonata-project/exporter/blob/1.x/docs/reference/symfony.rst
+.. _`the exporter bundle documentation`: https://github.com/sonata-project/exporter/blob/1.x/docs/reference/symfony.rst