Skip to content

[IMP] base: remove t-cache directive from ir.qweb #14693

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+0 −222
Open

[IMP] base: remove t-cache directive from ir.qweb #14693

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
222 changes: 0 additions & 222 deletions content/developer/reference/frontend/qweb.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -445,228 +445,6 @@ Debugging
The behaviour can be configured via :envvar:`PYTHONBREAKPOINT` or
:func:`sys.breakpointhook`.

Rendering cache:
----------------

``t-cache="key_cache"`` tags part of template to be cached at rendering time.
Every sub-directives will be call only during the first rendering. It means
that the sql queries excecuted during the rendering of those sub-directives
are also done only once.

``t-nocache="documentation"`` tags part of template to be render every time.
The content can only use the root values.

Why and when to use ``t-cache``?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This directive is used to speed up the rendering, by caching parts of the final
document, which may save queries to the database. However, it should be used
sparingly, as ``t-cache`` will inevitably complicate templates (and their
understanding of ``t-set`` for example).

However, in order to actually save database queries, it might be necessary to
render the template with values that are evaluated lazily. If those lazy
values are used in a cached part, they will not be evaluated if the part is
available in cache.

The ``t-cache`` directive is useful for template parts using values that depend
on a limited amount of data. We recommend to analyze the rendering of the
template with the profiler (by activating the "**Add qweb directive context**"
option). Passing lazy values to the rendering in controllers allow you to
display the directives using these values and triggering the queries.

A concern of using such a cache are making it available to different users
(different users should render the cached parts the same way). Another
potential issue is to invalidate its entries when necessary. For the latter,
the **key expression** should be chosen wisely. Using the ``write_date`` of a
recordset can make a cache key out-of-date without having to discard it
explicitly from the cache, for instance.

One should also pay attention to the fact that the values in ``t-cache`` parts
are scoped. This implies that if there are ``t-set`` directives in this part of
the template, the rendering of what comes after it could be different than if
there was no ``t-cache`` directive.

What if there is a ``t-cache`` inside a ``t-cache``?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The parts are cached. Each containing only the string corresponding to its
rendering. Thus, the ``t-cache`` inside will probably be read less often, its
cache key will not necessarily be used. If this must be the case, then you may
need to add a ``t-nocache`` (on the same node or a parent).

What is ``t-nocache`` used for?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to cache part of a template with ``t-cache`` but a small piece must
remain dynamic and be evaluated at cache times. However, the part in
``t-nocache`` will not have access to the ``t-set`` value of the template. Only
the values ​​provided by the controller are accessible there.
For example, the menu is cached because it's the same all the time and takes
time to render (using the performance devtools with the qweb context lets you
investigate). However, in the menu, we want the ecommerce cart to be always up
to date. So there is a ``t-nocache`` to keep this part dynamic.

The base of ``t-cache``
~~~~~~~~~~~~~~~~~~~~~~~

The ``t-cache`` directive allows you to store the rendered result of a template.
The **key expression** (eg 42: ``t-cache="42"``) will be evaluated as a python
expression. This will be used to generate the **cache key**. So there can be
different **cache values** (cached render part) for the same template part. If
the **key expression** is a tuple or a list, it will be searched when generating
the **cache key**. If one or more recordsets are returned by the **key
expression**, then the model, ids and their corresponding write_date will be
used to generate the **cache key**. Special case: If the **key expression**
returns a Falsy value, then the content will not be cached.

Example::

<div t-cache="record,bool(condition)">
<span t-if="condition" t-field="record.partner_id.name">
<span t-else="" t-field="record.partner_id" t-options-widget="contact">
</div>

In this case, there may be values ​​(string) in the cache corresponding to each
record already returned with a true condition, as well as for the false
condition. And if a module modifies the record, the write_date being modified,
the cached value is discarded.

``t-cache`` and scoped values (``t-set``, ``t-foreach``...)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Values in ``t-cache`` are scoped, this involves a change in behavior between
having or not having ``t-cache`` on one of the parent nodes. Don't forget to
take into account that Odoo uses a lot of templates, ``t-call`` and view
inheritance. Adding a ``t-cache`` can therefore modify the rendering of a
template that you do not see when editing.
(``t-foreach`` it's like a ``t-set`` for each iteration)

Example::

<div>
<t t-set="a" t-value="1"/>
<inside>
<t t-set="a" t-value="2"/>
<t t-out="a"/>
</inside>
<outside t-out="a"/>

<t t-set="b" t-value="1"/>
<inside t-cache="True">
<t t-set="b" t-value="2"/>
<t t-out="b"/>
</inside>
<outside t-out="b"/>
</div>

Will render::

<div>
<inside>2</inside>
<outside>2</inside>

<inside>2</inside>
<outside>1</inside>
</div>


The base of ``t-nocache``
~~~~~~~~~~~~~~~~~~~~~~~~~

The template part contained in a node with a ``t-nocache`` attribute is not
cached. This content is therefore **dynamic** and is rendered systematically.
However the available values are those provided by the controller (when
calling the ``_render`` method).

Example::

<section>
<article t-cache="record">
<title><t t-out="record.name"/> <i t-nocache="">(views: <t t-out="counter"/>)</i></titlle>
<content t-out="record.description"/>
</article>
</section>

Will render (counter = 1)::

<section>
<article>
<title>The record name <i>(views: 1)</i></titlle>
<content>Record description</content>
</article>
</section>

Here the ``<i>`` tag that contains the container will always be rendered. While
the rest is as a single string in the cache.

``t-nocache`` and scoped root values (``t-set``, ``t-foreach``...)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The contents of the ``t-nocache`` tag can be used for documentation and to
explain why the directive is added.
The values are scoped into ``t-nocache``, these values are root values only
(values provided by the controller and/or when calling the ``_render`` method
of ``ir.qweb``). ``t-set`` can be done in the template part, but will not be
available elsewhere.

Example::

<section>
<t t-set="counter" t-value="counter * 10"/>
<header t-nocache="">
<t t-set="counter" t-value="counter + 5"/>
(views: <t t-out="counter"/>)
</header>
<article t-cache="record">
<title><t t-out="record.name"/> <i t-nocache="">(views: <t t-out="counter"/>)</i></titlle>
<content t-out="record.description"/>
</article>
<footer>(views: <t t-out="counter"/>)</footer>
</section>

Will render (counter = 1)::

<section>
<header>
(views: 6)
</header>
<article>
<title>The record name <i>(views: 1)</i></titlle>
<content>Record description</content>
</article>
<footer>(views: 10)</footer>
</section>

Here the ``<i>`` tag that contains the container will always be rendered. While
the rest is as a single string in the cache. The counter is not updated by the
``t-set`` out of the ``t-nocache``

``t-nocache-*`` add some primitive values in the cache
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In order to be able to use values generated in the template, it is possible to
cache them. The directive is used as ``t-nocache-*="expr"`` where ``*`` is the
name of the chosen value and ``expr`` the python expression so the result will
be cached. The cached value must be primitive type.

Example::

<section t-cache="records">
<article t-foreach="records" t-as="record">
<header>
<title t-field="record.get_method_title()"/>
</header>
<footer t-nocache="This part has a dynamic counter and must be rendered all the time."
t-nocache-cached_value="record.get_base_counter()">
<span t-out="counter + cached_value"/>
</footer>
</article>
</section>

The value ``cached_value`` is cached with the cached template part of
``t-cache="records"`` and add to the scoped root values each time.

Helpers
-------

Expand Down