Update docs in order to avoid calling deprecated methods `setTemplate…

…()` and `setTemplates()` in `AbstractAdmin` PR sonata-project#6387 deprecates methods `AbstractAdmin::setTemplate()` and `AbstractAdmin::setTemplates()`, but the documentation still recommends to use them. These calls were updated in order to use the template registry services.
phansys · Oct 24, 2020 · ae95461 · ae95461
1 parent 47333b9
commit ae95461
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 63 deletions.
diff --git a/docs/cookbook/recipe_customizing_a_mosaic_list.rst b/docs/cookbook/recipe_customizing_a_mosaic_list.rst
@@ -33,26 +33,15 @@ First, configure the ``outer_list_rows_mosaic`` template key:
 
       <!-- config/services.xml -->
 
-       <service id="sonata.media.admin.media" class="%sonata.media.admin.media.class%">
-            <argument/>
-            <argument>%sonata.media.admin.media.entity%</argument>
-            <argument>%sonata.media.admin.media.controller%</argument>
+        <service id="sonata.media.admin.media.template_registry">
             <call method="setTemplates">
-                <argument type="collection">
-                    <argument key="outer_list_rows_mosaic">@SonataMedia/MediaAdmin/list_outer_rows_mosaic.html.twig</argument>
-                </argument>
-            </call>
-            <tag
-                name="sonata.admin"
-                manager_type="orm"
-                group="sonata_media"
-                label_catalogue="%sonata.media.admin.media.translation_domain%"
-                label="media"
-                label_translator_strategy="sonata.admin.label.strategy.underscore"
-                />
-       </service>
-
-The ``list_outer_rows_mosaic.html.twig`` is the name of one mosaic's tile. You should also extends the template and overwrite the default blocks availables.
+                 <argument type="collection">
+                     <argument key="outer_list_rows_mosaic">@SonataMedia/MediaAdmin/list_outer_rows_mosaic.html.twig</argument>
+                 </argument>
+             </call>
+        </service>
+
+The ``list_outer_rows_mosaic.html.twig`` is the name of one mosaic's tile. You should also extend the template and overwrite the default blocks available.
 
 .. code-block:: jinja
 

diff --git a/docs/cookbook/recipe_row_templates.rst b/docs/cookbook/recipe_row_templates.rst
@@ -17,7 +17,9 @@ The recipe
 Configure your Admin service
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The configuration takes place in the DIC by calling the ``setTemplates`` method.
+The configuration takes place in the DIC by calling the ``setTemplate()`` / ``setTemplates()``
+method in the service "%s.template_registry" service, where "%s" is the name of your
+admin service (by instance "sonata.admin.comment").
 Two template keys need to be set:
 
 - ``inner_list_row``: The template for the row, which you will customize. Often
@@ -32,10 +34,7 @@ Two template keys need to be set:
 
         <!-- config/services.xml -->
 
-        <service id="sonata.admin.comment" class="%sonata.admin.comment.class%">
-            <argument/>
-            <argument>%sonata.admin.comment.entity%</argument>
-            <argument>%sonata.admin.comment.controller%</argument>
+        <service id="sonata.admin.comment.template_registry">
             <call method="setTemplates">
                 <argument type="collection">
                     <argument key="inner_list_row">
@@ -46,14 +45,6 @@ Two template keys need to be set:
                     </argument>
                 </argument>
             </call>
-            <tag
-                name="sonata.admin"
-                manager_type="orm"
-                group="sonata_blog"
-                label="comments"
-                label_catalogue="%sonata.admin.comment.translation_domain%"
-                label_translator_strategy="sonata.admin.label.strategy.underscore"
-                />
         </service>
 
 Create your customized template
@@ -85,6 +76,6 @@ Once the templates are defined, create the template to render the row:
     {% endblock %}
 
 While this feature is nice to generate a rich list, you can break the layout and
-admin features such as batch and object actions. It is best to familiarise yourself
+admin features such as batch and object actions. It is best to familiarize yourself
 with the default templates and extend them where possible, only changing what you
 need to customize.
