1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

=========================
Generic content retrieval
=========================

A common task in Django applications is writing template tags which
retrieve particular pieces of content; for example, a weblog might
need a "get latest entries" tag, while a news site would want "get
latest stories", and so on. Writing these tags to work only with
specific models results in duplication of code across applications, so
``template_utils`` provides a set of template tags which can retrieve
content from any installed model, according to certain criteria.

To use these tags, you'll need to have ``template_utils`` in your
``INSTALLED_APPS`` list, and you'll need to have ``{% load
generic_content %}`` in your template.


``get_latest_object``
=====================

This tag retrieves the "latest" object from a model, according to the
model's default ordering.

Syntax::

    {% get_latest_object [app_name].[model_name] as [varname] %}

So, for example, to retrieve the latest ``FreeComment`` posted::

    {% get_latest_object comments.freecomment as latest_comment %}


``get_latest_objects``
======================

Similar to ``get_latest_object``, but takes an additional argument --
a number -- and returns a list of that many objects.

Syntax::

    {% get_latest_objects [app_name].[model_name] [num] as [varname] %}

Continuing with comments as an example::

    {% get_latest_objects comments.freecomment 5 as latest_comments %}


``get_random_object``
=====================

Retrieves a single object, randomly selected, from a model.

Syntax::

    {% get_random_object [app_name].[model_name] as [varname] %}

So to retrieve a random comment::

    {% get_random_object comments.freecomment as random_comment %}


``get_random_objects``
======================

Much like ``get_latest_objects``, this tag returns a given number of
objects (randomly selected).

Syntax::

    {% get_random_object [app_name].[model_name] [num] as [varname] %}


``retrieve_object``
===================

Retrieves a single specific object by primary-key lookup.

Syntax::

    {% retrieve_object [app_name].[model_name] [primary_key] as [varname] %}

For example, if you wanted to retrieve a flatpage with ``id`` 12::

    {% retrieve_object flatpages.flatpage 12 as my_flatpage %}


Performing additional filtering
===============================

The tags described above all use the default manager of the model
specified in the tag call, and by default do not perform any filtering
on the default ``QuerySet`` obtained from that manager. However, as a
convenience for situations where it is desirable or necessary to
filter the objects (e.g., to retrieve the latest public comments, or
latest objects with a particular status), two mechanisms are supplied:
one broad and one fine-grained.

The broader method involves adding an extra setting to your Django
settings file: ``GENERIC_CONTENT_LOOKUP_KWARGS``. The value of this
setting should be a dictionary with keys corresponding to names of
models (e.g., "comments.freecomment", "auth.user", etc.) and values
containing dictionaries of valid database lookup arguments for those
models. When this setting exists and contains an entry for the model
whose objects are being queried, ``get_latest_object``,
``get_latest_objects``, ``get_random_object`` and
``get_random_objects`` will all read the lookup arguments and apply
them to the model's default ``QuerySet``.

So, for example, if you wanted these tags to only retrieve comments
whose ``is_public`` field is set to ``True`` (useful if you're doing
comment moderation), you'd add this to your settings file:

    GENERIC_CONTENT_LOOKUP_KWARGS = {
        'comments.freecomment': { 'is_public__exact': True }
    }

Because it does a primary-key lookup (and thus it's safe to assume you
know precisely which object you want), ``retrieve_object`` does not
filter in any situation.

The finer-grained method involves subclassing the ``Node`` class
common to most of the tags listed above; they're instances of
``template_utils.templatetags.generic_content.GenericContentNode``,
which is documented in the file ``nodes.txt`` in this directory.