-title: Generate hierarchy
-linktitly: Hierarchy
-parent: Plugins
-ctime: 2009-06-26
-
-This is one of the more complex plugins, used to generate menus and
-breadcrumbs. For this, it reads certain keyword from the
-[[pageformat]], built an internal parent-child representation.
-
-This is later used for by the functions "`get_breadcrumbs()`" and
-"`get_sidemenu()`", which you call from the [[template_mako]].
-
-= Page attributes =
-
-At the "`scan`" [[hook|hooks]], the plugin looks for entries like:
-
- parent: Home
-
-or
-
- childs: Cmdline, Inheritance
-
-Here's an example of five pages with different attributes:
-
----
-
- title: Homepage
- linktitle: Home
-
----
-
- title: Impressum
- parent: Home
-
----
-
- title: Job
- parent: Home
-
----
-
- title: CV
- parent: Job
-
----
-
- title: Knowledge
- parent: Job
-
----
-
-= Internal representation =
-
-the plugin would populate the variables "`_childs`" and "`_parent`" like this:
-
- _parent = {
- 'Impressum': 'Home',
- 'CV': 'Job',
- 'Knowledge': 'Job',
- 'Job': 'Home'
- }
-
- _childs = {
- 'Home': [(100, 'Job'),
- (100, 'Impressum')],
- 'Job': [(100, 'CV'),
- (100, 'Knowledge')]}
-
-That's all you need to generate a sidemap, breadcrumbs or a side-menu.
-
-The pages are first ordered by some number, then by the "`linktitle`". If
-a page has no "`linktitle:`" attribute, then the normal title will be used
-instead.
-
-If you want to modify the sort-order, simply specify a "`order: 200`" in the
-page itself.
-
-= Generation of breadcrumbs =
-
-This is done via a suitable [[template_mako]]. The template uses the
-function "`get_breadcrumbs()`" and returns (linktitle, link) tuples. As a
-bonus: all the links are always relative to the calling page.
-
-Here's a sample Mako template excerpt:
-
- <ul>\
- % for page, link in get_breadcrumbs():
- <li><a href="${link}">${page.linktitle}</a></li>\
- % endfor
- </ul>\
-
-
-= Generation of a side-menu =
-
-This again is done via a suitable [[template_mako]]. The
-template uses the function "`get_sidemenu()`" and returns (level,
-part_of_path, is_current, title, link) tuples. Again all links are relative
-to the calling page.
-
-* "`level`" is the indendation level, starting with 0. You can use this for
- CSS "`id=`" or "`class`" attributes
-* "`part_of_path`" is a flag telling you if the mentioned page is part
- of your path, i.e. if the specified page is in the breadcrumbs.
-* "`is_current`" is a flag marking the current page.
-* "`title`" is the full title for the page
-* "`link`" is the relative URL to the page
-
-Here's a sample Mako template excerpt that converts this into a HTML menu:
-
- <ul id="sidebar">
- % for level, part_of_path, current, page, link in get_sidemenu():
- <li class="sidebar${level}"\
- % if current:
- id="sidebar_current">${page.linktitle | entity}</li>
- % else:
- ><a href="${link}">${page.linktitle | entity}</a></li>
- % endif
- % endfor
- </ul>
-
-= Generate a list of recently changed pages =
-
-To get a list of recently changed pages, do this:
-
- <%
- history = get_recently())
- %>
- % if len(history)>1:
- <h2>Recent changed</h2>
- % for page, link in history:
- % if page.mtime > page.ctime:
- Modified ${format_date(page.mtime)}\
- % else:
- Created ${format_date(page.ctime)}\
- % endif
- : <a href="${link}">${page.title | entity}</a><br />
- % endfor
- % endif
-
-
-= Generate a sitemap =
-
-To generate a site map for your whole project, do something like
-this:
-
- <%
- site = get_sitemap()
- %>
- <ul>
- % for level, page, link in site:
- <li id="sidemap${level}"><a href="${link}">${page.title}</a></li>
- % endfor
- </ul>
-
-Now you'd need to use CSS to indent the entries. If you prefer a more
-normal "`<ul>..<li><ul><li></li></ul>..</il>`" style, you'd could do this
-with some more advanced Mako template magic:
-
- <%
- site = get_sitemap()
- lvl = -1
- %>
- % for level, page, link in site:
- ### Adjust level by indenting/detenting via <ul> or </ul>:
- % while lvl < level:
- <ul><% lvl += 1 %>
- % endwhile
- % while lvl > level:
- </ul><% lvl -= 1 %>
- % endwhile
- ### Print out the <li>
- <li id="sidemap${level}"><a href="${link}">${page.title}</a></li>
- % endfor
- ### At the end of the sitemap, detent back to level -1
- % while lvl >= 0:
- </ul><% lvl -= 1 %>
- % endwhile