Fixed doc warnings and completed action_list

Resources/doc/reference/recipe_custom_action.rst

@@ -78,7 +78,7 @@ Or by overwriting the configuration in your ``config.yml``:
                 - AcmeDemoBundle:CRUD
 
 
-For more information about service configuration please refer to Step 3 of :doc:`getting_started`
+For more information about service configuration please refer to Step 3 of :doc:`../reference/getting_started`
 
 Create the custom action in your Controller
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -128,7 +128,7 @@ Create a template for the new action
 You need to tell SonataAdmin how to render your new action. You do that by creating a ``list__action_clone.html.twig`` in the
 namespace of your custom Admin Controller.
 
-.. code-block:: twig
+.. code-block:: html+jinja
 
     {# src/Acme/DemoBundle/Resources/views/CRUD/list__action_clone.html.twig #}
 

Resources/doc/index.rst

@@ -59,3 +59,4 @@ Cookbook
    cookbook/recipe_row_templates
    cookbook/recipe_sortable_listing
    cookbook/recipe_dynamic_form_modification
+   cookbook/recipe_custom_action

Resources/doc/reference/action_export.rst

@@ -1,10 +1,10 @@
 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 
+    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.

Resources/doc/reference/action_list.rst

@@ -14,18 +14,147 @@ to control what's visible.
 Basic configuration
 -------------------
 
+SonataAdmin Options that may affect the list view:
+
+.. code-block:: yaml
+
+    sonata_admin:
+        templates:
+            list:                       SonataAdminBundle:CRUD:list.html.twig
+            action:                     SonataAdminBundle:CRUD:action.html.twig
+            select:                     SonataAdminBundle:CRUD:list__select.html.twig
+            list_block:                 SonataAdminBundle:Block:block_admin_list.html.twig
+            short_object_description:   SonataAdminBundle:Helper:short-object-description.html.twig
+            batch:                      SonataAdminBundle:CRUD:list__batch.html.twig
+            inner_list_row:             SonataAdminBundle:CRUD:list_inner_row.html.twig
+            base_list_field:            SonataAdminBundle:CRUD:base_list_field.html.twig
+            pager_links:                SonataAdminBundle:Pager:links.html.twig
+            pager_results:              SonataAdminBundle:Pager:results.html.twig
+
+
 To do:
 
-- global (yml) options that affect the list view
 - a note about Routes and how disabling them disables the related action
-- using configureListFields() to set which fields to display
-- setting the identifier, and the available options
-- options available when adding general fields, inc custom templates
-- targeting submodel fields using dot-separated notation
 - adding custom columns
 
+Customizing the fields displayed on the list page
+-------------------------------------------------
+
+You can customize the columns displayed on the list through the ``configureListFields`` method:
+
+.. code-block:: php
+
+    <?php
+
+    // Example taken from Sonata E-Commerce Product Admin
+
+    public function configureListFields(ListMapper $list)
+    {
+        $list
+            // addIdentifier allows to specify that this column will provide a link to the entity's edition
+            ->addIdentifier('name')
+
+            // You may specify the field type directly as the second argument instead of in the options
+            ->add('isVariation', 'boolean')
+
+            // The type can be guessed as well
+            ->add('enabled', null, array('editable' => true))
+
+            // We can add options to the field depending on the type
+            ->add('price', 'currency', array('currency' => $this->currencyDetector->getCurrency()->getLabel()))
+
+            // Here we specify which method is used to render the label
+            ->add('productCategories', null, array('associated_tostring' => 'getCategory'))
+            ->add('productCollections', null, array('associated_tostring' => 'getCollection'))
+
+            // You may also use dotted-notation to access specific properties of a relation to the entity
+            ->add('image.name')
+
+            // You may also specify the actions you want to be displayed in the list
+            ->add('_action', 'actions', array(
+                'actions' => array(
+                    'show' => array(),
+                    'edit' => array(),
+                    'delete' => array(),
+                )
+            ))
+
+        ;
+    }
+
+Options
+^^^^^^^
+
+.. note::
+
+    * ``(m)`` stands for mandatory
+    * ``(o)`` stands for optional
+
+- ``type`` (m): define the field type - mandatory for the field description itself but will try to detect the type automatically if not specified
+- ``template`` (o): the template used to render the field
+- ``name`` (o): the name used for the column's title
+- ``link_parameters`` (o): add link parameter to the related Admin class when the ``Admin::generateUrl`` is called
+- ``code`` (o): the method name to retrieve the related value
+- ``associated_tostring`` (o): (deprecated, use associated_property option) the method to retrieve the "string" representation of the collection element.
+- ``associated_property`` (o): property path to retrieve the "string" representation of the collection element.
+- ``identifier`` (o): if set to true a link appear on the value to edit the element
+
+Available types and associated options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
 
-Customising the query used to generate the list
+    ``(m)`` means that option is mandatory
+
++-----------+----------------+-----------------------------------------------------------------------+
+| Type      | Options        | Description                                                           |
++===========+================+=======================================================================+
+| actions   | actions        | List of available actions                                             |
++-----------+----------------+-----------------------------------------------------------------------+
+| batch     |                | Renders a checkbox                                                    |
++-----------+----------------+-----------------------------------------------------------------------+
+| select    |                | Renders a select box                                                  |
++-----------+----------------+-----------------------------------------------------------------------+
+| array     |                | Displays an array                                                     |
++-----------+----------------+-----------------------------------------------------------------------+
+| boolean   | editable       | Yes/No; editable allows to edit directly from the list if authorized. |
++-----------+----------------+-----------------------------------------------------------------------+
+| choice    | choices        | Possible choices                                                      |
++           +----------------+-----------------------------------------------------------------------+
+|           | multiple       | Is it a multiple choice option? Defaults to false.                    |
++           +----------------+-----------------------------------------------------------------------+
+|           | delimiter      | Separator of values if multiple.                                      |
++           +----------------+-----------------------------------------------------------------------+
+|           | catalogue      | Translation catalogue.                                                |
++-----------+----------------+-----------------------------------------------------------------------+
+| currency  | currency (m)   | A currency string (EUR or USD for instance).                          |
++-----------+----------------+-----------------------------------------------------------------------+
+| date      | format         | A format understandable by Twig's ``date`` function.                  |
++-----------+----------------+-----------------------------------------------------------------------+
+| datetime  | format         | A format understandable by Twig's ``date`` function.                  |
++-----------+----------------+-----------------------------------------------------------------------+
+| percent   |                | Renders value as a percentage.                                        |
++-----------+----------------+-----------------------------------------------------------------------+
+| string    |                | Renders a simple string.                                              |
++-----------+----------------+-----------------------------------------------------------------------+
+| time      |                | Renders a datetime's time with format ``H:i:s``.                      |
++-----------+----------------+-----------------------------------------------------------------------+
+| trans     | catalogue      | Translates the value with catalogue ``catalogue`` if defined.         |
++-----------+----------------+-----------------------------------------------------------------------+
+| url       | url            | Adds a link with url ``url`` to the displayed value                   |
++           +----------------+-----------------------------------------------------------------------+
+|           | route          | Give a route to generate the url                                      |
++           +                +                                                                       +
+|           |   name         | Route name                                                            |
++           +                +                                                                       +
+|           |   parameters   | Route parameters                                                      |
++           +----------------+-----------------------------------------------------------------------+
+|           | hide_protocol  | Hide http:// or https:// (default false)                              |
++-----------+----------------+-----------------------------------------------------------------------+
+
+If you have the SonataDoctrineORMAdminBundle installed, you have access to more field types, see `SonataDoctrineORMAdminBundle Documentation <http://sonata-project.org/bundles/doctrine-orm-admin/master/doc/reference/list_field_definition.html>`_.
+
+Customizing the query used to generate the list
 -----------------------------------------------
 
 You can customize the list query thanks to the ``createQuery`` method.
@@ -45,7 +174,7 @@ You can customize the list query thanks to the ``createQuery`` method.
     }
 
 
