=== modified file 'lava_server/bread_crumbs.py'
@@ -18,7 +18,30 @@
"""
-Bread crubm management for LAVA server
+Bread crumb management for LAVA server.
+
+This system allows one to construct static trees of views (come to think about
+it it could also be used as a site map generator) where each view has at most
+one parent. In such model any view could be followed back through the parent
+link to create a bread crumb trail of named URLs.
+
+It is important to emphasise that this system is STATIC, that is, it is not
+based on browsing history. Regardless on how the user got to a particular view
+the bread crumb system will report the same set of pages. The idea is not to
+let users go back (that's the what the browser allows them to do) but to put
+the current page into context of where it "belongs".
+
+To use this system apply the @BreadCrumb(name, parent=parent_view,
+needs=['required', 'keywords']) decorator to your view function. To render
+breadcrumbs you can use the default template that is a part of
+"layout/content.html" template. Your context must include the bread_crumb_trail
+variable. To construct it call BreadCrumbTrail.leading_to(your_view_name, ...)
+passing any of the keyword arguments specified in needs of your and any parent
+views (yes this is annoying).
+
+A mistake in paring 'needs' to keywords passed to BreadCrumbTrail.leading_to()
+will result in logged warnings (either a name of the URL being not
+constructible). To fix that simply add the missing keyword argument and reload.
"""
from django.core.urlresolvers import reverse
@@ -26,8 +49,23 @@
class BreadCrumb(object):
+ """
+ A crumb of bread left in the forest of pages to let you go back to (no, not
+ to where you came from) where the developer desired you to go.
+ """
def __init__(self, name, parent=None, needs=None):
+ """
+ Construct a bread crumb object.
+
+ The name is the essential property creating the actual text visible on
+ web pages. It may be a static string or a new-style python string
+ template. Parent allows one to construct a static brad crumb tree where
+ each crubm may have at most one parent. Needs, if specified, must be
+ an array of strings that denote identifiers required to resolve the URL
+ of this bread crumb. The identifiers are obtained from the call
+ BreadCrumbTrail.leading_to().
+ """
self.name = name
self.view = None
self.parent = parent
@@ -38,11 +76,23 @@
self.name, self.view, self.parent)
def __call__(self, view):
+ """
+ Call method, used when decorating function-based views
+
+ Id does not redefine the function (so is not a real decorator) but
+ instead stores the bradcrubm object in the _bread_crumb attribute of
+ the function.
+ """
self.view = view
view._bread_crumb = self
return view
def get_name(self, kwargs):
+ """
+ Get the name of this crumb.
+
+ The name is formatted with the specfied keyword argments.
+ """
try:
return self.name.format(**kwargs)
except:
@@ -50,6 +100,14 @@
raise
def get_absolute_url(self, kwargs):
+ """
+ Get the URL of this crumb.
+
+ The URL is constructed with a call to dajngo's reverse() function. It
+ is supplemented with the same variables that were listed in needs array
+ in the bread crumb constructor. The arguments are passed in order, from
+ the kwargs dictionary.
+ """
try:
return reverse(self.view, args=[kwargs[name] for name in self.needs])
except:
@@ -58,6 +116,16 @@
class LiveBreadCrumb(object):
+ """
+ Bread crumb instance as observed by a particular request.
+
+ It is a binding between the global view-specific bread crumb object and
+ dynamic request-specific keyword arguments.
+
+ For convenience it provides two bread crumb functions (get_name() and
+ get_absolute_url()) that automatically provide the correct keyword
+ arguments.
+ """
def __init__(self, bread_crumb, kwargs):
self.bread_crumb = bread_crumb
@@ -71,6 +139,11 @@
class BreadCrumbTrail(object):
+ """
+ A list of live bread crumbs that lead from a particular view, along the
+ parent chain, all the way to the root view (that is without any parent
+ view).
+ """
def __init__(self, bread_crumb_list, kwargs):
self.bread_crumb_list = bread_crumb_list
@@ -82,6 +155,16 @@
@classmethod
def leading_to(cls, view, **kwargs):
+ """
+ Create an instance of BreadCrumbTrail that starts at the specified view.
+
+ Additional keyword arguments, if provided, will be available to
+ get_name() and get_absolute_url() of each LiveBreadCrumb that makes up
+ this trail. In practice they should contain a set of arguments that are
+ needed by any parent bread crumb URL or name.
+
+ TODO: could we check this statically somehow?
+ """
lst = []
while view is not None:
lst.append(view._bread_crumb)