docs/tutorials/shipherd.rst

   1 Using Shipherd in the Admin
   2 ===========================
   3
   4 The navigation mechanism is fairly complex; unfortunately, there's no real way around that - without a lot of equally complex code that you are quite welcome to write and contribute! ;-)
   5
   6 For this guide, we'll assume that you have the setup described in :doc:`getting-started`. We'll be adding a main :class:`.Navigation` to the root :class:`.Node` and making it display as part of the :class:`.Template`.
   7
   8 Before getting started, make sure that you've added :mod:`philo.contrib.shipherd` to your :setting:`INSTALLED_APPS`. :mod:`~philo.contrib.shipherd` template tags also require the request context processor, so make sure to set :setting:`TEMPLATE_CONTEXT_PROCESSORS` appropriately::
   9
  10         TEMPLATE_CONTEXT_PROCESSORS = (
  11                 # Defaults
  12                 "django.contrib.auth.context_processors.auth",
  13                 "django.core.context_processors.debug",
  14                 "django.core.context_processors.i18n",
  15                 "django.core.context_processors.media",
  16                 "django.core.context_processors.static",
  17                 "django.contrib.messages.context_processors.messages"
  18                 ...
  19                 "django.core.context_processors.request"
  20         )
  21
  22 Creating the Navigation
  23 +++++++++++++++++++++++
  24
  25 Start off by adding a new :class:`.Navigation` instance with :attr:`~.Navigation.node` set to the good ole' ``root`` node and :attr:`~.Navigation.key` set to ``main``. The default :attr:`~.Navigation.depth` of 3 is fine.
  26
  27 Now open up that first inline :class:`.NavigationItem`. Make the text ``Hello World`` and set the target :class:`.Node` to, again, ``root``. (Of course, this is a special case. If we had another node that we wanted to point to, we would choose that.)
  28
  29 Press save and you've created your first navigation.
  30
  31 Displaying the Navigation
  32 +++++++++++++++++++++++++
  33
  34 All you need to do now is show the navigation in the template! This is quite easy, using the :ttag:`~philo.contrib.shipherd.templatetags.shipherd.recursenavigation` templatetag. For now we'll keep it simple. Adjust the "Hello World Template" to look like this::
  35
  36         <html>{% load shipherd %}
  37             <head>
  38                 <title>{% container page_title %}</title>
  39             </head>
  40             <body>
  41                 <ul>
  42                     {% recursenavigation node "main" %}
  43                         <li{% if navloop.active %} class="active"{% endif %}>
  44                             <a href="{{ item.get_target_url }}">{{ item.text }}</a>
  45                         </li>
  46                     {% endrecursenavigation %}
  47                 </ul>
  48                 {% container page_body as content %}
  49                 {% if content %}
  50                     <p>{{ content }}</p>
  51                 {% endif %}
  52                 <p>The time is {% now %}.</p>
  53             </body>
  54         </html>
  55
  56 Now have a look at the page - your navigation is there!
  57
  58 Linking to google
  59 +++++++++++++++++
  60
  61 Edit the ``main`` :class:`.Navigation` again to add another :class:`.NavigationItem`. This time give it the :attr:`~.NavigationItem.text` ``Google`` and set the :attr:`~.TargetURLModel.url_or_subpath` field to ``http://google.com``. A navigation item will show up on the Hello World page that points to ``google.com``! Granted, your navigation probably shouldn't do that, because confusing navigation is confusing; the point is that it is possible to provide navigation to arbitrary URLs.
  62
  63 :attr:`~.TargetURLModel.url_or_subpath` can also be used in conjuction with a :class:`.Node` to link to a subpath beyond that :class:`.Node`'s url.