From 7c075440ea3fb082b9b081a3c1b20b2b62e0e4dc Mon Sep 17 00:00:00 2001
From: Malcolm Tredinnick <malcolm.tredinnick@gmail.com>
Date: Sun, 12 Sep 2010 20:34:11 +0000
Subject: [PATCH] Add intro-user-level documentation about calling model
 methods from views.

Patch from timo and shacker. Fixed #10903.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13808 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/topics/db/queries.txt |  2 ++
 docs/topics/templates.txt  | 39 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index 5c4941fbf2..b0d053c2e9 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -823,6 +823,8 @@ a join with an ``F()`` object, a ``FieldError`` will be raised::
     # THIS WILL RAISE A FieldError
     >>> Entry.objects.update(headline=F('blog__name'))
 
+.. _topics-db-queries-related:
+
 Related objects
 ===============
 
diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt
index 5586ed8c12..492d23d716 100644
--- a/docs/topics/templates.txt
+++ b/docs/topics/templates.txt
@@ -569,6 +569,45 @@ This doesn't affect what happens to data coming from the variable itself.
 The variable's contents are still automatically escaped, if necessary, because
 they're beyond the control of the template author.
 
+.. _template-accessing-methods:
+
+Accessing method calls
+======================
+
+Most method calls attached to objects are also available from within templates.
+This means that templates have access to much more than just class attributes
+(like field names) and variables passed in from views. For example, the Django
+ORM provides the :ref:`"entry_set"<topics-db-queries-related>` syntax for
+finding a collection of objects related on a foreign key. Therefore, given
+a model called "comment" with a foreign key relationship to a model called
+"task" you can loop through all comments attached to a given task like this::
+
+    {% for comment in task.comment_set.all %}
+        {{ comment }}
+    {% endfor %}
+
+Similarly, :doc:`QuerySets<ref/models/querysets>` provide a ``count()`` method
+to count the number of objects they contain. Therefore, you can obtain a count
+of all comments related to the current task with::
+
+    {{ task.comment_set.all.count }}
+
+And of course you can easily access methods you've explicitly defined on your
+own models::
+
+    # In model
+    class Task(models.Model):
+        def foo(self):
+            return "bar"
+
+    # In template
+    {{ task.foo }}
+
+Because Django intentionally limits the amount of logic processing available
+in the template language, it is not possible to pass arguments to method calls
+accessed from within templates. Data should be calculated in views, then passed
+to templates for display.
+
 .. _template-built-in-reference:
 
 Using the built-in reference