pedigree: added documentation (doc/plugins/pedigree.mdwn)

Signed-off-by: intrigeri <intrigeri@boum.org>

diff --git a/doc/plugins/pedigree.mdwn b/doc/plugins/pedigree.mdwn
new file mode 100644 (file)
index 0000000..41f7074
--- /dev/null
+++ b/doc/plugins/pedigree.mdwn
@@ -0,0 +1,145 @@
+[[!template id=plugin name=pedigree author="intrigeri"]]
+[[!tag type/useful]]
+
+This plugin provides a bunch of loops that one can use in his/her
+`HTML::Template`'s to iterate over all or a subset of a page's
+parents. One can think of pedigree as "`PARENTLINKS` on steroids".
+
+[[!toc ]]
+
+Content
+=======
+
+Loop variables
+--------------
+
+Inside any loop provided by the pedigree plugin, every path element
+has not only the `URL` and `PAGE` variables, as with `PARENTLINKS`,
+but also the following ones:
+
+* `ABSDEPTH` (positive integer): depth of the path leading to the
+  current path element, counting from the wiki's root, which has
+  `ABSDEPTH=0`
+* `DISTANCE` (positive integer): distance, expressed in path elements,
+  from the current page to the current path element; e.g. this is
+  1 for the current page's mother, 2 for its grand-mother, etc.
+* `IS_ROOT` (boolean): true if, and only if, this path element is the
+  wiki's root
+* `IS_SECOND_ANCESTOR` (boolean): true if, and only if, this path
+  element is the first one after the wiki's root, on the path leading
+  to the current page
+* `IS_GRAND_MOTHER` (boolean): true if, and only if, this path element
+  is the current page's grand-mother
+* `IS_MOTHER` (boolean): true if, and only if, this path element
+  is the current page's mother
+
+Loops
+-----
+
+### `PEDIGREE`
+
+Returns the same parents list as `PARENTLINKS` would, along with
+additional loop variables as explained above.
+
+### `PEDIGREE_BUT_ROOT`
+
+Returns the same parents list as `PEDIGREE` would, **but** the wiki
+root (i.e. homepage).
+
+In addition to pedigree's common loop variables, `PEDIGREE_BUT_ROOT`
+provides `RELDEPTH` (positive integer), whose value, for a given
+parent, is its relative depth, i.e. the depth of the path leading to
+it, counting from the first element returned by this loop.
+
+### `PEDIGREE_BUT_TWO_OLDEST`
+
+Returns the same parents list as `PEDIGREE` would, **but** the wiki
+root (i.e. homepage) and the next path component.
+
+In addition to pedigree's common loop variables,
+`PEDIGREE_BUT_TWO_OLDEST` provides `RELDEPTH`: depth of the path
+leading to the current parent, relative to the first element returned
+by this loop.
+
+Usage
+=====
+
+Styling parents depending on their depth
+----------------------------------------
+
+Say you want the parent links to be styled depending on their depth in
+the path leading to the current page; just add the following lines in
+`page.tmpl`:
+
+       <TMPL_LOOP NAME="PEDIGREE">
+       <a href="<TMPL_VAR NAME="URL">" class="parentdepth<TMPL_VAR NAME="ABSDEPTH">">
+         <TMPL_VAR NAME="PAGE">
+       </a> / 
+       </TMPL_LOOP>
+
+Then write the appropriate CSS bits for `a.parentdepth1`, etc.
+
+Skip some parents, style the others depending on their distance
+---------------------------------------------------------------
+
+Say you want to display the parents links, skipping the wiki homepage,
+styled depending on their distance from the current page; just add the
+following lines in `page.tmpl`:
+
+       <TMPL_LOOP NAME="PEDIGREE_BUT_ROOT">
+       <a href="<TMPL_VAR NAME="URL">" class="parentdistance<TMPL_VAR NAME="DISTANCE">">
+         <TMPL_VAR NAME="PAGE">
+       </a> / 
+       </TMPL_LOOP>
+
+Then write the appropriate CSS bits for `a.parentdistance1`, etc.
+
+Full-blown example
+------------------
+
+Let's have a look at a more complicated example; combining the boolean
+loop variables provided by this plugin (`IS_ROOT` and friends) and
+`HTML::Template` flow control structures, you can have custom HTML
+and/or CSS generated for some special path components; e.g.:
+
+       <!-- all parents, skipping mother and grand'ma, inside a common div+ul -->
+       <div id="oldestparents">
+       <ul>
+       <TMPL_LOOP NAME="PEDIGREE">
+         <TMPL_IF NAME="IS_GRAND_MOTHER">
+         <TMPL_ELSE>
+           <TMPL_IF NAME="IS_MOTHER">
+           <TMPL_ELSE>
+             <li><a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a></li>
+           </TMPL_IF>
+         </TMPL_IF>
+       </TMPL_LOOP>
+       </ul>
+       </div>
+       
+       <!-- dedicated div's for mother and grand'ma -->
+       <TMPL_LOOP NAME="PEDIGREE">
+         <TMPL_IF NAME="IS_GRAND_MOTHER">
+           <div id="grandma">
+             <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
+           </div>
+         <TMPL_ELSE>
+           <TMPL_IF NAME="IS_MOTHER">
+             <div id="mother">
+               <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
+             </div>
+           </TMPL_IF>
+         </TMPL_IF>
+       </TMPL_LOOP>
+       
+       <!-- eventually, the current page title -->
+       <TMPL_VAR NAME="TITLE">
+       </div>
+
+Known bugs
+==========
+
+If `PEDIGREE_BUT_ROOT` and `PEDIGREE_BUT_TWO_OLDEST` are used in the
+same `HTML::Template`, `RELDEPTH` has wrong values inside the
+`PEDIGREE_BUT_ROOT` loop. This can be fixed if anyone needs this to
+be working.