Merge pull request #2259 from greg0ire/doc_improvements

Finished proofreading the book. Say squash if it's ok.

Resources/doc/reference/advanced.rst

@@ -210,7 +210,7 @@ Lets consider a base class named `Person` and its subclasses `Student` and `Teac
             </service>
         </services>
 
-You will just need to change the way forms are configured in order to take into account this new subclasses:
+You will just need to change the way forms are configured in order to take into account these new subclasses:
 
 .. code-block:: php
 

Resources/doc/reference/batch_actions.rst

@@ -1,7 +1,7 @@
 Batch actions
 =============
 
-Batch actions are actions triggered on a set of selected objects. By default 
+Batch actions are actions triggered on a set of selected objects. By default,
 Admins have a ``delete`` action which allows you to remove several entries at once.
 
 Defining new actions
@@ -10,12 +10,13 @@ Defining new actions
 To create a new custom batch action which appears in the list view follow these steps:
 
 Override ``getBatchActions()`` in your ``Admin`` class to define the new batch actions
-by adding them to the $actions array. Each entry has two settings:
+by adding them to the ``$actions`` array. Each entry has two settings:
 
 - **label**: The name to use when offering this option to users, should be passed through the translator
-- **ask_confirmation**: defaults to true and means that the user will be asked for confirmation before the batch action is processed
+- **ask_confirmation**: defaults to true and means that the user will be asked
+  for confirmation before the batch action is processed
 
-For example, lets define a new ``merge`` action which takes a number of source items and 
+For example, lets define a new ``merge`` action which takes a number of source items and
 merges them onto a single target item. It should only be available when two conditions are met:
 
 - the EDIT and DELETE routes exist for this Admin (have not been disabled)
@@ -50,7 +51,7 @@ merges them onto a single target item. It should only be available when two cond
 (Optional) Overriding the batch selection template
 --------------------------------------------------
 
-A merge action requires two kind of selection: a set of source objects to merge from
+A merge action requires two kinds of selection: a set of source objects to merge from
 and a target object to merge into. By default, batch_actions only let you select one set
 of objects to manipulate. We can override this behavior by changing our list template 
 (``list__batch.html.twig``) and adding a radio button to choose the target object. 
@@ -99,7 +100,9 @@ This method may return three different values:
 
  - ``true``: The batch action is relevant and can be applied.
  - ``false``: Same as above, with the default "action aborted, no model selected" notification message.
- - a string: The batch action is not relevant given the current request parameters (for example the ``target`` is missing for a ``merge`` action). The returned string is a message displayed to the user.
+ - a string: The batch action is not relevant given the current request parameters
+   (for example the ``target`` is missing for a ``merge`` action).
+   The returned string is a message displayed to the user.
 
 .. code-block:: php
 
@@ -140,7 +143,7 @@ This method may return three different values:
 -------------------------------------
 
 In your admin class you can create a ``preBatchAction`` method to execute something before doing the batch action.
-The main purpose of this method is to alter the query or the list of selected id.
+The main purpose of this method is to alter the query or the list of selected ids.
 
 .. code-block:: php
 

Resources/doc/reference/conditional_validation.rst

@@ -5,7 +5,7 @@ The inline validation is about delegating model validation to a dedicated servic
 The current validation implementation built in the Symfony2 framework is very powerful
 as it allows to declare validation on a : class, field and getter. However these declarations
 can take a while to code for complex rules. As rules must be a set of a ``Constraint``
-and ``Validator`` instances.
+and a ``Validator`` instances.
 
 The inline validation tries to provide a nice solution by introducing an ``ErrorElement``
 object. The object can be used to check assertions against the model :

Resources/doc/reference/events.rst

@@ -1,29 +1,29 @@
 Events
 ======
 
-An event mechanism is available to add an extra entry point to extend Admin instance.
+An event mechanism is available to add an extra entry point to extend an Admin instance.
 
 ConfigureEvent
 ~~~~~~~~~~~~~~
 
 This event is generated when a form, list, show, datagrid is configured. The event names are:
 
- - sonata.admin.event.configure.form
- - sonata.admin.event.configure.list
- - sonata.admin.event.configure.datagrid
- - sonata.admin.event.configure.show
+ - ``sonata.admin.event.configure.form``
+ - ``sonata.admin.event.configure.list``
+ - ``sonata.admin.event.configure.datagrid``
+ - ``sonata.admin.event.configure.show``
 
 PersistenceEvent
 ~~~~~~~~~~~~~~~~
 
 This event is generated when a persistency layer update, save or delete an object. The event names are:
 
- - sonata.admin.event.persistence.pre_update
- - sonata.admin.event.persistence.post_update
- - sonata.admin.event.persistence.pre_persist
- - sonata.admin.event.persistence.post_persist
- - sonata.admin.event.persistence.pre_remove
- - sonata.admin.event.persistence.post_remove
+ - ``sonata.admin.event.persistence.pre_update``
+ - ``sonata.admin.event.persistence.post_update``
+ - ``sonata.admin.event.persistence.pre_persist``
+ - ``sonata.admin.event.persistence.post_persist``
+ - ``sonata.admin.event.persistence.pre_remove``
+ - ``sonata.admin.event.persistence.post_remove``
 
 
 ConfigureQueryEvent
@@ -36,14 +36,14 @@ BlockEvent
 
 Block events help you customize your templates. Available events are :
 
- - sonata.admin.dashboard.top
- - sonata.admin.dashboard.bottom
- - sonata.admin.list.table.top
- - sonata.admin.list.table.bottom
- - sonata.admin.edit.form.top
- - sonata.admin.edit.form.bottom
- - sonata.admin.show.top
- - sonata.admin.show.bottom
+ - ``sonata.admin.dashboard.top``
+ - ``sonata.admin.dashboard.bottom``
+ - ``sonata.admin.list.table.top``
+ - ``sonata.admin.list.table.bottom``
+ - ``sonata.admin.edit.form.top``
+ - ``sonata.admin.edit.form.bottom``
+ - ``sonata.admin.show.top``
+ - ``sonata.admin.show.bottom``
 
 If you want more information about block events, you should check the
 `"Event" section of block bundle documentation <http://sonata-project.org/bundles/block/master/doc/reference/events.html>`_.

