Update translation support, fix phpdocs

Admin/BaseFieldDescription.php

@@ -447,13 +447,31 @@ abstract class BaseFieldDescription implements FieldDescriptionInterface
         return preg_replace(array('/(^|_| )+(.)/e', '/\.(.)/e'), array("strtoupper('\\2')", "'_'.strtoupper('\\1')"), $property);
     }
 
+    /**
+     * Defines the help message
+     *
+     * @param $string help
+     */
     public function setHelp($help)
     {
         $this->help = $help;
     }
 
+    /**
+     * @return string
+     */
     public function getHelp()
     {
         return $this->help;
     }
+
+    /**
+     * return the label to use for the current field
+     *
+     * @return string
+     */
+    public function getLabel()
+    {
+        return $this->getOption('label', $this->getOption('name', $this->getName()));
+    }
 }

Builder/ListBuilderInterface.php

@@ -29,17 +29,16 @@ interface ListBuilderInterface
     /**
      * @abstract
      * @param \Sonata\AdminBundle\Admin\FieldDescriptionCollection $list
-     * @param \Sonata\AdminBundle\Admin\FieldDescription $fieldDescription
-     * @return void
+     * @param null|mixed $type
+     * @param \Sonata\AdminBundle\Admin\FieldDescriptionInterface $fieldDescription
+     * @param \Sonata\AdminBundle\Admin\AdminInterface $admin
      */
     function addField(FieldDescriptionCollection $list, $type = null, FieldDescriptionInterface $fieldDescription, AdminInterface $admin);
 
     /**
      * @abstract
      * @param \Sonata\AdminBundle\Admin\AdminInterface $admin
-     * @param \Sonata\AdminBundle\Admin\FieldDescription $fieldDescription
-     * @param array $options
-     * @return void
+     * @param \Sonata\AdminBundle\Admin\FieldDescriptionInterface $fieldDescription
      */
     function fixFieldDescription(AdminInterface $admin, FieldDescriptionInterface $fieldDescription);
 }

Datagrid/Datagrid.php

@@ -125,6 +125,24 @@ class Datagrid implements DatagridInterface
         $this->filters[$filter->getName()] = $filter;
     }
 
+    /**
+     * @param $name
+     * @return bool
+     */
+    public function hasFilter($name)
+    {
+        return isset($this->filters[$name]);
+    }
+
+    /**
+     * @param $name
+     * @return null
+     */
+    public function getFilter($name)
+    {
+        return $this->hasFilter($name) ? $this->filters[$name] : null;
+    }
+
     /**
      * @return array
      */
@@ -143,8 +161,8 @@ class Datagrid implements DatagridInterface
 
     /**
      * @param $name
+     * @param $operator
      * @param $value
-     * @return void
      */
     public function setValue($name, $operator, $value)
     {

Datagrid/DatagridInterface.php

@@ -14,7 +14,6 @@ use Sonata\AdminBundle\Filter\FilterInterface;
 
 interface DatagridInterface
 {
-
     /**
      * @abstract
      * @return \Sonata\AdminBundle\Datagrid\PagerInterface
@@ -67,8 +66,8 @@ interface DatagridInterface
     /**
      * @abstract
      * @param $name
+     * @param $operator
      * @param $value
-     * @return void
      */
     function setValue($name, $operator, $value);
 
@@ -77,4 +76,18 @@ interface DatagridInterface
      * @return \Symfony\Component\Form\Form
      */
     function getForm();
+
+    /**
+     * @abstract
+     * @param $name
+     * @return \Sonata\AdminBundle\Filter\FilterInterface
+     */
+    function getFilter($name);
+
+    /**
+     * @abstract
+     * @param $name
+     * @return bool
+     */
+    function hasFilter($name);
 }

Datagrid/DatagridMapper.php

@@ -15,6 +15,7 @@ use Sonata\AdminBundle\Admin\FieldDescriptionInterface;
 use Sonata\AdminBundle\Model\ModelManagerInterface;
 use Sonata\AdminBundle\Datagrid\DatagridInterface;
 use Sonata\AdminBundle\Builder\DatagridBuilderInterface;
+use Sonata\AdminBundle\Filter\FilterProxy;
 
 /**
  * This class is use to simulate the Form API

Filter/Filter.php

@@ -59,6 +59,15 @@ abstract class Filter implements FilterInterface
         return $default;
     }
 
+    /**
+     * @param $name
+     * @param $value
+     */
+    public function setOption($name, $value)
+    {
+        $this->options[$name] = $value;
+    }
+
     /**
      * @return string
      */
@@ -75,11 +84,22 @@ abstract class Filter implements FilterInterface
         return $this->getOption('field_options', array('required' => false));
     }
 