-Customising the sort order
+Customizing the sort order
 --------------------------
 
 Configure the default ordering in the list view

Resources/doc/reference/action_show.rst

@@ -3,8 +3,8 @@ The Show 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 
+    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 Show action and related configuration options.
@@ -73,7 +73,7 @@ Setting up a custom show template (very useful)
 
 The first thing you need to do is define it in app/config/config/yml:
 
-.. code-block:: yml
+.. code-block:: yaml
 
     sonata_admin:
         title:      Acme Admin Area

Resources/doc/reference/architecture.rst

@@ -158,15 +158,16 @@ which stores instances of ``FieldDescriptionInterface``. Picking up on our previ
 
 .. code-block:: php
 
-   namespace Acme\DemoBundle\Admin;
+    <?php
+    namespace Acme\DemoBundle\Admin;
 
-   use Sonata\AdminBundle\Admin\Admin;
-   use Sonata\AdminBundle\Datagrid\ListMapper;
-   use Sonata\AdminBundle\Datagrid\DatagridMapper;
-   use Sonata\AdminBundle\Form\FormMapper;
+    use Sonata\AdminBundle\Admin\Admin;
+    use Sonata\AdminBundle\Datagrid\ListMapper;
+    use Sonata\AdminBundle\Datagrid\DatagridMapper;
+    use Sonata\AdminBundle\Form\FormMapper;
 
