Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs in order to avoid calling deprecated methods setTemplate() and setTemplates() in AbstractAdmin #6538

Closed
wants to merge 2 commits into from
Closed

Update docs in order to avoid calling deprecated methods setTemplate() and setTemplates() in AbstractAdmin #6538

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f22f58b
Update docs in order to avoid calling deprecated methods `setTemplate…
phansys Oct 24, 2020
f01517c
Small grammar fixes in docs
phansys Oct 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 8 additions & 19 deletions docs/cookbook/recipe_customizing_a_mosaic_list.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
greg0ire marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: jinja

Expand Down
19 changes: 5 additions & 14 deletions docs/cookbook/recipe_row_templates.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 by calling the ``setTemplate()`` / ``setTemplates()``
method in the service ``%s.template_registry`` service, where ``%s`` is the name of your
admin service (for instance ``sonata.admin.comment``).
Two template keys need to be set:

- ``inner_list_row``: The template for the row, which you will customize. Often
Expand All @@ -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">
Expand All @@ -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
Expand Down Expand Up @@ -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
greg0ire marked this conversation as resolved.
Show resolved Hide resolved
with the default templates and extend them where possible, only changing what you
need to customize.
9 changes: 3 additions & 6 deletions docs/reference/search.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
35 changes: 11 additions & 24 deletions docs/reference/templates.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand All @@ -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>
Expand All @@ -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
greg0ire marked this conversation as resolved.
Show resolved Hide resolved
``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``.
Outside an ``Admin``, you can obtain the template registries through their service ID.
Use the ``Admin`` code + ``.template_registry`` as the service ID (i.e.
"app.admin.post" uses the template registry "app.admin.post.template_registry").
Copy link
Contributor

@greg0ire greg0ire Oct 24, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd use code markup here, but it's funny, that's the second time I have this discussion today, so don't hesitate to tell me if you feel strongly otherwise.

Suggested change
"app.admin.post" uses the template registry "app.admin.post.template_registry").
``app.admin.post`` uses the template registry ``app.admin.post.template_registry``).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there is no established rule for the case where we need to refer to service names, parameter names, package names, etc. (since they are names, sometimes it feels natural to use double quotes and treat them a literal strings).
Personally, I try to be consistent with this, but in some cases it depends on the context, I think.
In the same reasoning, I try to use backticks when referencing code snippets (with partial or complete fragments, IE AdminInterface::id()).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI the discussion I linked resolved in using backticks (there was no debate, we needed both backticks and quotes). I tend to use backticks for everything. So to me you can write "admin class", you can also write Admin class, but you can't write Admin class, because now you are using a technical name as it appears in the code, and names that appear in code may contain special characters that have meaning in markdown like underscores or stars, but also in normal language, for example dots. When you use backticks, a monospace font will be used, and the reader knows you are talking about something that will appear in the code, and not approximately referring to something using a high level term like "unit of work" or "repository interface".


The ``TemplateRegistry`` service that holds the global templates can be accessed
using the service ID "sonata.admin.global_template_registry".
Expand Down