+    /**
+     * @return string
+     */
     public function getLabel()
     {
         return $this->getOption('label', $this->getName());
     }
 
+    /**
+     * @param $label
+     */
+    public function setLabel($label)
+    {
+        $this->setOption('label', $label);
+    }
+
     /**
      * @return string
      */

Filter/FilterInterface.php

@@ -25,6 +25,13 @@ interface FilterInterface
      */
     function filter($queryBuilder, $alias, $field, $value);
 
+    /**
+     * @abstract
+     * @param $query
+     * @param $value
+     */
+    function apply($query, $value);
+
     /**
      * Returns the filter name
      * @abstract
@@ -36,10 +43,17 @@ interface FilterInterface
      * Returns the label name
      *
      * @abstract
-     * @return void
+     * @return string
      */
     function getLabel();
 
+    /**
+     * @abstract
+     *
+     * @param string $label
+     */
+    function setLabel($name);
+
     /**
      * @abstract
      * @return array
@@ -50,10 +64,17 @@ interface FilterInterface
      * @abstract
      * @param string $name
      * @param null $default
-     * @return void
+     * @return mixed
      */
     function getOption($name, $default = null);
 
+    /**
+     * @abstract
+     * @param $name
+     * @param $value
+     */
+    function setOption($name, $value);
+
     /**
      * @abstract
      * @param $name
@@ -62,21 +83,21 @@ interface FilterInterface
      */
     function initialize($name, array $options = array());
 
-        /**
+    /**
      * @abstract
-     * @return void
+     * @return string
      */
     function getFieldName();
 
     /**
      * @abstract
-     * @return void
+     * @return array
      */
     function getFieldOptions();
 
     /**
      * @abstract
-     * @return void
+     * @return string
      */
     function getFieldType();
 
@@ -84,7 +105,7 @@ interface FilterInterface
      * Returns the main widget used to render the filter
      *
      * @abstract
-     * @return void
+     * @return array
      */
     function getRenderSettings();
 }

Form/Extension/Field/Type/FormTypeFieldExtension.php