-   class PostAdmin extends Admin
-   {
+    class PostAdmin extends Admin
+    {
        // Fields to be shown on create/edit forms
        protected function configureFormFields(FormMapper $formMapper)
        {
@@ -195,7 +196,7 @@ which stores instances of ``FieldDescriptionInterface``. Picking up on our previ
                ->add('author')
            ;
        }
-   }
+    }
 
 Internally, the provided ``Admin`` class will use these three functions to create three
 ``FieldDescriptionCollection`` instances:

Resources/doc/reference/configuration.rst

@@ -1,9 +1,10 @@
-Warning: this doc page is not up to date and will be removed soon.
-==================================================================
+Configuration // Warning: this doc page is not up to date and will be removed soon.
+===================================================================================
 
-This page will be removed soon, as it's content is being improved and moved to
-other pages of the documentation. Please refer to each section's documentation for up-to-date
-information on SonataAdminBundle configuration options.
+.. note::
+    This page will be removed soon, as it's content is being improved and moved to
+    other pages of the documentation. Please refer to each section's documentation for up-to-date
+    information on SonataAdminBundle configuration options.
 
 Configuration
 -------------
@@ -23,17 +24,107 @@ Full Configuration Options
 
     .. code-block:: yaml
 
-        sonata_admin:
-            security:
-                handler: sonata.admin.security.handler.role
-                acl_user_manager: fos_user.user_manager # Name of the user manager service used to retrieve ACL users
+    # Default configuration for "SonataAdminBundle"
+    sonata_admin:
+        security:
+            handler:              sonata.admin.security.handler.noop
+            information:
 
-            options:
-                html5_validate: false # does not use html5 validation
-                confirm_exit:   false # disable confirmation when quitting with unsaved changes
-                use_select2:    false # disable select2
-                pager_links:    5     # pager max links to display
+                # Prototype
+                id:                   []
+            admin_permissions:
 
