docs/contrib/shipherd.rst

   1 Shipherd
   2 ========
   3
   4 .. automodule:: philo.contrib.shipherd
   5         :members:
   6
   7         :class:`.Node`\ s are useful for structuring a website; however, they are inherently unsuitable for creating site navigation.
   8
   9         The most glaring problem is that a navigation tree based on :class:`.Node`\ s would have one :class:`.Node` as the root, whereas navigation usually has multiple objects at the top level.
  10
  11         Additionally, navigation needs to have display text that is relevant to the current context; however, :class:`.Node`\ s do not have a field for that, and :class:`.View` subclasses with a name or title field will generally need to use it for database-searchable names.
  12
  13         Finally, :class:`.Node` structures are inherently unordered, while navigation is inherently ordered.
  14
  15         :mod:`~philo.contrib.shipherd` exists to resolve these issues by separating navigation structures from :class:`.Node` structures. It is instead structured around the way that site navigation works in the wild:
  16
  17         * A site may have one or more independent navigation bars (Main navigation, side navigation, etc.)
  18         * A navigation bar may be shared by sections of the website, or even by the entire site.
  19         * A navigation bar has a certain depth that it displays to.
  20
  21         The :class:`.Navigation` model supplies these features by attaching itself to a :class:`.Node` via :class:`ForeignKey` and adding a :attr:`navigation` property to :class:`.Node` which provides access to a :class:`.Node` instance's inherited :class:`.Navigation`\ s.
  22
  23         Each entry in the navigation bar is then represented by a :class:`.NavigationItem`, which stores information such as the :attr:`~.NavigationItem.order` and :attr:`~.NavigationItem.text` for the entry. Given an :class:`HttpRequest`, a :class:`.NavigationItem` can also tell whether it :meth:`~.NavigationItem.is_active` or :meth:`~.NavigationItem.has_active_descendants`.
  24
  25         Since the common pattern is to recurse through a navigation tree and render each part similarly, :mod:`~philo.contrib.shipherd` also ships with the :ttag:`~philo.contrib.shipherd.templatetags.shipherd.recursenavigation` template tag.
  26
  27 Models
  28 ++++++
  29
  30 .. automodule:: philo.contrib.shipherd.models
  31         :members: Navigation, NavigationItem, NavigationMapper
  32         :show-inheritance:
  33
  34 Navigation caching
  35 ------------------
  36
  37 .. autoclass:: NavigationManager
  38         :members:
  39
  40 .. autoclass:: NavigationItemManager
  41         :members:
  42
  43 .. autoclass:: NavigationCacheQuerySet
  44         :members:
  45
  46 Template tags
  47 +++++++++++++
  48
  49 .. automodule:: philo.contrib.shipherd.templatetags.shipherd
  50
  51 .. autotemplatetag:: recursenavigation
  52
  53 .. autotemplatefilter:: has_navigation
  54
  55 .. autotemplatefilter:: navigation_host