Resources/doc/reference/extensions.rst

@@ -30,7 +30,8 @@ Configuration
 There are two ways to configure your extensions and connect them to an admin.
 
 You can include this information in the service definition of your extension.
-Add the tag *sonata.admin.extension* and use the *target* attribute to point to the admin you want to modify. Please note you can specify as many tags you want.
+Add the tag *sonata.admin.extension* and use the *target* attribute to point to
+the admin you want to modify. Please note you can specify as many tags you want.
 Set the *global* attribute to *true* and the extension will be added to all admins.
 
 .. configuration-block::
@@ -67,10 +68,10 @@ extra options you can use to wire your extensions in a more dynamic way. This me
 admins that manage a class of a specific type.
 
 admins:
-    specify one or more admin service id's to which the Extension should be added
+    specify one or more admin service ids to which the Extension should be added
 
 excludes:
-    specify one or more admin service id's to which the Extension should not be added (this will prevent it matching
+    specify one or more admin service ids to which the Extension should not be added (this will prevent it matching
     any of the other settings)
 
 extends:

Resources/doc/reference/field_types.rst

@@ -45,11 +45,15 @@ Choice
     $listMapper->add(
         'status',
         'choice',
-        array('choices'=>array('prep'=>'Prepared', 'prog'=>'In progress', 'done'=>'Done'),
+        array('choices' => array(
+            'prep' => 'Prepared',
+            'prog' => 'In progress',
+            'done' => 'Done'
+        ),
         'catalogue' => 'AcmeDemoBundle'
     ));
 
-``choice`` filed type also supports multiple values that can be separated by ``delimiter`` (default delimiter is a comma ",").
+``choice`` field type also supports multiple values that can be separated by ``delimiter`` (default delimiter is a comma ",").
 
 .. code-block:: php
 
@@ -76,24 +80,36 @@ Parameters:
 * **route.name**: route name (e.g. ``acme_demo_homepage``)
 * **route.parameters**: array of route parameters (e.g. ``array('type'=>'example', 'display'=>'full')``)
 * **route.absolute**: boolean value, create absolute or relative url address based on ``route.name`` and  ``route.parameters`` (default ``false``)
-* **route.identifier_parameter_name**: parameter added to ``route.parameters``, it's value is an object identifier (e.g. 'id') to create dynamic links based on rendered objects.
+* **route.identifier_parameter_name**: parameter added to ``route.parameters``, its value is an object identifier (e.g. 'id') to create dynamic links based on rendered objects.
 
 .. code-block:: php
 
-    // Output for value `http://example.com`: `<a href="http://example.com">http://example.com</a>`
+    // Output for value `http://example.com`:
+    // `<a href="http://example.com">http://example.com</a>`
     $listMapper->add('targetUrl', 'url');
 
-    // Output for value `http://example.com`: `<a href="http://example.com">example.com</a>`
+    // Output for value `http://example.com`:
+    // `<a href="http://example.com">example.com</a>`
     $listMapper->add('targetUrl', 'url', array('hide_protocol' => true));
 
-    // Output for value `Homepage of example.com` : `<a href="http://example.com">Homepage of example.com</a>`
+    // Output for value `Homepage of example.com` :
+    // `<a href="http://example.com">Homepage of example.com</a>`
     $listMapper->add('title', 'url', array('url' => 'http://example.com'));
 
-    // Output for value `Acme Blog Homepage`: `<a href="http://blog.example.com">Acme Blog Homepage</a>`
-    $listMapper->add('title', 'url', array('route' => array('name'=>'acme_blog_homepage', 'absolute'=>true)));
-
-    // Output for value `Sonata is great!` (related object has identifier `123`): `<a href="http://blog.example.com/xml/123">Sonata is great!</a>`
-    $listMapper->add('title', 'url', array('route' => array('name'=>'acme_blog_article', 'absolute'=>true, 'parameters'=>array('format'=>'xml'), 'identifier_parameter_name'=>'id')));
+    // Output for value `Acme Blog Homepage`:
+    // `<a href="http://blog.example.com">Acme Blog Homepage</a>`
+    $listMapper->add('title', 'url', array('route' => array(
+        'name' => 'acme_blog_homepage',
+        'absolute' => true
+    )));
+
+    // Output for value `Sonata is great!` (related object has identifier `123`):
+    // `<a href="http://blog.example.com/xml/123">Sonata is great!</a>`
+    $listMapper->add('title', 'url', array('route' => array(
+        'name' => 'acme_blog_article',
+        'absolute' => true,
+        'parameters' => array('format' => 'xml'),
+        'identifier_parameter_name' => 'id')));
 
 .. note::
 

Resources/doc/reference/preview_mode.rst

@@ -4,7 +4,7 @@ Preview Mode
 Preview Mode is an optional view of an object before it is persisted or updated.
 
 The preview step can be enabled for an admin entity by overriding the public property
-$supportsPreviewMode and setting it to true.
+``$supportsPreviewMode`` and setting it to true.
 
 .. code-block:: php
 

Resources/doc/reference/security.rst

@@ -5,7 +5,7 @@ User management
 ---------------
 
 By default, the SonataAdminBundle does not come with any user management,
-however it is most likely the application requires such feature. The Sonata
+however it is most likely the application requires such a feature. The Sonata
 Project includes a ``SonataUserBundle`` which integrates the ``FOSUserBundle``.
 
 The ``FOSUserBundle`` adds support for a database-backed user system in Symfony2.
@@ -44,9 +44,9 @@ change the default value you can set the ``security_handler`` to
 ``sonata.admin.security.handler.acl`` or ``sonata.admin.security.handler.role``.
 
 To quickly secure an admin the role security can be used. It allows to specify
-the actions a user can with the admin. The ACL security system is more advanced
+the actions a user can do with the admin. The ACL security system is more advanced
 and allows to secure the objects. For people using the previous ACL
-implementation, you can switch the security_handler to the role security handler.
+implementation, you can switch the ``security_handler`` to the role security handler.
 
 Configuration
 ~~~~~~~~~~~~~
@@ -93,14 +93,16 @@ Later, we will explain how to set up ACL with the
 Role handler
 ------------
 
-The ``sonata.admin.security.handler.role`` allows you to operate finely on the actions that can be done (depending on the entity class), without requiring to set up ACL.
+The ``sonata.admin.security.handler.role`` allows you to operate finely on the
+actions that can be done (depending on the entity class), without requiring to set up ACL.
 
 Configuration
 ~~~~~~~~~~~~~
 
 First, activate the role security handler as described above.
 
-Each time an user tries to do an action in the admin, Sonata checks if he is either a super admin (``ROLE_SUPER_ADMIN``) **or** has the permission.
+Each time an user tries to do an action in the admin, Sonata checks if he is
+either a super admin (``ROLE_SUPER_ADMIN``) **or** has the permission.
 
 The permissions are:
 
@@ -151,7 +153,7 @@ in the Symfony documentation.
 Usage
 ~~~~~
 
-You can now test if an user is authorized from an Admin class:
+You can now test if a user is authorized from an Admin class:
 
 .. code-block:: php
 
@@ -175,11 +177,13 @@ Or from a Twig template:
             <p>Hello there!</p>
         {% endif %}
 
-Note that you don't have to re-specify the prefix.
+Note that you do not have to re-specify the prefix.
 
-Sonata check those permissions for the action it handles internally. Of course you will have to recheck them in your own code.
+Sonata checks those permissions for the action it handles internally.
+Of course you will have to recheck them in your own code.
 
-Yon can also create your own permissions, for example ``EMAIL`` (which will turn into role ``ROLE_SONATA_ADMIN_DEMO_FOO_EMAIL``).
+Yon can also create your own permissions, for example ``EMAIL``
+(which will turn into role ``ROLE_SONATA_ADMIN_DEMO_FOO_EMAIL``).
 
 Going further
 ~~~~~~~~~~~~~
@@ -227,8 +231,8 @@ ACL and FriendsOfSymfony/UserBundle
 
 If you want an easy way to handle users, please use:
 
-- `FOSUserBundle <https://github.com/FriendsOfSymfony/FOSUserBundle>`_: handle users and groups
-  stored in RDMS or MongoDB
+- `FOSUserBundle <https://github.com/FriendsOfSymfony/FOSUserBundle>`_: handles
+  users and groups stored in RDBMS or MongoDB
 - `SonataUserBundle <https://github.com/sonata-project/SonataUserBundle>`_: integrates the
   ``FriendsOfSymfony/UserBundle`` with the ``AdminBundle``
 
@@ -420,7 +424,8 @@ property ``$securityInformation`` to change this:
 - ``ROLE_SONATA_..._GUEST``
     a guest that is allowed to ``VIEW`` an object and a ``LIST`` of objects;
 - ``ROLE_SONATA_..._STAFF``
-    probably the biggest part of the users, a staff user  has the same permissions as guests and is additionally allowed to ``EDIT`` and ``CREATE`` new objects;
+    probably the biggest part of the users, a staff user  has the same permissions
+    as guests and is additionally allowed to ``EDIT`` and ``CREATE`` new objects;
 - ``ROLE_SONATA_..._EDITOR``
     an editor is granted all access and, compared to the staff users, is allowed to ``DELETE``;
 - ``ROLE_SONATA_..._ADMIN``
@@ -431,7 +436,7 @@ Owner:
 - when an object is created, the currently logged in user is set as owner for
   that object and is granted all access for that object;
 - this means the user owning the object is always allowed to ``DELETE`` the
-  object, even when it only has the staff role.
+  object, even when they only have the staff role.
 
 Vocabulary used for Access Control Lists:
 
@@ -640,7 +645,8 @@ In the templates, or in your code, you can use the Admin method ``isGranted()``:
 List filtering
 ~~~~~~~~~~~~~~
 
-List filtering using ACL is available as a third party bundle: `CoopTilleulsAclSonataAdminExtensionBundle <https://github.com/coopTilleuls/CoopTilleulsAclSonataAdminExtensionBundle>`_.  
+List filtering using ACL is available as a third party bundle:
+`CoopTilleulsAclSonataAdminExtensionBundle <https://github.com/coopTilleuls/CoopTilleulsAclSonataAdminExtensionBundle>`_.
 When enabled, the logged in user will only see the objects for which it has the `VIEW` right (or superior).
 
 ACL editor

Resources/doc/reference/templates.rst

@@ -2,7 +2,8 @@ Templates
 =========
 
 ``SonataAdminBundle`` comes with a significant amount of ``twig`` files used to display the
-different parts of each ``Admin`` action's page. If you read the ``Templates`` part of the :doc:`architecture` section of this guide, you should know by now how these are organized in
+different parts of each ``Admin`` action's page. If you read the ``Templates`` part of the
+:doc:`architecture` section of this guide, you should know by now how these are organized in
 the ``views`` folder. If you haven't, now would be a good time to do it.
 
 Besides these, some other views files are included from the storage layer. As their content and
@@ -39,14 +40,14 @@ As seen before, the ``CRUDController`` has several actions that allow you to man
 model instances. Each of those actions uses a specific template file to render its content.
 By default, ``SonataAdminBundle`` uses the following templates for their matching action:
 
-* list: SonataAdminBundle:CRUD:list.html.twig
-* show: SonataAdminBundle:CRUD:show.html.twig
-* edit: SonataAdminBundle:CRUD:edit.html.twig
-* history: SonataAdminBundle:CRUD:history.html.twig
-* preview: SonataAdminBundle:CRUD:preview.html.twig
-* delete: SonataAdminBundle:CRUD:delete.html.twig
-* batch_confirmation: SonataAdminBundle:CRUD:batch_confirmation.html.twig
-* acl: SonataAdminBundle:CRUD:acl.html.twig
+* ``list`` : SonataAdminBundle:CRUD:list.html.twig
+* ``show`` : SonataAdminBundle:CRUD:show.html.twig
+* ``edit`` : SonataAdminBundle:CRUD:edit.html.twig
+* ``history`` : SonataAdminBundle:CRUD:history.html.twig
+* ``preview`` : SonataAdminBundle:CRUD:preview.html.twig
+* ``delete`` : SonataAdminBundle:CRUD:delete.html.twig
+* ``batch_confirmation`` : SonataAdminBundle:CRUD:batch_confirmation.html.twig
+* ``acl`` : SonataAdminBundle:CRUD:acl.html.twig
 
 Notice that all these templates extend other templates, and some do only that. This inheritance
 architecture is designed to help you easily make customizations by extending these templates
@@ -71,16 +72,27 @@ Other Templates
 There are several other templates that can be customized, enabling you to fine-tune
 ``SonataAdminBundle``:
 
-* user_block: customizes the Twig block rendered by default in the top right corner of the admin interface, containing user information. Empty by default, see ``SonataUserBundle`` for a real example.
-* add_block: customizes the Twig block rendered by default in the top right corner of the admin interface, providing quick access to create operations on available admin classes.
-* history_revision_timestamp: customizes the way timestamps are rendered when using history related actions.
-* action: a generic template you can use for your custom actions
-* short_object_description: used by the ``getShortObjectDescriptionAction`` action from the ``HelperController``, this template displays a small description of a model instance.
-* list_block: the template used to render the dashboard's admin mapping lists. More info on the :doc:`dashboard` page.
+* ``user_block`` : customizes the Twig block rendered by default in the top right
+  corner of the admin interface, containing user information.
+  Empty by default, see ``SonataUserBundle`` for a real example.
+* ``add_block`` : customizes the Twig block rendered by default in the top right
+  corner of the admin interface, providing quick access to create operations on
+  available admin classes.
+* ``history_revision_timestamp:`` customizes the way timestamps are rendered when
+  using history related actions.
+* ``action`` : a generic template you can use for your custom actions
+* ``short_object_description`` : used by the ``getShortObjectDescriptionAction``
+  action from the ``HelperController``, this template displays a small
+  description of a model instance.
+* ``list_block`` : the template used to render the dashboard's admin mapping lists.
+  More info on the :doc:`dashboard` page.
 * batch: template used to render the checkboxes that precede each instance on list views.
-* select: when loading list views as part of sonata_admin form types, this template is used to create a button that allows you to select the matching line.
-* pager_links: renders the list of pages displayed at the end of the list view (when more than one page exists)
-* pager_results: renders the dropdown that lets you choose the number of elements per page on list views
+* ``select`` : when loading list views as part of sonata_admin form types, this
+  template is used to create a button that allows you to select the matching line.
+* ``pager_links`` : renders the list of pages displayed at the end of the list view
+  (when more than one page exists)
+* ``pager_results`` : renders the dropdown that lets you choose the number of
+  elements per page on list views
 
 Configuring templates
 ---------------------

Resources/doc/reference/translation.rst

@@ -141,8 +141,9 @@ The ``AdminBundle`` comes with different key label generation strategies:
     ``isValid`` => ``Is Valid``
 * ``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
-    ``isValid`` => ``form.label_is_valid``
+* ``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
     ``isValid`` => ``isValid``
 

Resources/doc/reference/troubleshooting.rst

@@ -4,7 +4,8 @@ Troubleshooting
 The toString method
 -------------------
 
-Sometimes the bundle needs to display your model objects, in order to do it, objects are converted to string by using the `__toString`_ magic method.
+Sometimes the bundle needs to display your model objects, in order to do it,
+objects are converted to string by using the `__toString`_ magic method.
 Take care to never return anything else than a string in this method.
 For example, if your method looks like that :
 
@@ -16,8 +17,9 @@ For example, if your method looks like that :
     }
 
 