-            # set to true to persist filter settings per admin module in the user's session
-            persist_filters: false
+                # Defaults:
+                - CREATE
+                - LIST
+                - DELETE
+                - UNDELETE
+                - EXPORT
+                - OPERATOR
+                - MASTER
+            object_permissions:
+
+                # Defaults:
+                - VIEW
+                - EDIT
+                - DELETE
+                - UNDELETE
+                - OPERATOR
+                - MASTER
+                - OWNER
+            acl_user_manager:     ~         # Name of the user manager service used to retrieve ACL users
+        title:                Sonata Admin
+        title_logo:           bundles/sonataadmin/logo_title.png
+        options:
+            html5_validate:       true      # use html5 validation
+            confirm_exit:         true      # enabled confirmation when quitting with unsaved changes
+            use_select2:          true      # enable select2
+            pager_links:          ~         # pager max links to display
+        dashboard:
+            groups:
+
+                # Prototype
+                id:
+                    label:                ~
+                    label_catalogue:      ~
+                    items:                []
+                    item_adds:            []
+                    roles:                []
+            blocks:
+                type:                 ~
+                settings:
+
+                    # Prototype
+                    id:                   []
+                position:             right
+        admin_services:
+
+            # Prototype
+            id:
+                model_manager:        ~
+                form_contractor:      ~
+                show_builder:         ~
+                list_builder:         ~
+                datagrid_builder:     ~
+                translator:           ~
+                configuration_pool:   ~
+                router:               ~
+                validator:            ~
+                security_handler:     ~
+                label:                ~
+        templates:
+            user_block:           SonataAdminBundle:Core:user_block.html.twig
+            layout:               SonataAdminBundle::standard_layout.html.twig
+            ajax:                 SonataAdminBundle::ajax_layout.html.twig
+            dashboard:            SonataAdminBundle:Core:dashboard.html.twig
+            search:               SonataAdminBundle:Core:search.html.twig
+            list:                 SonataAdminBundle:CRUD:list.html.twig
+            show:                 SonataAdminBundle:CRUD:show.html.twig
+            edit:                 SonataAdminBundle:CRUD:edit.html.twig
+            preview:              SonataAdminBundle:CRUD:preview.html.twig
+            history:              SonataAdminBundle:CRUD:history.html.twig
+            acl:                  SonataAdminBundle:CRUD:acl.html.twig
+            history_revision_timestamp:  SonataAdminBundle:CRUD:history_revision_timestamp.html.twig
+            action:               SonataAdminBundle:CRUD:action.html.twig
+            select:               SonataAdminBundle:CRUD:list__select.html.twig
+            list_block:           SonataAdminBundle:Block:block_admin_list.html.twig
+            search_result_block:  SonataAdminBundle:Block:block_search_result.html.twig
+            short_object_description:  SonataAdminBundle:Helper:short-object-description.html.twig
+            delete:               SonataAdminBundle:CRUD:delete.html.twig
+            batch:                SonataAdminBundle:CRUD:list__batch.html.twig
+            batch_confirmation:   SonataAdminBundle:CRUD:batch_confirmation.html.twig
+            inner_list_row:       SonataAdminBundle:CRUD:list_inner_row.html.twig
+            base_list_field:      SonataAdminBundle:CRUD:base_list_field.html.twig
+            pager_links:          SonataAdminBundle:Pager:links.html.twig
+            pager_results:        SonataAdminBundle:Pager:results.html.twig
+        extensions:
+
+            # Prototype
+            id:
+                admins:               []
+                excludes:             []
+                implements:           []
+                extends:              []
+                instanceof:           []
+        persist_filters:      false     # set to true to persist filter settings per admin module in the user's session
 

Resources/doc/reference/console.rst

@@ -25,9 +25,9 @@ Usage example:
 
 
 sonata:admin:generate
---------------------
+---------------------
 
-The ``sonata:admin:generate`` command generates a new Admin class based on the given model 
+The ``sonata:admin:generate`` command generates a new Admin class based on the given model
 class, registers it as a service and potentially creates a new controller.
 As an argument you need to specify the fully qualified model class.
 All passed arguments and options are used as default values in interactive mode.
@@ -51,9 +51,9 @@ Usage example:
 sonata:admin:list
 -----------------
 
-To see which admin services are available use the ``sonata:admin:list`` command. 
-It prints all the admin service ids available in your application. This command 
-gets the ids from the ``sonata.admin.pool`` service where all the available admin 
+To see which admin services are available use the ``sonata:admin:list`` command.
+It prints all the admin service ids available in your application. This command
+gets the ids from the ``sonata.admin.pool`` service where all the available admin
 services are registered.
 
 Usage example:
@@ -111,6 +111,6 @@ sonata:admin:generate-object-acl
 --------------------------------
 
 The ``sonata:admin:generate-object-acl`` is an interactive command which helps
-you to generate ACL entities for the objects handled by your Admins. See the help 
+you to generate ACL entities for the objects handled by your Admins. See the help
 of the command for more information.
 

Resources/doc/reference/form_help_message.rst

@@ -51,7 +51,7 @@ Advanced usage
 ^^^^^^^^^^^^^^
 
 Since help messages can contain HTML they can be used for more advanced solutions.
-See the cookbook entry :doc:`Showing image previews <recipe_image_previews>` for a detailed example of how to 
+See the cookbook entry :doc:`Showing image previews <../cookbook/recipe_image_previews>` for a detailed example of how to
 use help messages to display an image tag.
 
 

Resources/doc/reference/installation.rst

@@ -54,6 +54,7 @@ forget to enable SonataAdminBundle too:
 
 .. code-block:: php
 
+    <?php
     // app/AppKernel.php
     public function registerBundles()
     {

Resources/doc/reference/preview_mode.rst

@@ -34,7 +34,7 @@ Accepting the preview will store the entity as if the preview step was never the
 
 
 Simulating front-end rendering
-----------------------------
+------------------------------
 
 Preview can be used to render how the object would look like in your front-end environment.
 
@@ -118,7 +118,7 @@ Hiding the fieldset tags with css (display:none) will be enough to only show the
 
 Or if you prefer less:
 
-.. code-block:: less
+.. code-block:: sass
 
     div.sonata-preview-form {
       fieldset {

Resources/doc/reference/routing.rst

@@ -152,7 +152,7 @@ We now need to create our Controller, the easiest way is to extend the basic Son
     }
 
 Removing a route
---------------
+----------------
 
 Extending ``Sonata\AdminBundle\Admin\Admin`` will give your Admin classes the following
 default routes:

Resources/doc/reference/select2.rst

@@ -1,7 +1,7 @@
 Select2
 =======
 
-The admin comes with `select2 <http://ivaynberg.github.io/select2/>` integration
+The admin comes with `select2 <http://ivaynberg.github.io/select2/>`_ integration
 since version 2.2.6. Select2 is a jQuery based replacement for select boxes.
 It supports searching, remote data sets, and infinite scrolling of results.
 

Resources/doc/reference/templates.rst

@@ -62,7 +62,7 @@ Row Templates
 
 It is possible to completely change how each row of results is rendered in the
 list view, by customizing the ``inner_list_row`` and ``base_list_field`` templates.
-For more information about this, see the :doc:`recipe_row_templates`
+For more information about this, see the :doc:`../cookbook/recipe_row_templates`
 cookbook entry.
 
 Other Templates

Resources/doc/reference/translation.rst

@@ -137,17 +137,13 @@ labels are generated by using a simple rule:
 
 The ``AdminBundle`` comes with different key label generation strategies:
 
-- ``sonata.admin.label.strategy.native``: DEFAULT - Makes the string human
-  readable
+* ``sonata.admin.label.strategy.native``: DEFAULT - Makes the string human readable
     ``isValid`` => ``Is Valid``
-- ``sonata.admin.label.strategy.form_component``: The default behavior from the Form
-  Component
+* ``sonata.admin.label.strategy.form_component``: The default behavior from the Form Component
     ``isValid`` => ``Isvalid``
-- ``sonata.admin.label.strategy.underscore``: Changes the name into a token suitable for
-  translation by prepending "form.label" to an underscored version of the field name
+* ``sonata.admin.label.strategy.underscore``: Changes the name into a token suitable for translation by prepending "form.label" to an underscored version of the field name
     ``isValid`` => ``form.label_is_valid``
-- ``sonata.admin.label.strategy.noop``: does not alter the
-  string
+* ``sonata.admin.label.strategy.noop``: does not alter the string
     ``isValid`` => ``isValid``
 
 ``sonata.admin.label.strategy.underscore`` will be better for i18n applications