diff --git a/docs/reference/search.rst b/docs/reference/search.rst
@@ -38,17 +38,14 @@ You also need to configure the block in the sonata block config
                 sonata.admin.block.search_result:
                     contexts: [admin]
 
-You can also configure the block template per admin while defining the admin:
+You can also configure the block template per admin by calling ``setTemplate()``
+or ``setTemplates()`` methods in the admin template registry:
 
 .. configuration-block::
 
     .. code-block:: xml
 
-        <service id="app.admin.post" class="App\Admin\PostAdmin">
-              <tag name="sonata.admin" manager_type="orm" group="Content" label="Post"/>
-              <argument/>
-              <argument>App\Entity\Post</argument>
-              <argument/>
+        <service id="app.admin.post.template_registry">
               <call method="setTemplate">
                   <argument>search_result_block</argument>
                   <argument>@SonataPost/Block/block_search_result.html.twig</argument>

diff --git a/docs/reference/templates.rst b/docs/reference/templates.rst
@@ -153,10 +153,10 @@ You can specify your templates in the config file:
     Notice that this is a global change, meaning it will affect all model mappings
     automatically, both for ``Admin`` mappings defined by you and by other bundles.
 
-If you wish, you can specify custom templates on a per ``Admin`` mapping
-basis. Internally, the ``CRUDController`` fetches this information from the
+If you wish, you can specify custom templates on a per ``Admin`` template registry
+service basis. Internally, the ``CRUDController`` fetches this information from the
 ``TemplateRegistry`` class instance that belongs with the ``Admin``, so you
-can specify the templates to use in the ``Admin`` service definition:
+can specify the templates to use in the ``Admin`` template registry service definition:
 
 .. configuration-block::
 
@@ -165,26 +165,15 @@ can specify the templates to use in the ``Admin`` service definition:
         # config/services.yaml
 
         services:
-            app.admin.post:
-                class: App\Admin\PostAdmin
-                arguments:
-                    - ~
-                    - App\Entity\Post
-                    - ~
+            app.admin.post.template_registry:
                 calls:
                     - [setTemplate, ['edit', 'PostAdmin/edit.html.twig']]
-                tags:
-                    - { name: sonata.admin, manager_type: orm, group: 'Content', label: 'Post' }
 
     .. code-block:: xml
 
        <!-- config/services.xml -->
 
-        <service id="app.admin.post" class="App\Admin\PostAdmin">
-            <tag name="sonata.admin" manager_type="orm" group="Content" label="Post"/>
-            <argument/>
-            <argument>App\Entity\Post</argument>
-            <argument/>
+        <service id="app.admin.post.template_registry">
             <call method="setTemplate">
                 <argument>edit</argument>
                 <argument>PostAdmin/edit.html.twig</argument>
@@ -202,19 +191,17 @@ can specify the templates to use in the ``Admin`` service definition:
 
 Changes made using the ``setTemplate()`` and ``setTemplates()`` methods
 override the customizations made in the configuration file, so you can specify
-a global custom template and then override that customization on a specific
+a global custom template and then override that customization for a specific
 ``Admin`` class.
 
 Finding configured templates
 ----------------------------
 Each ``Admin`` has a ``TemplateRegistry`` service connected to it that holds
-the templates registered through the configuration above. Through the method
-``getTemplate($name)`` of that class, you can access the templates set for
-that ``Admin``. The ``TemplateRegistry`` is available through ``$this->getTemplateRegistry()``
-within the ``Admin``. Using the service container the template registries can
-be accessed outside an ``Admin``. Use the ``Admin`` code + ``.template_registry``
-as the service ID (i.e. "app.admin.post" uses the Template Registry
-"app.admin.post.template_registry").
+the templates registered through the configuration above. The ``TemplateRegistry``
+is available through ``$this->getTemplateRegistry()`` within the ``Admin``.
+Using the service container the template registries can be accessed outside an ``Admin``.
+Use the ``Admin`` code + ``.template_registry`` as the service ID (i.e.
+"app.admin.post" uses the template registry "app.admin.post.template_registry").
 
 The ``TemplateRegistry`` service that holds the global templates can be accessed
 using the service ID "sonata.admin.global_template_registry".