-You can't be sure your object will *always* have a title when the bundle will want to convert it to a string.
-So in order to avoid any fatal error, you must return an empty string (or anything you prefer) for when the title is missing, like this :
+You cannot be sure your object will *always* have a title when the bundle will want to convert it to a string.
+So in order to avoid any fatal error, you must return an empty string
+(or anything you prefer) for when the title is missing, like this :
 
 .. code-block:: php
 
@@ -33,20 +35,28 @@ So in order to avoid any fatal error, you must return an empty string (or anythi
 Large filters and long urls problem
 -----------------------------------
 
-If you will try to add hundreds filters to single admin class, you will get a problem - very long filter form url generated.
-In most cases you will get server response like *Error 400 Bad Request* OR *Error 414 Request-URI Too Long*. According to 
+If you will try to add hundreds of filters to a single admin class, you will get a problem - very long generated filter form url.
+In most cases you will get server response like *Error 400 Bad Request* OR *Error 414 Request-URI Too Long*. According to
 `a StackOverflow discussion <http://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers>`_
 "safe" url length is just around 2000 characters.
-You can fix this issue by adding simple JQuery code on your edit template
+You can fix this issue by adding a simple JQuery piece of code on your edit template :
 
 .. code-block:: javascript
 
     $(function() {
         // Add class 'had-value-on-load' to inputs/selects with values.
-        $(".sonata-filter-form input").add(".sonata-filter-form select").each(function(){ if($(this).val()) { $(this).addClass('had-value-on-load')}})
+        $(".sonata-filter-form input").add(".sonata-filter-form select").each(function(){
+            if($(this).val()) {
+                $(this).addClass('had-value-on-load');
+            }
+        });
         // REMOVE ALL EMPTY INPUT FROM FILTER FORM (except inputs, which has class 'had-value-on-load')
         $(".sonata-filter-form").submit(function() {
-            $(".sonata-filter-form input").add(".sonata-filter-form select").each(function(){ if(!$(this).val() && !$(this).hasClass('had-value-on-load')) { $(this).remove()}})
+            $(".sonata-filter-form input").add(".sonata-filter-form select").each(function(){
+                if(!$(this).val() && !$(this).hasClass('had-value-on-load')) {
+                    $(this).remove()
+                };
+            });
         });
     });