@@ -21,6 +21,10 @@ use Sonata\AdminBundle\Admin\FieldDescriptionInterface;
 
 class FormTypeFieldExtension extends AbstractTypeExtension
 {
+    /**
+     * @param \Symfony\Component\Form\FormBuilder $builder
+     * @param array $options
+     */
     public function buildForm(FormBuilder $builder, array $options)
     {
         $sonataAdmin = array(
@@ -50,6 +54,10 @@ class FormTypeFieldExtension extends AbstractTypeExtension
         $builder->setAttribute('sonata_admin', $sonataAdmin);
     }
 
+    /**
+     * @param \Symfony\Component\Form\FormView $view
+     * @param \Symfony\Component\Form\FormInterface $form
+     */
     public function buildView(FormView $view, FormInterface $form)
     {
         $sonataAdmin = $form->getAttribute('sonata_admin');

Form/Type/Filter/NumberType.php

@@ -32,6 +32,9 @@ class NumberType extends AbstractType
 
     protected $translator;
 
+    /**
+     * @param \Symfony\Component\Translation\TranslatorInterface $translator
+     */
     public function __construct(TranslatorInterface $translator)
     {
         $this->translator = $translator;
@@ -47,6 +50,10 @@ class NumberType extends AbstractType
         return 'sonata_type_filter_number';
     }
 
+    /**
+     * @param \Symfony\Component\Form\FormBuilder $builder
+     * @param array $options
+     */
     public function buildForm(FormBuilder $builder, array $options)
     {
         $choices = array(
@@ -63,6 +70,10 @@ class NumberType extends AbstractType
         ;
     }
 
+    /**
+     * @param array $options
+     * @return array
+     */
     public function getDefaultOptions(array $options)
     {
         $defaultOptions = array(

Resources/doc/index.rst

@@ -28,5 +28,6 @@ Reference Guide
    reference/saving_hooks
    reference/conditional_validation
    reference/templates
+   reference/translation
    reference/security
    reference/advance

Resources/doc/reference/translation.rst

@@ -0,0 +1,74 @@
+Translation
+===========
+
+There are two main catalogue names in an Admin class:
+
+* ``SonataAdminBundle`` : this catalogue is used to translate shared messages accross different admin
+* ``messages`` : this catalogue is used to translate the message for the current admin
+
+Ideally the ``messages`` catalogue should be changed to avoid any issues with other Admin classes.
+
+You have two options to configure the catalogue for the admin class:
+
+* one by defining a property
+
+.. code-block:: php
+
+    <?php
+    class PageAdmin extends Admin
+    {
+        protected $translationDomain = 'SonataPageBundle';
+    }
+
+
+* or by injecting the value through the container
+
+.. code-block:: xml
+
+        <service id="sonata.page.admin.page" class="Sonata\PageBundle\Admin\PageAdmin">
+            <tag name="sonata.admin" manager_type="orm" group="sonata_page" label="page"/>
+            <argument />
+            <argument>Application\Sonata\PageBundle\Entity\Page</argument>
+            <argument />
+
+            <call method="setTranslationDomain">
+                <argument>SonataPageBundle</argument>
+            </call>
+        </service>
+
+
+An admin instance always get the ``translator`` instance, so it can be used to translate messages within the
+``configure*Fields`` method or in templates.
+
+.. code-block:: jinja
+
+    {# the classical call by using the twig trans helper #}
+    {% trans from 'SonataPageBundle'%}message_create_snapshots{% endtrans %}
+
+    {# by using the admin trans method with hardcoded catalogue #}
+    {{ admin.trans('message_create_snapshots', {}, 'SonataPageBundle') }}
+
+    {# by using the admin trans with the configured catalogue #}
+    {{ admin.trans('message_create_snapshots') }}
+
+
+The later solution is more flexible as no catalogue parameters are hardcoded.
+
+Translate field labels
+----------------------
+
+The Admin bundle comes with a customized form field template. The most notable changes from the original one is the use
+of the translation domain provided by the Admin instance to translate label.
+
+By default, the label is the the field name. However a label can be defined as a the third argument of the ``add`` method:
+
+.. code-block:: php
+
+    <?php
+    class PageAdmin extends Admin
+    {
+        public function configureFormFields(FormMapper $formMapper)
+        {
+            $formMapper->add('name', null, array('required' => false, 'label' => 'label.name'));
+        }
+    }

Resources/views/CRUD/base_list.html.twig

@@ -49,13 +49,7 @@ file that was distributed with this source code.
                                     {% spaceless %}
                                         <th class="sonata-ba-list-field-header-{{ field_description.type}} {% if sortable %} sonata-ba-list-field-header-order-{{ sort_by|lower }} {{ sort_active_class }}{% endif %}">
                                             {% if sortable %}<a href="{{ admin.generateUrl('list', sort_parameters) }}">{% endif %}
-
-                                            {% if field_description.options.name is defined %}
-                                                {{ field_description.options.name|trans({}, admin.translationdomain) }}
-                                            {% else %}
-                                                {{ field_description.name|trans({}, admin.translationdomain) }}
-                                            {% endif %}
-
+                                            {{ admin.trans(field_description.label) }}
                                             {% if sortable %}</a>{% endif %}
                                         </th>
                                     {% endspaceless %}

Resources/views/CRUD/base_show.html.twig

@@ -34,7 +34,7 @@ file that was distributed with this source code.
                 {% if name %}
                     <tr class="sonata-ba-view-title">
                         <td colspan="2">
-                            {{ name|trans({}, admin.translationdomain) }}
+                            {{ admin.trans(field_description.label) }}
                         </td>
                     </tr>
                 {% endif %}

Resources/views/Form/filter_admin_fields.html.twig

@@ -9,15 +9,4 @@ file that was distributed with this source code.
 
 #}
 
-{% extends 'form_div_layout.html.twig' %}
-
-{% block field_row %}
-    <div>
-        {{ form_label(form) }}
-        <br />
-
-        <div class="sonata-ba-field">
-            {% block field %}{{ form_widget(form) }}{% endblock %}
-        </div>
-    </div>
-{% endblock field_row %}
+{% extends 'SonataAdminBundle:Form:silex_form_div_layout.html.twig' %}

Resources/views/Form/form_admin_fields.html.twig

@@ -21,12 +21,12 @@ file that was distributed with this source code.
         <label{% for attrname,attrvalue in attr %} {{attrname}}="{{attrvalue}}"{% endfor %}>
             {{ widget|raw }}
             <span>
-                {{ label|trans }}
+                {{ label|trans({}, sonata_admin.admin.translationDomain) }}
             </span>
             {{ required ? '*' : '' }}
         </label>
     {% else %}
-        <label{% for attrname,attrvalue in attr %} {{attrname}}="{{attrvalue}}"{% endfor %}>{{ label|trans }} {{ required ? '*' : '' }} </label>
+        <label{% for attrname,attrvalue in attr %} {{attrname}}="{{attrvalue}}"{% endfor %}>{{ label|trans({}, sonata_admin.admin.translationDomain) }} {{ required ? '*' : '' }} </label>
     {% endif %}
 {% endspaceless %}
 {% endblock %}

Twig/Extension/SonataAdminExtension.php

@@ -46,6 +46,9 @@ class SonataAdminExtension extends \Twig_Extension
         );
     }
 
+    /**
+     * @return array
+     */
     public function getTokenParsers()
     {
         return array();