From ee92df2cd0e3d6d93a13d6e74391ee495f9471c9 Mon Sep 17 00:00:00 2001 From: Stephen Burrows Date: Fri, 3 Jun 2011 17:06:13 -0400 Subject: [PATCH] Added a tutorial for Shipherd and made some minor doc improvements. --- docs/contrib/shipherd.rst | 1 + docs/tutorials/getting-started.rst | 22 +++++---- docs/tutorials/intro.rst | 1 + docs/tutorials/shipherd.rst | 49 +++++++++++++++++++ .../contrib/shipherd/templatetags/shipherd.py | 2 +- 5 files changed, 64 insertions(+), 11 deletions(-) create mode 100644 docs/tutorials/shipherd.rst diff --git a/docs/contrib/shipherd.rst b/docs/contrib/shipherd.rst index 915dac8..7d2eaf7 100644 --- a/docs/contrib/shipherd.rst +++ b/docs/contrib/shipherd.rst @@ -29,6 +29,7 @@ Models .. automodule:: philo.contrib.shipherd.models :members: Navigation, NavigationItem, NavigationMapper + :show-inheritance: Navigation caching ------------------ diff --git a/docs/tutorials/getting-started.rst b/docs/tutorials/getting-started.rst index eeb9ce8..d5d4c71 100644 --- a/docs/tutorials/getting-started.rst +++ b/docs/tutorials/getting-started.rst @@ -70,18 +70,20 @@ Editing page contents Great! We've got a page that says "Hello World". But what if we want it to say something else? Should we really have to edit the :class:`.Template` to change the content of the :class:`.Page`? And what if we want to share the :class:`.Template` but have different content? Adjust the :class:`.Template` to look like this:: - - {% container page_title %} - - - {% container page_body as content %} - {% if content %} -

{{ content }}

- {% endif %} -

The time is {% now %}.

- + + {% container page_title %} + + + {% container page_body as content %} + {% if content %} +

{{ content }}

+ {% endif %} +

The time is {% now %}.

+ Now go edit your :class:`.Page`. Two new fields called "Page title" and "Page body" have shown up! You can put anything you like in here and have it show up in the appropriate places when the page is rendered. .. seealso:: :ttag:`philo.templatetags.containers.container` + +Congrats! You've done it! diff --git a/docs/tutorials/intro.rst b/docs/tutorials/intro.rst index 903dfea..c7d3e99 100644 --- a/docs/tutorials/intro.rst +++ b/docs/tutorials/intro.rst @@ -5,3 +5,4 @@ Tutorials :maxdepth: 1 getting-started + shipherd diff --git a/docs/tutorials/shipherd.rst b/docs/tutorials/shipherd.rst new file mode 100644 index 0000000..f7988e6 --- /dev/null +++ b/docs/tutorials/shipherd.rst @@ -0,0 +1,49 @@ +Using Shipherd in the Admin +=========================== + +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! ;-) + +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`. + +Creating the Navigation ++++++++++++++++++++++++ + +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. + +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.) + +Press save and you've created your first navigation. + +Displaying the Navigation ++++++++++++++++++++++++++ + +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:: + + + + {% container page_title %} + + + + {% container page_body as content %} + {% if content %} +

{{ content }}

+ {% endif %} +

The time is {% now %}.

+ + + +Now have a look at the page - your navigation is there! + +Linking to google ++++++++++++++++++ + +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. + +: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. diff --git a/philo/contrib/shipherd/templatetags/shipherd.py b/philo/contrib/shipherd/templatetags/shipherd.py index 9e572aa..85a0bc5 100644 --- a/philo/contrib/shipherd/templatetags/shipherd.py +++ b/philo/contrib/shipherd/templatetags/shipherd.py @@ -131,7 +131,7 @@ def recursenavigation(parser, token):